1. 项目概述与核心定位1.1 这个项目到底解决什么问题第一次接触 litellm 是在一个多模型混用的项目里。当时团队同时接入了好几家不同厂商的大模型服务，每家的接口协议、鉴权方式、返回结构都不一样，代码里到处是 if-else 分支，维护起来非常痛苦。litellm 就是在这个背景下进入视野的——它本质上是一个统一的大模型调用中间层，用一套 OpenAI 兼容的接口格式，去对接市面上几十种不同的模型服务。说白了，它的核心价值就一句话：你只需要学会一套调用方式，就能切换任意后端模型。不管是商业闭源模型、开源自部署模型，还是本地推理服务，litellm 都帮你把差异抹平了。这对需要做模型对比、成本优化、故障降级的场景来说，价值非常大。它适合谁用？我总结下来有三类人最需要：一是做 AI 应用开发、需要灵活切换模型的工程师；二是做模型评测、要批量跑不同模型对比效果的算法同学；三是搭建内部 AI 网关、需要统一管理和计费的平台团队。哪怕你只是个人开发者，想在自己的小工具里同时支持几个模型，litellm 也能省掉大量适配代码。1.2 核心能力全景litellm 的能力可以分成几个层次来理解。最基础的是SDK 层，也就是在 Python 代码里直接import litellm，然后像调 OpenAI 一样调其他模型。往上是代理服务层，也就是把 litellm 跑成一个 HTTP 服务，对外暴露统一的 API 端点，任何语言写的客户端都能用。再往上是管理与治理层，包括密钥管理、用量统计、预算控制、限流、缓存这些生产环境必需的能力。我画个表把这几层能力对照一下，方便你判断自己需要用到哪一层：能力层次典型使用方式适用场景复杂度SDK 直调Python 代码内 import脚本、单机应用、快速验证低代理服务启动 HTTP 服务多语言客户端、团队共享中治理能力配置虚拟密钥、预算生产环境、多租户高理解这个分层很重要，因为很多人一上来就想把所有能力都用上，结果配置复杂到自己都理不清。我的建议是按需渐进：先用 SDK 跑通，再上代理，最后才考虑治理。2. 核心设计思路拆解2.1 为什么选择 OpenAI 格式作为统一标准这是 litellm 最关键的一个设计决策，值得单独说说。市面上模型服务那么多，为什么偏偏选 OpenAI 的接口格式作为统一标准？我的理解有三点原因。第一，OpenAI 的接口格式事实上已经成了行业通用语言。绝大多数模型服务商在提供 API 时，都会主动兼容 OpenAI 的格式，因为这样迁移成本最低。litellm 顺着这个趋势走，等于站在了生态的顺风位上。第二，请求和响应的数据结构设计得足够通用。messages 数组、role 角色、content 内容这套结构，能覆盖绝大多数对话场景，扩展性也好。你可以在 content 里塞多模态内容，可以用 tool_calls 做函数调用，基本够用。第三，降低用户的学习成本。开发者本来就会用 OpenAI 的 SDK，litellm 让你几乎不用改代码就能切换后端，这个迁移成本几乎为零。我自己从纯 OpenAI 切到 litellm 的时候，改动量就是加一行import和改一下模型名前缀。提示：虽然 litellm 以 OpenAI 格式为主，但它也支持其他格式的转换，比如 Anthropic 的原生格式、Cohere 的格式等。不过实际用下来，OpenAI 格式的兼容性最好，建议优先用它。2.2 模型命名规则的设计逻辑litellm 用一套前缀命名规则来区分不同的模型提供方，比如gpt-4走 OpenAI，claude-3-opus走 Anthropic，ollama/llama3走本地 Ollama。这个设计看起来简单，但背后有讲究。前缀的作用是路由。litellm 拿到模型名后，先解析前缀，确定用哪个 provider 的适配器，然后把统一的请求转换成该 provider 需要的格式，发出去，再把响应转回统一格式。整个过程对调用方透明。这种设计的好处是可扩展。新增一个 provider，只要注册一个新的前缀和对应的适配器就行，不影响已有逻辑。坏处是命名冲突，比如不同厂商可能有同名模型，这时候就得靠前缀区分。我踩过一次坑，本地部署的模型名和某个商业模型重名了，结果路由到了错误的后端，排查了半天才发现是命名问题。2.3 配置驱动的治理能力litellm 的代理模式是配置驱动的，一个 YAML 文件就能定义模型列表、路由策略、密钥、预算等。这种设计的好处是声明式、可版本化。你可以把配置文件纳入 Git 管理，每次变更都有记录，回滚也方便。我比较欣赏它的一点是，配置和代码分离。模型列表、API 密钥这些经常变的东西放在配置里，业务逻辑放在代码里，职责清晰。生产环境里，运维同学改配置就能调整模型路由，不用动代码重新部署，这个灵活性很实用。3. 核心细节与实操要点3.1 环境准备与安装安装本身很简单，但有几个细节要注意。基础安装用pip install litellm就够了，但如果你要用代理模式，建议装带 proxy 的完整版：pip install 'litellm[proxy]'。这个 extras 会把 FastAPI、Uvicorn 这些依赖一起装上。Python 版本建议 3.9 以上，我实测 3.8 也能跑，但有些新特性用不了。另外，如果你要用本地模型，可能还需要装对应的推理框架客户端，比如 Ollama 的 Python 包。注意：litellm 迭代很快，不同版本之间 API 可能有细微差异。生产环境建议锁定版本号，别用 latest，否则某天自动升级可能出问题。我就遇到过升级后某个参数默认值变了，导致行为不一致的情况。3.2 SDK 直调的关键参数SDK 直调是最简单的用法，核心就是completion函数。但有几个参数值得展开说。model参数决定路由，前面说了前缀规则。messages是对话历史，格式和 OpenAI 一致。api_key可以显式传，也可以走环境变量。我建议用环境变量管理密钥，别硬编码在代码里，这是基本的安全习惯。temperature、max_tokens、top_p这些采样参数，litellm 会尽量透传给后端。但要注意，不是所有后端都支持所有参数。比如某些开源模型不支持top_p，传了会被忽略或报错。我一般会先查一下目标模型的文档，确认支持哪些参数。还有一个容易被忽略的是timeout和max_retries。生产环境一定要设，否则某个后端卡住会拖垮整个请求链路。我一般设 timeout 30 秒，retries 2 次，配合降级策略使用。3.3 代理服务的配置结构代理模式的配置文件是核心，我拆解一下典型结构。顶层一般有model_list、general_settings、litellm_settings这几块。model_list定义可用模型，每个条目包含model_name（对外暴露的名字）和litellm_params（实际路由参数）。这里有个技巧：同一个实际模型可以注册多个 model_name，用于不同的路由策略或配额。general_settings管的是服务级配置，比如 master key、数据库连接。litellm_settings管的是行为配置，比如缓存、降级、回调。我建议配置文件的组织方式是：按环境分文件，dev、staging、prod 各一份，公共部分用 YAML 锚点复用。这样既清晰又不容易出错。3.4 密钥与预算管理生产环境里，密钥管理是个绕不开的话题。litellm 支持虚拟密钥，也就是给每个调用方发一个虚拟 key，背后映射到真实的后端密钥。这样做的好处是：真实密钥不暴露给调用方，可以随时吊销虚拟 key，还能给每个 key 设预算和限流。预算控制是按虚拟 key 维度统计用量的，可以设日预算、月预算。超了之后请求会被拒绝。这个功能对多租户场景特别有用，能防止某个调用方把额度用光。提示：虚拟密钥功能依赖数据库存储用量数据，所以要先配好数据库连接。SQLite 适合小规模，生产建议用 PostgreSQL。4. 实操过程与核心环节4.1 从零跑通 SDK 调用我带你走一遍完整流程。第一步，装包：pip install litellm。第二步，设环境变量，比如OPENAI_API_KEY、ANTHROPIC_API_KEY这些，litellm 会自动读取。第三步，写代码：import litellm response = litellm.completion( model="gpt-4", messages=[{"role": "user", "content": "你好"}], temperature=0.7, max_tokens=100 ) print(response.choices[0].message.content)这段代码跑通后，把model改成claude-3-opus，只要对应的环境变量设了，就能直接调 Anthropic 的模型，代码其他部分不用动。这就是 litellm 的核心体验。4.2 搭建代理服务的完整步骤代理服务稍微复杂点。第一步，准备配置文件config.yaml：model_list: - model_name: gpt-4 litellm_params: model: gpt-4 api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: claude-3-opus api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-my-master-key第二步，启动服务：litellm --config config.yaml --port 4000。第三步，用任意 HTTP 客户端调用，端点是http://localhost:4000/chat/completions，请求格式和 OpenAI 完全一致，只是把 base_url 指过来。我实测下来，这个流程十分钟能跑通。但生产部署要考虑进程管理、日志、监控这些，建议用容器化方式，配合健康检查端点。4.3 多模型路由与降级配置降级是 litellm 很实用的一个能力。配置里可以定义 fallbacks，比如主模型调用失败时自动切到备用模型：litellm_settings: fallbacks: [{"gpt-4": ["claude", "ollama/llama3"]}]这个配置的意思是，gpt-4 失败时依次尝试 claude 和本地 llama3。实际用下来，这个机制能显著提升可用性，尤其是依赖外部服务的时候。但要注意，降级不是万能的。不同模型的能力差异可能很大，降级后返回的结果质量可能下降。我的做法是：降级只用于非关键场景，关键场景宁可报错让上层处理。4.4 缓存配置与效果验证缓存能省钱也能提速。litellm 支持内存缓存和 Redis 缓存。配置：litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379开启后，相同的请求会命中缓存直接返回，不消耗后端额度。我实测在重复查询场景下，命中率能到 40% 以上，成本下降明显。但缓存有个坑：语义相同但措辞不同的请求不会命中。比如"你好"和"您好"是两个不同的 key。所以缓存对精确重复的请求有效，对语义相似的不行。如果需要语义缓存，得额外接向量检索，那是另一套方案了。5. 常见问题与排查技巧5.1 典型报错速查我把踩过的坑整理成表，方便你对照排查：报错信息常见原因解决思路AuthenticationError密钥没设或设错检查环境变量名是否匹配NotFoundError模型名或前缀写错核对 provider 前缀和模型名RateLimitError触发后端限流配置重试和降级Timeout后端响应慢调大 timeout 或换后端ContextWindowExceeded输入超长截断或换长上下文模型5.2 密钥读取的坑litellm 读环境变量的规则是os.environ/VAR_NAME，注意这个写法。我一开始直接写$VAR_NAME，结果不生效，排查了好久。另外，不同 provider 的环境变量名不一样，OpenAI 是OPENAI_API_KEY，Anthropic 是ANTHROPIC_API_KEY，别搞混。还有一个隐蔽的坑：环境变量在服务启动时读取。如果你启动后再改环境变量，服务不会感知。所以改完密钥要重启服务。5.3 流式输出的处理流式输出（streaming）在 litellm 里是支持的，但处理方式和普通请求不同。返回的是一个迭代器，要逐块读取。我见过有人直接把流式响应当普通响应用，结果拿到的是空内容。处理流式的正确姿势是遍历迭代器，累积 content 片段。另外，流式模式下有些统计信息（比如 token 用量）可能拿不到，需要额外配置。5.4 用量统计的准确性用量统计依赖后端返回的 usage 字段。但不是所有后端都返回准确的 usage，有些开源模型返回的是估算值，甚至不返回。这会导致统计偏差。我的做法是：对统计准确性要求高的场景，用支持精确 usage 的后端；对准确性要求不高的，接受估算值。另外，litellm 支持自定义回调，可以把用量数据推到自己的监控系统，做二次校验。6. 生产环境部署经验6.1 性能与并发调优代理服务的性能瓶颈通常在网络 IO 和后端响应速度上。litellm 本身是异步的，用 Uvicorn 跑多 worker 能提升并发。我一般设 worker 数为 CPU 核数的 2 倍左右。但要注意，worker 多了之后，内存缓存不共享。如果用了内存缓存，每个 worker 各存各的，命中率会下降。这种情况建议用 Redis 做共享缓存。6.2 监控与告警生产环境一定要有监控。litellm 支持多种回调，可以把请求日志、用量、延迟推到监控系统。我一般关注几个指标：请求成功率、P99 延迟、各模型用量占比、缓存命中率。告警阈值我设的是：成功率低于 95% 告警，P99 延迟超过 10 秒告警。这两个指标能覆盖大部分异常情况。6.3 安全加固要点安全方面有几个必做的点。第一，master key 一定要强，别用默认值。第二，虚拟密钥要设预算和限流，防止滥用。第三，代理服务不要直接暴露公网，放在内网或加一层网关。第四，日志里不要记录完整密钥，脱敏处理。我见过有人把代理服务直接暴露公网，结果被扫到后疯狂调用，账单爆炸。这个教训很深刻，安全配置不能省。7. 扩展玩法与个人体会7.1 结合本地模型的混合部署litellm 一个很实用的玩法是混合部署：简单请求走本地小模型，复杂请求走云端大模型。这样既能控制成本，又能保证效果。配置上就是注册两个模型，然后在业务层做路由判断。我实测下来，把 60% 的简单请求分流到本地模型后，云端成本下降了近一半，而用户体验基本没受影响。这个策略对成本敏感的场景很值得试。7.2 作为模型评测的基础设施做模型评测的时候，litellm 能省很多事。同一套评测代码，换个模型名就能跑不同模型，结果格式统一，方便对比。我一般会写个脚本，遍历模型列表，批量跑评测集，最后汇总成表格。这个用法对算法同学特别友好，不用为每个模型写适配代码，专注在评测逻辑上就行。7.3 我踩过的几个印象深刻的坑最后分享几个我踩过的坑，帮你少走弯路。第一个是模型名前缀遗漏，直接写llama3而不是ollama/llama3，结果路由失败。第二个是配置文件缩进错误，YAML 对缩进敏感，一个空格错位就解析失败。第三个是版本升级导致的参数默认值变化，升级前一定要看 changelog。这些坑都不难解决，但不知道的时候确实会卡很久。希望这些经验能帮你节省时间。litellm 这个工具，用熟了之后确实能大幅提升多模型场景的开发效率，值得花时间深入掌握。
1. 项目概述与核心定位1.1 这个项目到底解决什么问题第一次接触 litellm 是在一个多模型混用的项目里。当时团队同时接入了好几家不同厂商的大模型服务，每家的接口协议、鉴权方式、返回结构都不一样，代码里到处是 if-else 分支，维护起来非常痛苦。litellm 就是在这个背景下进入视野的——它本质上是一个统一的大模型调用中间层，用一套 OpenAI 兼容的接口格式，去对接市面上几十种不同的模型服务。说白了，它的核心价值就一句话：你只需要学会一套调用方式，就能切换任意后端模型。不管是商业闭源模型、开源自部署模型，还是本地推理服务，litellm 都帮你把差异抹平了。这对需要做模型对比、成本优化、故障降级的场景来说，价值非常大。它适合谁用？我总结下来有三类人最需要：一是做 AI 应用开发、需要灵活切换模型的工程师；二是做模型评测、要批量跑不同模型对比效果的算法同学；三是搭建内部 AI 网关、需要统一管理和计费的平台团队。哪怕你只是个人开发者，想在自己的小工具里同时支持几个模型，litellm 也能省掉大量适配代码。1.2 核心能力全景litellm 的能力可以分成几个层次来理解。最基础的是SDK 层，也就是在 Python 代码里直接import litellm，然后像调 OpenAI 一样调其他模型。往上是代理服务层，也就是把 litellm 跑成一个 HTTP 服务，对外暴露统一的 API 端点，任何语言写的客户端都能用。再往上是管理与治理层，包括密钥管理、用量统计、预算控制、限流、缓存这些生产环境必需的能力。我画个表把这几层能力对照一下，方便你判断自己需要用到哪一层：能力层次典型使用方式适用场景复杂度SDK 直调Python 代码内 import脚本、单机应用、快速验证低代理服务启动 HTTP 服务多语言客户端、团队共享中治理能力配置虚拟密钥、预算生产环境、多租户高理解这个分层很重要，因为很多人一上来就想把所有能力都用上，结果配置复杂到自己都理不清。我的建议是按需渐进：先用 SDK 跑通，再上代理，最后才考虑治理。2. 核心设计思路拆解2.1 为什么选择 OpenAI 格式作为统一标准这是 litellm 最关键的一个设计决策，值得单独说说。市面上模型服务那么多，为什么偏偏选 OpenAI 的接口格式作为统一标准？我的理解有三点原因。第一，OpenAI 的接口格式事实上已经成了行业通用语言。绝大多数模型服务商在提供 API 时，都会主动兼容 OpenAI 的格式，因为这样迁移成本最低。litellm 顺着这个趋势走，等于站在了生态的顺风位上。第二，请求和响应的数据结构设计得足够通用。messages 数组、role 角色、content 内容这套结构，能覆盖绝大多数对话场景，扩展性也好。你可以在 content 里塞多模态内容，可以用 tool_calls 做函数调用，基本够用。第三，降低用户的学习成本。开发者本来就会用 OpenAI 的 SDK，litellm 让你几乎不用改代码就能切换后端，这个迁移成本几乎为零。我自己从纯 OpenAI 切到 litellm 的时候，改动量就是加一行import和改一下模型名前缀。提示：虽然 litellm 以 OpenAI 格式为主，但它也支持其他格式的转换，比如 Anthropic 的原生格式、Cohere 的格式等。不过实际用下来，OpenAI 格式的兼容性最好，建议优先用它。2.2 模型命名规则的设计逻辑litellm 用一套前缀命名规则来区分不同的模型提供方，比如gpt-4走 OpenAI，claude-3-opus走 Anthropic，ollama/llama3走本地 Ollama。这个设计看起来简单，但背后有讲究。前缀的作用是路由。litellm 拿到模型名后，先解析前缀，确定用哪个 provider 的适配器，然后把统一的请求转换成该 provider 需要的格式，发出去，再把响应转回统一格式。整个过程对调用方透明。这种设计的好处是可扩展。新增一个 provider，只要注册一个新的前缀和对应的适配器就行，不影响已有逻辑。坏处是命名冲突，比如不同厂商可能有同名模型，这时候就得靠前缀区分。我踩过一次坑，本地部署的模型名和某个商业模型重名了，结果路由到了错误的后端，排查了半天才发现是命名问题。2.3 配置驱动的治理能力litellm 的代理模式是配置驱动的，一个 YAML 文件就能定义模型列表、路由策略、密钥、预算等。这种设计的好处是声明式、可版本化。你可以把配置文件纳入 Git 管理，每次变更都有记录，回滚也方便。我比较欣赏它的一点是，配置和代码分离。模型列表、API 密钥这些经常变的东西放在配置里，业务逻辑放在代码里，职责清晰。生产环境里，运维同学改配置就能调整模型路由，不用动代码重新部署，这个灵活性很实用。3. 核心细节与实操要点3.1 环境准备与安装安装本身很简单，但有几个细节要注意。基础安装用pip install litellm就够了，但如果你要用代理模式，建议装带 proxy 的完整版：pip install 'litellm[proxy]'。这个 extras 会把 FastAPI、Uvicorn 这些依赖一起装上。Python 版本建议 3.9 以上，我实测 3.8 也能跑，但有些新特性用不了。另外，如果你要用本地模型，可能还需要装对应的推理框架客户端，比如 Ollama 的 Python 包。注意：litellm 迭代很快，不同版本之间 API 可能有细微差异。生产环境建议锁定版本号，别用 latest，否则某天自动升级可能出问题。我就遇到过升级后某个参数默认值变了，导致行为不一致的情况。3.2 SDK 直调的关键参数SDK 直调是最简单的用法，核心就是completion函数。但有几个参数值得展开说。model参数决定路由，前面说了前缀规则。messages是对话历史，格式和 OpenAI 一致。api_key可以显式传，也可以走环境变量。我建议用环境变量管理密钥，别硬编码在代码里，这是基本的安全习惯。temperature、max_tokens、top_p这些采样参数，litellm 会尽量透传给后端。但要注意，不是所有后端都支持所有参数。比如某些开源模型不支持top_p，传了会被忽略或报错。我一般会先查一下目标模型的文档，确认支持哪些参数。还有一个容易被忽略的是timeout和max_retries。生产环境一定要设，否则某个后端卡住会拖垮整个请求链路。我一般设 timeout 30 秒，retries 2 次，配合降级策略使用。3.3 代理服务的配置结构代理模式的配置文件是核心，我拆解一下典型结构。顶层一般有model_list、general_settings、litellm_settings这几块。model_list定义可用模型，每个条目包含model_name（对外暴露的名字）和litellm_params（实际路由参数）。这里有个技巧：同一个实际模型可以注册多个 model_name，用于不同的路由策略或配额。general_settings管的是服务级配置，比如 master key、数据库连接。litellm_settings管的是行为配置，比如缓存、降级、回调。我建议配置文件的组织方式是：按环境分文件，dev、staging、prod 各一份，公共部分用 YAML 锚点复用。这样既清晰又不容易出错。3.4 密钥与预算管理生产环境里，密钥管理是个绕不开的话题。litellm 支持虚拟密钥，也就是给每个调用方发一个虚拟 key，背后映射到真实的后端密钥。这样做的好处是：真实密钥不暴露给调用方，可以随时吊销虚拟 key，还能给每个 key 设预算和限流。预算控制是按虚拟 key 维度统计用量的，可以设日预算、月预算。超了之后请求会被拒绝。这个功能对多租户场景特别有用，能防止某个调用方把额度用光。提示：虚拟密钥功能依赖数据库存储用量数据，所以要先配好数据库连接。SQLite 适合小规模，生产建议用 PostgreSQL。4. 实操过程与核心环节4.1 从零跑通 SDK 调用我带你走一遍完整流程。第一步，装包：pip install litellm。第二步，设环境变量，比如OPENAI_API_KEY、ANTHROPIC_API_KEY这些，litellm 会自动读取。第三步，写代码：import litellm response = litellm.completion( model="gpt-4", messages=[{"role": "user", "content": "你好"}], temperature=0.7, max_tokens=100 ) print(response.choices[0].message.content)这段代码跑通后，把model改成claude-3-opus，只要对应的环境变量设了，就能直接调 Anthropic 的模型，代码其他部分不用动。这就是 litellm 的核心体验。4.2 搭建代理服务的完整步骤代理服务稍微复杂点。第一步，准备配置文件config.yaml：model_list: - model_name: gpt-4 litellm_params: model: gpt-4 api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: claude-3-opus api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-my-master-key第二步，启动服务：litellm --config config.yaml --port 4000。第三步，用任意 HTTP 客户端调用，端点是http://localhost:4000/chat/completions，请求格式和 OpenAI 完全一致，只是把 base_url 指过来。我实测下来，这个流程十分钟能跑通。但生产部署要考虑进程管理、日志、监控这些，建议用容器化方式，配合健康检查端点。4.3 多模型路由与降级配置降级是 litellm 很实用的一个能力。配置里可以定义 fallbacks，比如主模型调用失败时自动切到备用模型：litellm_settings: fallbacks: [{"gpt-4": ["claude", "ollama/llama3"]}]这个配置的意思是，gpt-4 失败时依次尝试 claude 和本地 llama3。实际用下来，这个机制能显著提升可用性，尤其是依赖外部服务的时候。但要注意，降级不是万能的。不同模型的能力差异可能很大，降级后返回的结果质量可能下降。我的做法是：降级只用于非关键场景，关键场景宁可报错让上层处理。4.4 缓存配置与效果验证缓存能省钱也能提速。litellm 支持内存缓存和 Redis 缓存。配置：litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379开启后，相同的请求会命中缓存直接返回，不消耗后端额度。我实测在重复查询场景下，命中率能到 40% 以上，成本下降明显。但缓存有个坑：语义相同但措辞不同的请求不会命中。比如"你好"和"您好"是两个不同的 key。所以缓存对精确重复的请求有效，对语义相似的不行。如果需要语义缓存，得额外接向量检索，那是另一套方案了。5. 常见问题与排查技巧5.1 典型报错速查我把踩过的坑整理成表，方便你对照排查：报错信息常见原因解决思路AuthenticationError密钥没设或设错检查环境变量名是否匹配NotFoundError模型名或前缀写错核对 provider 前缀和模型名RateLimitError触发后端限流配置重试和降级Timeout后端响应慢调大 timeout 或换后端ContextWindowExceeded输入超长截断或换长上下文模型5.2 密钥读取的坑litellm 读环境变量的规则是os.environ/VAR_NAME，注意这个写法。我一开始直接写$VAR_NAME，结果不生效，排查了好久。另外，不同 provider 的环境变量名不一样，OpenAI 是OPENAI_API_KEY，Anthropic 是ANTHROPIC_API_KEY，别搞混。还有一个隐蔽的坑：环境变量在服务启动时读取。如果你启动后再改环境变量，服务不会感知。所以改完密钥要重启服务。5.3 流式输出的处理流式输出（streaming）在 litellm 里是支持的，但处理方式和普通请求不同。返回的是一个迭代器，要逐块读取。我见过有人直接把流式响应当普通响应用，结果拿到的是空内容。处理流式的正确姿势是遍历迭代器，累积 content 片段。另外，流式模式下有些统计信息（比如 token 用量）可能拿不到，需要额外配置。5.4 用量统计的准确性用量统计依赖后端返回的 usage 字段。但不是所有后端都返回准确的 usage，有些开源模型返回的是估算值，甚至不返回。这会导致统计偏差。我的做法是：对统计准确性要求高的场景，用支持精确 usage 的后端；对准确性要求不高的，接受估算值。另外，litellm 支持自定义回调，可以把用量数据推到自己的监控系统，做二次校验。6. 生产环境部署经验6.1 性能与并发调优代理服务的性能瓶颈通常在网络 IO 和后端响应速度上。litellm 本身是异步的，用 Uvicorn 跑多 worker 能提升并发。我一般设 worker 数为 CPU 核数的 2 倍左右。但要注意，worker 多了之后，内存缓存不共享。如果用了内存缓存，每个 worker 各存各的，命中率会下降。这种情况建议用 Redis 做共享缓存。6.2 监控与告警生产环境一定要有监控。litellm 支持多种回调，可以把请求日志、用量、延迟推到监控系统。我一般关注几个指标：请求成功率、P99 延迟、各模型用量占比、缓存命中率。告警阈值我设的是：成功率低于 95% 告警，P99 延迟超过 10 秒告警。这两个指标能覆盖大部分异常情况。6.3 安全加固要点安全方面有几个必做的点。第一，master key 一定要强，别用默认值。第二，虚拟密钥要设预算和限流，防止滥用。第三，代理服务不要直接暴露公网，放在内网或加一层网关。第四，日志里不要记录完整密钥，脱敏处理。我见过有人把代理服务直接暴露公网，结果被扫到后疯狂调用，账单爆炸。这个教训很深刻，安全配置不能省。7. 扩展玩法与个人体会7.1 结合本地模型的混合部署litellm 一个很实用的玩法是混合部署：简单请求走本地小模型，复杂请求走云端大模型。这样既能控制成本，又能保证效果。配置上就是注册两个模型，然后在业务层做路由判断。我实测下来，把 60% 的简单请求分流到本地模型后，云端成本下降了近一半，而用户体验基本没受影响。这个策略对成本敏感的场景很值得试。7.2 作为模型评测的基础设施做模型评测的时候，litellm 能省很多事。同一套评测代码，换个模型名就能跑不同模型，结果格式统一，方便对比。我一般会写个脚本，遍历模型列表，批量跑评测集，最后汇总成表格。这个用法对算法同学特别友好，不用为每个模型写适配代码，专注在评测逻辑上就行。7.3 我踩过的几个印象深刻的坑最后分享几个我踩过的坑，帮你少走弯路。第一个是模型名前缀遗漏，直接写llama3而不是ollama/llama3，结果路由失败。第二个是配置文件缩进错误，YAML 对缩进敏感，一个空格错位就解析失败。第三个是版本升级导致的参数默认值变化，升级前一定要看 changelog。这些坑都不难解决，但不知道的时候确实会卡很久。希望这些经验能帮你节省时间。litellm 这个工具，用熟了之后确实能大幅提升多模型场景的开发效率，值得花时间深入掌握。