For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /api/providers.md.
  • 简体中文
  • Octop 提供商 API:配置模型提供商与模型

    配置模型提供商,选择可用模型,并控制专家使用的默认模型。

    权限

    已登录用户可以列出全部提供商,并读取自己可选的模型。创建、更新、删除、测试提供商,以及设置全局默认模型,需要 providers 权限。写操作走 /api/admin/providers。

    OpenAI 兼容提供商可以选择 Responses(/v1/responses)或 Chat Completions。服务启动时会同步新的预置模型,腾讯云通道包含混元 HY4。

    端点

    方法路径描述
    GET/providers列出提供商(已登录用户,只读)
    GET/providers/resolved列出当前用户可选的已启用模型
    GET/providers/active-model获取全局默认模型
    PUT/providers/active-model设置全局默认模型(需要 providers 权限)
    POST/admin/providers添加提供商(需要 providers 权限)
    PATCH/admin/providers/{id}更新提供商(需要 providers 权限)
    DELETE/admin/providers/{id}删除提供商(需要 providers 权限)
    POST/admin/providers/{id}/test测试已保存的提供商(需要 providers 权限)

    创建提供商

    OpenAI

    curl -X POST http://127.0.0.1:8088/api/admin/providers \
      -H 'Authorization: Bearer <token>' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "openai",
        "kind": "openai",
        "base_url": "https://api.openai.com/v1",
        "api_key": "sk-..."
      }'

    本地 Ollama

    curl -X POST http://127.0.0.1:8088/api/admin/providers \
      -H 'Authorization: Bearer <token>' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "local-ollama",
        "kind": "ollama",
        "base_url": "http://127.0.0.1:11434"
      }'

    DashScope

    curl -X POST http://127.0.0.1:8088/api/admin/providers \
      -H 'Authorization: Bearer <token>' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "dashscope",
        "kind": "dashscope",
        "api_key": "sk-..."
      }'
    说明

    API 密钥会加密存储。更新密钥时,向 PATCH /api/admin/providers/{id} 提交新的 api_key。

    测试提供商

    创建提供商后,调用 test 端点验证连接是否健康。Octop 会发送一次轻量模型请求;如果是嵌入模型,则探测 embeddings 端点。对于常见的鉴权、余额、限流或服务不可用错误,Octop 会尽量返回本地化处理建议,而不是只暴露原始上游错误。

    curl -X POST http://127.0.0.1:8088/api/admin/providers/1/test \
      -H 'Authorization: Bearer <token>'

    响应:

    {"ok": true, "latency_ms": 312}

    如需测试指定聊天或嵌入模型,可在 JSON 请求体中传入 model_id 或 embedding: true。

    或失败时返回错误详情。

    列出可用模型

    curl http://127.0.0.1:8088/api/providers/resolved \
      -H 'Authorization: Bearer <token>'

    返回当前用户可选的已启用模型,每项包含 provider_name 和 model。

    设置活动模型

    需要 providers 权限:

    curl -X PUT http://127.0.0.1:8088/api/providers/active-model \
      -H 'Authorization: Bearer <token>' \
      -H 'Content-Type: application/json' \
      -d '{"provider_name": "openai", "model": "gpt-4o"}'
    注意

    删除仍被一个或多个专家引用的提供商将返回 409 PROVIDER_REFERENCED。请先将受影响专家重新指定到其他提供商。

    管理员共享提供商

    有 providers 权限的用户通过 /api/admin/providers 管理提供商。这些提供商对已登录用户可见,普通用户只能列出,不能修改或删除。

    Agent Client Protocol(ACP)

    方法路径描述
    GET/acp列出 ACP 运行时
    PUT/acp添加/更新 ACP 运行时
    GET/acp/{runner_name}获取运行时详情
    PUT/acp/{runner_name}更新运行时
    DELETE/acp/{runner_name}删除运行时
    GET/agents/{aid}/acp获取专家的 ACP 配置
    PUT/agents/{aid}/acp设置专家的 ACP 配置