@longzai-intelligence-model-gateway/sdk

TypeScript SDK for Model Gateway - 龙智智能模型网关官方 TypeScript SDK

目录

• 项目介绍
• 特性列表
• 安装说明
• 快速开始
• 基础使用
• 流式响应
• 管理API
• 错误处理
• 重试机制
• 拦截器
• 配置选项
• TypeScript支持
• API参考

项目介绍

@longzai-intelligence-model-gateway/sdk 是龙智智能模型网关的官方 TypeScript SDK。它提供了类型安全的 API 接口，让你能够轻松地与模型网关进行交互，实现统一的 AI 模型调用、管理和监控。

为什么选择这个 SDK？

• 统一接口：一个 API 调用多个 AI 提供商（OpenAI、Anthropic、Google 等）
• 智能路由：自动选择最优模型和提供商
• 成本优化：实时成本追踪和预算控制
• 类型安全：完整的 TypeScript 类型定义
• 开箱即用：内置重试、错误处理、拦截器等功能

特性列表

• ✅ 完整的 TypeScript 类型支持
• ✅ 聊天补全 API（Chat Completions）
• ✅ 文本补全 API（Completions）
• ✅ 文本嵌入 API（Embeddings）
• ✅ 流式响应支持（Server-Sent Events）
• ✅ 工具调用支持（Function Calling）
• ✅ 自动重试机制（可配置）
• ✅ 请求/响应/错误拦截器
• ✅ 完整的管理 API（提供商、模型、路由、预算等）
• ✅ 详细的错误类型和错误处理
• ✅ 零依赖（仅使用原生 fetch）

安装说明

使用 pnpm（推荐）

pnpm add @longzai-intelligence-model-gateway/sdk

使用 npm

npm install @longzai-intelligence-model-gateway/sdk

使用 yarn

yarn add @longzai-intelligence-model-gateway/sdk

环境要求

• Node.js >= 18.0.0（需要原生 fetch 支持）
• TypeScript >= 5.0.0（可选，用于类型支持）

快速开始

1. 创建客户端

import { ModelGatewayClient } from "@longzai-intelligence-model-gateway/sdk";

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
});

2. 发送聊天请求

const response = await client.chat.chat({
  model: "gpt-4",
  messages: [
    { role: "system", content: "你是一个有帮助的助手。" },
    { role: "user", content: "法国的首都是什么？" },
  ],
});

console.log(response.choices[0].message.content);
// 输出: 法国首都巴黎...

3. 流式响应

for await (const chunk of client.chat.chatStream({
  model: "gpt-4",
  messages: [{ role: "user", content: "讲一个短故事" }],
})) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

基础使用

聊天补全

import { ModelGatewayClient } from "@longzai-intelligence-model-gateway/sdk";

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
});

// 基础聊天
const response = await client.chat.chat({
  model: "gpt-4",
  messages: [{ role: "user", content: "你好！" }],
});

console.log(response.choices[0].message.content);

// 带参数的聊天
const response = await client.chat.chat({
  model: "gpt-4",
  messages: [
    { role: "system", content: "你是一个专业的程序员。" },
    { role: "user", content: "解释一下什么是闭包？" },
  ],
  temperature: 0.7,
  max_tokens: 500,
  top_p: 0.9,
});

// 查看网关附加信息
console.log("使用的模型:", response.gateway_model);
console.log("提供商:", response.gateway_provider);
console.log("成本:", response.gateway_cost);
console.log("Token 使用量:", response.usage);

文本补全

const response = await client.completions.complete({
  model: "gpt-3.5-turbo-instruct",
  prompt: "写一首关于编程的俳句：",
  max_tokens: 50,
  temperature: 0.8,
});

console.log(response.choices[0].text);

文本嵌入

const response = await client.embeddings.embed({
  model: "text-embedding-3-small",
  input: ["快速棕色狐狸跳过懒狗", "你好，世界！"],
});

console.log("嵌入向量数量:", response.data.length);
console.log("向量维度:", response.data[0].embedding.length);

模型列表

// 获取可用模型列表
const models = await client.models.list();

console.log("可用模型:");
for (const model of models.data) {
  console.log(`- ${model.id}`);
}

// 获取特定模型信息
const modelInfo = await client.models.get("gpt-4");
console.log(modelInfo);

工具调用

const response = await client.chat.chat({
  model: "gpt-4",
  messages: [{ role: "user", content: "巴黎和东京的天气怎么样？" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "获取指定城市的天气",
        parameters: {
          type: "object",
          properties: {
            city: {
              type: "string",
              description: "城市名称",
            },
          },
          required: ["city"],
        },
      },
    },
  ],
  tool_choice: "auto",
});

const toolCalls = response.choices[0].message.tool_calls;
if (toolCalls) {
  for (const call of toolCalls) {
    console.log(`工具: ${call.function.name}`);
    console.log(`参数: ${call.function.arguments}`);
  }
}

流式响应

基础流式调用

process.stdout.write("AI: ");

for await (const chunk of client.chat.chatStream({
  model: "gpt-4",
  messages: [{ role: "user", content: "讲一个有趣的故事" }],
})) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

console.log("\n");

流式工具调用

const toolCalls = new Map<number, { id: string; name: string; arguments: string }>();

for await (const chunk of client.chat.chatStream({
  model: "gpt-4",
  messages: [{ role: "user", content: "帮我查询北京的天气" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "获取城市天气",
        parameters: {
          type: "object",
          properties: { city: { type: "string" } },
          required: ["city"],
        },
      },
    },
  ],
})) {
  const delta = chunk.choices[0]?.delta;

  if (delta?.tool_calls) {
    for (const toolCall of delta.tool_calls) {
      const existing = toolCalls.get(toolCall.index) || {
        id: "",
        name: "",
        arguments: "",
      };
      toolCalls.set(toolCall.index, {
        id: toolCall.id ?? existing.id,
        name: toolCall.function?.name ?? existing.name,
        arguments: existing.arguments + (toolCall.function?.arguments ?? ""),
      });
    }
  }
}

console.log("收集到的工具调用:");
for (const [index, call] of toolCalls) {
  console.log(`  [${index}] ${call.name}(${call.arguments})`);
}

管理API

SDK 提供了完整的管理 API，用于管理提供商、模型、路由规则、预算等。

提供商管理

// 列出所有提供商
const providers = await client.admin.providers.list({
  page: 1,
  pageSize: 10,
});

// 创建新提供商
const provider = await client.admin.providers.create({
  name: "my-openai",
  type: "openai",
  endpoint: "https://api.openai.com/v1",
});

// 获取提供商详情
const details = await client.admin.providers.get(provider.id);

// 更新提供商
await client.admin.providers.update(provider.id, {
  status: "active",
});

// 删除提供商
await client.admin.providers.delete(provider.id);

模型管理

// 列出所有模型
const models = await client.admin.models.list({
  providerId: "provider-123",
});

// 创建模型配置
const model = await client.admin.models.create({
  name: "gpt-4-turbo",
  providerId: "provider-123",
  modelId: "gpt-4-1106-preview",
  inputPrice: 0.01,
  outputPrice: 0.03,
  maxContext: 128000,
  capabilities: ["chat", "function_call", "vision"],
});

// 更新模型
await client.admin.models.update(model.id, {
  status: "active",
  inputPrice: 0.008,
});

路由规则

// 列出路由规则
const rules = await client.admin.routing.list();

// 创建路由规则
const rule = await client.admin.routing.create({
  name: "cost-optimization",
  type: "cost-based",
  priority: 100,
  config: {
    preferCheaper: true,
    fallbackModels: ["gpt-3.5-turbo"],
  },
});

预算管理

// 创建预算
const budget = await client.admin.budgets.create({
  scopeType: "user",
  scopeId: "user-123",
  softLimit: 100,
  hardLimit: 150,
  period: "monthly",
});

// 查看预算使用情况
const usage = await client.admin.budgets.getUsage(budget.id);
console.log(`已使用: ${usage.usedAmount} (${usage.usagePercent}%)`);
console.log(`超过软限制: ${usage.isOverSoftLimit}`);

速率限制

// 配置速率限制
const rateLimit = await client.admin.rateLimits.create({
  scopeType: "user",
  scopeId: "user-123",
  requestsPerMinute: 60,
  tokensPerMinute: 100000,
});

API Key 管理

// 添加提供商 API Key
const apiKey = await client.admin.apiKeys.create({
  providerId: "provider-123",
  apiKey: "sk-xxx",
  keyAlias: "production-key",
});

// 列出 API Keys
const keys = await client.admin.apiKeys.list({
  providerId: "provider-123",
});

统计数据

// 获取使用统计
const stats = await client.admin.stats.getStats({
  startTime: "2024-01-01",
  endTime: "2024-01-31",
  groupBy: "day",
});

console.log("总请求数:", stats.requests.total);
console.log("成功率:", stats.requests.success / stats.requests.total);
console.log("总成本:", stats.cost.total);

错误处理

SDK 提供了详细的错误类型，方便进行精确的错误处理。

错误类型

| 错误类 | 说明 | HTTP 状态码 | | --------------------- | ---------------------------------- | ----------- | | GatewayError | 所有错误的基类 | - | | AuthenticationError | 认证失败（无效 API Key、权限不足） | 401, 403 | | ValidationError | 请求参数验证失败 | 400, 422 | | RateLimitError | 请求频率超过限制 | 429 | | NetworkError | 网络错误、超时等 | 5xx |

错误处理示例

import {
  ModelGatewayClient,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NetworkError,
  GatewayError,
} from "@longzai-intelligence-model-gateway/sdk";

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
});

try {
  const response = await client.chat.chat({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("认证失败:", error.message);
    console.error("状态码:", error.statusCode);
    // 处理认证错误，如刷新 API Key
  } else if (error instanceof ValidationError) {
    console.error("参数错误:", error.message);
    console.error("详情:", error.details);
    // 处理参数验证错误
  } else if (error instanceof RateLimitError) {
    console.error("请求过快:", error.message);
    console.error("等待时间:", error.retryAfter, "ms");
    console.error("限制详情:", error.limit);
    // 等待后重试
    if (error.retryAfter) {
      await new Promise((resolve) => setTimeout(resolve, error.retryAfter));
    }
  } else if (error instanceof NetworkError) {
    console.error("网络错误:", error.message);
    console.error("可重试:", error.retryable);
    // 根据情况决定是否重试
  } else if (error instanceof GatewayError) {
    console.error("网关错误:", error.message);
    console.error("错误码:", error.code);
    console.error("分类:", error.category);
  } else {
    throw error;
  }
}

错误信息结构

所有错误都包含以下属性：

interface GatewayError {
  name: string; // 错误名称
  message: string; // 错误消息
  code: ErrorCode; // 错误码
  statusCode: number; // HTTP 状态码
  category: ErrorCategory; // 错误分类
}

重试机制

SDK 内置了可配置的重试机制，自动处理临时性错误。

默认重试配置

const defaultRetryConfig = {
  maxRetries: 3, // 最大重试次数
  retryDelay: 1000, // 初始延迟（毫秒）
  exponentialBackoff: true, // 指数退避
  maxDelay: 30000, // 最大延迟（毫秒）
  retryableStatusCodes: [408, 429, 500, 502, 503, 504],
};

自定义重试配置

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
  retry: {
    maxRetries: 5,
    retryDelay: 2000,
    exponentialBackoff: true,
    maxDelay: 60000,
  },
});

使用预设配置

SDK 提供了多种预设的重试配置：

import {
  DEFAULT_RETRY_CONFIG,
  AGGRESSIVE_RETRY_CONFIG,
  CONSERVATIVE_RETRY_CONFIG,
  FAST_FAIL_RETRY_CONFIG,
  RATE_LIMIT_RETRY_CONFIG,
  createRetryConfig,
} from "@longzai-intelligence-model-gateway/sdk";

// 默认配置 - 适用于大多数场景
const client1 = new ModelGatewayClient({
  baseUrl: "...",
  apiKey: "...",
  retry: DEFAULT_RETRY_CONFIG,
});

// 激进配置 - 关键业务，更多重试
const client2 = new ModelGatewayClient({
  baseUrl: "...",
  apiKey: "...",
  retry: AGGRESSIVE_RETRY_CONFIG,
});

// 保守配置 - 非关键业务，减少重试
const client3 = new ModelGatewayClient({
  baseUrl: "...",
  apiKey: "...",
  retry: CONSERVATIVE_RETRY_CONFIG,
});

// 快速失败 - 需要快速响应
const client4 = new ModelGatewayClient({
  baseUrl: "...",
  apiKey: "...",
  retry: FAST_FAIL_RETRY_CONFIG,
});

// 速率限制专用 - 容易触发限流的场景
const client5 = new ModelGatewayClient({
  baseUrl: "...",
  apiKey: "...",
  retry: RATE_LIMIT_RETRY_CONFIG,
});

// 自定义配置（基于默认配置）
const client6 = new ModelGatewayClient({
  baseUrl: "...",
  apiKey: "...",
  retry: createRetryConfig({
    maxRetries: 4,
    initialDelay: 1500,
  }),
});

手动重试

import { withRetry, RetryManager } from "@longzai-intelligence-model-gateway/sdk";

// 使用 withRetry 包装函数
const result = await withRetry(
  async () => {
    return await client.chat.chat({
      model: "gpt-4",
      messages: [{ role: "user", content: "Hello!" }],
    });
  },
  { maxRetries: 3, initialDelay: 1000 },
);

// 使用 RetryManager
const retryManager = new RetryManager({
  maxRetries: 3,
  initialDelay: 1000,
  maxDelay: 30000,
  backoffFactor: 2,
});

const result = await retryManager.execute(async (context) => {
  console.log(`尝试 ${context.attempt + 1}/${context.maxRetries + 1}`);
  return await client.chat.chat({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  });
});

跳过重试

// 单次请求跳过重试
const response = await client.chat.chat(
  {
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  },
  { skipRetry: true },
);

拦截器

拦截器允许你在请求发送前、响应接收后、错误发生时进行自定义处理。

请求拦截器

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
});

// 添加请求拦截器
const removeInterceptor = client.useRequestInterceptor((config) => {
  console.log(`[请求] ${config.method} ${config.path}`);
  console.log("[请求体]", config.body);

  // 可以修改请求配置
  config.headers["X-Custom-Header"] = "custom-value";

  return config;
});

// 移除拦截器
removeInterceptor();

响应拦截器

client.useResponseInterceptor((response) => {
  console.log("[响应] 状态码:", response.status);
  console.log("[响应数据]", response.data);

  // 可以修改响应数据
  return response;
});

错误拦截器

client.useErrorInterceptor((error) => {
  console.error("[错误]", error.message);

  // 可以修改错误或进行日志记录
  if (error instanceof RateLimitError) {
    console.warn("触发速率限制，建议降低请求频率");
  }

  return error;
});

在配置中添加拦截器

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
  interceptors: {
    request: [
      (config) => {
        console.log("请求拦截器 1");
        return config;
      },
      (config) => {
        console.log("请求拦截器 2");
        return config;
      },
    ],
    response: [
      (response) => {
        console.log("响应拦截器");
        return response;
      },
    ],
    error: [
      (error) => {
        console.error("错误拦截器");
        return error;
      },
    ],
  },
});

实际应用示例

// 日志拦截器
client.useRequestInterceptor((config) => {
  config.headers["X-Request-Id"] = crypto.randomUUID();
  console.log(`[${new Date().toISOString()}] ${config.method} ${config.path}`);
  return config;
});

// 性能监控拦截器
const startTime = Date.now();
client.useResponseInterceptor((response) => {
  const duration = Date.now() - startTime;
  console.log(`请求耗时: ${duration}ms`);
  return response;
});

// 错误上报拦截器
client.useErrorInterceptor(async (error) => {
  await fetch("https://monitoring.example.com/errors", {
    method: "POST",
    body: JSON.stringify({
      message: error.message,
      code: error.code,
      timestamp: new Date().toISOString(),
    }),
  });
  return error;
});

配置选项

ClientConfig

创建客户端时的完整配置选项：

interface ClientConfig {
  /** 网关基础 URL（必填） */
  baseUrl: string;

  /** API 密钥（必填） */
  apiKey: string;

  /** 请求超时时间（毫秒），默认 30000 */
  timeout?: number;

  /** 重试配置 */
  retry?: Partial<RetryConfig>;

  /** 默认请求头 */
  defaultHeaders?: Record<string, string>;

  /** 拦截器配置 */
  interceptors?: Partial<Interceptors>;
}

RetryConfig

interface RetryConfig {
  /** 最大重试次数，默认 3 */
  maxRetries: number;

  /** 重试延迟（毫秒），默认 1000 */
  retryDelay: number;

  /** 是否启用指数退避，默认 true */
  exponentialBackoff: boolean;

  /** 最大延迟（毫秒），默认 30000 */
  maxDelay: number;

  /** 可重试的 HTTP 状态码 */
  retryableStatusCodes: number[];
}

完整配置示例

const client = new ModelGatewayClient({
  baseUrl: "https://gateway.example.com",
  apiKey: "your-api-key",
  timeout: 60000,
  retry: {
    maxRetries: 5,
    retryDelay: 2000,
    exponentialBackoff: true,
    maxDelay: 60000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  },
  defaultHeaders: {
    "X-App-Version": "1.0.0",
    "X-Platform": "node",
  },
  interceptors: {
    request: [
      /* 请求拦截器 */
    ],
    response: [
      /* 响应拦截器 */
    ],
    error: [
      /* 错误拦截器 */
    ],
  },
});

TypeScript支持

SDK 提供完整的 TypeScript 类型定义，支持类型推断和类型检查。

类型导出

import {
  // 客户端
  ModelGatewayClient,

  // API 类
  ChatAPI,
  CompletionsAPI,
  EmbeddingsAPI,
  ModelsAPI,

  // 管理API
  AdminAPI,
  ProvidersAPI,
  ModelsAPI as AdminModelsAPI,
  RoutingAPI,
  BudgetsAPI,
  RateLimitsAPI,
  ApiKeysAPI,
  AccessPoliciesAPI,
  AlertRulesAPI,
  StatsAPI,

  // 错误类
  GatewayError,
  NetworkError,
  AuthenticationError,
  RateLimitError,
  ValidationError,

  // 重试
  RetryManager,
  withRetry,

  // 类型定义
  ClientConfig,
  RequestConfig,
  RetryConfig,
  ChatCompletionRequest,
  ChatCompletionResponse,
  ChatCompletionChunk,
} from "@longzai-intelligence-model-gateway/sdk";

类型安全的请求

import type {
  ChatCompletionRequest,
  ChatCompletionResponse,
} from "@longzai-intelligence-model-gateway/sdk";

const request: ChatCompletionRequest = {
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
  temperature: 0.7,
};

const response: ChatCompletionResponse = await client.chat.chat(request);

泛型请求

interface CustomResponse {
  data: string;
  status: number;
}

const response = await client.get<CustomResponse>("/custom-endpoint");
// response 类型为 CustomResponse

API参考

ModelGatewayClient

主客户端类，提供所有 API 的访问入口。

属性

| 属性 | 类型 | 说明 | | ------------- | ---------------- | ------------ | | chat | ChatAPI | 聊天补全 API | | completions | CompletionsAPI | 文本补全 API | | embeddings | EmbeddingsAPI | 文本嵌入 API | | models | ModelsAPI | 模型列表 API | | admin | AdminAPI | 管理 API |

方法

| 方法 | 说明 | | ------------------------------------- | ---------------- | | request<T>(config) | 发送自定义请求 | | get<T>(path, query?, options?) | 发送 GET 请求 | | post<T>(path, body?, options?) | 发送 POST 请求 | | put<T>(path, body?, options?) | 发送 PUT 请求 | | delete<T>(path, options?) | 发送 DELETE 请求 | | patch<T>(path, body?, options?) | 发送 PATCH 请求 | | useRequestInterceptor(interceptor) | 添加请求拦截器 | | useResponseInterceptor(interceptor) | 添加响应拦截器 | | useErrorInterceptor(interceptor) | 添加错误拦截器 |

ChatAPI

聊天补全 API。

| 方法 | 说明 | | --------------------- | -------------------------- | | chat(request) | 发送聊天补全请求（非流式） | | chatStream(request) | 发送流式聊天补全请求 |

AdminAPI

管理 API 集合。

| 属性 | 类型 | 说明 | | ---------------- | ------------------- | ------------ | | providers | ProvidersAPI | 提供商管理 | | models | ModelsAPI | 模型管理 | | routing | RoutingAPI | 路由规则管理 | | budgets | BudgetsAPI | 预算管理 | | rateLimits | RateLimitsAPI | 速率限制管理 | | apiKeys | ApiKeysAPI | API Key 管理 | | accessPolicies | AccessPoliciesAPI | 访问策略管理 | | alertRules | AlertRulesAPI | 告警规则管理 | | stats | StatsAPI | 统计数据 |

许可证

MIT License

支持

如有问题或建议，请提交 Issue 或联系开发团队。