Spring AI 集成 Google GenAI深入解析扩展用量元数据Thinking/Cached/Tool-Use Tokens 与 Traffic Type【免费下载链接】spring-aiAn Application Framework for AI Engineering项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai导读本文基于 Spring AI 项目仓库中models/spring-ai-google-genai模块的官方 README系统讲解 Google GenAI 聊天模型集成方式以及 Spring AI 为其提供的**扩展用量元数据Extended Usage Metadata**能力。通过GoogleGenAiUsage类你可以在标准Usage接口的 Prompt/Completion/Total Token 基础上进一步获取思考令牌Thinking Tokens、缓存内容令牌Cached Content Tokens、工具调用令牌Tool-Use Tokens、按模态细分的令牌统计Modality Breakdowns以及请求流量类型Traffic Type。读完本文你将掌握依赖引入、环境变量配置、扩展元数据的每一项 API 用法及其源码级实现原理能够为基于 Gemini 系列模型的应用实现精细化的成本观测与用量审计。一、依赖引入Starter 与手动配置两种方式该模块在仓库中对应两个可引入的 Maven 构件分别面向 Spring Boot 自动装配场景与手动编程场景。1.1 使用 Spring Boot Starter推荐官方 README 推荐在 Spring Boot 项目中使用 Starter它会通过spring-ai-autoconfigure-model-google-genai自动完成GoogleGenAiChatModel、GoogleGenAiChatOptions等 Bean 的装配dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-google-genai/artifactId /dependency从仓库中的 starters/spring-ai-starter-model-google-genai/pom.xml 可以看到该 Starter 聚合了spring-ai-autoconfigure-model-google-genai、spring-ai-google-genai以及spring-ai-client-chat等核心依赖因此只需引入它即可获得完整的模型客户端能力。1.2 手动引入核心模块对于不使用 Spring Boot 自动装配、希望完全由自己掌控 Bean 生命周期的场景可以直接引入核心模块dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-google-genai/artifactId /dependency手动模式下你需要自行构造GoogleGenAiChatModel与GoogleGenAiChatOptions例如借助 Google GenAI 官方 Java SDK 的Client这与自动装配模式得到的最终模型对象在行为上是等价的。二、环境变量配置Google AI Studio 与 Vertex AI 两种接入方式spring-ai-google-genai模块底层通过 Google GenAI 官方 SDK 与 Gemini 模型通信。README 明确了在启用Vertex AI后端时需要配置的三个环境变量export GOOGLE_GENAI_USE_VERTEXAItrue export GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONyour-region各变量含义如下环境变量作用GOOGLE_GENAI_USE_VERTEXAI是否启用 Vertex AI 模式而非 Google AI Studio / Gemini API 模式取值true/falseGOOGLE_CLOUD_PROJECTVertex AI 所在 Google Cloud 项目 ID对应配置项spring.ai.google.genai.project-idGOOGLE_CLOUD_LOCATIONVertex AI 服务区域如us-central1对应配置项spring.ai.google.genai.location不使用 Vertex AI、而是直接调用 Gemini API 时则通过 API Key 认证。仓库中的迁移说明 MIGRATION_GUIDE.md 给出了对应的 Spring Boot 配置属性写法spring.ai.google.genai.api-keyyour-api-key spring.ai.google.genai.chat.modelgemini-2.0-flash以及 Vertex AI 模式spring.ai.google.genai.project-idmy-project spring.ai.google.genai.locationus-central1 spring.ai.google.genai.chat.modelgemini-2.0-flash同时自动装配类 GoogleGenAiChatAutoConfiguration.java 也支持通过spring.ai.google.genai.vertex-aitrue属性切换 Vertex AI 模式与上述环境变量等价。三、扩展用量元数据GoogleGenAiUsage类总览Google GenAI 模块的核心亮点在于提供了比标准Usage接口更丰富的用量跟踪能力。README 明确指出GoogleGenAiUsage类扩展了 Spring AI 标准的Usage接口并额外提供针对 Google GenAI 模型的令牌统计维度。在仓库源码 GoogleGenAiUsage.java 中可以看到该类继承自DefaultUsageSpring AI 标准Usage接口的默认实现主要新增字段包括字段类型含义thoughtsTokenCountInteger思考令牌数Thinking TokenscachedContentTokenCountInteger缓存内容令牌数Cached Content TokenstoolUsePromptTokenCountInteger工具调用提示令牌数Tool-Use TokenspromptTokensDetailsListGoogleGenAiModalityTokenCount请求输入的模态细分令牌统计candidatesTokensDetailsListGoogleGenAiModalityTokenCount响应输出的模态细分令牌统计cacheTokensDetailsListGoogleGenAiModalityTokenCount缓存内容的模态细分令牌统计toolUsePromptTokensDetailsListGoogleGenAiModalityTokenCount工具调用提示的模态细分令牌统计trafficTypeGoogleGenAiTrafficType请求流量类型此外该类提供了静态工厂方法from(GenerateContentResponseUsageMetadata)负责把 Google GenAI 官方 SDK 返回的GenerateContentResponseUsageMetadata转换成GoogleGenAiUsage实例SDK 原生元数据对象也会被保留可通过getNativeUsage()继续访问见 GoogleGenAiUsage.java。四、扩展维度详解与使用示例在拿到ChatResponse后将response.getMetadata().getUsage()强转为GoogleGenAiUsage即可访问以下扩展维度。注意只有开启了扩展元数据默认开启时返回的Usage实例才可强转为GoogleGenAiUsage否则它是基础DefaultUsage。4.1 基础令牌计数继承自标准 Usage三个基础维度getPromptTokens()、getCompletionTokens()、getTotalTokens()沿用标准Usage接口语义分别表示请求输入令牌、响应输出令牌与总令牌数适用于所有 Spring AI 模型无需任何额外配置。4.2 Thinking Tokens思考令牌针对 Gemini 2.0 Flash Thinking 这类支持推理reasoning的模型可以统计模型“思考”过程消耗的令牌ChatResponse response chatModel.call(prompt); GoogleGenAiUsage usage (GoogleGenAiUsage) response.getMetadata().getUsage(); Integer thoughtsTokens usage.getThoughtsTokenCount(); // Reasoning tokens从源码看该值直接取自 SDK 元数据的thoughtsTokenCount字段GoogleGenAiUsage.java。对非思考型模型该字段通常为null使用时建议判空。4.3 Cached Content Tokens缓存内容令牌借助上下文缓存Context Caching可以显著降低重复提示的 API 成本。通过该维度可以精确监控命中缓存上下文所消耗的令牌Integer cachedTokens usage.getCachedContentTokenCount(); // Cached context tokens值得注意的实现细节在 GoogleGenAiUsage.java 中该类重写了getCacheReadInputTokens()方法将cachedContentTokenCount以Long形式暴露给标准的用量观测体系使 Spring AI 的观测Observation与指标采集能够直接读取缓存命中令牌而无需感知 Google 特有类型。4.4 Tool-Use Tokens工具调用令牌在 Function Calling / Tool Use 场景下工具描述、参数 Schema 以及工具执行结果都会折算为令牌。该维度跟踪这部分消耗Integer toolUseTokens usage.getToolUsePromptTokenCount(); // Tool-use tokens4.5 Modality Breakdowns按模态细分的令牌统计Gemini 是原生多模态模型输入输出可能同时包含文本、图片、音频、视频。通过getPromptTokensDetails()可以获得请求输入按模态拆分的明细ListGoogleGenAiModalityTokenCount promptDetails usage.getPromptTokensDetails(); for (GoogleGenAiModalityTokenCount detail : promptDetails) { System.out.println(detail.getModality() : detail.getTokenCount()); }对应的 GoogleGenAiModalityTokenCount.java 是一个仅含modality与tokenCount两个字段的轻量值对象。从源码看其from()工厂方法会把 SDK 的MediaModality映射为更清晰的名称目前支持TEXT、IMAGE、VIDEO、AUDIO、DOCUMENT未指定或未知的类型统一归一为UNKNOWNGoogleGenAiModalityTokenCount.java。除promptTokensDetails请求输入外该类还提供三组平行维度getCandidatesTokensDetails()响应输出按模态的令牌统计getCacheTokensDetails()缓存内容按模态的令牌统计getToolUsePromptTokensDetails()工具调用提示按模态的令牌统计。4.6 Traffic Type流量类型用于标识请求消耗的是Pay-As-You-Go按量付费还是Provisioned Throughput预置吞吐配额GoogleGenAiTrafficType trafficType usage.getTrafficType(); // Returns: ON_DEMAND, PROVISIONED_THROUGHPUT, or UNKNOWNGoogleGenAiTrafficType.java 定义了三个枚举值ON_DEMAND、PROVISIONED_THROUGHPUT与UNKNOWN。从源码看from(TrafficType)会把 SDK 中的TRAFFIC_TYPE_UNSPECIFIED以及无法识别的值统一归并为UNKNOWN保证枚举取值稳定可序列化JsonValue输出字符串值。这一维度对按配额做容量规划、成本分摊非常实用。五、开关配置includeExtendedUsageMetadata默认情况下扩展元数据是开启的。你可以通过GoogleGenAiChatOptions的 Builder 显式控制GoogleGenAiChatOptions options GoogleGenAiChatOptions.builder() .model(gemini-2.0-flash) .includeExtendedUsageMetadata(true) // Enable extended metadata .build();includeExtendedUsageMetadata是 GoogleGenAiChatOptions.java 中的一个可选布尔字段Nullable Boolean可通过 Builder 的includeExtendedUsageMetadata(boolean)方法设置GoogleGenAiChatOptions.java。5.1 源码中的解析逻辑该开关在模型调用时如何生效从 GoogleGenAiChatModel.java 的getDefaultUsage()方法可以看到完整决策逻辑解析开关时优先使用请求级 Optionsprompt.getOptions()中的includeExtendedUsageMetadata其次回退到模型级默认 Options若开关为true或未配置默认即true则调用GoogleGenAiUsage.from(usageMetadata)生成携带全部扩展维度的GoogleGenAiUsage若开关为false则回退到仅含 Prompt/Completion/Total 三个基础计数的DefaultUsage以兼容旧行为。这意味着你可以按请求粒度独立控制是否收集扩展元数据例如对高频、低价值的调用关闭细粒度统计以节省解析开销而对需要计费审计的调用保持开启。六、完整示例一次多模态请求的用量观测以下完整代码来自 README 并稍作整理演示了从发起多模态请求到读取全部扩展元数据的全流程Component public class ExtendedUsageExample { private final GoogleGenAiChatModel chatModel; public void demonstrateExtendedUsage() { Prompt prompt new Prompt(Analyze this complex multi-modal request); ChatResponse response chatModel.call(prompt); // Cast to GoogleGenAiUsage for extended metadata GoogleGenAiUsage usage (GoogleGenAiUsage) response.getMetadata().getUsage(); // Basic token counts (standard Usage interface) System.out.println(Prompt tokens: usage.getPromptTokens()); System.out.println(Completion tokens: usage.getCompletionTokens()); System.out.println(Total tokens: usage.getTotalTokens()); // Extended metadata (Google GenAI specific) System.out.println(Thinking tokens: usage.getThoughtsTokenCount()); System.out.println(Cached tokens: usage.getCachedContentTokenCount()); System.out.println(Tool-use tokens: usage.getToolUsePromptTokenCount()); // Modality breakdowns if (usage.getPromptTokensDetails() ! null) { usage.getPromptTokensDetails().forEach(detail - System.out.println( detail.getModality() : detail.getTokenCount()) ); } // Traffic type System.out.println(Traffic type: usage.getTrafficType()); // Access native SDK object for any additional metadata GenerateContentResponseUsageMetadata nativeUsage (GenerateContentResponseUsageMetadata) usage.getNativeUsage(); } }几点实操提醒getThoughtsTokenCount()、getCachedContentTokenCount()、getToolUsePromptTokenCount()等扩展字段在对应场景不存在时返回null而非0打印或聚合前建议判空模态明细列表如getPromptTokensDetails()也可能为null示例中已做判空处理getNativeUsage()返回的是 Google GenAI SDK 的GenerateContentResponseUsageMetadata原始对象可用来访问该模块尚未封装的任何新字段保证不会因 SDK 演进而丢失信息。七、向后兼容性标准 Usage 接口不受影响扩展元数据在增强信息维度的同时完整保持了与标准Usage接口的向后兼容性。使用基础接口编写的代码无需任何改动即可继续运行// Works with any Spring AI model Usage usage response.getMetadata().getUsage(); Long promptTokens usage.getPromptTokens(); Long completionTokens usage.getCompletionTokens();这一兼容性由类继承结构保证GoogleGenAiUsage extends DefaultUsage而DefaultUsage实现了 Spring AI 的Usage接口因此强转前使用Usage类型接收是安全的反之在includeExtendedUsageMetadata(false)时返回的则是纯DefaultUsage实例源码见 GoogleGenAiChatModel.java此时不应再做向下强转。八、测试验证仓库中的行为证据仓库为扩展用量元数据提供了完整的单元测试见 GoogleGenAiChatModelExtendedUsageTests.java测试覆盖了以下关键场景可作为你理解与回归验证该功能的依据Thinking Tokens构造thoughtsTokenCount25的模拟响应断言getThoughtsTokenCount()返回 25且基础计数100/50/175正确测试第 79-122 行Cached Content断言getCachedContentTokenCount()为 80并验证promptTokens已包含缓存内容测试第 124-158 行Tool-Use Tokens断言getToolUsePromptTokenCount()为 30测试第 160-192 行Modality Breakdowns验证 TEXT 与 IMAGE 两类模态在 prompt 明细中的数量与顺序测试第 194-252 行Traffic Type验证ON_DEMAND与PROVISIONED_THROUGHPUT两种类型的映射测试第 254-282 行及 328-412 行开关关闭includeExtendedUsageMetadata(false)时返回的Usage不再是GoogleGenAiUsage实例且基础计数仍然正确测试第 284-325 行元数据缺失SDK 响应不含 usageMetadata 时优雅降级基础计数为 0、扩展字段为null不抛异常测试第 414-443 行。这些测试同时印证了前面提到的 null 语义与开关行为是你在生产代码中处理这些字段时的可靠参考。总结本文完整梳理了 Spring AIspring-ai-google-genai模块的集成路径Starter / 手动依赖、Google AI Studio / Vertex AI 两种环境配置并围绕 README 的核心内容——扩展用量元数据——展开了六个维度的 API 详解、开关配置的源码级解析、完整示例代码与兼容性说明。借助GoogleGenAiUsage开发者可以在标准令牌计数之外精确观测推理思考成本、缓存命中收益、工具调用开销、多模态令牌分布与配额类型为基于 Gemini 模型的 AI 应用构建起透明、可审计的成本观测体系。【免费下载链接】spring-aiAn Application Framework for AI Engineering项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考