1. 项目概述为什么我们需要一个统一的LLM调用库如果你最近在捣鼓AI应用开发尤其是基于Node.js的后端或者工具链那你大概率已经感受到了一个甜蜜的烦恼市面上的大语言模型LLM提供商太多了。OpenAI的GPT系列固然强大但成本、速率限制和特定场景下的需求常常让我们把目光投向Anthropic的Claude、Cohere的命令模型甚至是本地部署的Ollama。每个服务商都有自己的API格式、认证方式和参数命名规则。今天项目对接OpenAI明天要加个Claude做备选后天客户要求私有化部署一个Mistral模型——光是写一堆if-else来适配不同API就够喝一壶的了。这就是litellmjs要解决的核心问题。它是一个纯JavaScript/TypeScript实现的库目标是把所有主流甚至一些不那么主流的LLM API用一个统一的接口封装起来。你可以把它想象成数据库里的ORM对象关系映射只不过它映射的不是MySQL和PostgreSQL而是OpenAI、Anthropic、Cohere这些AI服务。它的终极愿景是你写一套代码就能无缝切换背后的大模型无论是调用、传参还是处理返回结果体验都保持一致。我最初接触它是因为一个需要同时调用GPT-4和本地Llama 2的项目。手动维护两套HTTP请求逻辑让我不胜其烦。litellmjs的出现让我只需要关心“我想让模型做什么”而不是“我该怎么调用这个特定模型的API”。它抽象了底层的复杂性让开发者能更专注于提示工程和业务逻辑本身。2. 核心设计思路与架构解析2.1 统一接口的设计哲学litellmjs的设计核心是“标准化”。它定义了两个最核心的接口completion文本补全/对话和embedding文本向量化。无论底层是哪个提供商你都通过这两个函数来调用。这种设计带来了几个显而易见的好处降低认知负担你不需要记忆每个API的端点URL、特定的HTTP头格式或怪异的JSON结构。一套参数走遍天下。提升代码可维护性业务逻辑与具体的模型提供商解耦。更换模型提供商就像更换配置文件一样简单核心业务代码几乎不用动。便于A/B测试与降级你可以轻松地设置模型优先级列表。当主模型如GPT-4达到速率限制或返回错误时可以自动降级到备用模型如Claude或本地模型而无需重写调用逻辑。它的架构可以粗略地分为三层适配器层Provider Adapters这是最底层为每个支持的提供商如openaianthropic实现了一个适配器。这个适配器的职责是将litellmjs的标准请求参数翻译成该提供商API能理解的格式并负责处理认证如API Key的放置位置和发起网络请求。核心路由层Core Router中间层。它根据用户传入的model参数字符串如“gpt-3.5-turbo”“claude-3-opus”来判断应该将请求路由到哪个适配器。它也可能处理一些通用逻辑比如重试机制、基础的错误处理。统一接口层Unified API暴露给开发者的顶层API即completion和embedding函数。它们提供类型安全的参数提示在TypeScript下体验极佳并返回标准化的响应对象。2.2 与Python版LiteLLM的关系及现状litellmjs是Python知名项目LiteLLM在JavaScript生态的移植。这意味着它的设计理念和API风格都尽可能与Python版保持一致方便跨语言团队的协作和知识迁移。然而移植并非完全同步。从提供的支持列表来看litellmjs目前还处于早期积极开发阶段。它的核心功能——标准化的completion和embedding——已经对几个主流提供商OpenAI Anthropic Cohere Ollama Mistral等实现了稳定支持并且支持流式响应streaming这是开发现代AI应用的必备特性。但Python版LiteLLM的一些高级功能在litellmjs中尚未实现最显著的就是**缓存Caching和代理服务器Proxy**功能。缓存对于成本优化至关重要。它能将相同的提示词-模型组合的响应结果缓存起来避免重复调用产生费用尤其适合开发、测试阶段或处理大量相似查询。代理Python版的代理功能非常强大可以作为一个独立的HTTP服务器运行统一接收请求并分发到后端的多个模型同时提供负载均衡、监控、密钥管理等功能。这对于构建企业级AI网关是核心组件。所以在选择litellmjs时你需要明确如果你当前的需求是快速、统一地调用多个模型的生成和嵌入能力它完全胜任。但如果你需要开箱即用的缓存、复杂的路由策略或一个集中式的代理服务你可能需要等待这些功能被移植或者考虑结合其他工具如自己用Redis实现缓存层。3. 快速上手指南从安装到第一个请求让我们跳过理论直接看看怎么用。假设你有一个Node.js项目版本建议在16以上。3.1 环境准备与安装首先通过npm安装它npm install litellm如果你使用TypeScript强烈推荐以获得更好的类型提示和开发体验确保你的tsconfig.json中moduleResolution设置正确如node16或nodenext。接下来你需要准备对应模型提供商的API密钥。这里以OpenAI为例。永远不要将API密钥硬编码在代码中提交到版本库。标准做法是使用环境变量。创建一个.env文件在你的项目根目录OPENAI_API_KEYsk-your-actual-openai-key-here ANTHROPIC_API_KEYyour-antropic-key-here # ... 其他提供商的Key然后在你的代码中通过dotenv这样的库来加载或者直接在部署平台的环境变量中配置。3.2 发起第一个同步请求现在让我们写一段最简单的代码调用GPT-3.5-Turbo模型。import { completion } from litellm; // 假设你已通过某种方式设置了 process.env[OPENAI_API_KEY] async function askAI() { try { const response await completion({ model: gpt-3.5-turbo, // 指定模型 messages: [ { role: system, content: 你是一个乐于助人的助手。 }, { role: user, content: 用一句话解释什么是量子计算。 } ], temperature: 0.7, // 控制创造性0-1之间越高越随机 max_tokens: 150, // 限制回复的最大长度 }); console.log(回复内容, response.choices[0]?.message?.content); console.log(本次消耗token数估算, response.usage?.total_tokens); // 响应结构是标准化的类似OpenAI的格式 } catch (error) { console.error(调用AI模型失败, error); } } askAI();执行这段代码你应该能很快得到一句关于量子计算的解释。这里有几个关键点model参数这是litellmjs的路由依据。字符串“gpt-3.5-turbo”会让库知道应该使用OpenAI的适配器并调用相应的API。messages参数这是目前LLM对话的标准格式一个对象数组每个对象包含rolesystemuserassistant和content。litellmjs会帮你把这个格式转换成不同提供商需要的格式例如Anthropic的API格式略有不同。响应对象response的结构是统一后的通常包含choices数组和usage等信息与OpenAI的响应格式高度相似这极大简化了后续处理。3.3 实现流式响应Streaming对于需要长时间生成文本或希望实现打字机输出效果的场景流式响应是必须的。litellmjs的流式调用同样简洁。import { completion } from litellm; async function streamAIResponse() { const stream await completion({ model: gpt-3.5-turbo, messages: [{ role: user, content: 写一个关于太空旅行的短故事开头。 }], stream: true, // 关键开启流式输出 temperature: 0.8, }); // 注意返回的是一个异步迭代器AsyncIterable for await (const chunk of stream) { // 每个chunk是一个部分响应对象 const content chunk.choices[0]?.delta?.content || ; process.stdout.write(content); // 逐块输出到控制台 } console.log(\n--- 流式输出结束 ---); } streamAIResponse();注意流式响应时返回的数据格式是分块的。每个chunk的delta属性包含了本次“增量”内容。你需要自己将这些片段拼接起来才能得到完整回复。同时流式响应通常不包含最终的usage统计这部分信息可能在流结束时以特殊事件发送或者需要你自行估算。4. 深入核心功能与多提供商实战掌握了基础调用后我们来深入看看如何利用litellmjs操作不同的模型提供商并处理一些常见需求。4.1 切换不同的模型提供商这是litellmjs的看家本领。切换模型通常只需要更改model参数字符串。库内部维护了一个模型标识符到提供商的映射。import { completion } from litellm; // 1. 调用 Anthropic 的 Claude 3 Haiku const claudeResponse await completion({ model: claude-3-haiku-20240307, // litellm 能识别这个模型名并路由到Anthropic messages: [{ role: user, content: 你好Claude。 }], max_tokens: 100, }); // 注意你需要设置 ANTHROPIC_API_KEY 环境变量 // 2. 调用 Cohere 的命令模型 const cohereResponse await completion({ model: command-r, // 对应 Cohere 的 Command R 模型 messages: [{ role: user, content: 总结以下文本... }], // Cohere可能用不同格式litellm会转换 }); // 注意你需要设置 COHERE_API_KEY 环境变量 // 3. 调用本地部署的 Ollama (运行 Llama 2) const ollamaResponse await completion({ model: ollama/llama2, // 模型名以 ollama/ 开头 messages: [{ role: user, content: Hello, Llama. }], apiBase: http://localhost:11434, // 关键指定你的Ollama服务地址 }); // 注意这里通常不需要API Key但需要确保Ollama服务正在运行关键点解析模型标识符litellmjs使用一套约定的模型字符串来路由。例如claude-3-前缀指向Anthropiccommand-前缀指向Cohere。对于Ollama需要显式加上ollama/前缀。具体支持的模型列表需要查阅项目文档。Ollama的特殊配置调用本地Ollama时必须通过apiBase参数指定Ollama服务器的地址默认是http://localhost:11434。这是因为它不遵循云服务的通用认证模式。环境变量每个提供商都需要其对应的API密钥作为环境变量变量名通常是{PROVIDER}_API_KEY的大写格式。litellmjs会自动读取这些变量。4.2 使用嵌入Embedding功能除了文本生成获取文本的向量表示嵌入也是AI应用的基础常用于搜索、聚类、推荐等。litellmjs同样标准化了embedding接口。import { embedding } from litellm; async function getEmbedding() { try { const embeddingResult await embedding({ model: text-embedding-3-small, // 使用OpenAI的嵌入模型 input: [机器学习是人工智能的一个分支。, 深度学习基于神经网络。], }); console.log(生成了 ${embeddingResult.data.length} 个嵌入向量); console.log(第一个向量的维度, embeddingResult.data[0].embedding.length); console.log(第一个向量的前5个值, embeddingResult.data[0].embedding.slice(0, 5)); // 响应结构{ data: [ { embedding: [number...], index: 0 }, ... ], model: ..., usage: {...} } } catch (error) { console.error(生成嵌入失败, error); } } getEmbedding();注意事项输入格式input参数可以是一个字符串也可以是一个字符串数组。批量处理文本时传入数组更高效。提供商支持并非所有提供商都支持嵌入功能。如前文表格所示OpenAI、Ollama、Mistral等支持但Anthropic、Cohere目前不支持。调用前需确认。向量维度不同模型的嵌入向量维度不同如text-embedding-3-small是1536维。在存储和计算相似度时必须确保对比的向量来自同一模型。4.3 高级参数与配置litellmjs致力于标准化输入参数。这意味着许多在特定提供商中可用的高级参数可以通过统一的参数名来设置。const response await completion({ model: gpt-4, messages: [...], temperature: 0.2, // 确定性更高适合事实性问答 top_p: 0.9, // 核采样与temperature二选一 max_tokens: 500, frequency_penalty: 0.5, // 降低重复用词的概率 presence_penalty: 0.3, // 鼓励谈论新话题 // 超时和重试配置如果底层适配器支持 timeout: 60000, // 60秒超时 // 特定于某个提供商的参数可能需要通过 extra_body 传递如果litellmjs尚未标准化 // extra_body: { some_vendor_specific_param: value } });实操心得temperature和max_tokens是你最需要关注的两个参数。对于创意写作temperature可以设到0.8-1.0对于代码生成或逻辑分析0.2-0.5会更稳定。max_tokens务必根据场景设置防止生成过长内容导致不必要的token消耗。对于未标准化的提供商特定参数查阅litellmjs的/docs/input-params.md文档是必须的或者查看其源码中对应适配器的实现。5. 开发、测试与问题排查指南如果你想为litellmjs贡献代码或者只是想深入了解其运行机制可以从源码开始。5.1 本地开发环境搭建# 1. 克隆仓库 git clone https://github.com/zya/litellmjs.git cd litellmjs # 2. 安装依赖 npm install # 3. 运行单元测试不依赖真实API npm test单元测试会验证核心逻辑、参数转换等是否正确是快速反馈的保障。5.2 端到端E2E测试运行E2E测试会真实调用各个AI提供商的API因此需要配置有效的API密钥。# 1. 复制环境变量模板 cp .example.env .env # 2. 编辑 .env 文件填入你的API密钥 # 至少需要填写你打算测试的提供商密钥例如 OPENAI_API_KEYsk-... ANTHROPIC_API_KEYsk-ant-... MISTRAL_API_KEY... # 对于Ollama确保本地服务运行通常不需要Key # 3. 运行E2E测试 npm run test:e2e重要提示运行E2E测试会产生真实的API调用费用请确保你了解相关成本并在测试后检查用量。建议为测试用途的API密钥设置较低的额度限制。5.3 常见问题与排查技巧在实际使用中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案错误Provider not supported1. 模型字符串拼写错误。2. 该提供商确实尚未被litellmjs支持。1. 检查model参数对照官方文档的支持列表。2. 对于Ollama模型名需以ollama/开头如ollama/llama2:7b。3. 查看项目GitHub的Issues或源码中的providers目录。错误API Key not found环境变量未正确设置或命名不对。1. 确认环境变量已加载如重启终端、IDE。2. 变量名必须全大写如OPENAI_API_KEY。3. 在代码中console.log(process.env.OPENAI_API_KEY)仅限开发环境确认是否读取到值注意安全。调用Ollama超时或连接失败1. Ollama服务未启动。2.apiBase地址或端口错误。3. 防火墙或网络策略阻止。1. 在终端运行ollama serve启动服务。2. 确认apiBase为http://localhost:11434默认。3. 尝试用curl http://localhost:11434/api/tags测试Ollama API是否可达。流式响应不工作或报错1. 提供商不支持流式。2. 处理流式响应的代码逻辑有误。3. 在Node.js环境使用了错误的异步处理方式。1. 查阅支持表格确认该模型支持stream: true。2. 确保使用for await...of语法消费流。3. 检查是否在支持Top-Level Await的环境或函数中调用。响应格式与预期不符1. 不同提供商返回的原始格式差异被标准化过程中可能丢失细节。2. 使用了非标准的参数。1. 查阅litellmjs的响应类型定义TypeScript类型。2. 尝试用console.log(JSON.stringify(response, null, 2))打印完整响应与提供商原始API文档对比。3. 考虑是否直接使用官方SDK以获得100%的特性支持。安装或导入时报错1. Node.js版本过低。2. TypeScript配置问题。3. 包管理器缓存问题。1. 升级Node.js至16或更高版本。2. 检查tsconfig.json确保module和moduleResolution设置正确如ES2022和node16。3. 尝试删除node_modules和package-lock.json后重新npm install。个人踩坑记录环境变量陷阱在Docker或某些服务器环境中环境变量名的大小写可能敏感。我曾因为将OPENAI_API_KEY误写为OpenAI_API_Key而调试了半小时。最稳妥的方式是在项目初始化时就打印出所有相关的环境变量名进行确认。Ollama模型拉取第一次使用model: ‘ollama/llama2’时如果本地没有llama2这个模型Ollama会自动从仓库拉取这可能需要很长时间且没有任何提示看起来就像卡住了。建议提前在命令行用ollama pull llama2拉取好模型。TypeScript类型提示litellmjs自带的TypeScript类型定义可能更新不及时。如果你发现某些参数或响应字段没有类型提示可以直接去查看src目录下的types.ts文件或者向项目提Issue。litellmjs为JavaScript/TypeScript开发者提供了一个优雅的抽象层让我们在面对纷繁复杂的LLM生态时能保持代码的简洁与一致性。虽然它在功能完备性上还落后于其Python原型但其核心的标准化调用能力已经非常可靠足以支撑起大多数多模型AI应用的原型开发和生产部署。随着社区的贡献缓存、代理等高级功能想必也会逐步到来。在AI应用开发日益复杂的今天这类“统一层”工具的价值只会越来越大。