02 - messages 与 content block 结构¶

messages 是一个 array，每条 message 是一个对象，必须包含 role 和 content（部分 role 还有额外字段）。

源码：litellm/types/llms/openai.py:666-838。

role 一览¶

role	使用场景	额外必填字段
`system`	系统提示	—
`developer`	OpenAI o1/gpt-5 推荐替代 `system` 的系统提示	—
`user`	用户输入（支持 string 或多模态 content block 数组）	—
`assistant`	模型历史输出 / 带工具调用的历史输出	`content` 可为 null，此时必须有 `tool_calls` 或 `function_call`
`tool`	工具调用结果	`tool_call_id`（必填）
`function`	⚠️ 已弃用，请用 `tool`	`name`（必填）

所有 role 对象都可选 name 字段（用于区分同 role 的不同参与者），多数 provider 忽略。

content 的两种形式¶

形式 A：纯字符串（最常用）¶

{"role": "user", "content": "你好"}

形式 B：content block 数组（多模态必用）¶

{
  "role": "user",
  "content": [
    {"type": "text", "text": "这张图里有什么？"},
    {"type": "image_url", "image_url": {"url": "https://.../cat.png", "detail": "high"}}
  ]
}

content block 类型¶

LiteLLM 允许的 content block type 列表（见 ValidChatCompletionMessageContentTypes）：

type	用途	字段	支持 provider
`text`	文本段	`text: str`	全部
`image_url`	图片 URL 或 base64 data URI	`image_url: {url, detail?, format?}`	OpenAI/Anthropic/Bedrock/Vertex/Gemini 等视觉模型
`input_audio`	音频（base64）	`input_audio: {data, format}`（见下）	OpenAI gpt-audio / Gemini
`audio_url`	音频 URL	`audio_url: {url}`	Gemini / Bedrock
`video_url`	视频 URL / data URI	`video_url: {url, detail?}`	Gemini / Bedrock Nova
`document`	文档原文 + 可选的 citations 开关	`source: {type, media_type, data}`、`title`、`context`、`citations: {enabled}`	Anthropic
`file`	上传过的文件引用或 inline 文件数据	`file: {file_id? / file_data?, filename?, format?, detail?, video_metadata?}`	OpenAI Files、Anthropic（PDF）、Gemini
`thinking`	模型思维链（assistant 侧回显时使用）	`thinking: str`、`signature`、`cache_control?`	Anthropic
`redacted_thinking`	被脱敏的思维链	`data: str`、`cache_control?`	Anthropic

image_url 细节¶

{"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR...", "detail": "high"}}

url 可填 http(s) 链接或 data: 协议的 base64。
detail：auto（默认）/low/high。
LiteLLM 有个私有扩展字段 format（非 OpenAI 官方），用来显式声明 MIME type；对部分 provider（Bedrock）有用。

file（PDF / 长文）¶

{"type": "file", "file": {"file_data": "<base64>", "filename": "spec.pdf"}}

若填 file_id 且值以 http:// / https:// / www. 开头，gpt_transformation.py 的 _handle_pdf_url 会自动下载并转 base64 填进 file_data。

message 级别的可选字段¶

1. `cache_control`（LiteLLM 包装的 Anthropic prompt caching）¶

任何 role 的 message，以及 text / image content block，都可以加：

{"type": "text", "text": "...(长 system prompt)...", "cache_control": {"type": "ephemeral"}}

只对 Anthropic（含 Bedrock Claude、Vertex Claude）生效。
其它 provider 会直接忽略这个字段，不报错。
计费见 billing-and-pricing/05-cache-pricing-bugs。

2. `tool_calls`（assistant 消息发起工具调用时）¶

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"city\": \"Beijing\"}"
      }
    }
  ]
}

随后 tool 消息用 tool_call_id 把结果回传：

{"role": "tool", "tool_call_id": "call_abc", "content": "晴，25℃"}

3. `thinking_blocks`（assistant 回传 Anthropic thinking）¶

assistant 消息可带 thinking_blocks，把上一次 Claude 返回的 thinking 原样回灌，以免丢失思维链上下文。

4. `reasoning_content`¶

assistant 消息的 reasoning_content 字段，装非 thinking 风格的推理内容（deepseek-reasoner 等）。

最小示例集合¶

纯文本

[
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Explain L1 regularization in one sentence."}
]

图像 + 文本

[
  {"role": "user", "content": [
    {"type": "text", "text": "Describe the image."},
    {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
  ]}
]

带工具调用的多轮

[
  {"role": "user", "content": "今天北京天气？"},
  {"role": "assistant", "content": null, "tool_calls": [
    {"id": "c1", "type": "function",
     "function": {"name": "get_weather", "arguments": "{\"city\":\"Beijing\"}"}}
  ]},
  {"role": "tool", "tool_call_id": "c1", "content": "晴，25℃"},
  {"role": "assistant", "content": "今天北京晴，25℃。"}
]

Anthropic prompt caching

[
  {"role": "system", "content": [
    {"type": "text", "text": "<很长的 system prompt>", "cache_control": {"type": "ephemeral"}}
  ]},
  {"role": "user", "content": "用户问题"}
]

代理层会对 messages 做的改写¶

场景	改写	触发条件
`validate_and_fix_openai_messages`	规范化 role / 合法性校验	每个请求
`get_completion_messages` 去重	避免 deep copy 失败、去重	每个请求
`modify_params=true` 下的 6 类修正	详见 config/modify-params	仅对 Anthropic / Bedrock

下游传入的 messages 与代理最终发出的 messages 可能不一致；如果要验证「实际发给上游的是什么」，开 general_settings.return_response_headers: true 看 response header 的 llm-api-request-model，或去 business log 里对照 proxy_server_request.body。