跳到主要内容

接入客户端

OmniGate 对下游暴露 OpenAI 兼容接口,绝大多数支持自定义 Base URL 的 SDK 和 AI 工具都能直接接入。

通用参数​

项值
Base URLhttp://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 foundmodel 填的不是已配置的路由别名,也不是合法的 provider/model

更多排查见 日志与排障。