LiteLLM 全面指南：一个库搞定 100+ 大模型 API 调用

LiteLLM 全面指南一个库搞定 100 大模型 API 调用告别为每个大模型厂商写一套适配代码的日子。LiteLLM 用统一的 OpenAI 格式接口把 OpenAI、Anthropic、Gemini、DeepSeek、通义千问等 100 模型提供商收进一个调用入口同时提供企业级 AI 网关能力。这篇文章带你从零上手并避开那些让人头疼的坑。项目地址https://github.com/BerriAI/litellm官方文档https://docs.litellm.ai/docs/。MIT 协议可以放心用在商业项目中。GitHub 28.5k Stars | MIT 开源协议 | 最新版本 1.92.0 | Python 3.10一、LiteLLM 是什么简单说LiteLLM 是一个开源的 AI 网关和统一 SDK。它的核心解决的问题是不同大模型厂商的 API 各写各的参数格式不统一、错误码不统一、流式响应不统一开发者每接入一个新模型就要写一套适配代码维护成本随着模型数量线性增长。LiteLLM 把所有这些差异抹平了。你只需要会openai.chat.completions.create()这一种调用方式换模型只需改一个字符串前缀比如把openai/gpt-4o改成anthropic/claude-sonnet-4-20250514剩下的参数转换、错误映射、流式解析全部由 LiteLLM 在内部处理。它有两种使用形态Python SDK直接在代码里 import 调用和AI Gateway 代理服务器部署为一个独立的 API 网关服务。前者适合个人开发者和小型项目快速上手后者适合团队和企业做集中化的模型调用管理。Stripe、Netflix、Google ADK 等公司都在生产环境中使用它1。统一接口自动转换参数格式自动转换参数格式自动转换参数格式你的应用代码OpenAI SDK / LangChainLiteLLM负载均衡 / 限流 / 预算成本追踪 / 虚拟密钥回退路由 / 安全护栏OpenAI / AzureGPT-4o / o3 / o4-miniAnthropic / GoogleClaude / GeminiDeepSeek / 通义千问Bedrock / Ollama ...二、核心能力一览能力说明统一调用接口100 模型提供商共用一套 OpenAI 格式的调用方式切换模型只改一个字符串AI Gateway 网关部署为独立代理服务支持虚拟密钥、限流、预算管理和负载均衡成本追踪自动计算每次调用的 Token 消耗和费用按用户、项目、团队维度汇总负载均衡与回退同一模型名映射多个部署支持权重分配、延迟路由和故障自动回退全链路可观测内置 OpenTelemetry v2 支持集成 Langfuse、Weights Biases 等平台MCP / A2A 网关在 /chat/completions 中直接调用 MCP 工具支持 A2A Agent 协议代理它支持的提供商覆盖面非常广从主流的 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure OpenAI到国内的通义千问Dashscope、DeepSeek、月之暗面Moonshot、智谱 AI、火山引擎再到本地部署方案 Ollama、vLLM、HuggingFace TGI 等总计超过 100 家2。支持的端点类型也不仅限于聊天补全还包括 Embeddings、图像生成、语音转文字、文字转语音、Rerank、Moderation 等。三、怎么用3.1、安装# Python SDKpipinstalllitellm# 或使用 uv官方推荐uvaddlitellm# 如果需要部署 Gateway 代理pipinstalllitellm[proxy]环境要求Python 版本需要 3.10 且 3.14。推荐使用 Python 3.11 或 3.12。3.2、方式一Python SDK 直接调用这是最快上手的方式。设置好各厂商的 API Key 环境变量然后用统一的completion()函数调用importosfromlitellmimportcompletion os.environ[OPENAI_API_KEY]sk-xxxos.environ[ANTHROPIC_API_KEY]sk-ant-xxxos.environ[DASHSCOPE_API_KEY]sk-xxx# 调用 OpenAI GPT-4orespcompletion(modelopenai/gpt-4o,messages[{role:user,content:用一句话介绍自己}])print(resp.choices[0].message.content)# 调用 Anthropic Claude —— 只改 model 前缀其余代码完全一样respcompletion(modelanthropic/claude-sonnet-4-20250514,messages[{role:user,content:用一句话介绍自己}])# 调用通义千问respcompletion(modeldashscope/qwen-plus,messages[{role:user,content:用一句话介绍自己}])# 调用本地 Ollamarespcompletion(modelollama/llama3,messages[{role:user,content:Hello}])核心逻辑就是completion(model提供商前缀/模型名, messages[...])。模型名称的完整格式规则可以在官方文档的 Providers 页面查到。所有响应对象都遵循 OpenAI 的ModelResponse格式不需要为不同厂商写不同的解析逻辑。3.3、方式二流式输出加一个streamTrue参数即可fromlitellmimportcompletionforchunkincompletion(modelopenai/gpt-4o,messages[{role:user,content:写一首短诗}],streamTrue):print(chunk.choices[0].delta.contentor,end)3.4、方式三异步调用importasynciofromlitellmimportacompletionasyncdefmain():responseawaitacompletion(modelanthropic/claude-sonnet-4-20250514,messages[{role:user,content:你好}])print(response.choices[0].message.content)asyncio.run(main())3.5、方式四部署 AI Gateway 代理当你需要管理多个 API Key、追踪团队成本、做负载均衡时Gateway 模式更合适。它对外暴露标准 OpenAI 兼容的 HTTP 端点任何已有的 OpenAI 客户端代码不用改一行只需把base_url指向 LiteLLM 代理即可。最简单的启动方式# 命令行一行启动代理运行在 http://0.0.0.0:4000litellm--modelgpt-4o多模型配置用 YAML 文件# config.yamlmodel_list:-model_name:my-model# 对外暴露的统一名称litellm_params:model:openai/gpt-4o# 实际调用的模型api_key:os.environ/OPENAI_API_KEY-model_name:my-model# 同名 负载均衡litellm_params:model:anthropic/claude-sonnet-4-20250514api_key:os.environ/ANTHROPIC_API_KEY# 可设置 weight 控制流量比例-model_name:local-llmlitellm_params:model:ollama/llama3api_base:http://localhost:11434# 启动代理litellm--configconfig.yaml--port4000客户端代码和调用 OpenAI 完全一样importopenai clientopenai.OpenAI(api_keyanything,# Gateway 自己管认证base_urlhttp://localhost:4000)responseclient.chat.completions.create(modelmy-model,# config.yaml 中的 model_namemessages[{role:user,content:你好}])生产部署建议用 Docker 部署 Gateway 更稳定同时搭配 PostgreSQL 存储配置和消费日志多实例场景下还需要 Redis 做状态同步限流计数、缓存等。官方提供了完整的 Docker Compose 模板和 Helm Chart。四、进阶用法4.1、成本追踪在 SDK 模式下可以用回调函数拿到每次调用的成本importlitellmdeftrack_cost(kwargs,completion_response,start_time,end_time):costkwargs.get(response_cost,0)modelkwargs.get(model)print(f模型{model}本次花费: ${cost:.6f})litellm.success_callback[track_cost]litellm.completion(modelopenai/gpt-4o,messages[...])在 Gateway 模式下成本追踪是自动开启的。你可以通过GET /global/spend/report接口按团队、用户、Key 维度查看消费报告也可以在管理后台Admin UI中直接查看。4.2、错误处理LiteLLM 把所有厂商的错误统一映射成了 OpenAI 风格的异常类型现有的错误处理代码不用改importlitellmtry:litellm.completion(modelanthropic/claude-sonnet-4-20250514,messages[...])exceptlitellm.AuthenticationError:print(API Key 错误或过期)exceptlitellm.RateLimitError:print(触发限流需要等待或切换模型)exceptlitellm.ContextWindowExceededError:print(输入超出模型上下文窗口)exceptlitellm.APIErrorase:print(f通用 API 错误:{e})4.3、可观测性集成一行代码接入主流可观测性平台# Langfuselitellm.success_callback[langfuse]# 多个平台同时接入litellm.success_callback[langfuse,mlflow,helicone]# 或使用 OpenTelemetry v2推荐单请求一条完整追踪链# 环境变量设置 LITELLM_OTEL_V2true 即可五、踩坑点与解决方案以下是从官方文档、GitHub Issues 和社区实践[3][4][^5]中整理出的高频问题。如果你正在准备将 LiteLLM 用到生产环境建议把这一节读完再动手。5.1、api_base 路径重复导致 404这是踩到最多的坑。LiteLLM 在调用 OpenAI 兼容 API 时会自动在api_base后面追加/chat/completions。如果你在配置里把这个路径也写上了最终请求的 URL 会变成/v1/chat/completions/chat/completions直接 404。# config.yaml# 错误写法api_base:https://coding.dashscope.aliyuncs.com/v1/chat/completions# 正确写法 —— 只写到 /v1api_base:https://coding.dashscope.aliyuncs.com/v15.2、配置修改后不生效LiteLLM Gateway 会把模型配置持久化到 PostgreSQL 数据库。你改了config.yaml或.env重启服务后发现用的还是旧配置就是因为数据库里的缓存覆盖了文件配置。解决方案开发环境执行docker-compose down -v清除数据卷后重启注意会丢失所有数据生产环境通过管理 UI 或/model/newAPI 修改配置不要直接改 YAML 文件或者在启动参数中设置STORE_MODEL_IN_DBFalse彻底关闭配置持久化5.3、custom_llm_provider 不能随便填对于 DeepSeek、通义千问这类 OpenAI 兼容的第三方 APIcustom_llm_provider必须填 LiteLLM 预定义的值。填了自定义名称会导致模型列表为空日志报Unsupported provider。正确做法是统一使用custom_llm_provider: openai然后通过api_base指向第三方端点。5.4、模型名称不匹配代码里调用的model名字必须和config.yaml中的model_name完全一致一个字符都不能差。比如配置里写gpt4o代码里写gpt-4o请求会直接 404。建议在团队内部维护一份统一的模型名称映射表。5.5、Docker 镜像拉取失败LiteLLM 的 Docker 镜像托管在ghcr.io国内网络访问经常超时或 EOF。可以编写重试脚本最多 50 次或者通过能访问 ghcr.io 的环境提前下载镜像后导出/导入。5.6、流式响应 SSE 格式兼容问题开启streamTrue后部分模型的流式转发返回的 SSE 格式和原生 OpenAI 不完全一致可能导致客户端解析异常。解决方案保持 LiteLLM 到最新版本流式兼容性在持续修复或在配置中对有问题的模型关闭流式支持。5.7、上下文窗口溢出当输入 Token 数加上请求的max_tokens超过模型上下文窗口上限时LiteLLM 会抛出ContextWindowExceededError。这个拦截发生在 LiteLLM 层面请求还没发到模型厂商。可以通过减少上下文输入、降低max_tokens或配置context_window_fallback自动降级到更长上下文的模型来解决。5.8、多实例部署缺少 Redis如果部署了多个 LiteLLM 实例做高可用但没有配置 Redis 共享状态限流计数、缓存等数据会在各实例间不一致。多实例部署必须在router_settings中配置 Redis# config.yamlrouter_settings:redis_host:redis.example.comredis_password:your-passwordredis_port:63795.9、环境变量传递问题Docker Compose 场景下确保.env文件和docker-compose.yml在同一目录使用${VAR:-default}语法设置默认值便于排查。可以用docker-compose exec litellm-proxy env | grep VAR验证容器内的变量是否正确。5.10、安全风险Pwn2Own Berlin 2026 已披露 LiteLLMcustom_llm_provider字段存在命令注入风险[^6]。在生产环境中务必限制配置文件的访问权限及时更新到最新版本以获取安全补丁。虚拟密钥Virtual Key必须以sk开头建议通过 API 动态生成和吊销不要硬编码在代码里。踩坑速查表问题现象常见原因快速排查404 Not Foundapi_base 路径重复或 model_name 不匹配检查 api_base 是否包含 /chat/completionsUnsupported providercustom_llm_provider 填了自定义值改为 openai 并设置 api_base改了配置不生效数据库缓存了旧配置清数据库卷或用 UI 修改ContextWindowExceededError输入 max_tokens 超过模型上限减少输入或降低 max_tokens限流失效多实例未配 Redis检查 router_settings 中 Redis 配置流式响应解析异常SSE 格式不兼容升级 LiteLLM 或关闭该模型的流式Docker 镜像拉不下来ghcr.io 国内访问受限重试脚本或提前导出镜像六、生产环境最佳实践6.1、路由策略选择策略适用场景配置方式simple-shuffle通用生产环境推荐基于权重随机分配latency-based-routing对延迟敏感的场景自动选择响应最快的部署cost-based-routing成本优先自动选择最便宜的部署6.2、关键配置建议重试与超时配置num_retries: 3和timeout: 30-60同时设置 fallback 链主模型失败时自动切换备用模型参数兼容设置drop_params: true自动丢弃目标模型不支持的参数避免因参数不兼容导致的报错密钥管理通过POST /key/generateAPI 动态生成虚拟密钥按项目或用户分配不同的预算和限流策略日志级别开发时用--detailed_debug排查问题生产环境通过LITELLM_LOGINFO控制日志量健康检查配置/health端点供负载均衡器探活确保故障实例及时摘除七、LiteLLM 适合谁用角色/场景推荐用法核心价值个人开发者 / 独立项目Python SDK一行代码切换模型快速验证想法AI 应用创业团队Gateway SDK统一管理 API Key、追踪成本、快速切换供应商企业 ML 平台团队Gateway多实例 Redis集中管控全公司模型调用、预算、权限、审计需要在 Claude Code / Cursor 中用多个模型Gateway通过 base_url 代理无需每个工具单独配置使用 LangChain / LlamaIndex 的项目SDK 或 GatewayLiteLLM 已集成到这两个框架的 LLM provider 中LiteLLM 的核心价值在于降低大模型调用的碎片化成本。当你的项目从接入 1 个模型扩展到 5 个、10 个模型时没有统一层的管理复杂度会急剧上升。LiteLLM 用一个稳定的抽象层把这个增长曲线压平了让你可以把精力放在业务逻辑而不是 API 适配上。BerriAI/litellm, GitHub 仓库 README ↩︎LiteLLM 官方文档 - 支持的模型提供商 ↩︎