配置 Backend 与 Endpoint¶

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

前提条件¶

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

创建 Backend¶

以 LLM Backend 为例：

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：

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

保存 data.id。

创建 Endpoint¶

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 探测模型：

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

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

更新 Endpoint 状态使用：

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。

下一步¶

最后更新于 2026 年 8 月 14 日