# GLOBAL AI GATEWAY 模型配置与购买指南

日期：2026-05-05

本文面向不熟悉 AI API、模型供应商和用量计费的客户管理员。目标是解释客户在门户里如何选择模型、购买 Service Credit、创建 API Key、管理小 B / C 两种模式下的用量，以及如何理解供应商路由、日志、审计和账单。

## 1. 基础概念

### Service Credit

Service Credit 是平台内的服务额度，用于消费 AI 服务。它不是钱包，不可提现，不可转让，不是现金或电子货币。客户购买 Service Credit 后，可以把额度用于文本、图像、视频、代码和智能体等 AI API 工作负载。

### 模型

模型是具体的 AI 能力，例如文本对话模型、图像生成模型、视频生成模型、代码模型。不同模型的价格、速度、质量、区域、数据留存和合规条件不同。

### 供应商

供应商是提供底层模型能力的上游平台，例如 DeepSeek、Doubao / 火山方舟、Kimi / Moonshot、GLM / 智谱等，也可以是 DPC、OpenRouter、LiteLLM、Portkey、私有模型集群、云厂商模型服务或企业自己的模型网关。GLOBAL AI GATEWAY 不应该锁死在某一个 provider、区域或行业场景里。系统会把供应商信息放入 provider policy 和通用 metadata，并根据合约、状态、区域、数据策略、能力、价格、SLA 和健康状态进行路由。

### 系统助手默认 Provider

系统内的 AI Chat 助手默认使用 DPC 作为后台大模型 provider。这里的“默认”只是当前部署选择，不是产品架构锁定。部署时保持 `ASSISTANT_PROVIDER=dpc`，并配置：

```text
DPC_API_KEY=...
DPC_BASE_URL=...
DPC_MODEL=...
```

如果没有配置 DPC 凭证，助手不会中断门户使用，会自动降级到本地规则回答和安全动作。客户侧可以继续用自然语言创建 key、查看 key 用量、查询模型目录；管理员侧仍然需要 admin secret，才能询问供应端、账单、审计、legal docs 和 monitoring 信息。

未来也可以把助手后台切到其他 OpenAI-compatible provider、内部模型网关或多 provider 路由层。对客户和管理员来说，应该看到的是统一的系统助手能力，而不是被迫理解后台具体是哪一家模型厂商。

### Provider Policy Metadata

Provider Policy 除了基础字段，还应支持可扩展 metadata。metadata 用来承载不适合写死在数据库列里的通用信息，例如：

- `protocol`：OpenAI-compatible、Anthropic-compatible、native REST、gRPC、batch、async job、private gateway。
- `workloadTypes`：text、chat、image、video、audio、embedding、rerank、coding、agent、moderation、speech、OCR、batch。
- `models`：每条模型路线的模型 ID、展示名、工作负载、endpoint、计费单位和状态。
- `commercialModels`：service credit、usage based、subscription、reserved capacity、BYOK、enterprise contract、fallback capacity。
- `jurisdictions`：US、EU、SG、HK、CN、global、contract-dependent 或客户指定区域。
- `complianceTags`：no-retention、metadata-only-logging、regional-routing-required、content-safety-review、DPA-required、resale-review-required。
- `slaTier` 和 `supportTier`：供应商 SLA、支持等级、升级路径。
- `customerSelectable`：客户是否能直接选择该 provider，还是只能由平台策略自动路由。

这样新增 provider、地区、模型类别或商业条款时，不需要重做门户信息架构，只需要新增 policy 和 metadata。

### API Key

API Key 是调用平台 API 的密钥。小 B 客户通常需要多个 key，例如按项目、部门、客户或环境拆分；C 端个人用户通常一个 key 就够。每个 key 都应该能看到独立请求数、消费金额、token 用量、模型和状态。

## 2. 小 B 和 C 两种使用模式

### 小 B 模式

适合工作室、小公司、代理商、团队或 reseller。建议：

- 一个组织账户下创建多个 API Key。
- 每个 key 绑定一个清晰用途，例如 `prod-webapp`、`marketing-image-gen`、`client-a-video`、`internal-coding-agent`。
- 按 key 查看消耗，避免下游客户或部门之间的成本混在一起。
- 给不同 key 配不同 scope 和预算上限。
- 财务对账时按 key、workspace、receipt、usage event 查询。

### C 端模式

适合个人开发者或个人用户。建议：

- 只创建一个主要 API Key。
- 用门户查看整体余额、最近用量和收据。
- 如果要测试不同模型，也可以临时创建测试 key，测试后撤销。

## 3. 选择模型前先选工作负载

不要一开始就问“哪个模型最好”。应该先明确用途。

### 文本 / Chat

适合：

- 聊天机器人
- 内容生成
- 摘要
- 翻译
- 分类
- 搜索增强问答
- 客服助手

常见配置：

- `model`: 文本模型 ID
- `messages`: 对话消息
- `max_tokens`: 最大输出长度
- `requiredNoRetention`: 是否要求上游不保留数据
- `region`: 区域偏好

### 图像生成

适合：

- 商品图
- 广告图
- 海报
- 头像
- 素材生成
- 创意草图

常见配置：

- `model`: 图像模型 ID
- `prompt`: 图片描述
- `size`: 图片尺寸
- `quality`: 质量
- `style`: 风格

注意：当前 testing build 展示图像生成的购买和接入路径，但真实图像 endpoint 仍需在后端接入对应供应商 API 后启用。

### 视频生成

适合：

- 产品短视频
- 广告素材
- 动态演示
- 社媒内容

常见配置：

- `model`: 视频模型 ID
- `prompt`: 视频描述
- `duration_seconds`: 时长
- `resolution`: 分辨率
- `fps`: 帧率

视频生成通常成本更高、异步时间更长，应单独配置预算和告警。

### 代码 / Agent

适合：

- 代码补全
- 测试生成
- 代码审查
- 自动修复
- 内部 agent workflow

常见配置：

- `model`: 代码模型 ID
- `task`: 任务说明
- `repository`: 仓库或项目标识
- `tools`: 允许调用的工具

代码模型可能涉及商业源码，需要更严格的数据留存、日志和权限策略。

## 4. 模型购买与接入流程

建议流程：

1. 在客户门户打开 Model Marketplace。
2. 按工作负载筛选：Text、Image、Video、Coding。
3. 查看每个模型路线的供应商、状态、区域、价格和合规条件。
4. 把需要的模型加入 Purchase Plan。
5. 确认购买额度和用途。
6. 创建 API Key。
7. 分配 key 给项目、部门或下游客户。
8. 调用 API。
9. 在 API Key Usage 里按 key 查看消耗。
10. 在收据和账单里对账。

当前 testing build 的 Purchase Plan 是购买和接入意向清单，还不是正式 checkout。正式 checkout 需要接入支付、订单、发票、税务、退款和合同条款。

## 5. API Key 配置建议

### 小 B 推荐命名

- `prod-main-app`
- `staging-test`
- `client-a-text`
- `client-b-image`
- `marketing-video`
- `internal-coding-agent`

### C 端推荐命名

- `personal-main`
- `personal-test`

### Scope 示例

文本 key：

```text
chat.completions
usage.read
```

多模态 key：

```text
chat.completions
images.generate
videos.generate
usage.read
```

代码 agent key：

```text
chat.completions
code.run
usage.read
```

生产环境不应所有 key 都给 `*` 权限。不同 key 的权限越清楚，后续审计和风控越容易。

## 6. 供应商状态说明

### active

供应商已配置 API key，且 policy 允许参与路由。

### inactive

供应商显示在目录里，但不会真实调用。常见原因：

- 还没有供应商 API key
- 合同还没审核
- 转售授权未确认
- 风险状态未通过

### evaluation_needed

表示需要商务、法务或技术评估。尤其是商业转售、数据处理、内容安全和 SLA。

## 7. 路由策略

一次请求不一定固定走某一个供应商。平台会根据以下条件筛选：

- 模型是否支持
- 供应商是否 active
- 是否允许转售
- 合约状态是否有效
- 区域是否满足
- no-retention 是否满足
- 供应商健康状态
- 价格和成本
- fallback 可用性

如果供应商失败，平台可以尝试另一个合规供应商。fallback 事件会进入 audit log。

## 8. 计费与账单

每次 AI 请求会形成 usage event，通常包含：

- request id
- organization id
- workspace id
- api key id
- provider id
- model id
- prompt tokens
- completion tokens
- customer charge
- provider cost
- pricing snapshot
- status
- created at

平台会将 usage event 连接到 ledger journal。客户侧看到的是 Service Credit 余额和消耗，Admin 侧看到客户计费、供应商成本、毛利、账本和审计证据。

## 9. 日志与隐私

默认原则：

- 记录 metadata。
- 不默认记录 raw prompt。
- 不默认记录完整模型响应。
- 不在 audit metadata 中写 API secret。
- request id、provider id、model id、usage、billing 可以记录。

如果客户要求 no-retention，路由必须筛掉不满足该要求的供应商。

## 10. 监控与告警

生产系统应至少有这些监控：

- 网关健康检查
- 上游供应商可用性
- 请求成功率
- P95 / P99 latency
- 供应商错误率
- fallback 次数
- 每 key 消费异常
- 每组织余额不足
- 月度预算快耗尽
- 审计链完整性
- 支付 webhook 失败
- ledger journal 异常

testing build 已经展示 monitoring surface，正式生产需要接入外部 uptime、metrics、log sink 和 alert channel。

## 11. 常见问题

### 为什么我看到某个模型是 inactive？

说明平台知道这个供应商或模型路线，但还没有完成 API key、合同、授权或风控配置。

### 我是小 B，应该买几个 key？

建议至少按用途拆：

- 生产 key
- 测试 key
- 每个下游客户一个 key
- 高成本视频或图像单独 key

### 为什么要按 key 看用量？

因为小 B 会有多个项目、客户或部门。按 key 对账可以知道是谁用了额度、用了什么模型、花了多少钱。

### 图像和视频可以跟文本共用余额吗？

可以。Service Credit 是统一额度，但不同工作负载有不同价格和风控策略。

### 客户可以直接选择供应商吗？

客户可以选择模型路线或偏好；最终是否可路由，还要看供应商状态、合约、区域、数据策略、健康状态和管理员配置。

## 12. 上线前必须完成

- 正式登录、RBAC、MFA 或 passkey
- API key scope 和预算上限
- 供应商 API key 安全存储
- 供应商转售授权
- ToS、隐私政策、DPA、SLA、退款条款
- 支付、订单、收据、税务和退款流程
- 外部监控和告警
- 日志留存策略
- 审计导出
- 客户级账单下载
- 模型目录版本管理