4. 配置模型供应商

完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向平台管理员和运维人员，说明如何把公有云模型平台、第三方聚合平台或企业自建的推理服务接入平台，并让它稳定、可核查地对外提供模型。读完后你可以新建并验证供应商、选择上游接口格式、维护多账号、调整超时与重试、查看探查与余额、核验上游真实性、做性能测试，并理解配置的变更机制。

模型供应商记录平台如何连接一个上游模型端点：供应商类型、请求地址、模型请求格式、调用凭据（账号）和已启用的模型。供应商下启用的模型称为上游，每个启用的上游都属于一个模型；调用方按模型的调用名调用，再由网关分发到它的上游，因此供应商是模型接入的第一步。

入口：「管理后台 › 模型 › 模型供应商」。价格维护在供应商详情的「模型定价」页签，分类维护在「分类管理」页签，两处内容见第 5 章。

前提：以租户管理员或具备供应商管理权限的角色登录，并已拿到上游的请求地址和有效凭据。凭据只在页面的凭据字段中填写，不要写进工单或截图。

4.1 查看供应商列表

适用场景：日常巡检，确认每个上游是否可用、启用了哪些模型、本月消耗了多少。

顶部搜索框按名称过滤。

4.2 新建并验证供应商

适用场景：首次接入一个公有云模型厂商、一个聚合平台，或企业内部自建的推理服务。

前提：已拿到上游的请求地址与有效凭据；公有云厂商的地址由供应商类型自动带出，自建服务需自己填写。

操作步骤

1. 在「模型供应商」页签选择「添加模型供应商」，填写「模型供应商名称」；「描述（可选）」建议写明用途与负责人。
2. 在「供应商」下拉中选择供应商类型。内置目录共 30 种，覆盖国内外云厂商、聚合平台与本地推理，例如 OpenAI、Anthropic、DeepSeek（深度求索）、通义千问、「本地部署」等。
3. 选中类型后「请求地址」自动填入默认地址，按实际端点修改。
4. 在「首个账号 API 密钥」中填写凭据，保存后它会成为一个账号（更多账号见第 4.4 节）。
5. 选择「测试连接并获取模型」。这一步只探测连接，不保存配置。
6. 连接成功后启用需要的模型；端点不返回模型列表时，在「输入模型名，回车添加」中手工填写后回车。
7. 在「将成为模型」一栏核对每个上游的去向：与已有模型同名的默认关联到该模型，其余默认新建同名模型，可以改名，也可以勾选要加入的模型分组。关联到已有模型的项会显示影响（第 6.1 节）。
8. 选择「保存模型供应商」。

连接失败时的提示：页面给出逐条明细，而不是只报「失败」。密钥无效时提示「连接失败：认证凭据无效或已过期（上游状态码 401）」，按接口分别列出「模型列表」「对话」的结果与上游原文，并列出已尝试的五种密钥传递方式（Authorization: Bearer、x-api-key、x-goog-api-key、api-key、?key=）全部被拒绝，可据此确认问题在密钥本身。

保存时的准入校验：保存时会再做一次上游连接测试。未通过时提示「上游连接测试未通过，配置暂未生效」，右侧提供「仍要保存（N 个密钥标为异常）」；选择后配置会保存，未通过的密钥标为异常，不参与调用。

你会看到：连接成功后端点返回的模型列在右侧，逐个启用即可；保存后回到列表，该供应商「可用」为开启，「账号」与「可用模型」两列显示可用账号数与已启用模型。

接入企业自建推理服务

自建的 vLLM、Xinference、Ollama 或其他 OpenAI 兼容推理服务，在「供应商」中选择「本地部署」接入。

1. 「服务地址」填协议与主机，不要在地址里带具体接口路径；「认证方式」选择「API 密钥」或「无需认证」。
2. 在「接口能力」表中逐项声明该服务提供的接口，共 8 项：对话、模型列表、文本补全、向量、重排、文生图、语音合成、语音转写。每项可单独开关、填路径、选格式（「OpenAI 兼容」或「Jina / Cohere 兼容」）。新建时「向量」「重排」「语音转写」默认开启，不提供的能力应主动关闭。
3. 路径从服务地址之后写起，例如把「对话」填为 /api/v1/agent-gateway/openai/v1/chat/completions。
4. 选择「测试连接并获取模型」，只启用需要的模型，保存。多勾一个未实现的接口，调用该接口时就会失败。

4.3 选择接口格式与协议转换

适用场景：上游只提供某一种协议（例如只提供 OpenAI Chat Completions），而调用方用 Anthropic 或 OpenAI Responses 等其他协议调用。

操作步骤

1. 新建供应商时在「模型请求格式」中选择；已有供应商在「编辑 AI 供应商」中修改。
2. 按上游要求选择密钥传递方式；留空时由连接测试自动识别，并保存第一个被接受的方式。
3. 保存。

该下拉只决定网关请求上游所用的协议，与调用方使用哪种协议无关。

协议转换：调用方可用任一入站协议调用，网关在入站协议与上游格式之间转换报文与响应。用 Anthropic 协议调用 OpenAI 格式的上游时，调用方拿到的是标准 Anthropic 结构：type: message，content 中同时有 thinking 与 text 块。

被丢弃的字段在哪里看：上游不支持的字段不会静默消失，会出现在三处：响应头 x-zenova-conversion-dropped（例如 anthropic.top_k，同时列在 access-control-expose-headers 中，浏览器端脚本也能读到）；调用详情「请求」页签的「差异」页签，顶部写明跨族转发的方向并列出「未转发到上游：其他字段 top_k」；「路由与改写」页签的「按目标能力调整」写明「已丢弃：anthropic.top_k（第 1 次尝试）」。

调用前的提示：员工在模型详情页的「API 调用」面板切换格式页签时，需要网关转换的页签上方会直接列出这个方向的转换影响，分「不会生效」与「会直接报错」两类。例如用 Anthropic 协议调用一个上游是 OpenAI Chat 格式的模型时，top_k 这类参数不会生效，网址形式的图片会让请求直接报错。原生支持的页签标有「原生」，默认选中的就是它。

提示与实际行为同源：条目由模型协议转换的实际实现逐条生成，「不会生效」的每一条都能和调用后响应头 x-zenova-conversion-dropped 里的标识对上，「会直接报错」的用法就是会遇到 400 request_transform_failed 的那些。

模型有多个不同格式的上游时，提示会按上游格式分组列出各自的条目，并写明「请求被分配到这些上游时会报错」。这是因为转换失败不会改用其它上游：网关在派发前就返回错误，同一个请求能不能成功取决于路由先选中了哪个上游。

注意：模型请求格式必须与上游实际协议一致，不一致会直接调用失败，修改后先做一次连通性测试。依赖协议专有参数的业务，建议让两者保持一致。

4.4 为同一供应商配置多个账号

适用场景：同一厂商有多把密钥或订阅账号需要分担请求、提高并发，或同一推理服务部署在多个地址希望统一调度。

操作步骤

1. 进入供应商详情的「账号」页签。
2. 选择「添加账号」，逐个填写该账号的地址与并发上限（留空为不限，只有上游限制单个账号的并发时才需要填写）；地址可指向与供应商地址不同的实例。
3. 保存后账号即参与调度。

你会看到：清单列为「账号」「类型」「地址」「状态」「用量」，可筛选。地址列写「供应商地址」表示沿用供应商请求地址，填了独立地址的账号指向另一个实例。请求在可用账号之间分担，异常的账号被跳过，原因以中文写在状态下方，例如「密钥无效或已吊销」。

调度方式：「账号」页签顶部有「调度方式」下拉，只有支持订阅账号的供应商才显示，纯 API 密钥的供应商没有这一项。默认「均衡分配」：请求在可用账号之间均衡分配，同一会话固定使用同一个账号。改为「优先用快重置的额度」后，请求优先使用额度最早重置的订阅账号；该账号用量达到 90% 后改用下一个账号；首选账号并发已满时立即顺延到下一个账号。

每分钟请求上限：添加或编辑账号时可填「每分钟请求上限」，留空表示不限。超过上限的请求自动落到池内其他账号；池内所有账号都到上限时，调用方收到 429，错误码 provider_account_rate_limited，稍后重试。

余额不足的冷却：账号余额不足时，本次请求换池内下一个账号继续，该账号进入冷却，状态列显示「冷却中」并在下一行写明原因与预计恢复时间。连续触发时冷却时长逐级加长：30 分钟 → 2 小时 → 8 小时 → 1 天 → 3 天 → 7 天（继续触发仍按 7 天）。在账号上选择「解除冷却」，或冷却结束后第一次调用成功，连续次数都会清零，之后再余额不足从 30 分钟重新开始。

注意：用不同地址登记多个账号，是平台内维护同一服务多实例的唯一方式。

4.5 配置传输超时、重试与健康检查

适用场景：上游响应慢、偶发失败，或需要让故障上游更快被识别。

操作步骤

1. 新建供应商时展开页面下方的「传输超时」「统一重试策略」「健康检查策略」三个折叠区；已有供应商在「编辑 AI 供应商」中修改。
2. 按下表调整数值，每项下方有含义说明。
3. 保存。再次打开编辑框，各项数值与勾选完整回显。

字段校验：超出范围或互相冲突时保存被拦，提示直接点名冲突字段，例如「连接超时不能大于首内容超时」；重试次数超上限时输入框上浮出「值必须小于或等于 5。」；探活间隔过小时提示「探活间隔须为 60 到 3600 秒之间的整数」。

注意：健康状态只影响路由优先级，请求照常发出，不会因一次探活失败就把供应商摘除；需要在失败时改走备用模型，应在流量规则中配置故障转移（第 15 章）。这些策略只在「编辑 AI 供应商」中可见。

4.6 查看可用性探查与上游余额

适用场景：日常确认供应商是否可用、排查调用失败、关注上游额度是否够用。

平台按「健康检查策略」的间隔周期探查供应商，默认每 300 秒一次；也可在「可用性探查」页签选择「连通性测试」立即发起一次。

你会看到：测试通常在数秒内返回结论并新增记录，列为「时间」「检查项」「结果」「健康状态」「延迟」，例如「对话 / 成功 / 健康 / 20 ms」。周期探查的历史一并保留，可判断故障是持续的还是偶发的。

探活历史里偶尔出现「未知接口 / 失败」这类记录，来自上游未实现的接口，与对话能力无关，判断是否可用以「对话」检查项为准。「基本信息」中的健康状态、失败原因与连接延迟取自不同时点，出现矛盾时以「可用性探查」最新一条为准。

上游余额：「基本信息」页签显示剩余额度与更新时间，例如「剩余额度 -0.118627 USD，更新于 3 分钟前」。该数字的来源取决于上游，有的返回真实余额，有的按累计用量推算，可能为负值；上游不提供余额查询接口时显示「此上游未提供余额查询接口」，是明确提示，不是加载失败。

注意：探查只代表探查时刻的连通性，调用失败的完整原因以请求详情为准（第 20 章）。点「连通性测试」后若无反馈、也无新增记录，先看「账号」页签；全部账号「异常」时，恢复可用账号后再试。

4.7 核验上游真实性

适用场景：通过中转渠道或第三方聚合平台接入模型时，确认上游实际提供的是所声明的模型，没有被替换、降级或做了协议翻译。

操作步骤

1. 进入供应商详情的「上游真实性」页签。核验只在点「核验」时运行，不会自动定期执行，模型初始为「未核验」。
2. 在目标模型行选择「核验」，等待结论，通常在一分钟内完成。
3. 选择「查看」打开核验详情，逐层读判断依据。

你会看到：每个模型给出总结论（「通过」「未通过」）与五层分项结果，另有一列「被动流量信号」。

注意：核验会向上游发送少量真实请求并消耗额度。能力层的视觉检查依赖向上游发送一张测试图片，若该上游对图片尺寸有最小限制，这一层可能因测试请求被拒绝而显示「未通过」；此时用尺寸正常的图片手动调用一次再判断。

4.8 对上游做性能测试

适用场景：上线前评估上游的延迟基线，比较不同供应商或不同账号的表现。

性能测试按并发阶梯向上游发送请求，测量首字延迟、字间延迟、端到端耗时与每 Token 耗时。页面明确两点：测试直连上游、不经过网关，不计入用量统计；测试与生产流量共用该供应商的额度，并发过高可能让线上请求被限流。

操作步骤

1. 进入供应商详情「性能测试」页签，选择「发起测试」。
2. 选择被测模型与并发档位；默认 1、4、16，可按需只保留较小的几档。
3. 填写每档请求数与输入 / 输出长度（Token），核对预估消耗（例如「本次最多消耗约 768 Token」），选择「开始测试」。

你会看到：开始约十几秒后出现第一个样本，概览给出各档的首字延迟、字间延迟、端到端耗时与每 Token 耗时并绘制趋势图；「分档明细」按档位列出各项指标。「取消测试」有二次确认，在途请求立即中止、已完成样本保留。发起与取消都记入「操作审计」，操作名为「发起供应商性能测试」。

注意：若进度长时间停在第一个请求，先「取消测试」，确认上游可达、模型可用后重试，并从最小档位开始。输出长度是随请求发给上游的建议值，部分上游不会严格遵循；解读端到端耗时要结合该档实际产出的 Token 量。

4.9 供应商配置的版本与变更追溯

适用场景：需要知道供应商配置何时被改过，以及确保错误配置不会直接生效。

操作步骤

1. 在供应商详情页右上角选择「编辑 AI 供应商」。
2. 按需修改描述、服务地址、接口能力、模型请求格式、超时、重试与健康检查策略，以及启用的模型。凭据统一在「账号」页签维护。
3. 选择「保存」。

每次保存都会生成一个新的配置版本，通过激活前校验后才生效，旧版本保留、不被覆盖。

激活前校验：保存时平台先用新配置做一次上游连接测试。未通过时提示「上游连接测试未通过，配置暂未生效；确认后可仍保存此配置」，确认后选择「仍要保存」才会激活。

变更追溯：「操作审计」页签按时间列出创建、更新、启停、性能测试等操作，更新类记录写明本次改动的项数，例如「更新模型供应商 · 修改 3 项」。

注意：详情页只展示当前生效的配置，没有历史版本列表与回退入口；需要回到旧配置时，按原值重新填写并保存，同样经过激活前校验。停用供应商（关闭「可用」或「开启」开关）只改变启停状态，不生成新版本。

能力说明

---

上一章：3. 组织与权限 · 下一章：5. 模型定价与分类