LiteLLM：统一API网关实现多模型无缝切换与智能路由

1. 项目概述：LiteLLM 是什么，它解决的到底是什么问题？

LiteLLM 这个名字在最近半年的技术圈里出现频率明显升高，尤其在中小型开发团队、独立开发者和AI应用快速验证场景中，几乎成了“模型网关”这个概念最常被提及的实现方案。它不是大语言模型本身，也不是一个训练框架，而是一个轻量级、高度兼容的统一API抽象层——你可以把它理解成给各种大模型服务装上的“万能转接头”。当你用 OpenAI 的 API 格式写好一段调用逻辑，LiteLLM 能让它原封不动地跑在 Anthropic、Google Gemini、Ollama 本地模型、甚至 Azure OpenAI 或某国产大模型厂商的私有接口上，中间几乎不需要改一行业务代码。

这背后解决的，是当前AI工程落地中最真实、最扎心的三个痛点：第一是供应商锁定（Vendor Lock-in），一旦业务深度绑定某家云厂商的模型API，后续想换模型、压成本、做多模型路由或灰度测试，就得重写整套调用链；第二是开发与测试效率低下，本地调试时想用 Ollama 跑 Llama3，上线却要切到 OpenAI，每次切换都要改 endpoint、key、参数名（比如max_tokensvsmax_output_tokens），光是参数对齐就能耗掉半天；第三是可观测性与治理缺失，没有统一入口，就无法集中记录请求耗时、token用量、错误率、模型响应分布，更别提做熔断、限流、缓存或成本分摊了。

LiteLLM 的核心价值，不在于它有多“智能”，而在于它足够“透明”和“可插拔”。它不做模型推理，只做协议翻译；不参与语义理解，只负责把messages数组、temperature、top_p这些通用字段，精准映射到后端不同服务商要求的字段结构里。我去年在一个客户侧的智能客服中台项目里实测过：原本对接 4 家模型服务商需要维护 4 套 SDK 和 4 套重试/降级逻辑，接入 LiteLLM 后，SDK 层直接归一为一套，运维配置从 4 个 YAML 文件压缩成 1 个model_router.yaml，上线新模型平均耗时从 2 天缩短到 15 分钟。这不是理论优势，是每天都在发生的工程提效。

它适合谁？如果你是正在搭建 RAG 应用、Agent 工作流或 AI Native 产品的工程师，手头已有 OpenAI 风格的 prompt 工程代码，但又不想被绑死在单一服务商上；如果你是技术负责人，需要为团队建立模型选型的弹性机制，同时控制 API 成本和故障影响面；或者你只是个想本地跑通一个完整 AI 流程的爱好者，手头只有 24G 显存的 3090，想先用 Ollama 跑通逻辑，再平滑迁移到云端——那 LiteLLM 就是你此刻最值得花 20 分钟搭起来的基础设施。它不炫技，但极其务实；不替代模型，却让模型真正变成可调度的资源。

2. 整体架构设计与方案选型逻辑

2.1 为什么不是自己写个“适配器”？LiteLLM 的不可替代性在哪？

很多人第一反应是：“这不就是个 if-else 转发器吗？我自己写个 Python 函数也能做。”这话在单模型、单场景下确实成立。但当真实业务复杂度上来后，自研适配器会迅速暴露出四个致命短板，而 LiteLLM 正是针对这些短板做了系统性加固。

首先是协议兼容的完整性。OpenAI API 看似简单，但实际包含 streaming 响应、function calling、tool choice、response format（如 JSON mode）、logprobs、parallel tool calls 等十余个高级特性。每个服务商对这些特性的支持程度千差万别：Anthropic 支持 tool use 但不叫 function calling；Google Gemini 的 streaming 响应结构完全不同；Ollama 的/chat接口连systemrole 都不原生支持。LiteLLM 内置了超过 100 种模型/服务商的 mapping 规则，每条规则都经过真实请求抓包验证，比如它会自动将 OpenAI 的{"role": "system", "content": "xxx"}在发送给 Ollama 时，转换为{"role": "user", "content": "System: xxx"}并插入到 messages 开头——这种细节，靠手写 if-else 很难覆盖全，更难长期维护。

其次是错误处理与重试策略的健壮性。不同服务商的错误码体系完全不统一：OpenAI 返回429表示 rate limit，Anthropic 是429但 message 字段叫status_text，Azure 是429但带x-ratelimit-reset-secondsheader，而某些国产模型返回500却实际是超时。LiteLLM 内置了标准化的错误分类（RateLimitError、BadRequestError、AuthenticationError等），并支持按错误类型配置差异化重试：对RateLimitError指数退避，对BadRequestError直接失败不重试。我们曾在线上遇到某模型服务商因证书更新导致所有请求返回ssl.SSLCertVerificationError，LiteLLM 的 fallback 机制自动将流量切到备用模型，整个过程对上游业务无感——这种级别的容错，自研适配器很难在短期内做到。

第三是可观测性与治理能力的开箱即用。LiteLLM 提供了完整的litellm.success_callback和litellm.failure_callback钩子，可无缝对接 Prometheus、Datadog 或自建日志系统。更重要的是，它内置了litellm.token_counter，能基于模型 tokenizer 精确计算输入输出 token 数（而非粗略估算），这对成本核算至关重要。我们曾用它发现某业务线 70% 的 token 消耗来自 system prompt 的重复加载——这个洞察直接推动了 prompt 缓存模块的落地。而自研方案往往要花额外精力去补全这些监控埋点。

最后是生态扩展的可持续性。LiteLLM 采用插件化设计，新增一个模型支持，只需提交一个 PR，定义completion()和embedding()两个函数，以及对应的get_supported_openai_params()和map_openai_params()。社区已贡献了对 Groq、Fireworks、DeepInfra、Together.ai 等新兴算力平台的支持。这意味着你今天选它，明天就能用上刚发布的模型，无需等待内部排期。这种演进速度，是任何封闭自研方案无法比拟的。

2.2 部署形态选择：本地进程 vs Docker vs 云服务？哪种更适合你的场景？

LiteLLM 本身是一个 Python 包，但它的部署方式直接影响可用性、隔离性和运维成本。我们根据实际项目经验，总结出三种主流形态及其适用边界：

形态一：本地进程直连（pip install litellm && litellm --model gpt-3.5-turbo）
这是最快上手的方式，适合个人开发、POC 验证或 CI/CD 中的单元测试。启动命令极简，5 秒内即可获得一个 OpenAI 兼容的本地服务。但它最大的问题是无状态、无并发保护、无健康检查。当多个测试用例并发请求时，容易触发 Ollama 的内存溢出；若后端模型服务临时不可用，LiteLLM 进程会直接报错退出。我们曾在一个自动化测试流水线中使用此模式，结果因某次网络抖动导致 LiteLLM 进程崩溃，整个测试链路中断。因此，它仅推荐用于“一次性、低负载、可丢弃”的场景。

形态二：Docker 容器化部署（官方镜像ghcr.io/berriai/litellm:latest）
这是生产环境最主流的选择。官方镜像预装了所有依赖，支持通过环境变量（LITELLM_MODEL_LIST）或挂载配置文件（config.yaml）动态加载模型列表。关键优势在于进程隔离、资源限制、健康探针和优雅重启。我们通常会配置--restart=unless-stopped和--memory=2g，并暴露/health端点供 Kubernetes liveness probe 使用。更重要的是，Docker 模式天然支持多实例部署，配合 Nginx 或 Traefik 做负载均衡，可轻松支撑每秒数百 QPS。某电商公司的商品描述生成服务，就采用 3 台 LiteLLM Docker 实例 + Consul 服务发现，稳定运行超 8 个月无重启。

形态三：托管云服务（LiteLLM Cloud / 自建 SaaS 化平台）
LiteLLM 官方提供了托管服务 LiteLLM Cloud，但更多企业会选择基于开源版自建 SaaS 平台。这种形态的核心价值是统一认证、细粒度配额、审计日志和模型市场。例如，我们可以为市场部开通claude-3-haiku的 1000 QPD 配额，为研发部开通llama3-70b的 5000 tokens/day 配额，并在后台看到每个部门的实时用量热力图。某金融科技公司就基于此构建了内部 AI 服务中心，业务方只需申请 Key，即可自助接入模型，IT 部门则通过后台一键调整配额或禁用异常调用——这种治理能力，是单纯部署一个进程无法提供的。

选择建议：个人学习 → 本地进程；中小团队 MVP → Docker；中大型企业规模化应用 → 自建 SaaS 平台。没有银弹，只有匹配。

3. 核心细节解析与实操要点

3.1 配置文件config.yaml的关键字段详解与避坑指南

LiteLLM 的灵魂在于config.yaml，它决定了模型如何被路由、如何被调用、如何被监控。一份典型的生产级配置远不止是罗列 model name，而是包含了路由策略、fallback 逻辑、缓存规则等深层控制。下面逐字段拆解其原理与实操陷阱。

model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo api_key: sk-xxx api_base: https://api.openai.com/v1 rpm: 3500 # requests per minute tpm: 180000 # tokens per minute - model_name: claude-3-haiku litellm_params: model: claude-3-haiku-20240307 api_key: xxx api_base: https://api.anthropic.com/v1 max_retries: 2

model_name是你在业务代码中调用时使用的逻辑名称（如litellm.completion(model="gpt-3.5-turbo", ...)），而litellm_params.model才是实际发送给服务商的物理模型名。这个分离设计是 LiteLLM 路由能力的基础。避坑点一：不要把model_name和litellm_params.model写成一样，否则会失去抽象意义。正确做法是model_name体现业务语义（如fast-response-model），litellm_params.model体现技术细节（如gpt-3.5-turbo-0125）。

rpm和tpm参数是 LiteLLM 内置的速率限制器（Rate Limiter）的关键。它不是简单的计数器，而是基于令牌桶算法（Token Bucket）实现的。rpm=3500表示每分钟最多允许 3500 次请求，但 LiteLLM 会将其平滑为每秒约 58.3 次，避免突发流量打垮后端。避坑点二：rpm和tpm必须与服务商文档严格对齐。OpenAI 的 gpt-3.5-turbo 免费 tier 是 3500 RPM / 180K TPM，但如果填错成rpm: 10000，LiteLLM 会盲目放行，导致服务商直接返回 429，此时 LiteLLM 的 fallback 机制可能来不及触发。我们曾因此被 OpenAI 临时封禁 API Key 2 小时——教训是：所有限速值必须从服务商控制台截图确认，而非凭记忆填写。

max_retries字段常被误解为“失败后重试几次”，其实它控制的是单次请求生命周期内的最大重试次数，且仅对网络超时、5xx 错误生效。对于 4xx 错误（如BadRequestError），LiteLLM 默认不重试，因为这类错误通常是请求本身有问题（如 prompt 过长、参数非法），重试毫无意义。避坑点三：不要盲目提高max_retries。我们曾将max_retries: 5应用于一个高延迟的国产模型，结果一次失败请求平均耗时 15 秒（3 次超时 × 5 秒），严重拖慢整体 P95 延迟。最终改为max_retries: 1+timeout: 8.0，并启用 fallback 到更快的模型，P95 从 12s 降至 2.3s。

更高级的配置是router_settings，它启用了 LiteLLM 的智能路由能力：

router_settings: num_retries: 1 timeout: 60 enable_pre_call_checks: true routing_strategy: least-busy

least-busy策略会实时统计每个模型实例的 pending 请求队列长度，优先将新请求发给最空闲的实例。这比简单的 round-robin 更能应对模型性能波动。但避坑点四：enable_pre_call_checks在高并发下可能成为瓶颈。它会在每次请求前调用/models接口检查模型健康状态，如果后端模型服务响应慢，这个检查本身就会增加 200ms 延迟。我们的解决方案是关闭它，改用定期心跳探测（litellm.health_check_interval=30），将健康检查与请求路径解耦。

3.2 模型路由与 fallback 机制的实战配置

LiteLLM 的 fallback 机制不是简单的“主备切换”，而是一套可编程的、支持多级嵌套的决策树。它的核心是litellm.set_fallbacks()函数和fallbacks配置项。下面是一个真实生产环境的 fallback 链配置：

fallbacks: - gpt-3.5-turbo: [gpt-4-turbo, claude-3-haiku] - gpt-4-turbo: [claude-3-sonnet, llama3-70b] - claude-3-haiku: [gpt-3.5-turbo, llama3-8b]

这段配置的含义是：当调用gpt-3.5-turbo失败时，LiteLLM 会依次尝试gpt-4-turbo和claude-3-haiku；如果gpt-4-turbo也失败，则继续尝试claude-3-sonnet，依此类推。关键原理在于：fallback 是按“调用链”而非“模型池”执行的。也就是说，它不会把所有 fallback 模型拉出来排序，而是严格遵循配置顺序，一个一个试，直到成功或耗尽列表。

这个机制的强大之处在于可以结合业务语义做精细化控制。例如，在一个法律文书生成场景中，我们定义了legal-review-model作为逻辑模型名，其 fallback 链为：

- legal-review-model: [claude-3-sonnet, gpt-4-turbo, gemini-1.5-pro]

理由很清晰：Claude 在长文本推理和法律条款严谨性上表现最佳，是首选；GPT-4-turbo 次之，但支持更大的上下文；Gemini-1.5-pro 作为兜底，胜在响应快、成本低。当用户上传一份 50 页 PDF 时，LiteLLM 会自动选择最适合处理长上下文的模型，而业务代码完全无感。

但 fallback 也有陷阱。避坑点五：fallback 不会自动修正请求参数。假设你的原始请求设置了max_tokens=4096，而 fallback 到的claude-3-haiku最大只支持4096输出，但它的max_tokens参数实际叫max_tokens_to_sample，且最大值是4096。LiteLLM 会自动做参数映射，但如果原始请求中包含了response_format: {"type": "json_object"}，而 fallback 模型根本不支持 JSON mode（如 Ollama 的 Llama3），LiteLLM 会直接报错，不会尝试移除该参数。我们的解决方案是在业务层封装一个safe_completion()函数，在调用 LiteLLM 前，根据目标模型能力动态裁剪参数——这提醒我们：fallback 是基础设施能力，但参数兼容性仍需业务层兜底。

另一个高级技巧是context-aware fallback。LiteLLM 支持通过litellm.context_window_fallbacks配置，根据输入内容长度自动选择 fallback 模型。例如：

litellm.context_window_fallbacks = { "gpt-3.5-turbo": ["gpt-4-turbo", "claude-3-haiku"], "gpt-4-turbo": ["claude-3-sonnet", "gemini-1.5-pro"] }

当输入 tokens 超过 8192 时，LiteLLM 会自动跳过gpt-3.5-turbo，直接从gpt-4-turbo开始尝试。这比静态 fallback 更智能，但也更难调试——我们曾因未在日志中打印实际触发的 fallback 路径，导致线上问题排查耗时 3 小时。因此，强烈建议开启详细日志：litellm.set_verbose = True，并在日志中搜索"fallback"关键字，它会清晰记录每次 fallback 的触发原因、尝试顺序和最终结果。

4. 实操过程与核心环节实现

4.1 从零开始部署一个高可用 LiteLLM 服务（Docker Compose 版）

下面是一个经过生产验证的docker-compose.yml，它不仅启动 LiteLLM，还集成了监控、日志、健康检查和配置热更新，可直接用于中小规模业务。

version: '3.8' services: litellm: image: ghcr.io/berriai/litellm:latest restart: unless-stopped ports: - "4000:4000" environment: - LITELLM_PORT=4000 - LITELLM_CONFIG_PATH=/app/config.yaml - LITELLM_LOG_LEVEL=INFO - LITELLM_HEALTH_CHECK_INTERVAL=30 - LITELLM_MAX_REQUESTS_PER_MINUTE=10000 - LITELLM_MAX_TOKENS_PER_MINUTE=500000 volumes: - ./config.yaml:/app/config.yaml:ro - ./logs:/app/logs healthcheck: test: ["CMD", "curl", "-f", "http://localhost:4000/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s deploy: resources: limits: memory: 2G cpus: '1.0' prometheus: image: prom/prometheus:latest volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro command: - '--config.file=/etc/prometheus/prometheus.yml' - '--storage.tsdb.path=/prometheus' ports: - "9090:9090" grafana: image: grafana/grafana:latest environment: - GF_SECURITY_ADMIN_PASSWORD=admin volumes: - ./grafana/provisioning:/etc/grafana/provisioning ports: - "3000:3000"

配套的prometheus.yml配置了对 LiteLLM metrics 的抓取：

global: scrape_interval: 15s scrape_configs: - job_name: 'litellm' static_configs: - targets: ['litellm:4000']

而config.yaml则启用了完整的可观测性：

model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo api_key: ${OPENAI_API_KEY} rpm: 3500 tpm: 180000 - model_name: llama3-8b litellm_params: model: ollama/llama3:8b api_base: http://host.docker.internal:11434 rpm: 10 tpm: 5000 litellm_settings: drop_params: false # 不丢弃未知参数，便于调试 success_callback: ["prometheus"] # 上报指标到 Prometheus failure_callback: ["prometheus", "slack"] # 失败时同时上报指标和发 Slack num_retries: 1 router_settings: routing_strategy: least-busy num_retries: 1 timeout: 60

实操步骤与现场记录：

1. 准备环境：在一台 4C8G 的云服务器上，安装 Docker 和 Docker Compose。注意：host.docker.internal在 Linux 上默认不存在，需在docker-compose.yml的 litellm service 下添加extra_hosts: ["host.docker.internal:host-gateway"]。

2. 创建目录结构：

   mkdir -p litellm/{logs,grafana/provisioning/dashboards} cd litellm

3. 编写配置文件：将上述docker-compose.yml、prometheus.yml、config.yaml保存到对应位置。特别注意config.yaml中的${OPENAI_API_KEY}，需在docker-compose.yml的 environment 中定义，或使用.env文件。

4. 启动服务：

   docker-compose up -d

   启动后，执行docker-compose logs -f litellm查看实时日志。正常启动会看到类似LiteLLM: Starting server on port 4000的日志。

5. 验证服务健康：

   curl http://localhost:4000/health # 返回 {"status": "healthy", "models": ["gpt-3.5-turbo", "llama3-8b"]}

6. 发送第一个请求（模拟业务调用）：

   curl -X POST "http://localhost:4000/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-xxx" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello!"}] }'

   如果返回了标准 OpenAI 格式的 response，说明服务已就绪。

关键参数解释与选择依据：

• LITELLM_HEALTH_CHECK_INTERVAL=30：每 30 秒主动探测一次后端模型服务的健康状态，避免将流量发给已宕机的实例。这个值不能设得太小（如 5s），否则会增加后端负担；也不能太大（如 120s），否则故障发现太慢。30s 是我们在多个项目中验证过的平衡点。
• deploy.resources.limits.memory=2G：LiteLLM 进程本身内存占用很低（通常 <200MB），但预留 2G 是为了容纳大量并发请求的上下文对象和日志缓冲区。我们曾将内存限制设为 512M，结果在 200 QPS 下频繁触发 OOM Killer，导致服务重启。
• healthcheck.start_period=40s：给予 LiteLLM 40 秒的启动宽限期，因为它需要加载配置、初始化连接池、预热 tokenizer，这个时间比普通 Web 服务长得多。

4.2 业务代码集成：如何在 Python 项目中安全调用 LiteLLM

LiteLLM 的 Python SDK 极其简洁，但“简洁”不等于“简单”。一个健壮的集成，需要处理超时、重试、fallback、日志和错误分类。下面是我们团队的标准封装：

import litellm from litellm import completion, embedding from litellm.exceptions import ( RateLimitError, BadRequestError, AuthenticationError, ContextWindowExceededError ) import logging # 全局配置 litellm.set_verbose = False # 生产环境关闭 verbose，避免日志爆炸 litellm.success_callback = ["langfuse"] # 集成 Langfuse 追踪 litellm.failure_callback = ["langfuse"] class AIAgent: def __init__(self, default_model="gpt-3.5-turbo"): self.default_model = default_model # 预加载常用模型，避免首次调用延迟 try: completion(model=self.default_model, messages=[{"role": "user", "content": "test"}], max_tokens=1) except Exception as e: logging.warning(f"Preload model {self.default_model} failed: {e}") def chat(self, messages, model=None, **kwargs): model = model or self.default_model # 动态设置超时，长上下文请求延长 timeout input_tokens = litellm.token_counter(model=model, messages=messages) timeout = 60 if input_tokens < 4000 else 120 try: response = completion( model=model, messages=messages, timeout=timeout, num_retries=1, # 交给 LiteLLM 统一管理重试 **kwargs ) return response except RateLimitError as e: logging.error(f"Rate limit exceeded for model {model}: {e}") # 触发告警，通知运维 self._alert_rate_limit(model) raise except ContextWindowExceededError as e: logging.error(f"Context window exceeded for model {model}: {e}") # 自动 fallback 到更大上下文模型 return self._fallback_to_larger_context(messages, **kwargs) except Exception as e: logging.exception(f"Unexpected error calling {model}: {e}") raise def _fallback_to_larger_context(self, messages, **kwargs): """根据输入长度，选择支持更大上下文的模型""" input_tokens = litellm.token_counter(model=self.default_model, messages=messages) if input_tokens > 32000: fallback_model = "claude-3-sonnet" elif input_tokens > 16000: fallback_model = "gpt-4-turbo" else: fallback_model = "gpt-3.5-turbo" logging.info(f"Fallback to {fallback_model} for long context") return self.chat(messages, model=fallback_model, **kwargs) def _alert_rate_limit(self, model): """发送 rate limit 告警""" # 这里可以集成企业微信、钉钉或 PagerDuty pass

这个封装的核心价值在于：

• 超时动态化：不再使用固定timeout=30，而是根据输入 tokens 长度智能调整。因为 1000 tokens 的请求和 10000 tokens 的请求，合理的超时阈值天差地别。我们曾用固定 timeout 导致大量TimeoutError被误判为模型故障，实际上只是请求太长。
• 错误分类处理：RateLimitError和ContextWindowExceededError是两类完全不同的问题，前者需要扩容或优化调用频次，后者需要换模型。混为一谈会导致错误的运维决策。
• 预加载（Preload）：completion(..., max_tokens=1)这个 trick 能在服务启动时就完成模型连接池的初始化和 tokenizer 加载，避免首个用户请求遭遇长达 5 秒的冷启动延迟。这是我们在 A/B 测试中验证过，能将 P99 延迟降低 4.2 秒的关键优化。
• Fallback 语义化：_fallback_to_larger_context()不是简单地换一个模型，而是根据输入长度这个业务指标，选择最合适的 fallback 模型，体现了 LiteLLM 作为“智能路由层”的真正价值。

5. 常见问题与排查技巧实录

5.1 “Connection refused” 错误：是 LiteLLM 挂了，还是后端模型没起来？

这是新手遇到的第一个高频问题。当你执行curl http://localhost:4000/chat/completions得到Failed to connect to localhost port 4000: Connection refused时，第一反应往往是“LiteLLM 没启动”。但根据我们线上 23 个项目的排障记录，70% 的情况其实是后端模型服务（如 Ollama、vLLM）根本没运行，LiteLLM 因无法连接而主动退出。

LiteLLM 的启动逻辑是：读取config.yaml→ 尝试连接每个litellm_params.api_base→ 如果任意一个连接失败，它会打印ERROR: Failed to connect to ...并立即退出进程。因此，Connection refused很可能意味着 LiteLLM 进程已经死了。

排查步骤：

1. 检查 LiteLLM 进程状态：

   docker-compose ps litellm # 看 STATUS 列是否为 "Up" # 如果是 "Exit 1"，说明启动失败

2. 查看启动失败日志：

   docker-compose logs litellm | head -50 # 重点找 "Failed to connect to" 或 "Connection refused" 字样

3. 验证后端模型服务：

   # 如果 config.yaml 里有 ollama/llama3:8b，检查 Ollama 是否运行 curl http://localhost:11434/api/tags # 应该返回包含 llama3 的 JSON

4. 临时绕过问题：注释掉config.yaml中所有暂时不用的模型，只保留一个确定能连通的（如gpt-3.5-turbo），再重启docker-compose up -d。如果成功，说明问题出在被注释的模型上。

独家技巧：使用litellm --test命令
LiteLLM 提供了一个诊断命令：

docker-compose exec litellm litellm --test --model gpt-3.5-turbo

它会模拟一次完整调用，输出详细的连接、认证、响应过程。这是我们定位网络问题的“瑞士军刀”。

5.2 “Bad request” 错误：参数映射失效的典型场景与修复

BadRequestError是第二大高频错误，根源几乎全是参数映射问题。LiteLLM 的映射规则非常精细，但仍有几个“灰色地带”容易踩坑。

场景一：systemrole 在 Ollama 中的特殊处理
Ollama 的/chatAPI 不原生支持systemrole。LiteLLM 的默认映射是将其转换为userrole 并加前缀System:。但某些 Ollama 模型（如phi3:mini）对前缀敏感，会把System: You are a helpful assistant.当作普通用户消息处理，导致指令失效。

修复方案：

• 方案 A（推荐）：在config.yaml中为该模型指定system_prompt参数：

  - model_name: phi3-mini litellm_params: model: ollama/phi3:mini system_prompt: "You are a helpful assistant."

• 方案 B：升级到 LiteLLM v1.42+，它增加了ollama_system_prompt配置项，可全局控制 system prompt 行为。

场景二：response_format的 JSON mode 兼容性
OpenAI 的response_format: {"type": "json_object"}是一个强大功能，但并非所有模型都支持。当 fallback 到llama3-8b时，LiteLLM 会尝试发送该参数，而 Ollama 会直接返回 400。

修复方案：
在业务代码中，调用前检测目标模型能力：

def supports_json_mode(model_name): json_models = ["gpt-3.5-turbo-0125", "gpt-4-turbo", "claude-3-sonnet"] return model_name in json_models if supports_json_mode(model): response = completion(model=model, messages=messages, response_format={"type": "json_object"}) else: # 降级为在 prompt 中强调 JSON 格式 messages[-1]["content"] += "\nRespond in valid JSON format only." response = completion(model=model, messages=messages)

场景三：tools参数的字段名差异
Anthropic 的 tool calling 使用tool_choice和tools字段，而 OpenAI 使用tool_choice和tools，看似一样，但 Anthropic 的tool_choice值是{"type": "tool", "name": "xxx"}，而 OpenAI 是{"type": "function", "function": {"name": "xxx"}}。LiteLLM 会自动转换，但如果你在tools定义中漏写了function字段，转换就会出错。

排查技巧：开启 verbose 日志

litellm.set_verbose = True response = completion(model="claude-3-haiku", messages=..., tools=tools)

日志中会打印出 LiteLLM实际发送给 Anthropic 的原始 payload，与官方文档对比，一眼就能