Local Model SDK

基于 Transformers.js + ONNX 的本地模型 SDK，支持 Language Model（文本生成）和 Embedding（文本嵌入）功能，完全兼容 AI SDK 规范。

特性

• ✅ Language Model 支持：基于 Transformers.js 的文本生成能力
• ✅ Embedding 支持：高质量的文本嵌入向量生成
• ✅ 流式生成：支持实时流式文本输出
• ✅ 批量处理：高效的批量嵌入处理
• ✅ 模型缓存：自动管理模型文件缓存
• ✅ AI SDK 兼容：完全兼容 AI SDK v3 规范
• ✅ TypeScript：完整的类型定义支持
• ✅ 离线运行：无需网络连接，完全本地化

安装

pnpm add @easbot/local-model-sdk

快速开始

Language Model - 文本生成

import { LocalModelProvider } from '@easbot/local-model-sdk';
import { generateText } from 'ai';

// 创建 Provider
const provider = new LocalModelProvider({
  cacheDir: '.cache/models', // 可选，默认为 ~/.cache/easbot/models
});

// 创建 Language Model
const model = provider.languageModel('qwen2.5-0.5b-instruct');

// 生成文本
const result = await generateText({
  model,
  prompt: 'What is the capital of France?',
});

console.log(result.text);

Language Model - 流式生成

import { streamText } from 'ai';

const result = streamText({
  model,
  prompt: 'Write a short story about a robot.',
});

// 逐块输出
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Embedding - 文本嵌入

import { embed, embedMany } from 'ai';

// 单个文本嵌入
const result = await embed({
  model: provider.textEmbeddingModel('bge-small-zh-v1.5'),
  value: 'Hello world',
});

console.log(result.embedding); // number[]

// 批量文本嵌入
const batchResult = await embedMany({
  model: provider.textEmbeddingModel('bge-small-zh-v1.5'),
  values: ['Text 1', 'Text 2', 'Text 3'],
});

console.log(batchResult.embeddings); // number[][]

支持的模型

Language Models

| 模型 ID | 描述 | 参数量 | |---------|------|--------| | qwen3-0.6b | Qwen3 0.6B 基础模型 | 0.6B | | qwen2.5-0.5b-instruct | Qwen2.5 0.5B 指令模型 | 0.5B | | qwen2.5-1.5b-instruct | Qwen2.5 1.5B 指令模型 | 1.5B | | qwen2.5-3b-instruct | Qwen2.5 3B 指令模型 | 3B |

Embedding Models

| 模型 ID | 描述 | 维度 | |---------|------|------| | bge-small-zh-v1.5 | BGE Small 中文模型 | 512 | | bge-base-zh-v1.5 | BGE Base 中文模型 | 768 | | bge-large-zh-v1.5 | BGE Large 中文模型 | 1024 |

API 文档

LocalModelProvider

Provider 类，用于创建和管理模型实例。

const provider = new LocalModelProvider({
  cacheDir: '.cache/models', // 可选
});

方法

• languageModel(modelId: string): LocalLanguageModel - 创建 Language Model 实例
• textEmbeddingModel(modelId: string): LocalEmbeddingModel - 创建 Embedding Model 实例
• getLoadedModels(): ModelInfo[] - 获取已加载的模型列表
• dispose(): Promise<void> - 卸载所有模型，释放资源

LocalLanguageModel

实现 AI SDK 的 LanguageModelV3 接口。

const model = provider.languageModel('qwen2.5-0.5b-instruct');

// 非流式生成
const result = await generateText({
  model,
  prompt: 'Your prompt here',
  temperature: 0.7,
  maxTokens: 100,
});

// 流式生成
const stream = streamText({
  model,
  prompt: 'Your prompt here',
});

LocalEmbeddingModel

实现 AI SDK 的 EmbeddingModelV2 接口。

const model = provider.textEmbeddingModel('bge-small-zh-v1.5');

// 单个文本
const result = await embed({
  model,
  value: 'Your text here',
});

// 批量文本
const batchResult = await embedMany({
  model,
  values: ['Text 1', 'Text 2', 'Text 3'],
});

配置选项

Provider 配置

interface LocalModelProviderConfig {
  /** 模型缓存目录，默认为 ~/.cache/easbot/models */
  cacheDir?: string;
}

生成选项

// 通过 AI SDK 的 generateText/streamText 传递
{
  temperature?: number;  // 0.0 - 2.0，默认 0.7
  maxTokens?: number;    // 最大生成 token 数
  topP?: number;         // 0.0 - 1.0，默认 0.9
  topK?: number;         // 默认 50
  abortSignal?: AbortSignal; // 取消信号
}

错误处理

SDK 提供详细的错误类型：

import { LocalModelError, ErrorCode } from '@easbot/local-model-sdk';

try {
  const result = await generateText({ model, prompt: 'Test' });
} catch (error) {
  if (error instanceof LocalModelError) {
    console.error(`Error [${error.code}]: ${error.message}`);
  }
}

错误代码

• MODEL_NOT_FOUND - 模型未找到
• MODEL_LOAD_ERROR - 模型加载失败
• MODEL_NOT_INITIALIZED - 模型未初始化
• GENERATION_ERROR - 生成错误
• EMBEDDING_ERROR - 嵌入错误
• INVALID_INPUT - 无效输入
• ABORTED - 操作已取消

性能优化

模型复用

Provider 会自动复用已加载的模型：

// 第一次调用会加载模型
const model1 = provider.languageModel('qwen2.5-0.5b-instruct');

// 第二次调用会复用已加载的模型
const model2 = provider.languageModel('qwen2.5-0.5b-instruct');

批量嵌入

使用 embedMany 进行批量处理，性能更优：

// 推荐：批量处理
const result = await embedMany({
  model,
  values: ['Text 1', 'Text 2', 'Text 3'],
});

// 不推荐：逐个处理
for (const text of texts) {
  await embed({ model, value: text });
}

资源管理

使用完毕后释放资源：

// 卸载所有模型
await provider.dispose();

示例

查看 examples/ 目录获取更多示例：

• basic-usage.ts - 基本用法
• streaming.ts - 流式生成
• embedding.ts - 文本嵌入
• batch-embedding.ts - 批量嵌入
• model-switching.ts - 模型切换
• error-handling.ts - 错误处理

模型下载

首次使用时，模型会自动从 Hugging Face 下载。如需离线使用，请参考 模型下载指南。

技术栈

• Transformers.js - 浏览器和 Node.js 中的 Transformers
• ONNX Runtime - 高性能推理引擎
• AI SDK - Vercel AI SDK v2

许可证

MIT

相关项目

• @easbot/ollama-sdk - Ollama 模型 SDK