省钱又提速：OmniBot Prompt Cache提示词缓存命中机制深度剖析

省钱又提速：OmniBot Prompt Cache提示词缓存命中机制深度剖析

【免费下载链接】OmniBotYour on-phone / mobile AI Agent / Claw, capable of operating terminals and performing a wide range of tasks in the Android world || 你的手机 AI 代理，她可以操作终端，也可以完成 Android 世界的广泛任务项目地址: https://gitcode.com/gh_mirrors/op/OmniBot

OmniBot 是一款跑在安卓手机上的 AI Agent，既能操作终端，也能完成 Android 世界的广泛任务。它内置的 Prompt Cache（提示词缓存）命中机制，让每一轮对话里重复的上下文"免费复用"，在省钱的同时显著提升首响应速度。本文带你搞懂它是怎么工作的。

为什么 Agent 每发一条消息都要"重新读全文"？

和普通聊天不同，OmniBot 这类 Agent 每轮请求都会携带很长的前缀：系统提示词、工具定义（一次可能多达 58 个）、历史消息、记忆与技能索引等，单条请求轻松突破 10 万字节。如果服务商对重复前缀不做缓存，每轮都要全量计费、全量推理，既贵又慢。

而只要请求前缀与上一次保持一致，服务商就能返回cached_tokens（缓存命中 token 数），这部分通常大幅降价甚至免费，响应也更快。OmniBot 的 Prompt Cache 机制，就是为了让这个命中"尽可能稳定发生"。

命中机制拆解：三步设计

第 1 步：为每段对话生成稳定缓存键

核心实现是 PromptCacheKeyStore.kt，它按"安装范围 + 会话 ID"拼出一个匿名稳定键：

omnibot:v1:<20位随机十六进制安装范围>:conversation:<conversationId>

• 稳定：同一会话内，键在整段生命周期不变，缓存才能持续命中；
• 隔离：20 位随机安装范围由 UUID 派生并持久化，避免两台手机上恰好都叫"会话 1"的用户被路由到同一个缓存命名空间；
• 隐私友好：键里不含账号、设备、提示词或 API 密钥等任何敏感数据，且长度被控制在 64 字符以内，兼容网关的标识符长度限制。

第 2 步：每次请求自动携带缓存键

用户消息进入执行器时，OmniAgentExecutor.kt 的processUserMessage会调用PromptCacheKeyStore.forConversation生成键，并作为 OpenAI 扩展字段prompt_cache_key随请求发出。响应中的cached_tokens则用于用量归属与统计。

第 3 步：兼容性保护，只发给"认"这个字段的接口

并非所有 Chat Completions 网关都接受prompt_cache_key——曾有服务商直接返回400: 未知请求字段。OmniBot 的策略是：

• 官方 OpenAI 接口：默认保留该字段；
• 其他第三方 / 本地接口：发送前自动移除顶层prompt_cache_key，避免请求整体失败；
• 本地仍保留身份标识用于用量归属，不改消息、不改密钥、不加重试。

相关修复记录见 prompt-cache-key-compatibility-2026-09-06.md，请求出口的过滤逻辑位于 HttpController.kt。

实测数据：命中率达到 99.8%

开发团队在同一台手机、同一接口、同一模型下，用固定约 13k token 前缀做了顺序对照实验（完整记录见 prompt-cache-hit-verification-2026-09-07.md）：

结论很清晰：携带稳定缓存键时，前缀几乎全部命中；缺省时该接口不命中。而带键首次命中时，响应头耗时从 8.4s 降到 1.9s——提速效果肉眼可见。

⚠️ 诚实的工程注记：高命中并不意味着"必然快"。同一轮测试中，带键命中 99.8% 仍出现过 10.9s 等待；另一台设备在 cached 10368/10447 时仍等待约 16s。缓存修复解决的是"前缀重算"的成本，网关排队、模型推理等其他上游延迟需要单独排查（见 chat-start-latency-2026-09-07.md）。

用户如何用好缓存？

1. 保持会话连续：同一会话连续追问，前缀天然稳定，命中最稳；
2. 避免频繁改系统提示与工具集：中途修改会"打断"前缀，缓存前缀作废、重新全量计费；
3. 技能按需展开：OmniBot 采用渐进披露设计，技能正文通过工具结果按需加载，而不是塞进头部消息——这正是为了不破坏整段会话前缀（实现见 OmniAgentExecutor.kt 注释说明）；
4. 模型配置保持稳定：更换模型或接口会进入新的缓存命名空间，首轮必然未命中。

OmniBot 生成 AI 图片等创作类任务同样受益于稳定的长前缀，缓存命中让连续创作更省更顺：

关键代码与文档索引

一句话总结：OmniBot 用"匿名稳定键 + 请求级字段 + 兼容性过滤"三层设计，把提示词缓存命中率稳定在 99% 以上，让手机上的 AI Agent 既省钱又更快——而它对"命中不等于必然低延迟"的坦诚测量，也值得每个做 Agent 的同学参考。

【免费下载链接】OmniBotYour on-phone / mobile AI Agent / Claw, capable of operating terminals and performing a wide range of tasks in the Android world || 你的手机 AI 代理，她可以操作终端，也可以完成 Android 世界的广泛任务项目地址: https://gitcode.com/gh_mirrors/op/OmniBot