OpenAI 兼容接入

多数团队最后都会回到一个很务实的目标：让调用层尽量只有一种写法。这样换模型、换供应商或做对比实验时，改动面才不会失控。

设计原则

你真正想统一的不是“品牌”，而是下面这三件事：

1. SDK 入口
2. 请求结构
3. 认证和观测方式

这也是为什么很多团队会把 api.clawsocket.com 放在接入层，而不是直接把多个上游揉进业务代码。

Node.js 示例

import OpenAI from "openai";

export function createLlmClient() {
  return new OpenAI({
    apiKey: process.env.CLAWSOCKET_API_KEY,
    baseURL: process.env.CLAWSOCKET_BASE_URL
  });
}

Python 示例

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["CLAWSOCKET_API_KEY"],
    base_url=os.environ["CLAWSOCKET_BASE_URL"],
)

result = client.chat.completions.create(
    model=os.environ["CLAWSOCKET_MODEL"],
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "输出一段中文测试文本。"},
    ],
)

print(result.choices[0].message.content)

cURL 示例

Authorization 头和请求体字段请以控制台文档为准。最小思路是：

curl "$CLAWSOCKET_BASE_URL" \
  -H "Authorization: Bearer $CLAWSOCKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$CLAWSOCKET_MODEL"'",
    "messages": [
      { "role": "user", "content": "给我一个接口联调检查项" }
    ]
  }'

常见误区

误区一：只改 base URL，不改配置层

如果模型名、超时、重试策略仍然散落在仓库里，接入层并没有真正统一。你只是把一个变量挪了地方。

误区二：把预览模型和正式模型共用一个别名

这样做短期方便，长期最危险。建议至少拆成：

• PRIMARY_MODEL
• CANARY_MODEL
• FALLBACK_MODEL

误区三：让前端直接持有真实 key

这类 key 必须只留在服务端。前端最多拿到你自己的业务 token，不应该直接接触真实上游密钥。

适合收敛在配置层的内容

• 当前使用的模型别名
• 默认超时时间
• 是否开启流式
• 是否开启主备切换
• 日志采样与错误上报

这些内容如果能集中在中转层或配置层，后续切换成本会明显下降。