MoeRouter 文档 获取 API Key

会话亲和与缓存

同一段对话的请求会优先留在同一条线路上,这样上游的提示词缓存才能命中。这一篇说明 MoeRouter 怎么识别“同一段对话”,亲和持续多久,以及什么时候会换线路。

更新于 2026-11-15 阅读约 3 分钟 实测:2026-11-15 实际请求

本页目录
  1. 为什么需要亲和
  2. 怎么识别“同一段对话”
  3. 亲和的范围和时长
  4. 亲和不是锁定
  5. 怎么确认亲和生效了
  6. 实际建议

为什么需要亲和#

大模型的提示词缓存是按上游各自保存的。一段对话的前几轮在线路 A 上处理过,缓存就在 A 那里;下一轮如果换到线路 B,B 那边没有缓存,整段上下文要按全价重新算一遍。

缓存命中的部分,价格通常只有正常输入的十分之一左右,有的模型更低。编程 Agent 每一轮都会把很长的上下文重新发一遍,缓存命不命中,费用能差出好几倍。

所以 MoeRouter 在“低价优先”之外加了一条规则:同一段对话,优先留在上一次成功的那条线路上。

怎么识别“同一段对话”#

MoeRouter 按下面的顺序找会话标识,用找到的第一个:

顺序 标识 谁会带
1 请求体里的 prompt_cache_key Codex、支持提示词缓存的 OpenAI 客户端
2 请求头 X-Session-Id、Session-Id、Session_id、X-Conversation-Id 部分客户端;你自己的程序也可以加
3 请求体里的 metadata.session_id、metadata.conversation_id、metadata.user_id 部分客户端
4 请求体里的 session_id、conversation_id、user 部分客户端
5 都没有时,用你的 API Key 本身 所有请求

有一个例外:Claude 模型在 /v1/messages 上最先看 metadata.user_id。Claude Code 把会话信息放在这个字段里。

也就是说:

  • 用 Claude Code、Codex:什么都不用做,它们自己带了会话标识。
  • 自己写程序:多轮对话时,每一轮带上同一个 prompt_cache_key 或 X-Session-Id。
  • 什么都不带:同一个 Key 对同一个模型的请求,会被当成同一个会话。

亲和的范围和时长#

  • 亲和是按 会话标识 + 模型 + 分组 + 接口类型 记的。同一个会话换了模型或者换了接口,线路会重新选。
  • 每次成功都会刷新,一小时内没有新请求就过期。
  • 记住的是最近一次成功的线路。请求因为故障换到了另一条线路并且成功了,之后就跟着新线路走。

亲和不是锁定#

亲和只是把上次的线路排到最前面,它仍然要通过和其他线路一样的检查:

  • 线路正在休息、并发已满或者已经停用:跳过它,按价格从低到高选别的。这一次请求会成功,只是缓存可能命不中。
  • 线路出错:换下一条,和普通请求一样。

所以亲和不会让你的请求卡在一条坏掉的线路上。

也有例外:少数模型各条线路的价格差别很大,对它们关闭了亲和,每次都选最便宜的线路。目前是 gemini-4-argon 的 Chat Completions 和 Gemini 原生接口。

怎么确认亲和生效了#

看响应头 X-Moe-Pricing-Policy:

X-Moe-Pricing-Policy: dynamic-session-affinity

出现这个值,说明这次请求沿用了会话上次成功的线路。第一次请求,或者上次的线路不可用时,值是 dynamic-lowest-cost。

亲和是在一次请求完全结束之后才记下来的。前一个请求刚返回就立刻发下一个,下一个可能还看不到它;正常的对话节奏不受影响。

缓存有没有命中,看返回的 usage:OpenAI 格式是 prompt_tokens_details.cached_tokens,Anthropic 格式是 cache_read_input_tokens。控制台的使用日志里也会列出缓存读取的 token 数。

实际建议#

一个 Key 同时跑好几个互不相关的任务时,给每个任务一个自己的会话标识。 否则它们会被当成同一个会话,挤在同一条线路上。

# 每段对话一个固定的值,整段对话都用它
reply = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=history,
    extra_headers={"X-Session-Id": conversation_id},
)

不要在一段对话中途换模型。 换了模型,亲和和缓存都从头开始。

缓存有保质期。 上游的缓存一般只保留几分钟到一小时。一段对话停了很久再继续,即使走的是同一条线路,缓存也可能已经过期。

把不变的内容放在前面。 系统提示词、工具定义、长文档放在请求的开头,变化的内容放在后面。缓存是按前缀匹配的,开头一变,后面全部失效。

↑↓ 选择Enter 打开可以直接粘贴报错原文