一套代码接入所有大模型:OpenAI 兼容适配器设计

一套代码接入所有大模型:OpenAI 兼容适配器设计

OpenAI、DeepSeek、通义、智谱、火山方舟......为什么换个供应商不用改业务代码?

抽象的价值

如果业务代码里直接写 fetch('https://api.openai.com/v1/chat/completions'),那换 DeepSeek 就要改 URL、改鉴权、改响应解析------散落在各处,改一次崩一次。

解法:定义一个 Provider 接口,所有供应商实现它,业务代码只面向接口编程。

ChatProvider 接口

ts 复制代码
interface ChatProvider {
  chatStream(params: {
    model: string;
    messages: ChatMessage[];
    temperature?: number;
    signal?: AbortSignal;
  }): AsyncGenerator<{ delta?: string; usage?: TokenUsage }>;

  embed(params: {
    model: string;
    input: string[];
    signal?: AbortSignal;
  }): Promise<{ vectors: number[][] }>;

  listModels(): Promise<ModelInfo[]>;
  testConnection(signal?: AbortSignal): Promise<void>;
}

四个方法覆盖对话、向量化、模型列表、连通性测试。业务层(core)只认这个接口,不管底下是哪家。

OpenAI 兼容适配器

市面上绝大多数大模型服务都兼容 OpenAI API 格式(包括国内的 DeepSeek、通义、智谱、火山方舟等)。所以一个适配器就能吃下大部分供应商:

ts 复制代码
function createOpenAICompatible(config): ChatProvider {
  return {
    async *chatStream({ model, messages, temperature, signal }) {
      const response = await fetchSse(`${config.baseUrl}/chat/completions`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${config.apiKey}` },
        body: JSON.stringify({ model, messages, temperature, stream: true }),
        signal,
      });

      for await (const event of parseSse(response)) {
        if (event.data === '[DONE]') break;
        const delta = event.data.choices?.[0]?.delta?.content;
        if (delta) yield { delta };
      }
    },
    // embed / listModels / testConnection 类似
  };
}

用户在设置页填 baseUrl、apiKey、模型名,就能接入任何 OpenAI 兼容服务。

HTTP 底座:超时、重试、错误归一化

适配器底下是统一的 HTTP 封装,处理所有供应商共有的脏活:

超时

用 AbortSignal.timeout() 设默认超时(30s)。但 SSE 流特殊:响应头到达后解除超时,否则长回复会被误杀。

重试

只对可重试的错误重试:

  • 连接错误(网络抖动)✅ 重试
  • 5xx(上游临时故障)✅ 重试,指数退避
  • 4xx(用户输入/鉴权问题)❌ 立即失败
  • 客户端 abort ❌ 不重试

默认重试 2 次,退避 1s → 2s。

错误归一化

不同供应商的错误格式五花八门,统一成领域错误:

ts 复制代码
class ProviderError extends Error {
  status: number;        // HTTP 状态码
  providerMessage: string; // 上游原始消息
  retriable: boolean;    // 是否可重试
}

业务层不用关心上游返回什么格式,只处理归一化后的 ProviderError。

注册中心:按协议选适配器

ts 复制代码
const registry = {
  'openai-compatible': createOpenAICompatible,
  'ollama': createOllamaProvider, // 预留
};

function getProvider(protocol, config) {
  const factory = registry[protocol];
  if (!factory) throw new Error(`不支持的协议: ${protocol}`);
  return factory(config);
}

新增供应商?只要它兼容 OpenAI,用户填配置就行,代码一行不用改。不兼容?加个适配器实现 ChatProvider 接口,注册进去。

连接测试的设计

设置页有个「测试连接」按钮,用户填完 Key 还没保存就能测。这个接口允许用临时未保存的配置测试:

ts 复制代码
// providerTestSchema
z.union([
  z.object({ id: z.string() }),              // 测已保存的供应商
  z.object({ protocol, baseUrl, apiKey }),   // 测临时配置
]);

实现就是调 testConnection()(内部发一个最小请求,比如 GET /models),成功返回 { ok: true },失败返回归一化错误。

Embedding 的批量处理

OpenAI 的 embeddings 接口有限制(单次最多若干条输入)。适配器自动分批:

ts 复制代码
async embed({ model, input, signal }) {
  const BATCH = 64;
  const results: number[][] = [];
  for (let i = 0; i < input.length; i += BATCH) {
    const batch = input.slice(i, i + BATCH);
    const resp = await fetchJson(`${baseUrl}/embeddings`, {...});
    // 按 index 归位,防止乱序
    for (const item of resp.data) results[item.index] = item.embedding;
  }
  return { vectors: results };
}

还要校验维度一致性------同一批向量维度必须相同。

小结

一套代码接入所有大模型的关键:

  1. 面向接口编程 :定义 ChatProvider,业务层不认具体供应商
  2. OpenAI 兼容适配器:吃下 90% 的市场,用户填配置即用
  3. HTTP 底座统一:超时、重试、错误归一化,适配器只管协议差异
  4. 注册中心可扩展:新协议加个适配器,不动业务代码

这样,从 OpenAI 换到火山方舟,用户改个 baseUrl 就行,代码零改动。

下一篇聊聊「Electron 桌面应用的进程模型:为什么 fork Next.js standalone」。

相关推荐
用户216076340831 天前
一个 2 MB 的 .zst 文件,解压出来只有十几 KB
node.js
学无止境小袁同学1 天前
OpenAI Agents SDK 模板操作手册(可直接操作)
大模型·openai·agent·sdk·大模型应用
沉默王二1 天前
腾讯这波上大分,Hy4-flash值得你猛蹬。
openai·agent·vibecoding
可夫小子1 天前
OpenAI 用 Codex 修 ChatGPT 性能,1700 次调查只直接合入 15 个 PR
openai·ai编程
木头左2 天前
【浏览器自动化】用 CDP 接管本机 Chrome:从一个宿主迁到另一个宿主的设计与踩坑
node.js·浏览器自动化·cdp·技能化·踩坑实践
cpolar技术支持3 天前
把 agent-autoloop 装在 Mac 上:用本机 Node 实跑一次「接活—提问—拍板—接着干」,再用 cpolar 把它的状态页开给不在工位的自己
node.js·内网穿透·cpolar·ai agent·agent-autoloop
SEO_juper3 天前
Node.js 全站 SEO 体检报告生成器:一次查完标题、描述、canonical、H1、图片
开发语言·前端·node.js·html·bash
ZzT3 天前
GPT-6.2 API 降价 20%,为什么老代码直接切过去反而更费钱?
openai·ai编程
ndz3 天前
GPT-6.2 API 接入笔记:Sol / Astra 怎么选,思考强度和调用示例
openai
木头左4 天前
【Node.js】Markdown 转带图片 Word 文档实战:docx 库转换器设计与 5 个踩坑
node.js·word·markdown·文档自动化