[Bug]: Google AI generateContent endpoints require a different request body shape than the native API

快速结论：此报错发生在通过 LiteLLM 代理服务器调用 Google AI generateContent 端点时，请求体格式与 Google 原生 API 不兼容。优先排查是否将 generationConfig 误写为 config，或将 safetySettings / systemInstruction 错误地放在顶层而非 extra_body 中。

问题场景

在 LiteLLM 代理服务器（形象为 main-stable 版本）中，通过 /v1beta/models/<model>:generateContent 端点调用 Google Gemini 模型时，请求体中的 generationConfig（如 responseMimeType、responseSchema）、safetySettings、systemInstruction 等参数被忽略或报错。该行为影响期望实现 Google 原生 API 无缝替换的场景。

报错原文

// 请求中 generationConfig 被忽略，返回纯文本响应而非结构化输出
// 请求中 safetySettings 被忽略，返回 safetyRatings: null
// 或 map_generate_content_optional_params 期望 system_instruction / safety_settings 在 config 内时出错

原因分析

这是 LiteLLM 内部实现不一致导致的已知 Bug。LiteLLM 的 generateContent 端点直接调用内部 agenerate_content 函数，未对请求体进行格式转换（reformatting），导致它期望的数据结构与 Google 原生 API 不同：

Google 原生 API 接受 generationConfig（camelCase 键）。
LiteLLM 端点实际期望 config（snake_case 键），如 response_mime_type 而非 responseMimeType。
safetySettings 和 systemInstruction 必须放在 extra_body 对象内，而非请求顶层。
map_generate_content_optional_params 函数进一步要求 system_instruction 和 safety_settings 在 config 内部，这与其他参数预期冲突。

环境排查

LiteLLM 版本：main-stable 镜像（或目前可用的最新版本）。
使用端点：/v1beta/models/<model>:generateContent（LiteLLM 代理路径）。
目标模型：Google Gemini 系列（如 gemini-2.0-flash）。
请求内容：检查是否直接在请求顶层使用了 generationConfig、safetySettings、systemInstruction。

解决步骤

将顶层的 generationConfig 字段替换为 config，并将其内的键改为 snake_case（例如 responseMimeType → response_mime_type，responseSchema → response_schema）。
将 safetySettings 和 systemInstruction 从请求顶层移除，放入 extra_body 对象中，保持字段名不变（camelCase）。
确认 config 字段内不包含 system_instruction 或 safety_settings，它们应仅通过 extra_body 传递。
具体示例（对比原生与 LiteLLM 工作方式）：
原生请求（不工作）：
{"generationConfig": {"responseMimeType": "application/json"}}
LiteLLM 兼容请求（工作）：
{"config": {"response_mime_type": "application/json"}}
原生安全设置（不工作）：
{"safetySettings": [{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}]}
LiteLLM 兼容请求（工作）：
{"extra_body": {"safetySettings": [{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}]}}

验证方法

发送 curl 请求后，检查返回的响应：

对于结构化输出，确认返回 JSON 格式内容，而非纯文本。
对于安全设置，确认响应中包含 "safetyRatings" 数组（而非 null），且对应类别设置生效。
使用 thinkingConfig 等高级参数时，验证模型是否能按预期输出思考过程。

参考来源

BerriAI/litellm #12671

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: Google AI generateContent endpoints require a different request body shape than the native API