配置模型路由策略¶

Router 是 Provider 类型级配置，用于控制同一工作区的 LLM、Embedding 或 Parser 请求如何使用已配置 Endpoint。更新 Router 前，先确保目标类型至少有一个可用 Backend 和 Endpoint。

读取当前配置¶

以 LLM Router 为例：

curl "$PRODUCT_API_BASE_URL/llm/router" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "strategy": "<STRATEGY>",
    "health_check_interval": 0,
    "max_retries": 0,
    "session_affinity": false
  }
}

字段	说明
`strategy`	当前路由策略。只使用接口支持的策略值。
`health_check_interval`	健康检查间隔配置。单位和允许范围以当前接口契约为准。
`max_retries`	Router 在自身策略内允许的最大重试配置，不替代客户端重试预算。
`session_affinity`	是否为相关请求保持 Endpoint 亲和性。

更新 Router¶

curl -X PUT "$PRODUCT_API_BASE_URL/llm/router" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "<SUPPORTED_STRATEGY>",
    "health_check_interval": <INTERVAL>,
    "max_retries": <MAX_RETRIES>,
    "session_affinity": true
  }'

所有字段均为可选更新项，但调用方应先读取当前配置，只发送需要修改的字段。成功响应返回更新后的 Router；再次调用 GET /{provider}/router，确认服务端保存值与预期一致。

LLM、Embedding 和 Parser 分别维护自己的 Router：

/llm/router
/embedding/router
/parser/router

不要把一个类型的 Router 配置直接复制到另一个类型。可用 Backend、Endpoint 和实际负载不同，策略选择也应分别验证。

验证变更¶

重新读取 Router，确认字段已经更新。
列出该 Provider 类型的 Backend 和 Endpoint，确认至少一个 Endpoint 可用。
对 LLM 或 Embedding 运行模型探测。
使用代表性的工作流、语义模型或智能体调用验证实际路由。

Router 更新成功只表示配置已经保存，不保证下游模型调用一定成功。客户端仍应设置自己的超时、幂等和重试边界，避免 Router 重试与客户端重试叠加造成请求放大。

常见问题¶

现象	先检查	下一步
Router 更新失败	策略值、数值范围和当前权限	重新读取当前配置，只修改一个字段后重试。
更新后任务仍失败	Endpoint 状态、Backend 探测和下游错误	先修复 Provider 连接，不反复切换 Router。
请求次数超出预期	Router `max_retries` 和客户端重试	统一总重试预算，并只对可重试错误执行退避。
Session 路由不稳定	`session_affinity` 和请求是否携带稳定会话上下文	确认调用链能持续提供同一会话标识。

下一步¶

最后更新于 2026 年 8 月 14 日