配置 Agent BYOK¶

BYOK 让 Agent 使用您自己的模型服务。您在 provider.json 中填写服务地址、API Key、模型和推理档位，再把文件内容保存到 etcd。

配置需要两套凭据：etcd 账号用于保存和读取模型配置，模型 API Key 用于调用模型服务。

BYOK 工作时序¶

sequenceDiagram
    autonumber
    participant Beak
    participant Agent as Agent（含安装）
    participant Etcd as etcd
    participant LLM as 模型服务

    Note over Beak,Agent: 用户填写 etcd 设置并安装 Agent
    Agent->>Beak: 读取已保存的 etcd 设置
    Agent->>Etcd: 读取 Provider 和模型配置
    Agent->>Beak: 同步可选择的模型

    Note over Beak: 用户选择模型并发起任务
    Beak->>Agent: 发送任务
    Agent->>LLM: 调用所选模型
    LLM-->>Agent: 返回响应
    Agent-->>Beak: 返回结果

    Note over Etcd: 用户更新完整 provider.json
    Etcd-->>Agent: 通知配置已更新
    Agent->>Etcd: 获取最新配置
    Agent->>Beak: 同步更新后的模型
    Note over Beak,Agent: 新任务使用新配置，正在执行的任务不受影响

    Note over Beak,Agent: 用户修改 etcd 连接设置后需重新安装<br/>普通升级继续使用当前 BYOK 设置

准备连接信息¶

开始前，请准备：

• etcd 地址，以及保存模型配置的 Key。本文使用 obs-agent/byok/providers。
• 专用 etcd 账号 obs-agent，用于写入模型配置，并供 Agent 读取。
• 模型服务的 API 根地址、API Key，以及供应商提供的模型 ID、能力和推理档位。

强烈建议新建 obs-agent 账号并设置独立的强密码，不要复用已有账号或密码。只授予它对指定 Key 的读写权限。

以下命令需要已安装 etcdctl。请让 etcd 管理员执行，替换地址和管理员用户名：

使用自建证书时，先设置 ETCDCTL_CACERT；需要客户端证书时，再设置 ETCDCTL_CERT 和 ETCDCTL_KEY，值均为证书或私钥文件路径。

export ETCDCTL_ENDPOINTS='https://<ETCD-HOST>:2379'
etcdctl --user='<ETCD-ADMIN-USER>' user add obs-agent
etcdctl --user='<ETCD-ADMIN-USER>' role add obs-agent-byok
etcdctl --user='<ETCD-ADMIN-USER>' role grant-permission obs-agent-byok readwrite 'obs-agent/byok/providers'
etcdctl --user='<ETCD-ADMIN-USER>' user grant-role obs-agent obs-agent-byok

按提示输入管理员密码；user add 还会要求设置 obs-agent 的新密码。

编写模型配置¶

创建 provider.json，用下面的示例作为起点。请替换服务地址、API Key 和模型 ID，并按供应商的实际能力填写窗口大小和推理档位。

{
  "schema_version": 1,
  "default_model": {
    "provider_id": "provider-a",
    "model_id": "<MODEL-ID>"
  },
  "providers": [
    {
      "id": "provider-a",
      "name": "My provider",
      "protocol": "openai_chat_completions",
      "base_url": "https://<PROVIDER-HOST>/v1",
      "api_key": "<PROVIDER-API-KEY>",
      "models": [
        {
          "id": "<MODEL-ID>",
          "name": "My model",
          "context_tokens": 524288,
          "input_modalities": ["text"],
          "output_modalities": ["text"],
          "supports_tools": true,
          "supports_json_schema": true,
          "reasoning": {
            "supports_enable": false,
            "supports_disable": false,
            "effort": {
              "status": "available",
              "request_path": ["reasoning_effort"],
              "levels": ["minimal", "balanced", "deep"],
              "default_level": "balanced"
            }
          }
        }
      ]
    }
  ]
}

示例中的推理字段和档位用于说明填写方法，请以模型供应商的说明为准。增加服务时，在 providers 中增加一项；增加模型时，在对应服务的 models 中增加一项。

填写服务和默认模型¶

服务 id 和模型 id 区分大小写。修改展示名称时，保留原有 id，方便已有任务继续识别模型。

填写模型能力¶

请使用有效 JSON，不添加 JSON 语法不支持的注释或重复字段。您可以增加 comment、owner 等备注字段，Agent 会忽略不认识的字段。

设置模型的推理档位¶

每个模型分别设置推理字段和档位。字段名、档位值及大小写均按供应商原值填写，菜单会显示您配置的档位。

例如，供应商使用 reasoning.effort，支持 Quick 和 Careful，可以填写：

{
  "supports_enable": false,
  "supports_disable": false,
  "effort": {
    "status": "available",
    "request_path": ["reasoning", "effort"],
    "levels": ["Quick", "Careful"],
    "default_level": "Careful"
  }
}

将这段内容替换到模型的 reasoning 中。您选择 Quick 时，Agent 就使用 Quick；未选择时使用 Careful。切换模型后，使用目标模型自己的档位。

模型没有可选档位，也不能独立开关推理时，填写：

{
  "supports_enable": false,
  "supports_disable": false,
  "effort": {
    "status": "unavailable",
    "levels": [],
    "default_level": null
  }
}

把模型配置保存到 etcd¶

在 provider.json 所在位置打开 Bash，替换 etcd 地址，执行以下命令。输入刚创建的 obs-agent 密码：

export ETCDCTL_ENDPOINTS='https://<ETCD-HOST>:2379'
read -r -s -p 'obs-agent password: ' ETCDCTL_PASSWORD
printf '\n'
export ETCDCTL_PASSWORD
ETCDCTL_USER='obs-agent' etcdctl put 'obs-agent/byok/providers' < provider.json
unset ETCDCTL_PASSWORD

看到 OK 即表示写入成功。首次写入会创建该 Key，后续写入会替换完整内容；每次更新都请保留其他服务和模型。使用证书连接时，沿用上一节的证书设置。

准备 Agent 的连接配置¶

填写连接 JSON¶

安装或重新安装 Agent 时，使用以下连接信息，填写同一个 etcd 账号 obs-agent：

在 Web 的 Agent 创建页或「运行与部署」页面填写并保存这些设置，再复制安装命令到目标机器执行。安装会自动读取已保存的设置，您无需在命令后追加 BYOK 内容。重新安装同一个 Agent 时也会复用这些设置。

{
  "schema_version": 1,
  "endpoints": ["https://<ETCD-HOST>:2379"],
  "user": "obs-agent",
  "password": "<OBS-AGENT-ETCD-PASSWORD>",
  "key": "obs-agent/byok/providers",
  "request_timeout": "10s"
}

替换所有尖括号占位值。key 必须与授权和写入时的 Key 完全一致；多个 etcd 地址分别填入 endpoints。连接账号和密码不能用模型 API Key 代替。

request_timeout 默认为 10s，需要时可调整，例如 15s。

使用自建 CA 时，在连接配置中增加 tls.ca_pem，填写完整证书内容。需要双向 TLS 时，再成对填写 tls.cert_pem 和 tls.client_key_pem。这些字段填写 PEM 内容，换行用 JSON 的 \n 表示，例如：

{
  "tls": {
    "ca_pem": "-----BEGIN CERTIFICATE-----\n<CA-CONTENT>\n-----END CERTIFICATE-----\n"
  }
}

把所需的 tls 字段加入完整连接配置；系统已信任 etcd 证书时无需填写。

查看连接配置保存位置¶

Agent 将连接配置保存在工作路径下的 .beak/private/byok.etcd.json。Linux 标准安装的位置为：

/var/lib/obs-agent/work/.beak/private/byok.etcd.json

使用自定义工作路径时，在该路径下查找 .beak/private/byok.etcd.json。

选择和更新模型¶

在 obscli 的 Task 中输入 /model，选择服务、模型及推理档位。菜单显示配置中的服务名称和模型名称，并用 服务ID/模型ID 区分同名模型；也可直接输入 /model provider-a/model-a <effort>。详细操作见 obscli 模型选择。

修改模型、API Key 或推理档位后，将完整 provider.json 再次写入同一个 etcd Key。Agent 会订阅这个 Key，并在收到变更通知后读取和校验新内容。校验成功后，新任务使用新配置；正在执行的任务继续使用原配置。轮换 API Key 时，请为已有任务留出完成时间。

撤下模型时，从对应的 models 中移除它；如果它是默认模型，同时指定新的默认模型。已有任务选择的模型被撤下后，后续执行使用默认模型。

更换 etcd 地址、账号、密码、Key 或证书时，在 Agent 的「运行与部署」页面更新并保存设置，然后重新执行安装命令。保存后，正在运行的 Agent 仍使用原配置；普通升级也不会应用这些修改。

切回 AIHub 模型¶

如需切回 AIHub 模型，在 Agent 的「运行与部署」页面选择「官方模型」，保存安装配置，然后复制新的安装命令重新安装 Agent。该命令会清除原来保存的 BYOK 设置。

仅清空启动参数、删除 etcd 中的模型配置或停止 etcd 服务，都不会切回 AIHub 模型。

遇到问题时检查¶

模型配置和连接配置均包含凭据，请妥善保管。提交问题时提供错误信息，并移除密码和 API Key。