response_format¶

Function calling / JSON mode / structured output 几乎是每个下游都会碰到的高级字段。这篇详细讲它们的结构和各 provider 的兼容差异。

源码：litellm/types/llms/openai.py:839-908。

1. tools¶

tools 是 function calling 的新接口（取代了 functions）。结构：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["city"]
        },
        "strict": true
      }
    }
  ]
}

字段：

字段	类型	含义
`type`	string	目前只有 `"function"` 有效
`function.name`	string	工具名，函数识别 key
`function.description`	string	工具作用描述（LLM 会读）
`function.parameters`	JSON Schema	参数 schema
`function.strict`	bool	OpenAI structured output 严格模式：强制 LLM 按 schema 输出、禁止出现 schema 外字段

LiteLLM 扩展：tool 对象可加 cache_control: {"type": "ephemeral"}，走 Anthropic prompt caching。

schema 清理：LiteLLM 会自动剥掉一些在部分 provider 上会炸的 schema 关键字（additionalProperties: false、$id、$schema、某些 provider 下的 strict），见 litellm/utils.py:3449。

2. tool_choice¶

取值	含义
`"auto"`	默认，由模型决定是否调用工具
`"none"`	禁止调用工具，强制出文本
`"required"`	必须调一个工具（OpenAI 新增）
`{"type": "function", "function": {"name": "foo"}}`	强制调用指定工具

各 provider 都实现了相应映射（比如 Vertex 会翻译成 ToolConfig.functionCallingConfig.mode = NONE/AUTO/ANY，见 gemini map_tool_choice_values）。

3. parallel_tool_calls¶

类型	bool
默认	provider 级 default（OpenAI 侧默认 true）
置 false	强制 LLM 每轮最多发一个 tool_call

OpenAI / Anthropic / Bedrock / Vertex 均支持。

4. functions / function_call（弃用）¶

仍然兼容，但 OpenAI 已下线文档。建议改用 tools / tool_choice。

{
  "functions": [{"name": "f", "parameters": {...}}],
  "function_call": "auto"
}

LiteLLM 会自动把旧格式翻译成新格式发给 provider，反向回来时也会把工具调用回填到 function_call 字段以保持兼容。

5. response_format¶

5.1 JSON mode¶

{"response_format": {"type": "json_object"}}

要求 LLM 输出合法 JSON（仍需要 prompt 里明确说明 schema 期待）。大多 OpenAI 兼容 provider 支持。

5.2 JSON Schema / Structured Outputs¶

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "Weather",
      "schema": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "temp_c": {"type": "number"}
        },
        "required": ["city", "temp_c"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

Python SDK 侧还允许直接传一个 pydantic.BaseModel 类；代理入口是 HTTP，必须是 dict。

支持 provider： - OpenAI（gpt-4o 及以后）、Azure OpenAI - Anthropic（Claude 3.7+ 通过 tool_use 模拟） - Vertex / Gemini（Gemini 2.x 原生支持） - Bedrock（Claude via converse）

5.3 text¶

某些 provider 上 {"type": "text"} 用来显式关闭 json 模式。

6. web_search_options¶

激活内置 Web 搜索（Perplexity 式）：

{
  "web_search_options": {
    "search_context_size": "medium",
    "user_location": {
      "type": "approximate",
      "approximate": {"city": "Beijing", "country": "CN"}
    }
  }
}

支持：OpenAI gpt-4o-search-preview、Gemini、Anthropic（部分 Claude 4.x）、Bedrock Nova 等。

7. 完整工具调用一次往返示例¶

curl https://proxy/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "天气怎么样？我在北京"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto",
    "parallel_tool_calls": false
  }'

响应：

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

客户端执行完 get_weather("Beijing") 后，再发第二轮请求，messages 里追加 assistant（含 tool_calls）+ tool（含 tool_call_id）两条消息。