chat/completions 下游请求参数全景¶

面向对象：下游应用开发人员，问「LiteLLM 代理的 /v1/chat/completions（以及 /chat/completions）到底能传哪些字段、不会报错、能生效、各字段是什么含义」。

本目录把答案拆成五篇独立文档，按阅读顺序递进：

文档	主题
01-openai-standard-params	OpenAI 官方兼容的标准字段（temperature、top_p、tools……）逐个解释
02-messages-and-content-blocks	`messages` 的完整结构：6 种 role、7 种 content block、缓存标记
03-tools-and-structured-output	`tools` / `tool_choice` / `response_format` / `functions` 等高级字段
04-litellm-specific-params	LiteLLM 在 OpenAI 协议外增加的 body 字段（metadata、guardrails、caching、fallbacks、thinking、reasoning_effort……）
05-provider-passthrough-and-drop-params	未知字段的处理机制：`extra_body` 透传、`drop_params`、`allowed_openai_params`、各 provider 的支持矩阵
06-streaming-usage-field	流式响应中的 `usage` 字段：为什么默认没有、怎么显式打开、各客户端怎么传、计费/审计不受影响的原因

关键结论（先读这里）¶

1. 代理入口不做 pydantic 字段白名单¶

/chat/completions 的 FastAPI 路由拿到请求体后，直接 orjson.loads(body) 得到一个 dict，不经过 pydantic 模型校验。也就是说：下游可以传入任何字段，是否报错、是否生效由后续三道关卡决定：

客户端 JSON body
      │
      ▼
_read_request_body   ──  纯 JSON 解析，字段无白名单
      │
      ▼
add_litellm_data_to_request  ──  追加 metadata / headers / team 控制
      │
      ▼
router.acompletion(**data)    ──  走 Router 按 deployment 路由
      │
      ▼
litellm.completion(**kwargs)  ──  核心函数，按 provider 做 get_optional_params
      │
      ▼
provider.map_openai_params()  ──  按 provider 过滤 / 转译 / 丢弃 / 塞 extra_body
      │
      ▼
Provider HTTP 调用

关键源码定位： - litellm/proxy/proxy_server.py:6407 — chat_completion 路由入口 - litellm/proxy/common_utils/http_parsing_utils.py:16 — _read_request_body - litellm/proxy/litellm_pre_call_utils.py:810 — add_litellm_data_to_request - litellm/main.py:1055 — completion() 函数签名 - litellm/utils.py:3856 — get_optional_params() 按 provider 过滤 - litellm/constants.py:561 — OPENAI_CHAT_COMPLETION_PARAMS 白名单

2. 字段可以分成四类¶

类别	是否报错	是否生效	示例
OpenAI 标准字段	不会	只要当前 provider 支持就生效，否则按 `drop_params` 决定是丢弃还是 `UnsupportedParamsError`	`temperature`、`tools`、`response_format`
LiteLLM 特有字段（body 内）	不会	LiteLLM 内部消费，不透传给 provider	`metadata`、`guardrails`、`caching`、`fallbacks`、`tags`、`user`
Provider 扩展字段（未知字段）	OpenAI 兼容 provider 永不报错，其它 provider 视 `drop_params` 决定	对 openai / azure / openai_compatible：塞进 `extra_body` 原样发出；对其它 provider：如果在 provider 白名单里则生效，否则按 `drop_params` 处理	`thinking`、`reasoning_effort`、`extra_body`、`seed`
鉴权 / 路由 / 特殊 header	不会	由代理消费	`Authorization`、`x-litellm-trace-id`、`x-litellm-session-id`、`x-litellm-tags`

3. 「兜底安全通道」：drop_params 与 allowed_openai_params¶

全局开关 litellm.drop_params = True（或 yaml litellm_settings.drop_params: true）：遇到 provider 不支持的字段直接丢弃，不报错。
请求级开关 drop_params: true（放在 body）：只对本次请求生效。
白名单 allowed_openai_params: ["xxx", "yyy"]：逼 LiteLLM 跳过对这些字段的支持度检查，原样透传给 provider。
黑名单 additional_drop_params: ["xxx"]：在「整体不 drop」的前提下，只丢这几个字段。

见 05-provider-passthrough-and-drop-params。

4. 报错长什么样¶

当下游传了 provider 不支持的字段、且没开 drop_params：

{
  "error": {
    "message": "anthropic does not support parameters: ['frequency_penalty'], for model=claude-3-5-sonnet. To drop these, set `litellm.drop_params=True` or for proxy:\n\nlitellm_settings:\n drop_params: true\n. \n If you want to use these params dynamically send allowed_openai_params=['frequency_penalty'] in your request.",
    "type": "UnsupportedParamsError",
    "code": 500
  }
}

见 litellm/utils.py:3919。

最小可用 payload¶

curl -X POST https://<proxy-host>/v1/chat/completions \
  -H "Authorization: Bearer sk-<proxy-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

只有 model（string）和 messages（list）两个字段是必填的。其余全部可选。