"5分钟上手"不是口号，是真的只要5分钟——前提是网关已经部署完成（参考私有化部署全攻略）。本文从登录管理后台那一刻开始计时，到应用发出第一个成功调用为止，把每一步压到秒级。
应用侧只需要做两件事——改两个参数——就能让存量应用立即走通MAI Gateway。所有改动的核心是OpenAI兼容协议：替换Base URL + 替换API Key，业务代码一行不动。
一、计时开始：登录管理后台（30秒）
打开浏览器访问 http://<your-gateway>:8080，使用管理员账号登录。首次登录需要：
- 输入初始管理员账号（部署时运维提供）
- 修改默认密码（强制要求）
- 进入「模型目录」页面
这一步验证的是网关进程状态——如果能正常登录，说明服务正常、数据库连接正常、管理后台渲染正常。
二、第1分钟：开通模型（60秒）
在「模型目录」页面启用业务要用的模型：
✓ Qwen-Max 启用 256K上下文 复杂推理
✓ Qwen-Fast 启用 128K上下文 低成本
✓ DeepSeek-V4 启用 256K上下文 代码生成
✓ GLM-5.1 启用 128K上下文 国产合规
✓ Kimi K2.6 启用 512K上下文 超长文档
✓ MiniMax M2.5 启用 256K上下文 长上下文
操作：每行点"启用"即可。后台会自动同步上游配置到所有网关节点（集群版秒级生效）。
这一步验证的是上游连通性——启用过程中如果报错"上游连接失败"，说明网关到模型供应商的网络有问题，需要运维检查防火墙和出网白名单。
三、第2分钟：创建项目并分配密钥（90秒）
在「组织管理」→「项目」中创建第一个项目：
| 字段 | 填写示例 | 说明 |
|---|---|---|
| 项目名称 | 智能客服 | 项目唯一标识 |
| 部门归属 | 客服中心 | 用于预算分摊 |
| 默认配额 | 500,000 Token/月 | 起步保守，后续按需调 |
| 模型范围 | 全部启用模型 | 限制可见模型范围可收紧 |
创建完成后立即生成密钥：
项目：智能客服
密钥：sk-mai-prod-cs-a3f9b2c8d7e6
显示：sk-mai-prod-cs-a3f●●●
权限：仅本项目 · 全部模型
配额：500,000 Token/月 · 80%提醒 · 100%熔断
密钥只在创建时完整展示一次，立即复制保存。
这一步验证的是RBAC和配额体系——密钥已绑定到具体项目，所有调用会自动归集到这个部门的预算。
四、第3分钟：改造应用（90秒）
存量应用原本直接调用大模型API（如OpenAI），现在改为走MAI Gateway。改动只有两处：
改造前（直连OpenAI）
from openai import OpenAI
client = OpenAI(
api_key="sk-prod-openai-xxxxx", # OpenAI密钥
base_url="https://api.openai.com/v1"
)
改造后（走MAI Gateway）
from openai import OpenAI
client = OpenAI(
api_key="sk-mai-prod-cs-a3f9b2c8d7e6", # MAI Gateway密钥（仅改这一行）
base_url="http://your-gateway:8080/v1" # 网关地址（改Base URL）
)
response = client.chat.completions.create(
model="qwen-max", # 可用模型名从网关模型目录获取
messages=[{"role": "user", "content": "..."}]
)
两处改动：
api_key：从OpenAI密钥换成MAI Gateway分配的密钥base_url：从OpenAI地址换成MAI Gateway地址
业务代码、消息格式、调用逻辑全部不变。这就是OpenAI兼容协议的红利——存量应用5分钟内切换到企业级AI网关，不依赖任何框架重写。
这一步验证的是OpenAI兼容接入——如果应用改造后调用失败，最常见的原因不是协议不兼容，而是Base URL写错或模型名拼错。
五、第4分钟：第一次调用验证（60秒）
在终端用curl做一次冒烟测试，确认网关工作正常：
curl -X POST http://your-gateway:8080/v1/chat/completions \
-H "Authorization: Bearer sk-mai-prod-cs-a3f9b2c8d7e6" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-max",
"messages": [{"role": "user", "content": "你好"}]
}'
预期返回：
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1725432100,
"model": "qwen-max",
"choices": [
{
"message": {"role": "assistant", "content": "你好！"},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 5,
"completion_tokens": 4,
"total_tokens": 9
}
}
冒烟测试通过的两个关键信号：
- HTTP 200响应
- 返回JSON包含
usage字段（Token消耗已记录）
这一步验证的是端到端可用性——从密钥鉴权→配额校验→上游路由→调用成功→Token计量，全链路通畅。
六、第5分钟：查看调用流水（30秒）
回到管理后台「实时大盘」，应该看到刚才那条冒烟测试的调用记录：
14:32:08.518 客服/智能助理 sk-mai-prod-cs-a3f●●● qwen-max 9 Token 486ms ● SUCCESS
5个字段确认全链路通畅：
- 时间：调用发生时刻
- 项目：智能助理（密钥自动绑定到项目）
- 密钥：sk-mai-prod-cs-a3f●●●（脱敏显示）
- 模型：qwen-max（网关路由到的实际模型）
- Token：9（包含输入输出）
- 状态：SUCCESS
这一步验证的是审计体系——调用日志已经按"人·项目·密钥·模型·时间"全维度留痕，月末可以直接归集到部门预算。
七、计时结束：5分钟回顾
| 分钟 | 步骤 | 验证点 |
|---|---|---|
| 第0-30秒 | 登录管理后台 | 网关进程正常 |
| 第1分钟 | 启用模型 | 上游连通 |
| 第2分钟 | 创建项目+密钥 | RBAC+配额生效 |
| 第3分钟 | 应用改造（两行） | OpenAI兼容接入 |
| 第4分钟 | 冒烟测试 | 端到端可用 |
| 第5分钟 | 查看调用记录 | 全链路审计 |
5分钟结束，应用已经接入了企业级AI网关。所有大模型调用现在都自动：
- 走MAI Gateway的鉴权、配额、审计
- 按部门/项目分摊Token消耗
- 记录到全链路日志
- 享受七级配额80%提醒→95%告警→100%熔断的预算管控
八、上手后第一周要做的三件事
5分钟是入门，第1周才是真正发挥价值的时候：
第1件事：把其他存量应用迁移过来
存量应用分三类，分别处理：
- 直连OpenAI：改两个参数，5分钟迁移
- 直连Anthropic/Google：同样OpenAI兼容，改Base URL + API Key（Anthropic需用网关的兼容映射模型名）
- 用Dify/Cherry Studio等工具：在工具设置里把Base URL改成网关地址，API Key填网关密钥
第2件事：根据业务难度配置路由
不路由调度的网关等于没接。入门第一天按默认路由跑通，第二周开始调：
- 简单任务（短文本客服）：Qwen-Fast
- 复杂推理（多步骤分析）：Qwen-Max
- 代码任务（开发助手）：DeepSeek-V4
- 长文档（合同分析）：Kimi K2.6
第3件事：把部门预算设到合理值
网关默认保守配额（每项目50万Token），第一周观察真实消耗：
- 客服类：日均1-3万Token属正常
- 营销类：日均5-10万Token（含批量生成）
- 研发类：日均3-8万Token（含代码生成）
月底做预算审计：超出80%触发告警的项目，分析是配额设小还是真有异常调用。
九、5分钟上手的常见错误排查
| 现象 | 原因 | 解决方法 |
|---|---|---|
| curl返回401 | 密钥错误或网关未识别 | 确认密钥复制完整，无空格 |
| curl返回403 | 密钥配额耗尽或模型不在权限范围 | 检查配额用量、模型启用状态 |
| curl返回404 | Base URL路径错误 | 确认Base URL以/v1结尾 |
| curl返回500 | 上游连接失败 | 检查网关到上游供应商的网络 |
| 调用成功但Token为0 | 模型名拼写错误，回退到默认 | 检查model参数是否在模型目录 |
结语
5分钟快速上手的本质：把企业级AI治理能力压成两个参数改动。
应用侧改两行（Base URL + API Key），业务代码完全不动，立即获得——鉴权、配额、路由、审计、安全、计费六项治理能力。这正是OpenAI兼容协议的价值：让治理的复杂度从应用侧迁移到网关侧。
接入只是开始。第1个月用好路由和配额，第3个月跑通月末归集报表，第12个月Token进入财务预算——这是从"用起来"到"管起来"的完整路径。5分钟解决接入问题，5个月解决治理问题。
