# 配置模型路由策略

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

## 读取当前配置

以 LLM Router 为例：

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

```json
{
  "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

```bash
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：

```text
/llm/router
/embedding/router
/parser/router
```

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

## 验证变更

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

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

## 常见问题

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

## 下一步

- [检查 Backend 和 Endpoint](provider-backend.md)
- [使用配置后的 Provider 处理语义模型来源](../semantic-models/sources-processing.md)