SDK 与框架接入

SDK 与框架接入

> 平台网关兼容 OpenAI 接口协议：任何支持自定义网关地址的 OpenAI 典型 SDK 或框架改两个参数即可接入，本文给出主流语言接入样例与原生协议、实时语音、绘图、批量与 MCP 等特殊调用形态。

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key="sk-你的密钥",
)

# 非流式
resp = client.chat.completions.create(
    model="模型名",
    messages=[{"role": "user", "content": "用一句话介绍统一网关"}],
)
print(resp.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="模型名",
    messages=[{"role": "user", "content": "讲一个三段式的故事"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Node.js（openai SDK）

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.example.com/v1',
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: '模型名',
  messages: [{ role: 'user', content: '用一句话介绍统一网关' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

向量化与图像生成同理（client.embeddings.create / client.images.generate），端点见端点总表。

原生协议直连（Anthropic / Gemini）

除 OpenAI 兼容格式外，平台直接暴露两种原生协议入口，请求体与响应体按各自官方协议处理，调度、配额、计费链路与 OpenAI 入口完全一致——Claude / Gemini 官方 SDK 无需适配层即可直连：

# Anthropic Messages 协议（认证：x-api-key 头或 Authorization: Bearer）
curl https://api.example.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "模型名",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话介绍统一网关"}]
  }'

# Gemini 原生协议（认证：x-goog-api-key 头或 ?key= 查询参数）
curl "https://api.example.com/v1beta/models/模型名:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $API_KEY" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "用一句话介绍统一网关"}]}]
  }'

智能路由：客户端零改动

管理员开启智能路由后，把 model 填成 "auto"，网关在你的可用模型中自动选型（策略与评分见智能路由），客户端无需任何其他改动。计费与日志落在实际选中的模型名下；可用模型过滤后为空时返回 404 并说明 auto 无可用候选。

实时语音（WebSocket）

端点 GET /v1/realtime，OpenAI Realtime 协议的透明双向隧道——客户端事件原样透传上游。认证二选一：握手头 Authorization: Bearer（服务端客户端推荐），或子协议 Sec-WebSocket-Protocol: openai-insecure-api-key.<密钥>（浏览器 WebSocket 无法自定义请求头时，OpenAI SDK 默认即此形态）。

注意两条计费语义：按连接建立计一次调用（不是按消息条数）；实时连接不参与跨模型降级（连接建立后模型已定），断线重连会再计一次，客户端要做重连退避。

import asyncio, json, os, websockets

async def main():
    headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
    async with websockets.connect(
        "wss://api.example.com/v1/realtime?model=模型名",
        additional_headers=headers,
    ) as ws:
        await ws.send(json.dumps({
            "type": "response.create",
            "response": {"modalities": ["text"], "instructions": "用一句话打招呼"},
        }))
        async for message in ws:
            print(json.loads(message)["type"])

asyncio.run(main())

绘图 / 视频任务（MJ 兼容端点）

绘图与视频走 MJ 兼容端点：POST 提交任务、GET 查询进度。提交计数、轮询查询不计数——查询走本地任务表不产生上游调用，可放心高频轮询。认证沿用 Authorization: Bearer，并兼容 mj-api-secret 头。

# 提交绘图任务
curl https://api.example.com/mj/submit/imagine \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"prompt": "一座横跨算力集群的桥梁，工程插画风格 --ar 16:9"}'
# → {"code":1,"description":"提交成功","result":"任务号"}

# 轮询进度（status 到 SUCCESS 后 imageUrl 即成品地址）
curl "https://api.example.com/mj/task/任务号/fetch" -H "Authorization: Bearer $API_KEY"

视频生成同理（POST /mj/submit/video 提交、同端点查询）。任务记录与产物预览在使用日志的「绘图」「任务」分区可查。

批量与 MCP

批量 API：JSONL 上传 → 建批 → 跟踪 → 下载，五步同一把密钥，custom_id 逐行对账；MCP 工具网关：POST /mcp（JSON-RPC 2.0）三步握手 / 列目录 / 调用，标准库即可、无需专用 SDK。

框架接入

任何允许自定义 OpenAI base_url 的框架与工具（如 LangChain、Dify、各类聊天客户端与 IDE 插件）都按「改 base_url 为 https://api.example.com/v1、填平台密钥」两步接入，模型名以模型广场公示为准。框架侧的流式、工具调用、结构化输出等能力随所用端点协议（OpenAI 兼容 / 原生协议）自然可用。

错误响应结构

推理接口错误统一为 {"error": {"message", "type", "code"}} 结构，code 为机器可读错误码；管理 / 治理接口的业务拒绝多为 HTTP 200 + success:false + error_code。完整码表与重试纪律见错误码总表。