9. 调用方、API 密钥、认证与授权

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

调用身份、访问授权与流量计数分别管理：调用方先用有效凭据通过认证，网关再按模型服务的可用范围判断是否允许调用，最后按配额、流量规则和全局限额决定是否放行以及如何计数。

9.1 理解调用对象

在流量规则中按调用方匹配时，先在条件分组「谁在调用」中选择「调用方类型」，再选择具体「主体」。调用方类型的可选项由平台按当前许可下发，例如「API 密钥」「平台用户」。调用身份只来自平台认证结果和网关的受信上下文，「验证规则」中输入的身份仅用于模拟，不构成真实授权；不要在普通请求头中自行声明其他用户身份。

9.2 API 密钥的创建与管理

API 密钥由成员在能力中心创建，管理员不在管理控制台中新建 Key。

• 成员创建：在「能力中心 → 模型广场」的模型详情选择「获取 API 密钥」，或在「能力中心 → 首页 → API 密钥」选择「创建 key」。每把 Key 绑定一个模型服务，可调用该服务下全部已启用模型，并按所选归属计入额度池。步骤与两个入口的差异（有效期、名称、原文是否再次可见）见第 8.3 节。
• 导入已有 Key：创建时在「指定 API 密钥（可选）」中填写已有 Key 字符串（32～512 位），适用于业务系统已经在使用某个 Key、需要迁移到网关的场景。
• 管理员管理：在「API 密钥管理」页签按名称或前缀、状态、模型服务、调用方检索全部 Key，执行轮换、禁用、删除和单独设置额度（第 6.7 节、第 7.5 节）。

为业务系统准备 Key 的建议流程：

1. 确定负责该业务系统的成员，确认其在目标模型服务的可用范围内（第 7 章）。
2. 由该成员创建 Key，选择与成本核算一致的「API 密钥归属」。
3. 立即把 Key 原文交付到业务系统的密钥管理系统。
4. 如需限制单把 Key 的消耗，由管理员在 Key 详情的「额度」中设置额度池。
5. 用最小请求完成一次调用，在「调用日志」或模型服务的「调用情况」中核对调用方、模型、状态和 Token。

Key 的状态包括“可用”“已禁用”“已过期”“已删除”（成员侧的“已撤销”与管理员侧的“已删除”对应同一状态）。业务系统收到鉴权失败时，应按错误码判断是 Key 状态问题还是网络问题，不要统一当作网络故障重试。

9.3 轮换、禁用和应急处理

常规轮换由管理员在「API 密钥管理」中执行：

1. 打开目标 Key 的详情，选择「轮换密钥」并确认。
2. 立即复制新密钥（只显示一次），更新到业务系统。
3. 旧密钥在宽限期内仍可用，到期自动失效。宽限期在「管理控制台 → 组织与权限 → 账号与会话安全」页面选择「安全策略」，在「模型 API 密钥轮换宽限期」中设置，默认 24 小时，范围 0～168 小时。
4. 在宽限期内确认业务系统已切换到新密钥。

成员不能轮换 Key。成员自行更换时，先创建新 Key 并完成切换验证，再「撤销」旧 Key。

发现泄露时不要使用轮换（旧密钥在宽限期内仍有效），应立即「禁用」或「删除」该 Key，再查询泄露后的调用记录。禁用后不能在管理控制台重新启用；删除不可恢复。两种操作都只阻止后续调用，不会删除已经生成的日志和用量记录。

9.4 分发能力和设置生效时间

模型服务、MCP 服务、Skill、外部智能体、API 服务等能力都通过同一个「可用范围」对话框授权，对象类型为「所有用户」「部门」「职能组」和「成员」。模型服务的操作步骤见第 7.1 节。

生效时间：

1. 在「可用范围」对话框选好对象后选择「下一步」，进入「配置目标有效期」。
2. 选择默认有效期：7 天、30 天、自定义或长期有效（默认长期有效）。自定义时设置「开始生效」和「结束生效」时间，结束时间必须晚于开始时间。
3. 需要为不同对象设置不同有效期时，开启「为选中角色分配单独有效期」。
4. 保存后检查对象行的状态：“N 后生效”“生效中”“剩余 N”或“已失效”，其中 N 为剩余时长，例如“2 小时 15 分”。
5. 使用目标成员账号验证能力列表可见、直接访问和实际调用。

已有对象的有效期可通过「编辑有效期」单独修改，改期只作用于当前对象。授权到期后请求被拒绝，页面也不再把该授权展示为有效；历史授权记录保留用于审计。

9.5 认证方式支持边界

外部连接器（如 MCP 服务）使用的上游认证方式，在对应连接器的鉴权设置中配置和测试，不属于模型调用的认证方式。

9.6 创建、启停并维护调用规则

入口：「管理控制台 → 路由策略 → 流量规则」，需要动态路由许可，并以租户管理员或「安全管理员」角色登录。页面页签为「规则清单」「全局限额」「意图集」「缓存」。完整说明见第 15 章。

1. 在「规则清单」中搜索目标规则，或选择「新建规则」，填写名称、调用类型和匹配条件。
2. 按业务选择转发、放行或拒绝，或增加检测、限额、改写等动作。核对增强规则和终止规则的区别。
3. 选择「保存规则」，在「确认变更」中核对字段差异、关联对象和命中顺序后选择「确认并应用」（新建与编辑都经过这一步，见第 15.3.1 节）。规则清单中的启停开关、拖动排序和删除在确认后直接生效。
4. 核对启用状态和下发提示，使用「验证规则」检查正例与反例，再通过实际入口验证目标、权限和执行结果。
5. 停用使用「停用」，修改使用「编辑」。删除前准备替代路由和保护，删除后不能在页面直接恢复。
6. 预览提示配置已被修改时，按提示重新生成预览后再确认，不要重复提交过期的确认。

授权的起止时间在可用范围中设置（第 9.4 节）。流量规则中的临时阈值和临时豁免只调整相应保护，不延长授权或凭据有效期。

9.7 调用身份、计数与配额

授权范围决定“是否可以调用”，匹配条件决定“是否适用某条规则”，计数维度决定“如何分别累计”。

1. 在模型服务的「可用范围与配额」中核对目标调用方的授权与有效期。

2. 在「规则清单」中选择真实入口提供的调用方身份作为条件。

3. 在「全局限额」中「新增限额」，「限制类型」可选「请求次数」「并发限制」「熔断」等（见第 15.4.2 节）。分别填写「匹配条件」和「计数维度」，例如匹配客服模型、计数维度选择「按 API 密钥」，使每把 Key 各自累计。

4. 配置阈值和处理方式，保存后核对下发状态。

5. 用范围内、范围外及不同计数对象的请求分别验证，确认没有把多方流量累计到同一对象。

6. 请求被拒绝时按错误码区分来源：

   错误码	来源
   POOL_EXHAUSTED	模型服务、部门、职能组、个人或单把 Key 的额度池用尽，错误详情的 scope_kind 指明对象类型（第 7.6 节）
   MODEL_SERVICE_QUOTA_HARD_REJECT	超出模型服务可用额度
   TRAFFIC_RATE_LIMITED	流量规则或全局限额的次数限速
   TRAFFIC_CONCURRENCY_LIMITED	同时进行的调用数已满
   TRAFFIC_CIRCUIT_OPEN	熔断打开

普通请求携带的任意身份或标签不能替代受信认证信息。调整组织成员、凭据或模型授权后，应重新验证路由条件与计数范围。

9.8 鉴权故障定位

---

上一章：8. 成员使用模型 · 下一章：10. 调用接口