ADK 上下文缓存实战：用 Cache Analysis Research Assistant 量化 Gemini 显式与隐式缓存的性能收益

ADK 上下文缓存实战用 Cache Analysis Research Assistant 量化 Gemini 显式与隐式缓存的性能收益【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读本文以 ADK 仓库中的contributing/samples/context_management/cache_analysis示例为蓝本系统讲解如何在 ADKAgent Development Kit中通过 App 级ContextCacheConfig配置上下文缓存并借助自动化的run_cache_experiments.py脚本量化缓存带来的延迟与成本收益。你将掌握缓存配置参数min_tokens/ttl_seconds/cache_intervals的含义与取值边界、显式缓存ADK explicit caching与 Google 内置隐式缓存implicit caching的差异、不同 Gemini 模型自动适配的实验类型以及如何通过cached_content_token_count等指标验证缓存命中效果。示例定位为什么需要一个研究助手Agent 来测试缓存上下文缓存Context Caching的核心收益在于当同一会话的多次请求共享大量稳定的前缀内容系统指令、工具定义时模型服务商可以直接复用已处理过的前缀从而显著降低首 token 延迟与输入 token 成本。但缓存的生效存在阈值门槛模型相关的最小 token 数、TTL 窗口、以及显式与隐式两种机制之分只有用足够大的 Prompt 反复实测才能得出可信结论。cache_analysis示例正是为此设计的缓存性能研究平台一个承载4200 token巨型系统指令的研究分析 Agent超过 Gemini 2.5 的 2048 token 与 Gemini 3 的 4096 token 缓存下限确保能触发缓存挂载7 个专业化研究/分析工具覆盖纯文本对话与工具调用两类请求场景在App 级别配置上下文缓存遵循 ADK 官方推荐的最佳实践内置自动化实验脚本支持任意 Gemini 模型并自动切换实验类型。其完整代码位于 contributing/samples/context_management/cache_analysis包含 4 个源文件文件职责agent.py定义研究助手 Agent、7 个工具函数及 App 级缓存配置run_cache_experiments.py自动化对比实验脚本显式 vs 隐式/无缓存utils.py测试 Prompt 集、异步调用封装、批量实验与统计工具README.md使用说明本文所依据的核心文档Agent 结构7 个工具组成的图示例 Agent 名为cache_analysis_assistant其工具拓扑如下取自 README 的 mermaid 图这 7 个工具均为纯 Python 函数工具由 agent.py 定义每个都带有详尽参数注释与模拟处理逻辑。其设计意图是工具定义本身会进入模型上下文工具越多、参数描述越详细可缓存的上下文就越大从而更贴近真实生产中工具密集型 Agent 的缓存形态。例如benchmark_performance(system_name, metrics, duration, load_profile)支持latency/throughput/cpu/memory/network/scalability/stability等指标维度与constant/realistic/peak/stress/spike多种负载模式。App 级缓存配置ContextCacheConfig 详解示例明确强调Context caching is configured at the App level这是 ADK 的最佳实践。配置代码与 README 示例一致也即 agent.py 中的实际实现from google.adk.agents.context_cache_config import ContextCacheConfig from google.adk.apps.app import App cache_analysis_app App( namecache_analysis, root_agentcache_analysis_agent, context_cache_configContextCacheConfig( min_tokens4096, ttl_seconds600, # 10 minutes for research sessions cache_intervals3, # Maximum invocations before cache refresh ), )为什么必须在 App 级配置从源码看context_cache_config是App的构造参数见 src/google/adk/apps/app.py并且 context_cache_config.py 的类文档明确说明When this config is present on an app, context caching is enabled for all agents. When absent (None), context caching is disabled. 也就是说缓存配置的作用域是整个 App 内的所有 LLM Agent将配置挂在 App 上才能保证缓存前缀系统指令 工具定义在多次调用间稳定复用。若绕过 App 直接传递独立 Agent会话管理与缓存生命周期将无法正确关联——这也是文档故障排查章节强调runner.app_name的原因。三个核心参数ContextCacheConfig的完整字段定义见 src/google/adk/agents/context_cache_config.py关键参数如下参数示例取值默认值约束作用cache_intervals3101 ~ 100同一缓存被复用的最大调用次数超过后刷新缓存ttl_seconds600180030 分钟 0缓存的存活时间秒示例设为 10 分钟以适配研究会话min_tokens40960 0启用缓存所需的前置请求 token 下限create_http_optionstypes.HttpOptions(timeout10000)None—传给 GenAI 客户端的CachedContent.create()超时选项需要特别注意min_tokens的语义见源码字段描述它基于上一轮请求的实际 prompt token 数进行门槛判断而非对当前请求的估算并且缓存最早在会话的第二轮开始且可缓存前缀需达到模型特定下限。这意味着单轮会话或过短的会话永远不会被缓存。示例把min_tokens设为 4096与文档中确保满足缓存阈值的故障排查建议一致。此外从缓存管理器的实现src/google/adk/models/gemini_context_cache_manager.py可以看到模型级的最小缓存 token 门槛是硬编码的Gemini 2.5系列_GEMINI_2_5_MIN_CACHE_TOKENS 2048Gemini 3系列_GEMINI_3_MIN_CACHE_TOKENS 4096即即便你设置min_tokens0模型自身的最小阈值依然生效。准备测试输入通用问答与工具调用两类 Prompt实验使用 utils.py 中的get_test_prompts()提供 10 条标准化 Prompt设计上刻意分为两组Prompt 1–5不触发函数调用通用问题如Hello, what can you do for me?、What is artificial intelligence and how does it work in modern applications?等作为基线查询Prompt 6–10触发函数调用带显式参数的精确工具请求例如Use benchmark_performance with system_nameE-commerce Platform, metrics[latency, throughput], durationstandard, load_profilerealistic.Call analyze_data_patterns with datapremium customer engagement and conversion events for the last 30 days, analysis_typetrends.Run research_literature for topicfintech user experience and security, sources[industry, academic], depthcomprehensive.Execute design_scalability_architecture with current_architecturemonolith, expected_growth{user_growth_multiplier: 10x}, scalability_requirements{availability_target: 99.9%}, technology_preferences[kubernetes].Perform analyze_security_vulnerabilities on system_components[web_frontend, api_endpoints], security_scopecomprehensive, compliance_frameworks[SOC2].两类 Prompt 的对照意义在于纯文本 Agent 的缓存收益主要在延迟而工具密集型 Agent 可能产生轻微缓存建立开销但成本收益依然显著——这与文档Expected Results章节的描述相互印证。运行缓存对比实验命令行用法run_cache_experiments.py自动化执行 Prompt 集合并对比不同模型/缓存模式的性能。完整参数如下对应 run_cache_experiments.py 中的 argparse 定义# 测试任意 Gemini 模型——脚本自动判断实验类型 python run_cache_experiments.py model_name --output results.json # 示例Gemini 2.5 Flash python run_cache_experiments.py gemini-2.5-flash --output gemini_2_5_results.json # 多次迭代取平均结果 python run_cache_experiments.py gemini-2.5-flash --repeat 3 --output averaged_results.json参数默认值说明model位置参数必填被测模型名如gemini-2.5-flash--outputcache_{model}_results.json结果 JSON 输出文件名--repeat1实验重复次数用于取平均含标准差统计--cached-firstFalse反转顺序先跑缓存组再跑非缓存组默认非缓存组先跑--request-delay2.0两次 API 请求之间的间隔秒数避免过载--log-levelINFO日志级别DEBUG/INFO/WARNING/ERROR脚本内部做了什么从源码可以还原实验的完整流程克隆 Agent 变体create_agent_variant()run_cache_experiments.py通过copy.deepcopy复制根 Agent替换模型名并向指令前置注入当前时间戳——这是为了避免多次运行间隐式缓存复用导致的结果污染。随后分别构造带ContextCacheConfig的 App缓存组与context_cache_configNone的 App非缓存组。隔离会话为两个变体分别创建独立会话session_cached与session_uncached互不干扰对应文档故障排查中避免会话交叉污染的做法。批量执行run_experiment_batch()utils.py逐条运行 10 个 Prompt通过runner.run_async()收集每轮的usage_metadata统计prompt_token_count与cached_content_token_count并计算缓存命中率cached/prompt、缓存利用率发生命中的请求占比、平均每请求缓存 token 数。深度分析analyze_cache_performance_from_sessions()调用 ADK 内置的CachePerformanceAnalyzer见 src/google/adk/utils/cache_performance_analyzer.py基于会话事件历史中的cache_metadata分析命中率、缓存刷新次数、平均复用轮次等更细粒度的指标。重复与统计--repeat 1时通过calculate_averaged_results()输出均值与标准差_calculate_std并保留每次运行的完整明细。结果落盘以 JSON 格式保存完整结果包含cache_analysis.cached_experiment与cache_analysis.uncached_experiment两组指标。直接运行或调试 Agent除了实验脚本还可以用 ADK CLI 直接运行或调试该 Agent对应 README 的命令# 直接运行 Agent adk run contributing/samples/context_management/cache_analysis # 启动 Web 界面进行调试 adk web contributing/samples/context_management注意agent.py末尾同时导出了app cache_analysis_app与root_agent cache_analysis_agent见 agent.py注释明确指出Export as app since its an App, not an Agent——即该文件对外的主入口是 App 对象root_agent仅为向后兼容保留。使用 CLI 调试时务必让 Runner 以App对象初始化并用runner.app_name创建会话否则可能出现文档故障排查章节提到的 Session not found 错误。实验类型脚本如何自动适配模型get_experiment_labels()run_cache_experiments.py根据模型名中是否包含2.5来决定实验类型含 2.5 的模型如gemini-2.5-flashGemini 2.5 系列内置 Google 隐式缓存因此对比的是显式缓存 vs 隐式缓存Explicit CachingADK 显式缓存 Google 隐式缓存同时生效Implicit Only仅依赖 Google 内置隐式缓存测量目标显式缓存相对内置隐式缓存的增量收益延迟与命中率差异。其他模型如gemini-2.0-flashGemini 2.0 无内置隐式缓存因此对比的是显式缓存 vs 完全无缓存Explicit Caching启用 ADK 显式缓存Uncachedcontext_cache_configNone完全禁用缓存测量目标缓存的基线性能与成本收益。这一设计让脚本对任意 Gemini 模型开箱即用无需修改代码。预期结果与指标解读文档给出以下经验性结论注意这些是示例作者给出的参考区间实际数值取决于模型、Prompt 与网络环境应以本地实验输出为准性能提升纯文本 Agent 在开启缓存后通常观察到30–70% 的延迟下降工具密集型 Agent 可能因首次建立缓存产生少量额外开销但整体成本收益仍然显著。成本节省被缓存内容的输入 token 成本最多可降低75%即仅支付正常输入成本的 25%。Token 指标缓存命中成功的关键信号是cached_content_token_count非零。在实验结果 JSON 中你可以重点关注以下指标均由CachePerformanceAnalyzer产出指标含义cache_hit_ratio_percent缓存命中 token 数 / 总 prompt token 数cache_utilization_ratio_percent发生缓存命中的请求数 / 总请求数avg_cached_tokens_per_request每个请求平均命中的缓存 token 数cache_refreshes/avg_invocations_used缓存刷新次数 / 平均复用轮次与cache_intervals相关故障排查cached_content_token_count 恒为 0如果实验全程命中数为 0按以下顺序排查核对模型名确保与官方命名完全一致如gemini-2.5-flash名称不匹配会导致缓存配置无法正确下发。确认达到 min_tokens 阈值示例设置 4096 token 门槛README 与 agent.py 均为此值同时牢记模型侧硬门槛——Gemini 2.5 为 2048、Gemini 3 为 4096gemini_context_cache_manager.py。Prompt 系统指令总 token 不足时不会触发缓存。确认使用 App 级配置ContextCacheConfig必须挂在App上而不是把独立 Agent 直接传给 Runner配置缺失None即等价于禁用缓存见 context_cache_config.py 的类文档。会话轮次缓存最早在会话第二轮生效min_tokens基于上一轮实际 token 数判断单轮会话永远不会有命中。Session not found 错误确认使用runner.app_name创建会话实验脚本中的写法是session_service.create_session(app_namerunner.app_name, user_idUSER_ID)确保用InMemoryRunner(appapp, app_nameNone)以App对象正确初始化 Runner见 run_cache_experiments.py并让缓存组与非缓存组使用彼此独立的会话避免数据串扰。底层机制补充显式缓存的生命周期管理为便于理解实验数字这里简要说明 ADK 显式缓存的工作方式。GeminiContextCacheManagersrc/google/adk/models/gemini_context_cache_manager.py负责缓存生命周期的核心逻辑基于请求内容哈希判断既有缓存是否可复用有效则直接设置cached_content并从请求中剥离已缓存内容缓存创建时使用ttl_string如600s设置存活时间超过cache_intervals次复用或 TTL 过期后触发缓存刷新每个请求的缓存元数据CacheMetadata会写入会话事件流这正是CachePerformanceAnalyzer事后分析的依据——它遍历session.events中带cache_metadata的事件按event.author agent_name过滤出指定 Agent 的缓存历史cache_performance_analyzer.py。理解了这条请求 → 缓存命中/刷新 → 事件落盘 → 分析器统计的链路实验脚本输出的每个百分比就都有了明确的来源。小结cache_analysis示例为 ADK 用户提供了一条完整的缓存实证路径在 App 级用ContextCacheConfig开启显式缓存用巨型系统指令与 7 工具 Agent 构造高价值缓存前缀再通过run_cache_experiments.py在显式 vs 隐式Gemini 2.5或显式 vs 无缓存Gemini 2.0两种模式下量化延迟与成本收益。将本文介绍的参数语义、脚本流程与故障排查清单结合起来你可以快速把同一套方法论复用到自己的 Agent 项目中用cached_content_token_count与命中率指标驱动缓存调优决策。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考