@easbot/llm weekly downloads statistics

@easbot/llm

English | 中文

@easbot/llm 是 EASBot 生态系统的 AI 模型聚合层，负责多厂商 SDK 的动态加载、模型路由、配置管理与高层 Model Provider 的能力封装。给业务包（agent / codebase / memory / note / skills / gateway）提供统一的 LLM 调用抽象，避免每个工具包重复实现 provider 路由、auth 管理和错误归一化。

版本

v0.3.29

当前状态（V4 重构后）

本包已从 @easbot/types 的早期占位实现演化为承载 provider/ + model/ 两套核心模块** 的生产级 AI 网关层：

• ✅ src/provider/（7 文件）：完整的工业级 provider 抽象
  • Provider 命名空间 —— 25+ 内置 SDK（OpenAI / Anthropic / Azure / Bedrock / Vertex / OpenRouter / Copilot / Ollama / 本地模型等）的动态加载器、ModelsDev catalog 合并、模型缓存、SDK 实例池化
  • ProviderError 命名空间 —— APICallError 解析（含 25+ 种"上下文溢出"模式正则识别）
  • ProviderAuth 命名空间 —— OAuth + API key 双轨认证
  • ProviderTransform 命名空间 —— 模型 variant / tool / 限制处理
  • ModelsDev 命名空间 —— models.dev catalog 的 zod schema + 加载 + 远程刷新
  • definition.ts —— DEFAULT_ENABLED_PROVIDERS 白名单 + CUSTOM_PROVIDER_DEFINITIONS 本地 SDK 快照 + PROVIDER_DISPLAY_NAMES 友好名映射
  • sdk/copilot/ —— 自研 GitHub Copilot 兼容 SDK（chat + responses + 6 个 tool）
• ✅ src/model/（4 命名空间）：高层 Model Provider
  • RerankProvider 命名空间 —— LLM 驱动的文档重排序（与 Memory 混合搜索权重统一）
  • GraphProvider 命名空间 —— 从非结构化文本提取实体关系（11 类 EntityType + 9 类 RelationType）
  • SummaryProvider 命名空间 —— note / memory 摘要（LLM-based）
  • EmbeddingProvider 命名空间 —— 文本嵌入（单文本 / 批量；走 AI SDK 标准 embed / embedMany；默认模型 easbot-local/bge-base-zh-v1.5）
• ✅ src/config/（V3 新增）：独立 LLM Config 模块，仿 packages/gateway/src/config/ 模式
  • LLMConfig / ProviderConfig / ProviderAuthMethod —— zod schema（独立可用，也可作为注入 Config 的实现来源）
  • Config namespace —— get() / provider(id)（优先走注入，降级到本地 loader）
• ✅ src/interfaces.ts（V3 新增 / V4 精简）：Adapter Registry + Env / Flag namespace
  • 4 个 Provider 接口（IConfigProvider / IInstanceProvider / IGlobalPathProvider / IInstallationProvider；Auth 已下沉到 @easbot/utils.Auth）
  • setAdapterRegistry(...) —— agent 包启动时一次注入，完全解耦本包对 agent 内部模块的所有依赖
  • getI<X>Provider() 便捷访问器 —— 未注入时 fail-fast 抛错（不静默退化）
  • readEnvString / readFlagBool / readFlagNumber —— 静态读取，避免对注入的依赖
  • Env / Flag namespace —— 镜像 process.env 的静态字面（用于 IDE 提示 / 文档生成 / 配置检查）
• ✅ src/index.ts —— 聚合导出入口（4 provider 命名空间 + 3 model 命名空间 + 自研 Copilot SDK + 3 常量 + Config / interfaces 接入点 + AdapterRegistry + 4 Provider 接口）

核心特性

• 25+ 内置 AI SDK 动态加载：按需 import，避免打包产物膨胀
• 三层数据源融合：models.dev 远程 catalog + 构建时 snapshot + 本地 CUSTOM_PROVIDER_DEFINITIONS（用于 ollama / easbot-local 这类不出现在 models.dev 的本仓自研 SDK）
• 统一 Provider 命名空间：Provider.list() / getModel() / parseModel() 一行调用，与具体 SDK 解耦
• OAuth + API key 双轨：ProviderAuth namespace 管理 OAuth flow / API key 持久化 / 注入到 SDK options
• Context Overflow 自动识别：跨厂商统一的"上下文超限"语义（25+ 正则模式 + 4 种 HTTP status 兜底）
• 自研 GitHub Copilot 兼容 SDK：完整实现 chat + responses API + 6 个 tool（code-interpreter / file-search / web-search / image-generation / local-shell / web-search-preview）
• 持久化模型缓存：构建时生成 models-snapshot.ts，运行时优先用本地，避免冷启动连网
• 极简聚合导出：@easbot/llm 一行引入 5+3 个命名空间 + 自研 SDK + 关键常量

安装

pnpm add @easbot/llm

快速上手

1. 列出所有已配置的 provider

import { Provider } from '@easbot/llm';

const allProviders = await Provider.list();
// { openai: { id, name, source, env, models, ... }, anthropic: {...}, ... }

2. 获取特定模型（按 provider/model 字符串路由）

import { Provider } from '@easbot/llm';

const gpt4 = await Provider.getModel('openai/gpt-4');
// gpt4: LanguageModelV3（AI SDK v6 规范）

const embed = await Provider.getModel('openai/text-embedding-3-small');
// embed: EmbeddingModelV3

const rerank = await Provider.getModel('easbot-local/rerank-proxy');
// rerank: RerankingModelV3

3. 解析模型 ID（安全拆分，不抛错）

import { Provider } from '@easbot/llm';

const { providerId, modelId } = Provider.parseModel('openai/gpt-4o');
// { providerId: 'openai', modelId: 'gpt-4o' }

4. 解析 API 错误（含 context overflow 识别）

import { ProviderError, APICallError } from 'ai';

try {
  await someProvider.doCall(...);
} catch (e) {
  if (e instanceof APICallError) {
    const parsed = ProviderError.parseAPICallError({ providerId: 'openai', error: e });
    if (parsed.type === 'context_overflow') {
      // UI: "上下文超限，请缩短输入或切换模型"
    }
  }
}

5. 高层 Model Provider 直接调用

import { RerankProvider, GraphProvider, SummaryProvider } from '@easbot/llm';

// 文档重排序
const reranked = await RerankProvider.rerank({
  query: '...',
  documents: ['...', '...'],
});

// 图谱实体提取
const graph = await GraphProvider.generateGraph({
  chunks: ['chunk1...', 'chunk2...', '...'], // 任意长度数组
  prompt: { maxChunks: 5, maxConcurrency: 3 }, // v0.8：per-call 切片 + 3 并发
});
// graph.entities / relations / summary 直接入库

v0.8 行为契约（packages/llm/src/model/graph.ts）：

• 所有 chunks 都被尝试抽取：chunks 数组按 prompt.maxChunks（默认 5）切片成多组，每组调一次 LLM；不再像 v0.7 那样硬截断到前 5 个 chunk。
• chunk 级 3 并发：多组用轻量级 semaphore 并发跑（prompt.maxConcurrency，默认 3），避免触发 provider 限流。
• 局部失败容错：单组 LLM 失败 → 仅丢该组结果，其他组继续。不会因一次失败让整个文档 KG 留空。
• 边界感知截断：超长 chunk 走 splitByBoundary 进一步切分（按 \n\n / \n / 空白找最近边界），保证 entity name 不被切碎。

// Note 知识库摘要
const summary = await SummaryProvider.summarizeNote({
  query: '...',
  chunks: [...],
});

6. 文本嵌入（EmbeddingProvider）

import { EmbeddingProvider } from '@easbot/llm';

// 单文本嵌入 — 返回 EmbedOutput（含 embedding + usage.tokens）
const single = await EmbeddingProvider.embedText({ value: '一段中文文本' });
// single.embedding: number[]（默认 bge-base-zh-v1.5 输出 512 维）
// single.usage.tokens: number

// 批量嵌入（推荐：单次 API 调用比 N 次 aiEmbed 更高效）
const batch = await EmbeddingProvider.embedTexts({ values: ['a', 'b', 'c'] });
// batch.embeddings: number[][]（与 values 一一对应）
// batch.usage.tokens: number

// 显式指定模型（跳过 Provider.defaultModel）
import { Provider } from '@easbot/llm';
const customModel = Provider.parseModel('openai/text-embedding-3-small');
const r = await EmbeddingProvider.embedText({ value: 'hi', model: customModel });
```…