生产环境中的 AI 系统经常收到语义相近、但字节并不完全一致的请求。一位用户问：“如何重置密码？”另一位用户可能问：“忘记密码后应该怎样修改？”即使这两个问题的意图几乎相同，客服助手也可能把它们都发送给同一个模型，并携带相同的策略上下文。
精确匹配缓存无法将这两个提示词关联起来。它看到的是不同的请求体，因此会把两次请求都发送到上游。语义 AI 缓存则可以比较它们的含义，并在提示词足够相似时复用先前的响应。
更广泛的复用可以降低模型延迟和 Token 消耗，但也会改变风险模型。精确匹配回答的是一个严格限定的问题：“我以前是否见过这个规范化请求？”语义匹配需要回答一个更难的问题：“这个请求是否足够接近，以至于同一个回答仍然正确、具备时效性、安全且符合授权要求？”
API7 网关 3.10.3 于 2026 年 7 月 14 日发布，使这一问题具备了可操作性。该版本为 AI Cache 插件增加基于 RediSearch 的语义匹配能力，可以缓存和重放完整的服务器发送事件（SSE）响应，并新增以缓存为中心的 Prometheus 指标。新版本还强化了内容审核行为，并对语义嵌入凭证进行存储时加密。
如果需要了解集群级升级准备，包括内存容量、代理信任、身份控制、数据库行为，以及控制面到数据面的升级顺序，请先阅读 API7 网关 3.10.3：让企业升级更安全。本文承接升级规划完成后的阶段，重点讨论如何安全运营语义 AI 缓存。
这次更新带来的不只是覆盖范围更广的缓存，而是一套网关层控制闭环：决定何时可以复用 AI 响应、验证复用决策是否生效，并在出现问题时限制影响范围。
1flowchart LR
2 request[Chat Completions 请求] --> exact{精确缓存是否命中？}
3 exact -- 是 --> exactHit[返回缓存响应]
4 exact -- 否 --> embed[对配置的提示词窗口生成嵌入]
5 embed --> search[搜索 RediSearch 向量索引]
6 search --> similar{相似度是否满足策略？}
7 similar -- 是 --> semanticHit[返回语义缓存响应]
8 similar -- 否 --> model[调用选定的 LLM]
9 model --> client[流式或普通返回响应]
10 model --> complete[捕获完整且符合要求的响应]
11 complete --> store[存储以供后续请求使用]
12 exactHit --> client
13 semanticHit --> client精确匹配会漏掉有价值的重复请求
API7 网关在 3.10.2 版本中引入了 LLM 响应的精确匹配缓存。网关识别请求格式，把规范化请求与选定的 AI 实例配置组合起来，应用配置的缓存键范围，然后把符合条件的成功响应存入 Redis。后续完全相同的请求可以直接获得缓存响应，无须再次调用模型。
精确缓存仍然是最安全的第一层，因为它的复用规则很容易解释。根据 AI Cache 文档，它适用于 Chat Completions、Anthropic Messages、Responses API、嵌入、Bedrock Converse 和其他 JSON 透传流量等请求格式。它特别适合重复分类提示词、固定知识问答或能够生成稳定请求体的内部自动化等确定性工作负载。
真实用户流量往往没那么规整。标点、语序、礼貌用语和细微的上下文差异都会形成不同的载荷。应用中间件也可能加入一些不断变化、却不会改变用户意图的字段。因此，精确匹配只能覆盖生产环境中一部分可复用请求。
语义缓存需要显式启用。layers 的默认值是 ["exact"]；只有将 semantic 加入 layers 并配置 semantic，L2 路径才会生效。启用后，语义缓存会在精确匹配未命中时增加第二层检查。对于受支持的 Chat Completions 请求，网关会为配置的提示词窗口生成嵌入，并在 RediSearch 向量索引中查找相似度达到配置阈值的缓存提示词。语义命中后，网关返回已存储的响应，并通过 X-AI-Cache-Similarity 报告相似度，让调用方能够看到这次更广泛的复用决策。
这种执行顺序很重要。精确匹配仍然是成本较低且结果精确的第一道检查。只有精确检查未命中时，网关才会执行嵌入和向量搜索。如果两层缓存都找不到符合要求的响应，请求会继续发送到选定的 LLM，符合条件的响应则可以写入缓存。
AI Cache 文档也明确说明了当前的 L2 边界：语义匹配支持纯文本 Chat Completions。其他已识别的请求格式会跳过语义层；如果 Chat Completions 包含图片或音频等非文本内容块、tool_calls、function_call，或者配置的嵌入窗口为空，同样会跳过语义层。精确缓存仍然可以覆盖上述请求。平台团队因此能够引入语义复用，同时避免把无法完整表达响应决定因素的输入变成向量搜索键。
流式响应改变了复用的经济性
流式传输是交互式 AI 应用的核心，因为它可以降低感知延迟。模型仍在生成内容时，用户就能开始阅读。3.10.3 之前，流式请求会绕过 API7 网关的 AI Cache，因此许多对延迟敏感的对话工作负载无法从响应复用中获益。
在 3.10.3 中，网关可以缓存和重放完整的 SSE 响应，并保留其流式内容类型。这让常见的流式 LLM 链路也能获得缓存带来的经济收益：重复且符合要求的请求可以收到重放的流，而无须再次消耗模型生成资源。
这一边界被有意限定得十分具体。网关缓存的是完整响应流，而不是部分响应。采用其他帧格式的流量会绕过缓存，例如使用 AWS event-stream 格式的 Bedrock ConverseStream。系统不能把所有标记为“流式”的响应都视为可以互换。
流式复用还需要从产品角度评估。重放旧的响应流可以保留交付格式，却无法让旧回答重新具备时效性。与账户状态、库存、故障状态或快速变化的文档有关的响应，可能会比一般说明更快失效。精确缓存和语义缓存的有效期都应根据答案来源的变化速度来设定，而不应只考虑模型调用成本。
团队还应该度量用户真正获得的体验。缓存命中可以避免模型生成，但 SSE 重放的时间特征可能与模型实时输出不同。应评估首字节时间、首段模型内容时间、总响应时间和客户端兼容性，并确认下游观测机制能否区分重放响应与新生成响应。下游防护插件缓冲输出时，可能只发送 SSE keep-alive 注释，而暂不增量交付模型内容，因此连接保持活跃并不意味着用户已经收到新的 Token。
复用范围也是授权决策
语义相似并不能证明两个调用方有权共享同一个答案。即使提示词表达的意思相同，它们仍可能属于不同租户、角色、区域、订阅或数据分类上下文。
AI Cache 配置文档提供了多种控制项，可以把这些差异转化为缓存边界：
- 默认情况下，路由之间相互隔离。启用
cache_key.share_across_routes会主动从缓存键中移除路由 ID。 - 启用
cache_key.include_consumer会把已认证的消费者名称加入缓存键，从而按消费者隔离缓存响应。 cache_key.include_vars会把选定的网关上下文变量加入缓存键，让策略相关的不同维度能够隔离原本相似的请求。- 当请求头匹配配置值时，
bypass_on会跳过缓存。 max_cache_body_size会阻止超过指定大小的响应进入缓存。exact.ttl和semantic.ttl分别控制两层缓存的有效期，默认值依次为 3,600 秒和 86,400 秒。两者应依据同一套时效要求分别配置：语义命中可以将 L2 响应回填到精确缓存层，因此只缩短exact.ttl并不能限制语义回答的缓存时长。响应头可以暴露缓存状态和缓存时长。
这些控制项应从数据边界出发进行设计。如果响应包含特定租户的数据，消费者或租户上下文就应该成为缓存范围的一部分。如果请求要求模型使用实时账户状态，对应路由可能需要配置缓存绕过规则。如果同一路由同时提供公共文档和需要身份认证的故障排查内容，拆分路由或使用显式范围变量会比共用一个缓存更容易解释。
默认值 cache_key.include_consumer: false 并非建议所有调用方共享答案，而是意味着运维人员必须主动判断消费者身份是否影响响应的复用资格。同样的原则也适用于跨路由共享：扩大复用池可以提高命中率，但也会增加必须证明为等价的上下文数量。
1flowchart TD
2 candidate[候选缓存复用] --> public{响应是否与调用方无关？}
3 public -- 否 --> consumer[加入消费者或租户上下文]
4 public -- 是 --> fresh{答案在精确缓存和语义缓存的 TTL 内是否稳定？}
5 consumer --> fresh
6 fresh -- 否 --> bypass[绕过缓存或缩短有效期]
7 fresh -- 是 --> policy{策略和模型上下文是否相同？}
8 policy -- 否 --> scope[加入上下文变量或拆分路由]
9 policy -- 是 --> allow[允许查询缓存]
10 scope --> allow
11 bypass --> model[调用 LLM]
12 allow --> lookup[先查询精确缓存，再查询语义缓存]相似度阈值也是一种策略边界。较宽松的阈值可以提高命中率，但也会增加缓存答案只是“相关”而非真正“可互换”的概率。较严格的阈值可以降低这种风险，却可能让一些有价值的重复请求无法命中。应使用具有代表性的评估集选择阈值，而不是只凭直觉判断。
对于每个候选语义命中，都要检查缓存响应是否仍然满足应用对新提示词的质量要求。评估集应包含容易出错的组合：措辞相似但实体不同、否定表达、日期变化、权限级别不同，以及正确答案依赖某个细小限定条件的提示词。这些场景可以验证阈值和提示词窗口是否保留了真正重要的差异。
缓存安全与内容安全必须一并设计
缓存可以减少模型调用，但不能成为绕过内容控制的未审查通道。按照默认插件优先级，ai-cache 会先于 AI AWS Content Moderation、AI Aliyun Content Moderation 和 AI Lakera Guard 插件运行。缓存命中发生在访问阶段：此时 AI 实例已选定，但优先级较低的内容审核访问处理器尚未运行，且不会触发上游模型调用。因此，这些请求检查以及针对提供商响应的审核路径不会在本次命中时重新执行。被复用的响应是在先前未命中时写入缓存的，但当前请求不会从这些插件获得新的审核决定。
这一执行顺序也是从 3.10.2 升级时必须验证的 AWS 内容审核变化。在 3.10.2 中，AI AWS Content Moderation 在 rewrite 阶段、ai-cache 的访问阶段缓存查询之前运行，因此会检查随后命中缓存的请求。在 3.10.3 中，该插件改为在 access 阶段以优先级 1031 运行，排在优先级 1035 的 ai-cache 之后，所以缓存命中不再获得新的 AWS 请求审核结果。
平台团队必须为每条路由明确内容审核、防护规则与缓存查询之间的关系，并确保只有符合缓存准入条件的响应可以写入缓存。如果策略要求每次请求或响应都重新执行内容审核，应让相关流量绕过缓存，或在上线前与 API7 验证是否存在受支持的插件排序方案。测试必须覆盖命中与未命中，并使用生产环境计划采用的完整配置。
API7 网关 3.10.3 扩展了可用于验证这些行为的策略控制：
- AI Aliyun Content Moderation 新增
request_check_roles，团队可以选择检查user、tool和/或system内容。用户和工具内容遵循配置的最后一轮或全部轮次模式；选中系统内容后，系统内容会在每次请求时接受检查。 - AI AWS Content Moderation 现在会在 AI 协议识别后运行，检查上游 LLM 实际看到的解码提示词，而不是原始 HTTP JSON 外壳。
- AI Lakera Guard 现在会在告警模式的流式输出中应用
fail_open。当action: alert且direction: output或both时，设置fail_open: true会保持流式透传。使用默认的fail_open: false时，插件会缓冲模型内容，在生成期间可能只发送 SSE keep-alive 注释，并在生成完成且最终审核判定内容安全后释放干净内容。在这一默认的失败关闭配置下，若 Lakera API 出错或超时，响应流会被阻止，而不是被放行。
这些变化让内容审核更加精确，但并未消除对路由级威胁模型的需求。需确定缓存响应是否需要输出检查、哪些不安全或敏感请求类别应绕过缓存，以及故障发生时应采取何种行为。应测试实际配置的插件组合，而不是根据概念架构图假设所有部署都遵循同一种执行顺序。
语义缓存还会引入嵌入模型提供商的凭证。在 3.10.3 中，控制面会对语义 AI Cache 使用的 OpenAI 和 Azure OpenAI API Key 字段进行存储时加密。升级期间，3.10.3 控制面可能会写入这些加密字段，而旧版 3.10.2 数据面还无法解密。控制面升级后应尽快升级数据面，并在两端都运行 3.10.3 前避免编辑受影响的缓存配置。
这种混合版本限制也是缓存可用性的一部分。如果嵌入请求无法通过身份认证，语义查询就不能按预期工作。应将凭证兼容性、密钥轮换和故障行为与 Redis 及 RediSearch 健康状态一并纳入发布检查。
可观测性让缓存成为可运营系统
如果运维人员无法洞察缓存策略的执行效果，该策略就是不完整的。3.10.3 为 AI Cache 的命中、未命中、绕过和嵌入延迟新增 Prometheus 指标。响应路径还会通过 X-AI-Cache-Status 暴露 HIT、MISS 或 BYPASS；命中时会提供 X-AI-Cache-Age，语义命中还会提供 X-AI-Cache-Similarity。
这些信号分别回答不同问题：
- 命中率： 缓存是否找到了可以复用的流量？
ai_cache_hits_total的layer标签显示命中来自exact层还是semantic层？ - 未命中率： 流量确实是全新内容，还是相似度策略过于严格？
- 绕过率： 显式
bypass_on规则、缺少 AI 实例、非 SSE 流式帧格式或无法读取的 JSON 请求体，是否排除了超出预期的流量？ - 嵌入延迟： 语义查询节省的模型时间，是否足以抵消自身开销？
- 缓存时长： 客户端收到的响应是否仍处于预期时效范围内？
- 相似度： 实际语义命中对应的提示词相似度如何？
切勿孤立地优化单一指标。更高的语义命中率可能掩盖回答质量下降。即使嵌入延迟很低，一旦 RediSearch、Redis 或嵌入服务不可用，缓存也会采用失败开放（fail-open）策略，将错误视为未命中并继续请求上游。尽管请求仍能继续执行，模型负载、成本和延迟却可能突然上升。若动态或敏感流量本应被排除，较低的绕过率反而可能不利。
应构建一张同时展示缓存结果、上游 Token 使用量、端到端延迟、错误率和应用质量评估的仪表盘，并在条件允许时按路由、消费者类别、模型和策略版本进行划分。修改阈值或范围时，还应在发布记录中添加标记，以便运维人员把变化与命中率和质量联系起来。
还可以针对已配置的路由执行一个小型测试，验证调用方能够看到的行为。以下示例假设已经设置 layers: ["exact", "semantic"]，并正确配置了 semantic。默认的 semantic.similarity_threshold: 0.95 较为严格，这组措辞差异较大的提示词可能得到 MISS，而不是语义命中。如果需要专门观察 X-AI-Cache-Similarity，应使用评估集验证过的阈值或语义更接近的改写，而不应仅为了制造命中而降低阈值。
1curl -i "${AI_GATEWAY_URL}/v1/chat/completions" \
2 -H "Content-Type: application/json" \
3 -d '{"messages":[{"role":"user","content":"How do I reset my password?"}]}'
4
5# 等待异步语义缓存写入完成。
6sleep 1
7
8curl -i "${AI_GATEWAY_URL}/v1/chat/completions" \
9 -H "Content-Type: application/json" \
10 -d '{"messages":[{"role":"user","content":"What is the process for changing a forgotten password?"}]}'检查 X-AI-Cache-Status、X-AI-Cache-Age，以及语义命中时的 X-AI-Cache-Similarity。然后使用刻意设计为不同含义的提示词，以及不同消费者或租户上下文重复测试。测试的目的不是强行制造命中，而是验证配置的策略能否在正确场景下准确命中和未命中。
以可度量的策略逐步上线语义 AI 缓存
安全发布应从本质上适合复用答案的工作负载开始。公共产品文档、稳定的支持流程和重复出现的内部知识问题，通常比个性化建议、实时运维状态、受监管决策或包含隐私数据的提示词更适合作为第一批候选。
可以按照以下步骤逐步推进：
- 分类工作负载。 记录响应中的哪些属性依赖调用方身份、租户、时间、区域、模型、工具或实时数据。
- 定义缓存范围。 除非确需跨路由复用，否则保持路由隔离。只要授权或回答含义会发生变化，就应加入消费者或上下文变量。
- 设置时效和绕过规则。 根据数据源变化速度分别设置
exact.ttl和semantic.ttl，并绕过需要实时生成或包含策略敏感标识的请求。 - 启用并准备语义缓存。 设置
layers: ["exact", "semantic"]，配置semantic，并验证 Redis 和 RediSearch 的容量、延迟、持久化、TLS、身份认证和故障处理；通过受支持的密钥引用保存嵌入凭证。 - 构建评估集。 包含真实的同义改写、容易混淆的相近表达、否定句式、实体变化、权限变化、过时事实、对抗性提示词和流式响应。
- 开展金丝雀验证。 先从一条范围较窄的路由或一个网关组开始，把缓存结果、模型调用、延迟、Token 用量和回答质量与对照组比较。
- 测试内容审核路径。 使用计划投入生产的完整插件配置，逐一验证安全、不安全、缓存、未缓存、流式、提供商错误和内容审核超时等场景。加入 AWS 请求审核在缓存命中与未命中情况下的升级回归测试，并对比 Lakera 告警模式流式输出在
fail_open: true和false时的行为。 - 在明确保障条件下扩展。 只有当质量和隔离持续满足约定标准时，才逐步扩大流量，同时保留发生故障时快速绕过或关闭缓存的路径。
1flowchart LR
2 classify[评估复用风险] --> scope[设置隔离与时效策略]
3 scope --> evaluate[构建相似度评估集]
4 evaluate --> canary[金丝雀验证语义缓存]
5 canary --> observe[度量成本、延迟与质量]
6 observe --> decision{策略是否符合保障条件？}
7 decision -- 否 --> tune[收紧阈值、范围或绕过规则]
8 tune --> canary
9 decision -- 是 --> expand[逐步扩大流量]这种方法让回滚变得简单。若回答质量下滑，可收紧阈值或绕过受影响流量；如果隔离效果存疑，可以增加范围维度或拆分路由；若嵌入延迟抵消了收益，可在排查期间回退至仅精确缓存模式。由于策略位于网关层，应用端点无须改变。
优化复用，而非仅追求命中率
用户重复表达相同语义的情况，比发送字节完全相同的请求更常见，因此语义 AI 缓存可以提升生产 LLM 流量的经济效益。API7 网关 3.10.3 让受支持的 Chat Completions 和完整 SSE 响应能够实现这种复用，并通过指标和响应头让缓存决策变得可观察。
工程目标并非建立尽可能大的缓存，而是在不跨越身份边界、不提供过期状态、不削弱内容审核、不返回仅表面相似的答案的前提下，找到最大范围的可复用响应。
这正是语义 AI 缓存应当位于受治理流量层的原因。网关已经能够看到路由、消费者、请求上下文、选定的模型实例、内容审核策略、响应结果和遥测信号，因此可以将效率优化与保护 AI 请求链路的既有边界相结合。
阅读完整的 API7 网关 3.10.3 发布说明，查看 AI Cache 的工作方式与配置，并从复用策略可以被清楚解释、验证和端到端度量的小范围工作负载开始。若要了解更完整的流量控制模型，请继续阅读 API7 AI 网关如何管理和保护 AI 流量。