如何大幅降低LLM调用成本commerce-agents的Prompt缓存字节级稳定优化实践与验证方法【免费下载链接】commerce-agentsReference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.项目地址: https://gitcode.com/gh_mirrors/co/commerce-agentscommerce-agents是基于 Claude 构建购物 AgentShopping Agent与商家 AgentMerchant Agent的开源参考蓝图内置零售、旅行、电信、娱乐四个可运行示例。除了功能设计它最值得初学者借鉴的是一套Prompt 缓存字节级稳定优化实践通过把请求前缀稳定到一个字节都不变让第二轮、第三轮对话大量命中缓存读取cache read从而显著降低 LLM 调用成本、缩短响应延迟。本文带你理解它的核心思路、关键实现与验证方法。为什么字节级稳定是省钱的关键Claude 的 Prompt 缓存规则很直接请求的前缀只要有一个字节变化缓存就失效整段前缀要重新处理并重新计费。一次请求的缓存前缀按顺序是tools工具列表→system系统提示→ 消息历史缓存断点cache breakpoint标记了下一轮可以读回来的范围。commerce-agents 的做法可以概括为一句话所有每请求都会变的东西购物车、当前页面、时钟、记忆事实全部隔离到一个独立的动态上下文块里绝不让它污染稳定前缀。状态没变的对话轮次整段历史都走缓存读取状态变了比如购物车写入、换了页面也最多只多读一次。三个缓存断点请求前缀的路标参考实现统一使用 commerce-common/commerce_common/prompt_assembly.py 放置三个断点最后一个工具with_tool_cache_control(tools)只给工具列表的最后一项打上缓存标记工具数组整体被纳入缓存范围。静态系统文本build_system_blocks(static, context)把静态身份/规则文本作为带断点的第一个 system 块每请求的上下文放在它后面的第二个、不带断点的system 块里。最新一条已持久化消息build_request_messages(messages, rolling_breakpointTrue)只给当次发出的请求打滚动标记——下一轮调用时之前各轮包括很长的搜索结果都变成缓存读取。标记只存在于请求副本上绝不写回持久化历史。这个设计在 plugins/commerce-builder/skills/commerce-prompt-caching/SKILL.md 中有完整说明是该项目的缓存稳定装配参考规范。静态与动态分离哪些字段是提示词字节以购物 Agent 为例shopping-agent/core/shopping_agent/prompt.py 做了清晰切分部分内容稳定性build_static_system身份、工作规则、信任与边界规则、技能索引只依赖部署配置整个部署生命周期内字节相同build_dynamic_context用户偏好、记忆事实、购物车、当前页面、账户上下文、时间每轮渲染一次包在数据围栏内放在断点之后两个细节特别抠时钟只精确到小时context_clock把分钟、秒、微秒清零。如果渲染到分钟几乎每一轮都会因为时间变化而改变动态块导致反复重读整段对话——一小时之内字节不变缓存才稳得住。工具列表每次构建出相同的字节内置工具固定顺序、技能枚举排序、扩展按给定顺序追加全部注册工具随每次请求发出由执行器在调用到达时决定能否服务。每次请求临时决定带哪些工具正是最常见的缓存杀手之一。配置里标了(prompt)的字段如brand_name、brand_voice、各角色的enable_*开关会被渲染进静态文本或工具列表改动它们等于重新部署而门槛词表、内存设置、延迟旋钮eager_tool_dispatch、rolling_conversation_cache等不是提示词字节随意改动不影响缓存。哪些习惯会击穿缓存命中项目把踩坑清单写得非常直白适合当自检表用把每请求内容用户名、购物车数量、页码、时钟分钟、请求 ID塞进静态块或工具列表——上下文块可以放前四种请求 ID 则哪里都不该放用 set/dict 不排序地迭代进提示词或 schema顺序随机 字节随机在对话轮内重建静态文本或工具列表而不是在构造函数里一次构建两个运行时都在__init__中构建_static_system与_tools之后只渲染动态块把滚动标记持久化进会话历史导致每轮多一个标记前缀短于模型的最小可缓存长度写了也读不回在运行中的部署上开关(prompt)字段或技能——每个都意味着重新部署。另外有两个有意跳过标记的场景单条消息的首次调用一次性会话只付写、无读以及tool_choice非auto的强制轮tool_choice是消息区间的键强制轮写入的条目后续 auto 轮读不到但系统/工具区仍会命中。验证方法不靠猜靠测试和计数器单元测试双保险。tests/test_role_registries.py 对每个角色构建两遍提示词和工具并逐字节比较检查缓存标记位置并断言所有非提示词设置改变后字节不变commerce-common/tests/test_prompt_assembly.py 覆盖块构建、上下文时钟同一小时内10:02与10:58渲染相同字节、滚动标记的前滚与清除、以及两个跳过场景tests/test_turn_loop.py 把两个角色的对话循环钉死在同一组块、标记与干净历史上。每个部署应带同样三项检查。线上看三个数。每轮turn_complete事件携带usage由 commerce-common/commerce_common/turn.py 的usage_totals汇总本次各次调用的四项计数与elapsed_ms每次模型调用也会通过log_model_call记一行含同样计数器的日志。值得按配置版本持续跟踪的指标cache reads 占输入 token 的比例核心省钱指标elapsed_ms与每轮模型调用次数第二轮对话的 cache read 为零 前缀变了这是最直接的故障信号部署环境实测。跑一次三轮对话读第二、三轮的cache_read_input_tokensscripts/smoke_chat.py 会直接打印 cache read 计数。任何重写请求的代理或重试层只会在这里暴露别无他处。快速上手跑起来亲眼看到缓存生效环境要求 Python 3.11 与 Node 22。仓库地址https://gitcode.com/gh_mirrors/co/commerce-agentsgit clone https://gitcode.com/gh_mirrors/co/commerce-agents cd commerce-agents pip install -r requirements.txt cp .env.example .env # 填入 ANTHROPIC_API_KEY (cd examples npm ci) python scripts/run_demo.py retail # API :8000 商城前端 :3000启动后与购物助手连续对话两轮以上观察 scripts/smoke_chat.py 或运行日志中的cache_read计数第二轮开始明显上涨就说明静态/动态分离与滚动断点在工作。完整目录结构、部署到其他平台Vertex AI、Bedrock 等见 docs/deployment.md 与 README.md。小结commerce-agents 的 Prompt 缓存实践可以浓缩为四条经验稳定前缀 动态尾巴工具与静态系统文本字节级恒定每请求内容全部进第二个 system 块三个断点覆盖全前缀最后一个工具、静态文本、滚动到最新持久化消息警惕隐形字节不排序的集合、分钟级时钟、请求 ID、运行中改配置都是击穿点验证先行两次构建逐字节比较的测试 cache read 比例监控让省没省钱一目了然。这套模式不依赖特定业务任何多轮对话型 Agent 都可以照搬——把前缀做到字节级稳定成本与延迟的下降会自然发生。【免费下载链接】commerce-agentsReference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.项目地址: https://gitcode.com/gh_mirrors/co/commerce-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考