9Router 通用工具集成指南:用 OpenAI 兼容 API 连接任意应用

原创2026-09-11 10:54:521,613 阅读
文章标签:人工智能LLM 网关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-20251101
  • cc/claude-sonnet-4-20250514
  • cc/claude-haiku-4-20250514

DeepSeek 模型(前缀 cx/)

  • cx/deepseek-chat
  • cx/deepseek-reasoner

GLM 模型(智谱 AI,前缀 glm/)

  • glm/glm-4-plus
  • glm/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 等端点的完整参数说明
登录后查看全文
9router