4. 配置模型供应商

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

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

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

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

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

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

4.1 查看供应商列表

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

顶部搜索框按名称过滤。

4.2 新建、编辑并验证供应商

适用场景：首次接入一个公有云模型厂商、一个聚合平台，或企业内部自建的推理服务；已有供应商换地址、换密钥或增减启用模型。

前提：已拿到上游的请求地址与有效凭据。目录中带默认地址的供应商类型会预填地址；没有默认地址的类型必须自己填写，不填时字段下方提示「请填写服务地址」。

新增与编辑用同一个编辑页，布局也一致：左栏是连接配置（供应商、服务地址、API 密钥等，其余项收在「更多设置」中），右栏是「接口」与「模型」两个页签，页面底部一条常驻操作栏放「模型供应商名称」与取消、保存。两者的差别只有两处：编辑时各字段回填当前配置，模型页签直接列出该供应商已有的全部模型（见下文「编辑已有供应商」）。

操作步骤

1. 在「模型供应商」页签选择「添加模型供应商」，进入编辑页。
2. 在左栏「供应商」下拉中选择供应商类型。内置目录共 30 种，覆盖国内外云厂商、聚合平台与本地推理，例如 OpenAI、Anthropic、DeepSeek（深度求索）、通义千问、「本地部署」等。
3. 「服务地址」按实际端点填写。目录中带默认地址的类型已预填默认地址，接入中转或自建服务时替换为实际地址；类型没有默认地址时必须填写。
4. 在「API 密钥」中填写凭据，保存后它会成为一个账号（更多账号见第 4.4 节）。
5. 选择「测试连接并获取模型」。这一步只探测连接，不保存配置；结果框给出结论、逐条明细与下一步，见下方「结果框的三种结论」。
6. 切到右栏「模型」页签。表格打开即列出全部候选模型，不需要先点按钮：已启用的、已停用的、后台新发现的和本次没有获取到的都在同一张表里，表格上方一行汇总写明「将新建 N 个、关联 M 个、待处理 K 个；其中 P 个尚未定价」。
7. 逐行核对「决策」列：与已有模型同名（不区分大小写）的上游默认关联到该模型，其余默认新建同名模型，新建的名字在这一列给出，可以改成别的名字；关联到已有模型的项会显示影响（第 6.1 节）。勾选行后可以批量「启用」「停用」「按建议处理」「新建为独立模型」；模型多时表格分页，并用上方的搜索与筛选（全部、已启用、新发现、待处理、未定价）在同一张表内定位。
8. 接入本地部署的推理服务时，先在「接口」页签的接口表中声明接口（见下方「接入企业自建推理服务」）。
9. 在页面底部填写「模型供应商名称」，「更多设置」中的「描述」建议写明用途与负责人。
10. 选择「保存」。保存沿用第 5 步测试得到的结论，见下方「保存前的确认」。

结果框的三种结论：结果框按本次测试的结论换颜色与语气，三种结论对模型页签的影响不同。

部分可用的原因属于网关节点出口一类时（连接超时、域名解析、证书、代理），结果框另附一句说明该节点的出口网络由平台管理员维护。

连接失败时的提示：结果框不只报一句「失败」，结论之下是逐步明细：按接口分别列出「模型列表」「对话」的结果与上游原文；密钥被拒时写明凭据无效或已过期并附上游状态码，同时说明逐个尝试过的密钥传递方式全部被拒绝，可据此判断问题在密钥本身。

保存前的确认：保存沿用本次测试得到的结论。结论为「部分可用」时，确认框写明哪些网关节点当前连不上该服务、经这些节点的请求会失败，选择「仍要保存」才生效；结论为「不可用」时同样先确认再保存。改了服务地址、API 密钥、请求格式等连接字段后，结果框会提示「连接配置已改动，请重新测试」；此时直接保存，平台会按最新配置重新测试一遍再判断。

你会看到：保存后进入该供应商的详情页；回到列表，该供应商「可用」为开启，「账号」与「可用模型」两列显示可用账号数与已启用模型。

编辑已有供应商

适用场景：上游换了地址或密钥、要启用新到的模型、调整超时与重试，或修正请求格式。

操作步骤

1. 进入供应商详情页，在页头选择「编辑」；也可以在「模型供应商」列表的行菜单中选择「编辑」。两种入口进入的是同一个编辑页。
2. 左栏按需修改连接配置。目录中带默认地址的类型已预填默认地址，实际地址不同时替换；没有默认地址的类型必须填写。
3. 密钥框留空表示沿用已保存的密钥，需要换密钥时填写新的值。以账号池方式维护多个账号时，密钥在供应商详情的「账号」页签中管理，编辑页只提示到该页签处理（第 4.4 节）。
4. 「模型」页签打开即列出已启用、已停用、后台新发现与本次没有获取到的全部候选，不需要先点任何按钮。需要重新拉取上游当前提供的模型时，选择「测试连接并获取模型」，新拿到的模型按上游名合并进同一张表，已有行的启用状态与决策不变。
5. 「接口」页签中，本地部署的接口声明可直接在接口表里改，开关、路径与格式随保存一起生效。
6. 选择「保存」。保存沿用本次测试得到的结论，改过连接字段后按上文「保存前的确认」处理。

你会看到：保存后回到详情页，详情头部的更新时间刷新，「操作审计」页签多一条更新记录（第 4.9 节）。

注意：两个管理员先后编辑同一个供应商时，后保存的一方会看到「配置已被他人更新」，页面不会用旧内容覆盖别人的改动，可以载入最新配置后重做本次修改。有未保存改动时离开页面，会先确认再离开。

接入企业自建推理服务

自建的 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. 在编辑页展开左栏的「更多设置」，在「模型请求格式」中选择；新增与编辑都在同一处修改。
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 次尝试）」。

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

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

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

操作步骤

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

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

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

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

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

注意：用不同地址登记多个账号，是平台内维护同一服务多实例的唯一方式。以账号池方式维护多个账号时，密钥只在本页签中增删改；编辑页只提示「密钥在『账号』页签管理」，不在编辑页改密钥。

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

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

操作步骤

1. 在编辑页展开左栏的「更多设置」，其中「运行策略」一组含「传输超时」「统一重试策略」「健康检查策略」三个折叠区；新增时各项预填平台默认值，编辑时回填当前值。
2. 按下表调整数值，每项下方有含义说明。
3. 保存。再次打开编辑页，各项数值与勾选完整回显。

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

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

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

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

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

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

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

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

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

4.7 核验上游真实性

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

操作步骤

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

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

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

4.8 对上游做性能测试

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

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

操作步骤

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

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

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

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

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

操作步骤

1. 在供应商详情页页头选择「编辑」；也可以在「模型供应商」列表的行菜单中选择「编辑」。
2. 按需修改描述、服务地址、接口声明、模型请求格式、超时、重试与健康检查策略，以及「模型」页签中的启用与决策。单一身份的密钥留空即沿用已保存的密钥；以账号池方式维护的密钥在「账号」页签中改。
3. 选择「保存」。

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

激活前校验：保存沿用本次编辑中测试得到的结论。结论未全部可用时提示「上游连接测试未通过，配置暂未生效；确认后可仍保存此配置」，确认后选择「仍要保存」才会激活；改过连接字段后未重新测试的，保存时会按最新配置重新测一遍再判断。两个管理员先后保存同一个供应商时，后保存的一方会看到「配置已被他人更新」，载入最新配置后重做本次修改即可。

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

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

4.10 连接排查顺序与配置完成标准

适用场景：测试连接失败、保存后供应商显示异常，或员工反馈对话与调用报上游错误时，按固定顺序排查，避免反复改动无关配置。

排查顺序

1. 「请求地址」是否包含上游要求的协议、域名和路径；接入本地部署服务时，「服务地址」不要带接口路径，路径写在「接口」页签的接口表中。
2. 「账号」页签中的密钥是否仍有效、是否有调用目标模型的权限；异常账号的原因写在状态下方。
3. 平台所在网络能否访问该上游；内网部署访问公网厂商时，确认网关节点的出口已放通，可在平台控制台「运行监控 › 出口连通性」查看（第 33.13 节）。
4. 「供应商」类型与「模型请求格式」是否与上游实际协议一致（第 4.3 节）。
5. 「可用性探查」页签最新一条记录的「对话」检查项是否成功（第 4.6 节）。
6. 仍无法定位时，记录发生时间、供应商名称、页面上的错误明细与请求详情中的链路 ID，按第 37 章联系支持；不要在工单、截图或对话中记录或发送密钥。

配置完成标准：以下三项同时满足，才算一个供应商配置完成；只保存了名称和密钥，并不能保证员工可以使用。

• 「测试连接并获取模型」的结论为「连接正常」，或在结论未全部可用时确认后保存；
• 至少启用一个需要的模型，列表「可用模型」列显示该模型；
• 保存后列表中「可用」开关为开启，「账号」列显示至少一个可用账号，「健康」时间线最近一格正常。

注意：供应商配置完成后，模型还要加入模型分组并设置可用范围，员工和智能体才能使用（第 6 章、第 7 章）。

能力说明

---

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