API Key Groups（API Key 分组）

用一组逻辑边界，把成百上千把 Key 的配额、模型、路由、计费、风险、合规彻底分离开

如果说 Hydite Vtslx AO 是一座统一的大模型 API 高速路网，那 API Key Groups 就是这张路网上的 分区路政：每一个 Group 都是一个独立的逻辑边界，里面的 Key 共享同一套配额、模型白名单、路由策略、计费分摊、日志策略、风控规则。

一句话：Key 是身份，Group 是策略。 想批量管理几十、几百、上千把 Key，又不想被它们的差异淹没，就要用 Group。

绝大多数客户在调用量上来之后，90% 的运维问题、95% 的合规问题和 99% 的成本归因问题都能在 Group 这一层解决。这也是为什么我们把它放在「最值得讲」的位置。

1. 为什么单纯靠 Key 不够#

只有 Key 时，你迟早会撞到下面这些天花板：

• 配额没人管：所有 Key 共用同一个限流池，一个调用量爆掉，全公司一起 429。
• 账单分不清：上个月烧了 4 万美金，但说不清是哪个产品 / 团队 / 客户烧的。
• 模型一刀切：要么全员能用 GPT-4o，要么全员不能用，没办法只给某个高价值场景开通。
• 泄露半径无穷大：一把 Key 被前端代码意外提交到 GitHub，整个组织都跟着翻车。
• 路由策略冲突：A 团队希望走「最低延迟」，B 团队希望走「最低成本」，没法用同一套策略。
• 合规审计混乱：金融业务和营销业务的调用混在同一份日志里，过审计是噩梦。

Group 把上面六类问题一次性解决：每个 Group 都是一台独立的策略小机器，进出 Group 的所有调用都自动套上这台机器的规则。

2. 心智模型#

1
┌─────────────────────────┐
2
                          │      Organization       │   ← 顶层主体（一个公司一个）
3
                          └────────────┬────────────┘
4
                                       │
5
            ┌──────────────────────────┼──────────────────────────┐
6
            │                          │                          │
7
   ┌────────▼─────────┐      ┌─────────▼────────┐      ┌──────────▼─────────┐
8
   │  Group: prod      │      │ Group: staging   │      │ Group: customer-X  │
9
   │  • 100k RPM       │      │ • 1k RPM         │      │ • 500 RPM          │
10
   │  • $50k/月预算    │      │ • $500/月预算    │      │ • 客户专属计费     │
11
   │  • 全模型可用     │      │ • 仅便宜模型      │      │ • 仅 Anthropic     │
12
   │  • Latency-first  │      │ • Cost-first     │      │ • 客户白标日志     │
13
   └────────┬─────────┘      └─────────┬────────┘      └──────────┬─────────┘
14
            │                          │                          │
15
        ┌───┴───┐                  ┌───┴───┐                  ┌───┴───┐
16
        │ Keys  │                  │ Keys  │                  │ Keys  │
17
        └───────┘                  └───────┘                  └───────┘

继承顺序：Organization → Group → Key

• 任意一层都能定义配额、白名单、风控、Webhook、日志策略。
• 下层只能更严，不能更松。例如 Org 给 100k RPM，Group 至多 100k；Key 至多 Group 的值。
• 任何冲突都按**「最严格者胜出」**规则触发。

这意味着安全团队可以在 Org 层定一套兜底红线，业务团队在 Group 层做精细化配置，开发同学在 Key 层做最后微调 —— 各司其职、互不干扰。

3. 一个 Group 能配置什么#

这些能力中，配额、模型、计费归账、日志 在所有档位都可用；自定义路由策略 / Guardrail 规则集 / SIEM 导出 仅企业定制开放（详见 Dedicated Instance）。

4. 六个真实场景#

4.1 多环境隔离（最常见）#

把 dev / staging / prod 各拆一个 Group：

• dev：1k RPM、$200 预算、仅平台便宜模型（GPT-4o-mini / Haiku）、日志保留 7 天。
• staging：3k RPM、$1k 预算、与 prod 同模型集合、日志保留 30 天。
• prod：按业务峰值的 2 倍配额、足额预算、日志保留 1 年并导出客户 SIEM。

收益：研发误用昂贵模型不会拖垮 prod 预算；prod 出现异常不会被开发流量混淆。

4.2 多产品线 / 多业务单元#

一家公司同时跑 SaaS、H5 营销、内部 BI 三个产品：

1
Group: saas-app          Group: marketing       Group: internal-bi
2
RPM   60k                RPM   3k               RPM   200
3
预算  $30k                预算  $2k               预算  $300
4
模型  生产级 SLA          模型  仅图文摘要         模型  仅嵌入 + 排序
5
路由  Latency-first      路由  Cost-first         路由  最稳定的单点

月底直接打开控制台 Billing → Group，看到三个产品各自的成本曲线、token 消耗与单次调用成本，财务再也不用拉跨产品工单了。

4.3 白标多租户（SaaS 二级转售）#

如果你正在用 Hydite 做 LLM 中台并对外二次售卖，每一个下游客户 = 一个 Group：

• 客户 A 的所有应用调用都走 customer-a Group，只能调你给他开放的模型集合。
• 客户 B 用同一套 Hydite 实例，但 Group 内的配额、计费、日志、Webhook 全部独立。
• 你给客户的账单可以按月按 Group 自动生成，加上你自己的服务费 markup。
• 任何一个客户 Key 泄露都被锁在他自己的 Group 里，不会越界到其它客户。

这正是 Hydite 自己服务下游 PaaS 客户时的标准玩法。

4.4 安全分级 / 数据敏感度#

• public-website Group：只能调摘要 / 翻译类模型，强制 PII 脱敏，日志全量保存。
• customer-support Group：能调更强模型，但日志写入审计 Bucket、保留 7 年。
• red-team Group：开通越狱研究，只允许特定 IP，日志额外加密。

对应的合规审计直接以 Group 为单元出报告，不再需要在海量调用里筛选。

4.5 灰度新模型#

新模型上线时，先开一个 canary-claude-sonnet-4-5 Group：

• 路由策略改为 A/B 10%，90% 走旧模型，10% 走新模型。
• 配额限制在每分钟 200 次，避免新模型成本失控。
• 单独的 Webhook，错误率超过 1% 立即报警。
• 一周后效果好，把这 10% 路由策略合并回主 Group；效果不好，关闭 Group 即一刀切回滚。

灰度期间所有数据互不污染，决策依据干净清晰。

4.6 临时活动 / 黑客松 / 教学#

需要给 100 个学生 / 演讲嘉宾 / 黑客松选手发 Key 时：

• 建一个 event-2025-summit Group，单 Key TTL 7 天，单 Key 预算 $5。
• Group 总预算 $500、总 RPM 限制为单 Key 的 100 倍。
• 一键签发 100 把同 Group 的 Key（控制台批量生成）。
• 活动结束后，整个 Group 一键禁用，所有 100 把 Key 同步失效，无残留风险。

5. 五种常用拓扑#

最佳实践是先按合规边界切（不能跨的死活别合并），再按业务线切，最后按环境切。混合层数超过 3 层后管理成本会快速上升。

6. 三步上手#

Step 1 — 控制台创建 Group#

控制台 → Channels（API Key Groups） → Create Group。表单字段：

• Name：prod-api、customer-acme、event-2025-summit …
• Tier：选「Standard / Strict / Audit」三个预设，或选「Custom」走完整表单。
• 配额：RPM · TPM · 月预算 · 软预算。
• 模型白名单：从下拉里勾选允许的模型（支持按厂商整组勾选）。
• 路由策略：选预设或绑定企业版的自定义 YAML。
• 告警 Webhook：粘贴飞书 / 钉钉 / Slack 接收地址。

提交后立刻生成一个稳定的 Group ID，例如 grp_acme_prod。

Step 2 — 在 Group 里签发 Key#

同一页 → Generate Key in this Group：

• Alias：方便业务侧识别的别名，如 frontend-web。
• 过期时间 / TTL。
• Key 级别覆盖（可选）：进一步收紧 RPM / 模型范围。
• Tag：用于成本归账，例如 team=growth、env=prod。

签发后 Key 形如 sk-hydite-...，Group 信息嵌入 Key 元数据，业务调用时无需在请求里指明 Group。

Step 3 — 业务侧零代码切换#

1
client = OpenAI(
2
    api_key="sk-hydite-...",
3
    base_url="https://api.hydite.com/v1",
4
)
5
client.chat.completions.create(model="claude-sonnet-4-5", messages=[...])

不需要传 Group ID，Hydite 在收到请求时根据 Key 自动套上整个 Group 的策略包。要切换策略只需把业务上的 Key 换成另一个 Group 下的 Key —— 业务代码完全不动。

7. 运营 Playbook#

移动 Key#

需要把一把 Key 从 dev 改到 staging 时，控制台 Move to Group 一键切换；也支持 API：

1
curl -X POST https://api.hydite.com/key/move \
2
  -H "Authorization: Bearer $ADMIN_KEY" \
3
  -d '{"key": "sk-hydite-...", "to_group": "grp_acme_staging"}'

迁移不会改变 Key 字符串，业务侧无感。历史用量记录保留，新调用按目标 Group 策略生效。

批量操作

针对一个 Group 内的所有 Key 可以一键完成：

• 全部禁用 / 全部启用 / 全部轮换
• 修改默认 TTL / 默认模型
• 批量打 Tag / 改成本中心
• 批量推送 Webhook 配置

适合在合并部门、转换计费主体、年度合规审查等场景使用。

用量与成本归账

每个 Group 都暴露独立的接口与控制台视图：

• GET /spend/groups/{group_id} — token / 美元 / 调用次数
• GET /spend/groups/{group_id}/by-model — 按模型分摊
• GET /spend/groups/{group_id}/by-key — 找出 Top 消费者
• GET /spend/groups/{group_id}/timeline — 任意粒度时间序列

财务系统可以通过定时任务把每个 Group 的月度消费直接同步到 ERP / NetSuite / Workday，不再依赖人工核对。

审计与合规

每个 Group 拥有独立的审计流水，包括：

• 谁在何时修改了 Group 策略（控制台或 API）
• 谁在何时签发 / 撤销 / 移动了 Key
• 哪些调用触发了 Guardrail
• 哪些调用因预算 / 限流被拒绝
• 哪些 Webhook 已发出 / 已确认

这是出具 SOC2 / 等保 / HIPAA 报告时的「现成原件」。

应急封锁

异常时一把刀切下去：

• 控制台 → Group → Pause ⇒ 整个 Group 在 5 秒内停止响应。
• 控制台 → Group → Disable + Revoke all keys ⇒ 全部 Key 永久失效，需要重新签发。
• API： POST /group/{id}/quarantine ⇒ 进入隔离模式：只允许特定 IP 调用 / 仅允许 read-only 模型 / 强制全审计。

8. 与 Org / Team / Key 的关系#

Team 管"谁可以做"，Group 管"调用必须遵守什么"，二者正交。一个开发同学可以同时属于 Engineering Team，但他在 prod Group 里只能签出受限 Key，在 dev Group 里能签出更宽松的 Key。

9. 反模式（不要这样用）#

• ❌ 每把 Key 一个 Group：策略粒度倒挂，Group 失去价值。
• ❌ 把 Group 当 Tag 用：只挂 Tag 不开配额，发生事故时无任何防御。
• ❌ Group 嵌套太深：超过 3 层就会让审计与排查变成噩梦，建议用扁平命名 + 前缀。
• ❌ 不设默认 Group：很多团队所有调用都漏到 default，这相当于裸奔。
• ❌ 在 Key 上做差异化、Group 留空：升级、迁移、改路由时要逐 Key 调整，等于没用 Group。
• ❌ 共享一个 Webhook 给所有 Group：报警洪流互相覆盖，事故定位困难。

10. 是否所有档位都能用 Group？#

详见 Shared Edge Instance 与 Dedicated Instance。

下一步

• 配额与限流深入 → Rate Limiting
• 自定义子域名 → Custom Domains
• 想从一组 Key 升级到 Group 化运营？打开控制台 Channels → New Group，30 分钟跑通第一个分组。