9Router 通用工具集成指南:用 OpenAI 兼容 API 连接任意应用
9Router 通用工具集成指南:用 OpenAI 兼容 API 连接任意应用
9Router 除了为 Claude Code、Codex、Cursor 等专用 CLI 提供集成外,还暴露了一个标准的 OpenAI 兼容 API 端点,任何支持 OpenAI 协议的工具——从 Python/Node 脚本、Postman 到 LangChain、LlamaIndex——都可以用几乎零成本接入。本篇指南完整讲解 9Router 的通用集成模式:Base URL 与鉴权配置、模型命名规则、多语言 SDK 示例、批处理与流式处理、环境变量管理、错误处理与重试,以及常见问题排障,读完即可把任意 OpenAI 兼容客户端接入 9Router。
概述:9Router 的通用接入能力
9Router 核心设计之一是“以 OpenAI API 格式统一转发”:对外它表现为一个 OpenAI 兼容服务,对内通过 translator 层 将请求转换成上游各家供应商(Anthropic、DeepSeek、Zhipu 等)的原生协议。因此,任何能发出 OpenAI 格式请求的客户端都能接入,包括:
- 自定义脚本与应用程序(Python、Node.js、Go 等)
- API 客户端与测试工具(Postman、Insomnia、cURL)
- CLI 工具与实用程序
- 第三方集成(自动化平台、工作流引擎)
- 开发框架(LangChain、LlamaIndex 等)
从源码结构看,这一兼容层的端点全部位于 src/app/api/v1/ 下,除 chat/completions 外还提供 embeddings、images/generations、audio/speech(TTS)、audio/transcriptions(STT)、search、web/fetch 等能力,其中 LLM 对话统一走 /v1/chat/completions。
通用接入模式:Base URL 与鉴权
任何 OpenAI 兼容工具,只需在设置中填写以下三个字段即可接入 9Router:
本地 9Router(自托管):
Base URL: http://localhost:20128/v1
API Key: your-api-key-from-dashboard
Model: 任意9Router模型 (cc/*, cx/*, glm/*等)
云 9Router:
Base URL: https://9router.com/v1
API Key: your-api-key-from-dashboard
Model: 任意9Router模型 (cc/*, cx/*, glm/*等)
几点说明:
- 端口 20128 是本地 9Router 服务默认监听端口,在 .env.example、docker-compose.yml 与 Dockerfile 中均可查到,自托管时确保该端口未被占用或按需修改。
- Base URL 必须带
/v1后缀:9Router 的 OpenAI 兼容路由注册在/v1前缀下,漏掉会导致 404。 - API Key 从 9Router 仪表盘获取;本地模式默认也要求携带 Bearer Token,与云端保持一致。
- Model 字段使用
别名/模型ID两级命名,下文详述。
可用模型:cc/*、cx/*、glm/* 命名规则
9Router 的模型 ID 采用 alias/modelId 格式,alias 是供应商短名,modelId 是供应商侧模型名。该规则在 模型信息接口 中实现:路由把 id 按第一个 / 拆分为 alias 与 modelId,再通过 ALIAS_TO_ID 映射到供应商。别名本身定义在 open-sse/providers/registry/ 下,例如:
- claude.js 中
alias: "cc"→ Claude 系列 - codex.js 中
alias: "cx"→ Codex/DeepSeek 系列 - glm.js 中
alias: "glm"→ Zhipu GLM 系列
文档给出的常用模型示例如下:
Claude 模型(Anthropic,前缀 cc/)
cc/claude-opus-4-5-20251101cc/claude-sonnet-4-20250514cc/claude-haiku-4-20250514
DeepSeek 模型(前缀 cx/)
cx/deepseek-chatcx/deepseek-reasoner
GLM 模型(智谱 AI,前缀 glm/)
glm/glm-4-plusglm/glm-4-flash
提示:完整可用模型列表可通过
curl http://localhost:20128/v1/models实时获取,返回内容即为当前实例实际可用的模型清单。模型 ID 区分大小写,请勿随意缩写。
集成示例:主流语言与 HTTP 客户端
以下示例均以本地 http://localhost:20128/v1 与 cc/claude-sonnet-4-20250514 为例,云端部署时只需替换 Base URL 与 API Key。
Python + OpenAI SDK
from openai import OpenAI
client = OpenAI(
api_key="your-api-key-from-dashboard",
base_url="http://localhost:20128/v1"
)
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[
{"role": "user", "content": "Hello, how are you?"}
]
)
print(response.choices[0].message.content)
Node.js + OpenAI SDK
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-api-key-from-dashboard",
baseURL: "http://localhost:20128/v1"
});
const response = await client.chat.completions.create({
model: "cc/claude-sonnet-4-20250514",
messages: [
{ role: "user", content: "Hello, how are you?" }
]
});
console.log(response.choices[0].message.content);
cURL 命令
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-from-dashboard" \
-d '{
"model": "cc/claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello, how are you?"}
]
}'
HTTP 客户端(Postman / Insomnia)
在请求面板中依次配置:
Request:
POST http://localhost:20128/v1/chat/completions
Headers:
Content-Type: application/json
Authorization: Bearer your-api-key-from-dashboard
Body:
{
"model": "cc/claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello, how are you?"}
],
"temperature": 0.7,
"max_tokens": 1000
}
temperature 控制输出的随机性(0 为确定性最高),max_tokens 限制单次响应最大 token 数,这两个参数与 OpenAI 官方语义一致。
LangChain 集成
from langchain.chat_models import ChatOpenAI
from langchain.schema import HumanMessage
llm = ChatOpenAI(
model_name="cc/claude-sonnet-4-20250514",
openai_api_key="your-api-key-from-dashboard",
openai_api_base="http://localhost:20128/v1",
temperature=0.7
)
messages = [HumanMessage(content="Explain quantum computing")]
response = llm(messages)
print(response.content)
LlamaIndex 集成
from llama_index.llms import OpenAI
llm = OpenAI(
model="cc/claude-sonnet-4-20250514",
api_key="your-api-key-from-dashboard",
api_base="http://localhost:20128/v1"
)
response = llm.complete("What is machine learning?")
print(response.text)
自定义脚本实战:批处理、流式响应与多模型对比
除了框架集成,9Router 也很适合在自定义脚本中作为统一 LLM 网关,一次配置、多模型调用。
批量处理脚本
以下脚本将多个 prompt 依次提交到 cx/deepseek-chat,收集结果后以 JSON 输出:
import openai
import json
openai.api_key = "your-api-key-from-dashboard"
openai.api_base = "http://localhost:20128/v1"
def process_batch(prompts, model="cx/deepseek-chat"):
results = []
for prompt in prompts:
response = openai.ChatCompletion.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
results.append({
"prompt": prompt,
"response": response.choices[0].message.content
})
return results
prompts = [
"Explain AI in one sentence",
"What is machine learning?",
"Define neural networks"
]
results = process_batch(prompts)
print(json.dumps(results, indent=2))
流式响应处理器
长回答场景建议开启 stream: true,逐 chunk 输出,降低首字延迟并减少内存占用:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-api-key-from-dashboard",
baseURL: "http://localhost:20128/v1"
});
async function streamResponse(prompt) {
const stream = await client.chat.completions.create({
model: "cc/claude-sonnet-4-20250514",
messages: [{ role: "user", content: prompt }],
stream: true
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || "";
process.stdout.write(content);
}
}
streamResponse("Write a short story about AI");
流式能力在服务端由 sse/handlers/chat.js 等处理器支撑,它会把上游各供应商的流式响应统一转换为 OpenAI 的 SSE 分片格式,因此客户端侧只需按 OpenAI SDK 的标准流式 API 消费即可。
多模型对比脚本
一个请求循环遍历 cc/、cx/、glm/ 三类模型,便于横向评估输出质量:
from openai import OpenAI
client = OpenAI(
api_key="your-api-key-from-dashboard",
base_url="http://localhost:20128/v1"
)
models = [
"cc/claude-sonnet-4-20250514",
"cx/deepseek-chat",
"glm/glm-4-plus"
]
prompt = "Explain quantum computing in simple terms"
for model in models:
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
print(f"\n=== {model} ===")
print(response.choices[0].message.content)
通用集成模式:环境变量、错误处理与重试
环境变量管理
把凭据与端点抽到环境变量中,避免把 API Key 硬编码进代码:
# .env文件
ROUTER_API_KEY=your-api-key-from-dashboard
ROUTER_BASE_URL=http://localhost:20128/v1
ROUTER_MODEL=cc/claude-sonnet-4-20250514
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("ROUTER_API_KEY"),
base_url=os.getenv("ROUTER_BASE_URL")
)
错误处理
所有请求都应包在 try-catch 中,统一捕获 OpenAIError:
from openai import OpenAI, OpenAIError
client = OpenAI(
api_key="your-api-key",
base_url="http://localhost:20128/v1"
)
try:
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)
except OpenAIError as e:
print(f"Error: {e}")
重试逻辑(指数退避)
针对限流(429)实现指数退避重试,避免打满上游配额:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
api_key="your-api-key",
base_url="http://localhost:20128/v1"
)
def chat_with_retry(prompt, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
except RateLimitError:
if attempt < max_retries - 1:
time.sleep(2 ** attempt) # Exponential backoff
else:
raise
故障排查
连接问题
现象: 无法连接 9Router
# 检查 9Router 是否在运行
curl http://localhost:20128/health
# 预期响应:
{"status": "ok"}
排查方向:
- 确认 9Router 进程正在运行
- 确认端口 20128 未被防火墙或代理拦截
- 确认 Base URL 拼写正确(必须包含
/v1)
认证错误(401 Unauthorized)
Error: Invalid API key
排查方向:
- 从仪表盘重新复制 API Key,确认未过期或被重置
- 确认请求头格式为
Authorization: Bearer your-api-key - 检查 API Key 前后是否有多余空格或换行符
模型未找到(404 Model not found)
Error: Model 'cc/claude-opus' not found
排查方向:
- 使用完整精确的模型名(模型 ID 区分大小写),如
cc/claude-opus-4-5-20251101 - 通过
curl http://localhost:20128/v1/models确认模型在当前实例中确实存在 - 确认当前账号/计划对该模型已启用(部分供应商模型按计划开放)
请求超时
Error: Request timed out after 30s
排查方向:
- 在客户端配置中调大超时时间(如 60s 或更长)
- 对时间敏感任务选用速度更快的模型(如
cc/claude-haiku-4-20250514、glm/glm-4-flash) - 检查客户端到 9Router 的网络链路质量
限流(429 Too Many Requests)
Error: Rate limit exceeded
排查方向:
- 在代码中实现指数退避重试(见上文示例)
- 降低单位时间内的请求频率
- 在仪表盘中查看当前限流阈值与用量
- 必要时升级计划以获取更高配额
最佳实践
安全
- API Key 一律存入环境变量,绝不硬编码
- 不要把 API Key 提交到版本管理仓库
- 云端部署场景使用 HTTPS 加密传输
- 定期轮换 API Key,降低泄露风险
性能
- 按任务复杂度选择合适模型:简单任务用轻量模型,复杂推理用旗舰模型
- 对重复查询做结果缓存
- 长响应优先使用流式输出
- 尽可能合并请求、批量提交
错误处理
- 所有调用包裹 try-catch
- 对限流与瞬时错误做指数退避重试
- 记录错误日志便于定位问题
- 为主流程提供降级/备用通道
成本优化
- 简单任务优先选择性价比高的模型(如
glm/glm-4-flash、cx/deepseek-chat) - 合理使用缓存减少重复计费
- 在仪表盘持续监控各模型用量
- 在代码层对请求频率设限
下一步
接入通用 OpenAI 兼容端点后,还可以继续探索 9Router 的专项集成与进阶能力:
- Cursor 配置指南:IDE 集成
- Continue 配置指南:VSCode 扩展
- CLI 基础用法:命令行直接调用
- 模型选择概览:了解全部可用模型与别名
- API 参考:
/v1/models、/v1/chat/completions等端点的完整参数说明