OpenAIHUB

统一 AI 接口网关 — 多供应商路由、负载均衡、熔断保护、幂等保证。

---

核心能力

模块	功能
Provider 适配器	16+ AI 供应商统一接口（OpenAI、Anthropic、DeepSeek、智谱、Kimi、阿里、腾讯、华为、火山引擎等）
虚拟模型路由	加权随机 / 延迟优先 / 优先级排序，自动故障转移
熔断器	以 channel:model 为粒度的三态熔断（Closed → Open → Half-Open），Redis 跨进程 + 进程内降级
幂等守卫	Idempotency-Key + Redis NX 锁 + SHA-256 请求体哈希，防止重复请求
重试策略	5 级错误分类（Rate Limit / Server Error / Client Error / Stream Break / Unknown），指数退避 + jitter
输入校验	完整的 OpenAI 兼容 API Zod Schema（Chat / Embeddings / Images / Audio / Moderations / Responses）
数据库 Schema	PostgreSQL + Drizzle ORM 表定义（渠道、Token、日志、虚拟模型、熔断事件、幂等事件）

快速开始

安装

npm install openaihub
# or
yarn add openaihub
# or
pnpm add openaihub

基础用法

import {
  ProviderAdapterFactory,
  breakerCheck,
  breakerSuccess,
  breakerFailure,
  chatCompletionSchema,
  validateBody,
} from "openaihub";

// 1. 选择供应商
const adapter = ProviderAdapterFactory.getAdapter("deepseek");

// 2. 流式调用
const stream = adapter.callChatCompletionStream(
  process.env.DEEPSEEK_API_KEY!,
  "deepseek-v4-flash",
  [{ role: "user", content: "你好" }],
  undefined,
  { temperature: 0.7 }
);

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

// 3. 输入校验
const result = validateBody(chatCompletionSchema, reqBody);
if (!result.success) {
  console.error("Validation error:", result.details);
}

熔断器示例

import { breakerCheck, breakerSuccess, breakerFailure } from "openaihub";

const scope = "channel-123:deepseek-v4-flash";

// 调用前检查
const check = await breakerCheck({ scope });
if (!check.allowed) {
  throw new Error(`熔断中: ${check.reason}`);
}

try {
  const result = await adapter.callChatCompletion(key, model, messages);
  await breakerSuccess({ scope }); // 成功上报
} catch (error) {
  await breakerFailure({ scope }); // 失败上报
  throw error;
}

幂等守卫示例

import { checkIdempotency, commitIdempotencyResponse, rollbackIdempotencyLock } from "openaihub";

const idempotencyKey = req.headers["idempotency-key"];
const check = await checkIdempotency(idempotencyKey);

if (!check.newRequest) {
  // 返回缓存的响应
  return new Response(check.cachedBody, { status: check.cachedStatus });
}

try {
  const result = await processRequest(req);
  await commitIdempotencyResponse(idempotencyKey, 200, JSON.stringify(result));
  return result;
} catch (error) {
  await rollbackIdempotencyLock(idempotencyKey);
  throw error;
}

Redis 配置

import { setRedisProvider, EnvRedisProvider } from "openaihub";

// 默认从 REDIS_URL / UPSTASH_REDIS_REST_URL 环境变量读取
setRedisProvider(new EnvRedisProvider());

// 或注入自定义 Redis 客户端
setRedisProvider({
  async getClient() {
    const Redis = await import("ioredis");
    return new Redis.default("redis://localhost:6379");
  },
});

支持的供应商

供应商	类型	基 URL
OpenAI	openai	https://api.openai.com
Anthropic	anthropic	https://api.anthropic.com
Google AI (Gemini)	google	https://generativelanguage.googleapis.com
Meta (Llama via Groq)	meta	https://api.groq.com/openai
智谱 AI	zhipu	https://open.bigmodel.cn
Kimi (Moonshot)	moonshot	https://api.moonshot.cn
DeepSeek	deepseek	https://api.deepseek.com
MiniMax	minimax	https://api.minimax.chat
Alibaba 百炼	alibaba	https://dashscope.aliyuncs.com
Tencent Hunyuan	tencent	https://api.hunyuan.cloud.tencent.com
ByteDance Ark	bytedance	https://ark.cn-beijing.volces.com
ByteDance Doubao	bytedance_doubao	https://ark.cn-beijing.volces.com
华为云 ModelArts	huawei	https://api.modelarts-maas.com
OpenRouter	openrouter	https://openrouter.ai/api/v1
xAI Grok	xai	https://api.x.ai/v1
小米 MiMo	xiaomi_mimo	https://api.xiaomimimo.com

数据库 Schema

-- 使用 Drizzle ORM 生成 PostgreSQL 表
-- 详见 src/schema/schema.ts

-- 核心表：
-- api_hub_channels     — 渠道配置
-- api_hub_tokens       — API Token 管理
-- api_hub_logs         — 调用日志
-- api_hub_virtual_models — 虚拟模型定义
-- api_hub_breaker_events — 熔断事件
-- api_hub_idempotency_events — 幂等事件

许可证

Apache License 2.0 — 详见 LICENSE

Copyright 2026 shoushinya

---

OpenAIHUB is part of a larger AI gateway platform. This package provides the core routing, provider adaptation, and reliability components.