MoeRouter 文档 获取 API Key

动态路由:请求是怎么选线路的

MoeRouter 为每个模型准备多条线路。这一篇说明一次请求怎么排序、怎么挑线路、失败后怎么切换,以及你能从响应里看到什么。附一个可以动手试的演示。

更新于 2026-11-15 阅读约 4 分钟

本页目录
  1. 一句话版本
  2. 动手试一试
  3. 一次请求经过的步骤
  4. 什么情况会换线路
  5. 线路的休息
  6. 接续上一轮的请求
  7. 怎么知道这次走了哪种选择
  8. 这对价格意味着什么
  9. 你可以做的事

一句话版本#

同一个模型在 MoeRouter 背后有多条线路,每条线路的价格和状态都不一样。你发来一个请求,MoeRouter 把它交给当前可用的线路里最便宜的一条;这条线路出问题,就自动换下一条。你始终只用一个接口地址和一个 Key。

动手试一试#

下面是一个简化的演示:一个模型,三条线路。改变条件,再点“发送请求”,看请求怎么走。数字只是示意。

一次请求经过的步骤#

  1. 筛出能用的线路。 从这个模型的所有线路里,留下你的 Key 所在分组能用、并且支持你用的接口的那些。一个模型在某个分组里一条线路都没有,或者没有线路支持这个接口,请求会立刻收到 404 和原因,见报错对照表。

  2. 按价格排序。 每条线路有自己的价目。MoeRouter 按这次请求的大小,估算它在每条线路上的价格,从低到高排好。长上下文加价、非高峰时段价格这些因素都会算进去。

  3. 会话亲和。 如果这个会话上一次成功用的线路还在名单里,把它排到最前面。这样上游的提示词缓存才能命中。详见会话亲和与缓存。

  4. 从前往后找第一条可用的。 跳过这三种线路:

    • 正在休息的:刚刚出过错;
    • 并发已满的:每条线路同时处理的请求数有上限;
    • 不能处理这个请求的:例如请求要接续上一轮的状态,而这条线路做不到。
  5. 发出请求。 成功就把回答返回给你,并记住这条线路。

  6. 失败就换下一条。 出错的线路去休息,请求交给名单里的下一条。一个请求最多尝试 6 条线路。

什么情况会换线路#

会换:上游限流(429)、上游出错或过载(5xx)、上游迟迟不开始响应、上游账号本身的问题(欠费、Key 失效)。这些都和你的请求无关,换一条线路通常就好了。

不会换:

  • 请求本身有问题(400)。换哪条线路结果都一样,所以直接把错误返回给你。
  • 上游已经处理了很久之后才超时(504、524)。重来一遍多半还是超时,而且可能重复计费。
  • 回答已经开始输出之后才出的错。已经发出去的内容不能从头再来。
  • 你主动断开了连接。

线路的休息#

一条线路因为限流、出错、过载或者账号问题失败之后,会对你的账号休息十几秒。这期间你的请求不再去碰它,直接走别的线路。

如果短时间内有不止一个账号在同一条线路上失败,这条线路会对所有人休息一小会儿,免得每个人都去撞一次。

休息是自动结束的。线路恢复之后,下一次请求会重新按价格排序,便宜的线路又排回前面。

只有一条线路的模型

有些模型只有一条线路。它出错之后的十几秒里,这个模型对你暂时不可用,你会收到 503、错误码 model_temporarily_unavailable 和一个 Retry-After 响应头,告诉你几秒后再试。大多数客户端会自动等待并重试。

接续上一轮的请求#

有三类请求只能由“原来那条线路”或者支持接续的线路处理:

  • 用 previous_response_id 接续一个已存储的响应;
  • 后台模式(background: true);
  • 请求里带着上一轮的加密推理内容。Codex 这类编程 Agent 从第二轮起可能会带。

这些状态存在上游那一侧,别的线路读不到。目前 gpt-6-astra 和 gpt-6.1-sol 有支持接续的线路。其他模型收到这类请求会返回 400 和 stateful_request_not_supported,提示里会列出能接续的模型。

怎么知道这次走了哪种选择#

模型请求的响应里有一个 X-Moe-Pricing-Policy 响应头:

值 含义
dynamic-lowest-cost 选了当前可用线路里最便宜的一条
dynamic-session-affinity 沿用了这个会话上次成功的线路
dynamic-long-context-preference 输入很长,选了更适合长上下文的线路
curl -sS -D - -o /dev/null https://moerouter.com/v1/chat/completions \
  -H "Authorization: Bearer $MOEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-terra", "messages": [{"role": "user", "content": "你好"}]}' \
  | grep -i x-moe

每次请求实际扣了多少,在控制台的使用日志里能看到。

这对价格意味着什么#

模型广场上显示的是参考价。每次请求按实际走到的那条线路的价格结算:

  • 大多数时候走的是最便宜的线路;
  • 便宜的线路在休息、满载或者不能处理这个请求时,会落到贵一些的线路上,这一次请求就按那条线路的价格算。

所以同一个模型,不同时间的单价可能略有不同。详见计费与额度。想要固定的价格,可以用 stable 分组。

你可以做的事#

  • 让同一段对话带上固定的会话标识。 这样它会留在同一条线路上,缓存能命中,花费更低。见会话亲和与缓存。
  • 收到 Retry-After 就照它等。 立刻重试只会再碰一次正在休息的线路。
  • 不要高频重放失败的请求。 上游限流时,重放越快,恢复越慢。
  • 长任务用流式输出。 长时间没有任何输出的连接,容易在中途被网络设备断开。

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