> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Router 配置获取与更新接口

> 以 JSON 形式获取当前 router YAML 配置，或使用经过校验的配置对象更新它。写入需要管理员权限。

使用配置接口检查或替换 router 的实时配置。GET 请求返回序列化为 JSON 的当前 YAML v0.3 配置。PUT 请求用一个经过校验的对象替换整个配置。只有管理员调用者可以更新配置。

配置组织为顶层块：`listeners`、`providers`、`entrypoints`、`recipes` 与 `global`。

## 接口

```http theme={null}
GET /v1/router/config
```

```http theme={null}
PUT /v1/router/config
```

## 认证

使用会话 Cookie 认证，或携带 `Authorization: Bearer <api-key>`。PUT 方法需要管理员角色。

## GET 响应

<ResponseField name="config" type="object">
  当前的 router 配置。

  <Expandable title="属性">
    <ResponseField name="listeners" type="array">
      router 监听的绑定地址与端口。

      <Expandable title="items">
        <ResponseField name="address" type="string">
          绑定地址。
        </ResponseField>

        <ResponseField name="port" type="integer">
          绑定端口。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="providers" type="array">
      带默认模型与后端引用的 provider 定义。

      <Expandable title="items">
        <ResponseField name="name" type="string">
          provider 标识符。
        </ResponseField>

        <ResponseField name="default_model" type="string">
          未指定模型时的回退模型。
        </ResponseField>

        <ResponseField name="models" type="array">
          每个模型的后端引用。

          <Expandable title="items">
            <ResponseField name="name" type="string">
              模型名称。
            </ResponseField>

            <ResponseField name="backend_ref" type="string">
              后端端点或标识符。
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="entrypoints" type="array">
      虚拟模型到 router 与配方组合的映射。

      <Expandable title="items">
        <ResponseField name="model" type="string">
          向客户端暴露的虚拟模型名称。
        </ResponseField>

        <ResponseField name="router" type="string">
          router 标识符。
        </ResponseField>

        <ResponseField name="recipe" type="string">
          配方标识符。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recipes" type="array">
      路由配方，分为语义（`semantic`）或智能体（`agent`）。

      <Expandable title="items">
        <ResponseField name="name" type="string">
          配方标识符。
        </ResponseField>

        <ResponseField name="type" type="string">
          配方类别。`semantic`（routing.*）或 `agent`（agent.*）。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="global" type="object">
      全局设置，例如认证路径、密钥路径与用户路径。

      <Expandable title="属性">
        <ResponseField name="auth" type="string">
          认证配置路径。
        </ResponseField>

        <ResponseField name="keys" type="string">
          API 密钥配置路径。
        </ResponseField>

        <ResponseField name="users" type="string">
          用户配置路径。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## PUT 请求体

<ParamField body="listeners" type="array">
  绑定地址与端口。
</ParamField>

<ParamField body="providers" type="array" required>
  provider 定义。
</ParamField>

<ParamField body="entrypoints" type="array" required>
  虚拟模型映射。
</ParamField>

<ParamField body="recipes" type="array" required>
  路由配方。
</ParamField>

<ParamField body="global" type="object" required>
  全局设置。
</ParamField>

## PUT 响应

<ResponseField name="applied" type="boolean">
  新配置是否被接受并应用。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # 获取当前配置
  curl -X GET "https://router.example.com/v1/router/config" \
    -H "Authorization: Bearer <api-key>"

  # 更新配置（仅管理员）
  curl -X PUT "https://router.example.com/v1/router/config" \
    -H "Authorization: Bearer <api-key>" \
    -H "Content-Type: application/json" \
    -d '{"listeners":[{"address":"0.0.0.0","port":8080}],"providers":[],"entrypoints":[],"recipes":[],"global":{}}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "config": {
      "listeners": [{"address": "0.0.0.0", "port": 8080}],
      "providers": [
        {
          "name": "openai",
          "default_model": "gpt-4o",
          "models": [
            {"name": "gpt-4o", "backend_ref": "openai/gpt-4o"}
          ]
        }
      ],
      "entrypoints": [
        {"model": "default", "router": "main", "recipe": "semantic-router"}
      ],
      "recipes": [
        {"name": "semantic-router", "type": "semantic"}
      ],
      "global": {
        "auth": "config/auth.yaml",
        "keys": "config/keys.yaml",
        "users": "config/users.yaml"
      }
    }
  }
  ```
</ResponseExample>