供应商集成 BYOK
接入企业自有模型供应商，打通企业模型、项目权限、调用验证和故障回退。
1. 先确认 BYOK 解决什么问题
BYOK 是 Bring Your Own Key，即“使用自有供应商密钥”。企业已在模型厂商购买资源或有单独协议时，可把该账号接入网关，继续使用自己的资源，同时集中管理连接信息和调用记录。只使用胜算云平台模型的企业无需配置 BYOK。配置属于企业范围，由具备 BYOK 管理权限的账号维护。
2. 从供应商侧准备连接信息
先在所选供应商的控制台确认该供应商页面要求的项目、区域、接入地址、部署或模型标识和密钥。不同供应商要求不同，以添加页面中的必填项为准。
- 密钥仍在有效期内，并拥有目标模型或部署的调用权限。
- 区域、接入地址和部署名称相互匹配，不混用测试与生产环境。
- 供应商账户余额、额度和限流可以承接预期流量。
- 只为网关授予完成调用所需的最小权限。
3. 添加并验证供应商
- 进入企业管理的「BYOK」，在“可用供应商”找到目标供应商并点击“配置”；已有配置时点击“编辑”。
- 选择供应商类型，按页面要求填写连接信息和密钥。
- 选择企业准备开放的模型或部署范围。
- 按需决定是否允许同模型的胜算云渠道回退。
- 保存后确认供应商配置、模型范围和回退设置都已刷新。
按供应商维护连接配置，再到项目中核对模型与成员授权。
影响与边界
完整密钥保存后不再回显。保存失败时重新填写敏感信息，不要把密钥贴到截图、工单或聊天记录中。
4. 把模型真正交付给项目成员
供应商保存成功代表接入配置已建立。接下来按模型管理和成员权限规则交付给使用者；项目模型授权是网关通用能力，不是 BYOK 独有能力。
- 确认目标模型已进入企业可用模型目录。
- 进入目标项目的「模型管理」；模型限制开启时，把目标模型加入项目允许清单。
- 进入「项目成员」的模型权限配置，为目标角色授予该模型。
- 使用目标成员自己的项目 API Key 验证，管理员身份不能代替成员权限。
5. 决定是否允许付费回退
回退只是在当前模型的 BYOK 接入失败时，决定是否允许同一模型改走胜算云渠道；它不会自动换成另一种模型。
| 失败原因 | 是否允许回退 | 需要注意 |
|---|---|---|
| 凭证无效、供应商限流、超时或不可用 | 开启回退时可以 | 实际转入胜算云渠道后产生平台消费 |
| 请求参数错误 | 不可以 | 修正请求后重试 |
| 账号、项目或模型权限拒绝 | 不可以 | 回到成员、模型和凭证范围排查 |
| 内容安全拒绝或未开通平台权益 | 不可以 | 不会通过付费回退绕过限制 |
6. 用真实调用验证接入结果
- 切换到目标项目和目标成员权限，确认模型可见。
- 使用属于该成员和项目的 API Key 发起一次直连调用。
- 如业务使用路由，再用路由 ID 发起多次测试调用。
- 在调用日志中核对实际模型、接入方式、结果和平台费用。
- 主动制造受控的供应商失败场景时，只验证已允许的回退边界，不在生产流量上试错。
需要注意
验证完成的标志不是“供应商已保存”，而是目标成员能调用，且日志中的实际渠道和费用归属符合预期。
7. 安全轮换供应商密钥
- 在供应商侧创建新密钥，暂时保留旧密钥。
- 在 BYOK 配置中更新密钥并保存。
- 使用目标项目和模型完成真实调用验证。
- 确认日志已使用预期接入方式后，再在供应商侧撤销旧密钥。
8. 停用或删除前检查影响
先确认该供应商配置关联的企业模型，以及这些模型被哪些项目、角色和路由使用。停用或删除后，依赖该渠道且没有其他合法接入路径的调用会失败。
影响与边界
不要把开启回退当作无条件兜底。目标模型没有可用胜算云渠道、平台权益未开通或失败原因不在允许范围内时，调用仍会失败。
9. 模型不可见或调用失败时
- 企业层：检查供应商密钥、区域、接入地址、部署、额度和连接结果。
- 项目层：检查模型是否进入企业目录和当前项目允许范围。
- 成员层：检查当前账号的项目关系、角色和模型权限。
- 调用层：检查 API Key、模型或路由是否属于同一项目。
- 结果层：用请求 ID 在调用日志中确认实际渠道、错误和费用，不只看供应商配置状态。