05 - 未知字段透传、drop_params、provider 兼容矩阵¶

这篇解决「我传了 OpenAI / LiteLLM 协议里没列过的字段，会怎么样？」的问题。

判断规则（逐步）¶

LiteLLM 在 get_optional_params() 里走这套流程（litellm/utils.py:3856）：

用户 passed_params（body 里所有字段）
      │
      ▼
按 provider 取 supported_params = get_supported_openai_params(model, provider)
      │
      ▼
supported_params += allowed_openai_params    # 白名单扩展
      │
      ▼
遍历 non_default_params：
  ├─ 在 supported_params 里             → 走 provider.map_openai_params() 翻译
  ├─ 不在 supported_params 里 ⬇
  │    ├─ drop_params=True              → 静默丢弃
  │    └─ drop_params=False             → raise UnsupportedParamsError
  │
  ▼
add_provider_specific_params_to_optional_params(passed_params):
  ├─ provider ∈ {openai, azure, text-completion-openai, openai_compatible_*}
  │    → 未知字段全部塞进 optional_params["extra_body"]
  └─ 其它 provider
       → 未知字段直接塞进 optional_params（让 provider transformation 自己处理）

关键源码： - 过滤与丢弃 litellm/utils.py:3888-3929 - extra_body 收集 litellm/utils.py:4624-4681 - _apply_openai_param_overrides（白名单透传） litellm/utils.py:4683-4695

场景一：OpenAI / Azure / OpenAI-兼容上游¶

litellm.openai_compatible_providers 列表里的 provider（包含 openai、azure、perplexity、deepseek、xai、groq、together、anyscale、nvidia_nim、volcengine、wandb、mistral 等）走「未知字段一律装进 extra_body，原样发给 provider」的策略。

这意味着下游可以随便加 provider 新增字段，不需要升 LiteLLM 版本。比如：

{
  "model": "openai/gpt-4o",
  "messages": [...],
  "some_brand_new_openai_field": "value"
}

最终 LiteLLM 调 OpenAI SDK 时会把它放在 extra_body={"some_brand_new_openai_field": "value"}，OpenAI SDK 再把它 merge 进 HTTP body。

如果既传了 extra_body 字段又传了顶层字段，两者会 merge，顶层字段优先。见 litellm/utils.py:4647-4655。

常见需要用 extra_body 传的字段¶

字段	场景
`reasoning`	deepseek-reasoner、部分 openai_compat provider
`enable_thinking` / `thinking_config`	阿里通义千问、豆包
`structured_outputs` 变体	provider 自研
`min_p` / `top_k` / `repetition_penalty`	开源模型（vLLM、Together 等）
`provider_specific_header`	Anthropic Cache 策略等

场景二：非 OpenAI 兼容上游（Anthropic / Bedrock / Vertex / Gemini / Cohere……）¶

对这些 provider： - 在 get_supported_openai_params() 里没列的字段，按 drop_params 决定抛错或丢弃。 - 在列表里的字段，走 provider 的 map_openai_params() 翻译成 native 参数（比如 OpenAI 的 max_tokens 翻成 Anthropic 的 max_tokens，OpenAI 的 stop 翻成 Anthropic 的 stop_sequences）。 - allowed_openai_params 白名单会把字段临时加入 supported_params，跳过校验，然后原样放进 optional_params（由 provider transformation 决定怎么用）。

drop_params 的三种生效方式¶

作用域	用法
全局（Python）	`litellm.drop_params = True`
全局（yaml）	`yaml<br>litellm_settings:<br> drop_params: true<br>`
请求级	在 body 顶层加 `"drop_params": true`
环境变量	`LITELLM_DROP_PARAMS=true`

推荐策略：代理生产环境开全局 drop_params: true，让下游不用关心上游兼容性；对敏感业务（工具调用失败不能吞）单独开 drop_params: false。

allowed_openai_params / additional_drop_params¶

例：强制透传 `frequency_penalty` 给 Anthropic¶

{
  "model": "claude-3-5-sonnet",
  "messages": [...],
  "frequency_penalty": 0.3,
  "allowed_openai_params": ["frequency_penalty"]
}

LiteLLM 跳过校验，把 frequency_penalty 塞进 optional_params 发给 Anthropic（实际 Anthropic 会忽略这个字段，但至少不报错）。

例：屏蔽掉某个字段¶

{
  "model": "gpt-4o",
  "messages": [...],
  "seed": 42,
  "additional_drop_params": ["seed"]
}

请求级黑名单，不往上游发。

provider 支持矩阵（选摘）¶

源码索引：provider transformation 目录 litellm/llms/

OpenAI（`gpt_transformation.py`）¶

基础 params：frequency_penalty, logit_bias, logprobs, top_logprobs, max_tokens, max_completion_tokens, modalities, prediction, n, presence_penalty, seed, stop, stream, stream_options, temperature, top_p, tools, tool_choice, function_call, functions, max_retries, extra_headers, parallel_tool_calls, audio, web_search_options, service_tier, safety_identifier, prompt_cache_key, store

模型特殊： - gpt-4 / gpt-3.5-turbo-16k 不支持 response_format - gpt-audio 额外支持 audio - gpt-5 只支持子集（max_tokens, max_completion_tokens, stream, stream_options, web_search_options, service_tier, safety_identifier, response_format, user, store, verbosity, max_retries, extra_headers）

Anthropic（`anthropic/chat/transformation.py`）¶

stream, stop, temperature, top_p, max_tokens, max_completion_tokens, tools, tool_choice, extra_headers, parallel_tool_calls, response_format, user, web_search_options, speed, context_management

Claude 3.7 Sonnet / 4.x 额外支持：thinking, reasoning_effort

不支持：n, frequency_penalty, presence_penalty, logit_bias, seed, logprobs, top_logprobs, modalities, audio

Bedrock Converse（`bedrock/chat/converse_transformation.py`）¶

默认：max_tokens, max_completion_tokens, stream, stream_options, stop, temperature, top_p, extra_headers, response_format, requestMetadata, service_tier, parallel_tool_calls

Claude ARN 模型追加：tools, tool_choice, thinking, reasoning_effort（Nova 还追加 web_search_options）

Vertex / Gemini（`vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py`）¶

temperature, top_p, max_tokens, max_completion_tokens, stream, tools, functions, tool_choice, response_format, n, stop, extra_headers, seed, logprobs, top_logprobs, modalities, parallel_tool_calls, web_search_options

非 preview 模型额外：frequency_penalty, presence_penalty Gemini 2.5 thinking 模型额外：reasoning_effort, thinking

Google AI Studio Gemini（`gemini/chat/transformation.py`）¶

temperature, top_p, max_tokens, max_completion_tokens, stream, tools, tool_choice, functions, response_format, n, stop, logprobs, frequency_penalty, presence_penalty, modalities, parallel_tool_calls, web_search_options

reasoning 模型额外：reasoning_effort, thinking audio 模型额外：audio

extra_body 实战¶

OpenAI 官方 SDK 允许：

from openai import OpenAI
client = OpenAI(base_url="https://proxy/v1", api_key="sk-xxx")
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role":"user","content":"hi"}],
    extra_body={"custom_vendor_field": "foo"}
)

SDK 会把 extra_body merge 进最终 HTTP body。所以下游既可以直接把字段写在顶层（LiteLLM 会自动归集到 extra_body），也可以显式用 SDK 的 extra_body 参数。

排错清单¶

现象	检查
`UnsupportedParamsError: xxx does not support parameters: [...]`	检查 `drop_params` 配置，或用 `allowed_openai_params` 强行放行
字段传了但上游不生效	走的是非 OpenAI 兼容 provider，而且字段被 LiteLLM silent drop 了。打开 `LITELLM_LOG=DEBUG` 看 `Non-Default params passed to completion()` 与最终 optional_params 对比
需要看实际下发给上游的 body	查 business log 的 `proxy_server_request.body`（代理层记录） + provider 侧 HTTP log（如 Anthropic console）
OpenAI 返回 `unknown_parameter` 400	`extra_body` 里塞了 OpenAI 真的不认的字段；回退删字段或用 `additional_drop_params` 拦掉
Anthropic 返回 role 顺序错误	参考 config/modify-params，按需开启 `modify_params: true`

总结表：字段处理优先级¶

优先级	规则
1	`additional_drop_params` 里的字段 → 永远丢弃
2	`allowed_openai_params` 里的字段 → 跳过校验原样透传
3	provider `get_supported_openai_params()` 白名单命中 → 通过 `map_openai_params` 翻译
4	上游是 OpenAI 兼容 → 进 `extra_body` 原样发
5	上游是非 OpenAI 兼容 + `drop_params=true` → 静默丢
6	上游是非 OpenAI 兼容 + `drop_params=false`（默认） → 抛 `UnsupportedParamsError`