providers.toml：厂商连接¶

真实文件是 config/providers.toml，每个 [[api_providers]] 是一条可复用连接。 同一连接可以供多个模型使用，换密钥不必逐个编辑模型。 逐字段说明见厂商模板。

连接名、预设与实际地址¶

name 是模型引用的唯一名称；kind 是地址预设标识，两者职责不同。 首装预设均为 dashscope，但两者不要求保持同名。 base_url 非空时使用显式地址；留空才按 kind 查内置地址。 未知预设加空地址无法使用，选用的候选会在配置加载时暴露该问题。

修改 kind 不会覆盖已配置的 base_url。 更换服务时，应核对地址、鉴权、模型 ID 和额外参数是否相互匹配。 兼容接口通常填写服务基础地址，不应包含完整的聊天接口路径。 内置预设仅提供地址，账号、密钥和模型权限需独立开通。

四种鉴权方式¶

下表适用于 client_type = "openai" 的兼容接口。

本地免鉴权应选择 none；保留 bearer 并清空密钥会导致配置校验失败。 认证头应由鉴权字段统一配置，避免在 default_headers 中重复定义。 额外请求头和固定查询参数分别放在 default_headers、default_query， 只填写服务端明确要求的键，鉴权仍由三个专用字段管理。

面板读配置时不回传明文 Key；已存条目编辑时密钥框留空表示保留原值。 直接编辑 TOML 时不保留空值对应的旧密钥；清空 api_key 会清除磁盘凭据。 面板把连接改为免鉴权时会清空原密钥，同时应清空认证字段名。 面板按连接名称匹配已保存的密钥；修改连接名称时须重新填写密钥。 配置与备份都含真实凭据，不提交到版本控制。

超时和安全重试¶

timeout_ms 默认 120000，约束单次 HTTP 连接与流式读取。 max_retries 默认 2，是尚未产生可见内容时，同一连接内允许的重试次数。 retry_interval_ms 默认 800，是重试间隔。 重试次数不是总尝试次数，也不是任务备用模型的数量。

连接重试受任务首字窗口约束；窗口为 30 秒时，全部重试可能因超时而提前终止。 调整参数前，应区分握手、鉴权、模型参数、服务端错误和超时等故障类型。 鉴权和请求格式错误不会因延长等待而解决。 普通流式内容开始输出后，中途出错不会从头重试，以避免重复发送回复。 候选切换与慢响应记录见模型配置。

本地推理服务¶

先单独启动能提供兼容接口的本地服务，记下实际地址和模型 ID。 以下是一条免鉴权连接示例，端口 8000 必须替换为实际监听值：

[[api_providers]]
name = "local"
kind = "openai"
base_url = "http://127.0.0.1:8000/v1"
api_key = ""
auth_type = "none"
auth_name = ""
client_type = "openai"

将该片段添加至已有 providers 文件，并保留原有 [inner]。 再在模型目录将目标条目的 api_provider 设为 local， 真实模型 ID 填本地服务接受的名称，并分配给任务。 本地服务不支持的百炼 extra_body 参数应予以移除。

127.0.0.1 指后端所在的机器；容器里的本地地址不等于宿主机。 如果模型服务在另一台机器，填写后端能访问的地址。 本地推理服务需独立启动；免鉴权配置不包含服务监听范围检查。

模型列表与协议类型¶

model_list_endpoint 默认 /models，用于面板连接测试与拉取目录。 服务没有实现目录接口时，拉取失败不能单独证明聊天接口也不可用。 目录成功返回同样不证明其中每个模型支持视觉、工具调用或嵌入。

client_type = "openai" 对应兼容接口，可承载对话、视觉、嵌入和语音。 client_type = "volcengine" 使用专用语音协议，只能绑定 tts 任务。 后者还要填写 app_id 与作为访问凭据的 api_key， 音色和集群则在功能配置中填写。 不能把语音专用连接分配给日常对话候选。

保存与核对¶

只改连接名时，也要更新每个引用它的模型。 保存并重启后端，先确认没有悬空引用与凭据校验错误。 随后使用实际任务验证接口，并结合调用记录分析服务端返回信息。 首装六个模型共用一条连接，这条连接不可用会同时影响它们。 有多条连接时，故障隔离按厂商连接名称处理，具体策略见模型配置。