接入客户端
OmniGate 对下游暴露 OpenAI 兼容接口,绝大多数支持自定义 Base URL 的 SDK 和 AI 工具都能直接接入。
通用参数
| 项 | 值 |
|---|---|
| Base URL | http://127.0.0.1:17777/v1 |
| API Key | 管理台创建的虚拟密钥 vk-... |
| Model | 管理台配置的逻辑路由名,例如 glm |
虚拟密钥不是上游密钥。上游密钥只在管理台里保存,由网关替换后再发给提供方。
OpenAI SDK
Python
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:17777/v1",
api_key="vk-xxxx",
)
resp = client.chat.completions.create(
model="glm",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
Node.js
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "http://127.0.0.1:17777/v1",
apiKey: "vk-xxxx",
});
const resp = await client.chat.completions.create({
model: "glm",
messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
环境变量
很多 CLI 和工具直接读环境变量,不必改代码:
export OPENAI_BASE_URL="http://127.0.0.1:17777/v1"
export OPENAI_API_KEY="vk-xxxx"
Anthropic 客户端
OmniGate 同时提供 /v1/messages 原生端点。Anthropic SDK 默认把密钥放在 x-api-key,而 OmniGate 的 /v1 只认 Authorization: Bearer,所以要用 SDK 的 auth_token / authToken 参数,而不是 api_key:
from anthropic import Anthropic
client = Anthropic(
base_url="http://127.0.0.1:17777",
auth_token="vk-xxxx",
)
base_url 填到根地址即可,SDK 会自己拼 /v1/messages。模型名仍然填路由别名(该路由的端点类型必须是 messages)。
常见 AI 工具
Cline、Cherry Studio、ChatBox、Open WebUI 等工具一般在「模型提供商」里选 OpenAI Compatible,然后填:
- API Base / Base URL:
http://127.0.0.1:17777/v1 - API Key:
vk-... - Model:路由别名
如果工具要求填“模型列表”,手动输入路由别名即可;也可以先访问 /v1/models 看当前可用的逻辑路由。
客户端如果跑在另一台机器或容器里,
127.0.0.1指向的是它自己。把启动层server.host改成0.0.0.0,并让客户端使用宿主机的局域网 IP。
常见错误
| 现象 | 原因 |
|---|---|
401 invalid virtual key | 虚拟密钥错误、被删除,或密钥被停用 |
403 key_disabled | 虚拟密钥被停用 |
402 budget_exceeded | 当日或当月额度用满 |
429 rate_limit_exceeded | 每小时请求数超限 |
429 concurrency_exceeded | 并发请求数超限 |
404 model not found | model 填的不是已配置的路由别名,也不是合法的 provider/model |
更多排查见 日志与排障。