五分钟上手
这篇从空配置走到第一个成功的 /v1/chat/completions 请求。示例用智谱作为上游,换成任意 OpenAI 兼容端点都可以。
1. 启动并打开管理台
omnigate start
浏览器打开 http://127.0.0.1:17777/manage。本地默认免登录;如果 config.yaml 里配了 admin.username / admin.password,先登录。
2. 添加提供商
进入 配置中心 → 提供商 → 新增。
| 字段 | 示例 |
|---|---|
| 名称 | zhipu |
| Base URL | https://open.bigmodel.cn/api/paas/v4 |
| 代理 URL | 留空(需要时再填) |
| 首字响应超时 | 120000 ms |
Base URL 要自带版本段(智谱是 /v4,OpenAI 是 /v1),网关不会自动推断。
3. 添加上游密钥
在刚创建的 zhipu 提供商下点 新增密钥,填入上游 API Key。名称只是标识,同一提供商内唯一。
4. 添加模型
进入 配置中心 → 模型 → 新增。
| 字段 | 示例 |
|---|---|
| 真实模型名 | glm-4.6 |
| 模型类型 | chat |
| 上游协议 | completions |
| 绑定密钥 | 勾选第 3 步的密钥 |
| 计费 | 按量,填输入 / 缓存 / 输出价格(可留 0) |
点 获取模型 可以从上游 /v1/models 拉列表,直接勾选真实模型名。
5. 创建逻辑路由
进入 路由 → 对话 → 新增。
| 字段 | 示例 |
|---|---|
| 模型别名 | glm |
| 端点类型 | completions |
| 目标模型 | zhipu / glm-4.6,权重 1 |
| 兜底模型 | 可留空 |
客户端请求里的 model 填的就是这个别名 glm。一个别名后面可以挂多个模型,按权重分流。
6. 创建虚拟密钥
进入 虚拟密钥 → 新增。创建成功后会弹窗给出完整 vk-...,复制保存;列表默认脱敏。
小时请求数、并发上限、日/月限额都可以留 0 表示不限制。正式发给别人时建议至少设一个日限额。
7. 发出第一个请求
curl http://127.0.0.1:17777/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer vk-xxxx" \
-d '{"model": "glm", "messages": [{"role": "user", "content": "你好"}]}'
看到正常的 OpenAI 格式响应就说明链路通了。
8. 把密钥交给使用者
把 vk-... 和门户地址 http://127.0.0.1:17777/portal 一起给对方。对方用密钥登录后,只能看到自己的用量、可调用的模型/MCP 和请求日志,全站只读,见 密钥门户。