page-agent提示词缓存优化指南：cachedTokens如何帮企业省下API账单

page-agent提示词缓存优化指南：cachedTokens如何帮企业省下API账单

【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent

page-agent是一个纯 JavaScript 的页面内 GUI Agent，让 AI 用自然语言直接控制网页界面——点按钮、填表单、读页面，全部在浏览器里完成，无需浏览器扩展或截图识别。它天生适合做企业 SaaS 里的 AI 副驾驶，但每执行一步任务，就会把系统提示词和完整对话历史重新发给大模型。任务步骤越多、系统提示词越长，API 账单就越贵。好消息是：page-agent 已内置cachedTokens缓存命中统计，再配合各模型供应商的**提示词缓存（Prompt Caching）**能力，企业可以把重复计费的部分大幅打折，省下可观的 LLM 成本。

提示词缓存为什么能省钱？

先理解账单是怎么"烧"出来的：

Agent 类应用的特点是：多轮、长上下文、前缀稳定。前几十步里反复发送的同一段系统提示词和历史消息，正是缓存的"黄金命中区"。主流供应商对缓存命中的输入 Token 通常按1/10 甚至更低的价格计费——也就是说，一次长任务的账单可能直接砍掉一大块。

cachedTokens 从哪来：page-agent 内置的缓存命中率统计

page-agent 不需要你手动解析原始响应。它的 OpenAI 兼容客户端会自动从接口返回的usage.prompt_tokens_details.cached_tokens中提取缓存命中量，作为cachedTokens字段透出：

• 字段定义：packages/llms/src/types.ts 中标注为Prompt cache hits
• 提取逻辑：packages/llms/src/OpenAIClient.ts
• 事件上报：每个 Agent 步骤的usage都会带上该字段，见 packages/core/src/types.ts

这意味着你的监控面板里可以做一个简单的健康指标：

缓存命中率 = cachedTokens ÷ promptTokens

命中率长期低于 50%，说明前缀不稳定（比如系统提示词里塞了时间戳、随机 ID），缓存几乎白开；命中率能稳定在 80% 以上，才是省钱的正确姿势。

最快配置方法：用 transformRequestBody 开启主动缓存

不同供应商的缓存开关不一样，page-agent 提供transformRequestBody钩子，让你在请求发出去之前注入缓存标记。官方文档在 packages/website/src/pages/docs/features/models/page.tsx，下面是最常用的两家：

Claude：一行请求体级 cache_control

Claude 支持全局自动缓存，只需在请求体顶层加一个标记：

transformRequestBody: (requestBody) => ({ ...requestBody, cache_control: { type: 'ephemeral' }, }),

阿里云百炼 Qwen：给 system 消息打标

Qwen 系模型需要把cache_control挂在 system 消息的文本块上：

transformRequestBody: (requestBody) => { const [systemMessage, ...rest] = requestBody.messages return { ...requestBody, messages: [ { ...systemMessage, content: [{ type: 'text', text: systemMessage.content, cache_control: { type: 'ephemeral' } }] }, ...rest, ], } },

💡 两个示例都来自官方文档的完整实现，直接抄即可。更详细的供应商差异，可看 transformRequestBody 配置说明。

省多少钱？一个粗略的账单估算

以一个典型场景算账：Agent 每步输入约 8000 tokens，一次任务 15 步，输入 Token 单价 $3/百万：

单任务省约 70%。按企业每天 1 万次任务、长提示词场景，月度节省可达数万美元级——这还没算缓存命中带来的响应延迟下降（命中部分无需重新预计算）。

实操清单：5 步让账单降下来

1. 确认你的模型支持缓存：OpenAI、Claude、通义千问等均支持，本地模型（Ollama 等）通常不支持
2. 按供应商注入缓存标记：用transformRequestBody配置（见上文）
3. 盯住 cachedTokens：把每步的cachedTokens / promptTokens画成监控曲线
4. 保持前缀稳定：系统提示词里别放时间戳、随机值，把易变内容放到对话后半段
5. 用 rawResponse 抽查：packages/core/src/types.ts 的调试字段可保留原始响应，验证cached_tokens是否真的在增长

相关文件索引

• 缓存字段类型定义：packages/llms/src/types.ts
• OpenAI 客户端缓存提取：packages/llms/src/OpenAIClient.ts
• 步骤事件 usage 结构：packages/core/src/types.ts
• 主动缓存官方文档：packages/website/src/pages/docs/features/models/page.tsx

一句话总结：page-agent 把cachedTokens送进了每一步的执行数据里，企业要做的只是打开供应商的缓存开关、盯住命中率曲线——API 账单自然会给出正反馈。

【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent