# 配置 Backend 与 Endpoint

Backend 保存模型服务配置，Endpoint 表示该 Backend 下的实际服务地址。完成本页操作后，你将创建 Backend 和 Endpoint，并保存两个 ID 以便更新状态和路由配置。

## 前提条件

- 已选择 [Provider 类型](provider.md)。
- 已准备服务地址、Provider API Key，以及该类型所需的模型列表或 MIME 类型。
- 当前身份具有管理模型供给配置的权限。

## 创建 Backend

以 LLM Backend 为例：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/llm/backends" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<BACKEND_NAME>",
    "type": "<PROVIDER_PROTOCOL>",
    "api_key": "<PROVIDER_API_KEY>",
    "models": ["<MODEL_ID>"],
    "timeout_seconds": 30
  }'
```

| 字段 | 类型 | 适用类型 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 全部 | Backend 名称。 |
| `type` | string | 按 Provider | 服务协议或实现类型，使用当前接口支持的值。 |
| `api_key` | string | 需要凭据时 | 远程 Provider 密钥。不会作为明文读回。 |
| `models` | string[] | LLM、Embedding | Backend 提供的模型 ID；至少提供一个。 |
| `reasoning_control_protocol` | string | 支持时 | 推理控制协议。只为明确支持的 LLM Backend 设置。 |
| `timeout_seconds` | integer | 支持时 | Backend 请求超时配置。示例值不代表默认值。 |
| `supported_mime_types` | string[] | Parser | Parser 接受的 MIME 类型；不要用于 LLM 或 Embedding。 |

成功响应返回 Backend，不包含明文 API Key：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 601,
    "name": "<BACKEND_NAME>",
    "type": "<PROVIDER_PROTOCOL>",
    "timeout_seconds": 30,
    "models": ["<MODEL_ID>"],
    "endpoints": []
  }
}
```

保存 `data.id`。

## 创建 Endpoint

```bash
curl -X POST "$PRODUCT_API_BASE_URL/llm/backends/$BACKEND_ID/endpoints" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"address": "<PROVIDER_ENDPOINT>"}'
```

成功响应中的 `id` 是 Endpoint ID，`backend_id` 应与当前 Backend 一致。保存 Endpoint ID，并检查返回的 `status`。

## 探测和修改 Endpoint 状态

LLM 和 Embedding 可以通过以下接口使用已配置 Backend 探测模型：

```text
POST /{provider}/backends/{backend_id}/probe-models
```

请求体包含 Provider API Key。Parser 不支持该操作。

更新 Endpoint 状态使用：

```text
PUT /{provider}/backends/{backend_id}/endpoints/{endpoint_id}/status
```

请求体为 `{"status":"<STATUS>"}`。只使用当前接口返回或文档明确支持的状态值；更新后重新列出 Endpoint，确认可用列表符合预期。

## 一体化配置 LLM Backend

`POST /llm/setup` 可以在一次请求中创建 Backend 和 Endpoint，请求包含名称、地址、模型列表及 Backend 选项。成功响应分别返回 `backend` 和 `endpoint`。需要分别控制创建、探测或回滚时，使用独立接口更容易定位失败步骤。

## 更新和删除

| 方法与路径 | 用途 |
| --- | --- |
| `GET /{provider}/backends` | 列出 Backend |
| `GET /{provider}/backends/{backend_id}` | 读取 Backend |
| `PUT /{provider}/backends/{backend_id}` | 更新名称、密钥、模型或类型专属配置 |
| `GET /{provider}/backends/{backend_id}/endpoints` | 列出 Endpoint |
| `DELETE /{provider}/backends/{backend_id}` | 删除 Backend |

轮换密钥时发送新的 `api_key`，然后运行代表性探测。删除 Backend 或停用最后一个可用 Endpoint 可能中断工作流、语义模型处理和智能体调用；操作前先检查下游绑定。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 创建被拒绝 | Provider 类型、模型列表或 MIME 类型 | 按类型移除不适用字段，并补齐必需字段。 |
| 探测失败 | 服务地址、网络、Provider API Key 和协议类型 | 修正后重新探测，不重复运行下游任务。 |
| 详情中没有 API Key | 密钥是否已经安全保存 | 这是密钥保护行为；需要轮换时提交新值。 |
| Endpoint 状态更新后不可见 | 最新 Endpoint 列表和状态 | 重新读取列表；部分类型不会在可用列表中返回离线 Endpoint。 |

## 下一步

- [配置模型路由策略](router.md)
- [查看产品可选模型](provider.md#查看产品可选模型)