Agent 网关

缓存

以 Markdown 格式查看

Alephant AI Gateway 可以复用符合条件的模型响应，让重复请求避免不必要的上游调用。这可以降低稳定、可重复工作负载的延迟和 provider 成本。

缓存控制项是可选的 Gateway 请求头。Gateway 在处理请求时使用这些请求头，不会把它们发送给上游模型 provider。应用仍需自行判断响应是否适合安全复用。

缓存模式

Alephant 使用“缓存”描述多种不同机制。它们的行为和生命周期并不相同。

模式作用
精确匹配响应缓存当请求产生相同缓存身份时复用响应。
语义缓存当 workspace 已配置语义缓存和 embedding 支持时，查找相似度达到要求的请求。
Provider 原生 prompt caching在上游 provider 内复用 prompt token。该行为通过 provider 用量和价格体现，不是 Alephant Gateway 响应缓存命中。
内部运行状态支持路由、策略上下文、幂等、session 和 Gateway 保护，不是可复用的模型响应。

何时使用缓存

适合缓存的请求通常具有稳定输入，并且响应可以在多次请求之间保持有效：

  • 基于低频变更内容的知识问答
  • 重复的分类、提取或摘要
  • 使用可重复变量的固定 prompt 模板
  • 对低延迟有要求的读密集型工作负载

以下情况应谨慎使用缓存：

  • 答案必须反映实时数据
  • 请求包含敏感信息或用户特有信息
  • 请求可能调用工具或产生外部副作用
  • 授权或业务状态可能在两次请求之间发生变化
  • 应用依赖刻意生成的随机输出

Gateway 无法判断每一种业务特有的复用边界。当响应必须基于当前请求重新生成时，请关闭缓存读取和写入。

配置响应缓存

核心缓存请求头

请求头用途
Alephant-Cache-Enabled设为 true 时启用缓存行为。
Alephant-Cache-Read设为 true 时允许从缓存读取。
Alephant-Cache-Save设为 true 时允许保存符合条件的响应。
Alephant-Cache-Bucket-Max-Size可选的 bucket 数量，有效范围为 1-20。
Alephant-Cache-Seed参与缓存身份派生的可选 seed，可用于隔离明确的应用上下文。
Alephant-Cache-Control可选缓存控制，例如 max-age 或 s-maxage。

读取与保存行为

当应用需要可预期的行为时，请显式设置读取和保存控制项。

EnabledReadSave行为
truetruetrue先尝试读取缓存；符合条件的未命中响应可以保存。
truetruefalse读取已有响应，但不保存未命中响应。
truefalsetrue跳过缓存查找，并允许写入符合条件的响应。
未启用任意任意不使用其他控制项激活响应缓存。

Workspace 和 Gateway 配置可能影响缓存可用性。当应用依赖特定读写行为时，不应依赖未公开的默认值。

语义缓存请求头

语义缓存属于高级控制项。仅当 workspace 已配置语义缓存和 embedding 服务时使用。

请求头用途
Alephant-Embeddings-Model语义缓存查找使用的 embedding model。
Alephant-Embeddings-KeyGateway 执行查找时使用的 embedding 凭据。
Alephant-Cache-Semantic-Threshold语义匹配的相似度阈值。
Alephant-Cache-Ttl语义缓存使用的 TTL。

请把 embedding 凭据视为 secret，不要提交到源码仓库，也不要写入应用日志。

示例

以下请求显式启用缓存读取和写入，并把缓存响应的最长有效时间设置为一小时：

$curl "$ALEPHANT_GATEWAY_BASE_URL/v1/chat/completions" \
>  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>  -H "Content-Type: application/json" \
>  -H "Alephant-Cache-Enabled: true" \
>  -H "Alephant-Cache-Read: true" \
>  -H "Alephant-Cache-Save: true" \
>  -H "Alephant-Cache-Control: max-age=3600" \
>  -d '{
>    "model": "openai/gpt-4o-mini",
>    "messages": [
>      {
>        "role": "user",
>        "content": "Summarize the refund policy in three bullets."
>      }
>    ]
>  }'

再次发送相同的稳定输入，然后比较缓存响应元数据和 Logs 中的请求。max-age=3600 是本示例显式设置的值，并不表示 Gateway 存在某个隐含的默认生命周期。

请求生命周期

启用缓存的请求遵循以下逻辑流程：

  1. 验证 Virtual Key，并解析 workspace、model 和请求上下文。
  2. 根据适用的请求内容和缓存控制项派生缓存身份。
  3. 如果允许读取，则尝试精确匹配查找或已配置的语义查找。
  4. 查找成功时返回可复用响应和缓存元数据。
  5. 未命中时，把请求发送给选定的上游 provider。
  6. 如果允许保存且响应符合条件，则将其写入响应缓存。
  7. 继续在已配置的 Logs、Analytics 和成本归因链路中记录请求。

以上是逻辑阶段，不代表对内部线程顺序、Redis 操作或强一致性的承诺。

验证缓存命中

启用缓存的响应可能包含：

响应头用途
alephant-cache请求的缓存状态。
alephant-cache-bucket-idx返回缓存条目的 bucket 索引。
alephant-cache-latency缓存查找延迟。
alephant-idAlephant 请求标识符，对缓存返回的响应尤其有用。

验证方法：

  1. 启用缓存读取和写入，对同一稳定请求发送两次。
  2. 比较 alephant-cache、缓存延迟和 Alephant 请求标识符。
  3. 打开 Logs，检查缓存状态、provider、token、成本和请求上下文。
  4. 如果第二次请求仍未命中，比较 model、messages、参数、seed、TTL 和缓存控制项。

alephant-cache 报告的具体值可能取决于已部署的 Gateway 版本。请检查实际响应，不要依赖未公开的枚举。

故障排查

现象检查项
看似相同的 prompt 仍未命中比较完整请求、model、参数、seed、TTL、workspace 和缓存控制项。
关闭保存后请求仍然命中Alephant-Cache-Save: false 不会阻止 Alephant-Cache-Read: true 读取已有条目。
未执行语义查找确认 workspace、embedding model、embedding 凭据和相似度阈值均已配置。
响应可能跨越业务边界关闭读取和保存，或者使用显式 seed 隔离边界清晰的应用上下文。
不同部署的缓存行为不同比较 Gateway 版本、workspace 配置和底层缓存服务。

内部缓存与状态

Gateway 还会保存短期或可复用的运行状态。这些机制支持请求处理，但不同于模型响应缓存。

类别内部状态用户可感知的作用
请求与策略上下文Prompt Cache、PII Cache 开关、VK Enrichment Cache解析 prompt 模板，并使用 workspace 和 department 元数据补充策略或日志上下文。
模型与语义能力发现Model Catalog Cache、Embedding Base URL Cache加速模型支持情况查找，并选择已配置的 embedding 服务。
异步任务一致性Image Task Affinity、Image Task Cost Claim复用图片任务创建时选定的 provider 路径，并防止重复成本认领。
Agent 与工具 sessionMCP Session Cache、MCP Session Lock、Agent Step State复用 MCP session、协调初始化，并检测重复或冲突 step。
Endpoint 与区域路由x402 Endpoint Snapshot、x402 Signing Secret、Regional Endpoint解析 endpoint 配置、受保护的签名材料和已确定的区域路由。
Gateway 保护Workspace Concurrency、Client IP Rate Limit、Gateway In-flight Limit执行 workspace、客户端 IP 和 Gateway 全局流量保护。

这些状态不共享统一的 TTL 或失效规则。未命中可能触发数据库查找或重新初始化，不一定表示故障。并发、限流、锁和幂等状态都不代表可复用的模型响应。其 key、value 和生命周期属于部署实现，而不是公开 API 合同。

缓存、日志与计费

Logs 和计费链路还会维护其他缓存与聚合数据，用于模型价格、自定义价格、workspace 或 department 消费、Virtual Key 消费、token 和请求计数、Agent 成本、用量限制决策、鉴权以及通用查询结果。

排查成本时，应区分以下事件：

  • Provider 原生 cached token 事件通过 provider 用量和价格体现。
  • Gateway 响应缓存命中会在再次生成上游响应之前复用已有响应。
  • 内部价格缓存命中只会加速成本计算。
  • 限流与消费聚合服务于执行和报告，不是响应缓存。

缓存命中仍应具有可观测元数据。请以实际 Logs 和 Analytics 记录为准，判断请求的 provider token、Gateway 费用、缓存节省和归因成本。

安全与运维建议

  • 不要缓存授权决策、一次性结果，或不得跨请求复用的敏感响应。
  • 不要把 secret、个人数据或受监管标识符放入 cache seed 或自定义可观测 metadata。
  • 应用必须使用已公开的 Gateway 请求头和响应头，不应依赖内部 Redis key。
  • Private deployment 应把 Redis 或 Valkey 作为受保护的基础设施：限制网络访问、要求身份验证、在支持时加密传输，并避免在日志中暴露运行值。
  • 修改缓存配置后，应先使用非敏感测试请求验证行为，再扩大启用范围。

相关页面