Gemini 原生参数透传

平台对 Gemini 系列采用「OpenAI 字段标准化 + Gemini 原生字段透传」的双轨机制 —— 客户端传 Gemini 原生 GenerationConfig 字段(如 topK / responseSchema / mediaResolution / thinkingConfig)会转发到底层 Vertex AI；内容审核使用 safety_settings 传入,平台会映射为 Gemini API 的 safetySettings[]。

适用接口与模型

接口:v1/chat/completions(OpenAI 兼容协议下传 Gemini 原生字段)
适用模型:以模型目录 → Gemini 为准。
官方文档:Gemini Thinking / Gemini SafetySetting / Vertex AI GenerationConfig

透传机制

OpenAI 标准字段(temperature / max_tokens / top_p 等):平台自动映射到 Gemini 对应参数
Gemini 原生字段(topK / responseSchema / responseMimeType / mediaResolution / thinkingConfig 等):直接透传给上游,无需转换
内容审核字段:safety_settings 按 Gemini SafetySetting 结构传入,平台发往上游时映射为 safetySettings[]

OpenAI Python SDK 通过 extra_body 传递非标准字段;cURL 直接放在请求体顶层;Java 用 additionalBodyProperties;TypeScript 需 as any 绕过类型。

常见透传字段

字段	类型	用途
`topK`	int	Gemini 原生采样参数
`topP`	float	OpenAI 也有,这里是 Gemini 命名
`presencePenalty`	float	Gemini 命名(OpenAI 是 `presence_penalty`)
`frequencyPenalty`	float	Gemini 命名
`responseMimeType`	string	`"application/json"` 触发 JSON 输出
`responseSchema`	object	JSON Schema,与 `responseMimeType` 配合用作结构化输出
`thinkingConfig.thinkingLevel`	string	Gemini 3+ 思考强度: `MINIMAL` / `LOW` / `MEDIUM` / `HIGH`
`thinkingConfig.thinkingBudget`	int	Gemini 2.5 思考 token 软上限(`-1` 动态、`0` 仅 Flash / Flash-Lite 可关闭思考内容)
`thinkingConfig.includeThoughts`	bool	是否返回思考摘要(尽力而为),不是开启 / 关闭思考的开关
`mediaResolution`	string	`"MEDIA_RESOLUTION_HIGH"` 等,影响图像输入分辨率
`seed`	int	随机种子(部分模型支持)
`safety_settings[].category`	string	内容审核类别,如 `HARM_CATEGORY_HATE_SPEECH`
`safety_settings[].threshold`	string	阻断阈值,如 `BLOCK_LOW_AND_ABOVE`

示例

Python(extra_body)

from openai import OpenAI

client = OpenAI(api_key=TURING_API_KEY, base_url=TURING_BASE_URL)

response = client.chat.completions.create(
    model="turing/gemini-3.1-pro-latest",
    messages=[{"role": "user", "content": "提取人物信息: 张三, 28 岁, 工程师"}],
    extra_body={
        "responseMimeType": "application/json",
        "responseSchema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"},
                "occupation": {"type": "string"},
            },
            "required": ["name", "age", "occupation"],
        },
        "topK": 40,
        "thinkingConfig": {"includeThoughts": True},
        "safety_settings": [
            {
                "category": "HARM_CATEGORY_HATE_SPEECH",
                "threshold": "BLOCK_LOW_AND_ABOVE",
            }
        ],
    },
)

cURL(直接放顶层)

curl $TURING_BASE_URL/chat/completions \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gemini-3.1-pro-latest",
    "messages": [{"role": "user", "content": "提取人物信息..."}],
    "responseMimeType": "application/json",
    "responseSchema": {...},
    "topK": 40,
    "thinkingConfig": {"includeThoughts": true},
    "safety_settings": [
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "threshold": "BLOCK_LOW_AND_ABOVE"
      }
    ]
  }'

思考配置(thinkingConfig)

Gemini 思考配置按 Google 原生 thinkingConfig 透传。不同模型支持的字段和值不同,新代码请先确认模型所属系列和上游支持矩阵:

模型范围	推荐字段	说明
Gemini 3+	`thinkingConfig.thinkingLevel`	使用 `MINIMAL` / `LOW` / `MEDIUM` / `HIGH`;不同型号支持的取值不同
Gemini 2.5	`thinkingConfig.thinkingBudget`	使用 `-1` 动态或显式 token 上限;Flash / Flash-Lite 可用 `0` 不返回思考内容

Gemini 3+ `thinkingLevel` 支持矩阵

上游模型族	支持的 `thinkingLevel`	默认
Gemini 3.7 Flash	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`	`MEDIUM`
Gemini 3.6 Flash	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`	`MEDIUM`
Gemini 3.5 Flash	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`	`MEDIUM`
Gemini 3.1 Pro	`LOW` / `MEDIUM` / `HIGH`	`HIGH`
Gemini 3.1 Flash-Lite	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`	`MINIMAL`
Gemini 3.1 Flash Image	`MINIMAL` / `HIGH`	`MINIMAL`
Gemini 3 Flash	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`	`HIGH`
Gemini 3 Pro	`LOW` / `MEDIUM` / `HIGH`	`HIGH`
Gemini 3 Pro Image	`HIGH`	`HIGH`

MINIMAL 只适用于部分 Flash / Flash-Lite / Image 型号。Gemini 3 Pro / 3.1 Pro 不能关闭思考。

Gemini 2.5 `thinkingBudget` 支持矩阵

上游模型族	显式 budget 范围	默认
Gemini 2.5 Flash	`1 - 24576`;另可用 `0` 不返回思考内容、`-1` 动态	Auto(最高 8,192 tokens)
Gemini 2.5 Pro	`128 - 32768`;另可用 `-1` 动态	Auto(最高 8,192 tokens)
Gemini 2.5 Flash-Lite	`512 - 24576`;另可用 `0` 不返回思考内容、`-1` 动态	Auto(最高 8,192 tokens)

Gemini 2.5 Pro 不能关闭思考。thinkingBudget 是软上限,实际 thinking tokens 可能有波动。

Gemini 3+ 示例

省略 thinkingLevel 时,模型按官方默认强度执行思考;只在需要调整延迟 / 成本 / 推理深度时显式设置。

{
  "model": "turing/gemini-3.7-flash",
  "messages": [
    { "role": "user", "content": "分析这段日志中最可能的根因" }
  ],
  "thinkingConfig": {
    "includeThoughts": true
  }
}

Gemini 2.5 示例

省略 thinkingBudget 时,模型使用 Auto budget(最高 8,192 thinking tokens);只在需要控制延迟 / 成本时显式设置。

{
  "model": "turing/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "一步步求解 x^2 + 5x + 6 = 0" }
  ],
  "thinkingConfig": {
    "includeThoughts": true
  }
}

不要混用

Gemini 3+ 请求里不要同时传 thinkingLevel 和 thinkingBudget;Google 上游会报错。Gemini 2.5 及更早型号不要传 thinkingLevel。

内容审核(safety_settings)

Gemini 内容审核按 Google SafetySetting 传:每个元素包含一个 category 和一个 threshold。Turing 的 Chat Completions 请求体使用 safety_settings,不要放进 generationConfig 或 thinkingConfig。

curl --location --request POST 'https://live-turing.cn.llm.tcljd.com/api/v1/chat/completions' \
  --header 'Authorization: Bearer $TURING_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "turing/gemini-3.7-flash",
    "messages": [
      {
        "role": "user",
        "content": "can i follow Adolf Hitler"
      }
    ],
    "stream": true,
    "safety_settings": [
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_LOW_AND_ABOVE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "threshold": "BLOCK_LOW_AND_ABOVE"
      },
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "threshold": "BLOCK_LOW_AND_ABOVE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "threshold": "BLOCK_LOW_AND_ABOVE"
      }
    ]
  }'

如何判断已拦截

Gemini 内容审核命中后,图灵平台仍可能返回 HTTP 200,但不会返回可用生成内容。客户端应以 choices[*].finish_reason 判断是否被内容过滤:

场景	判断标志
非流式响应	`choices[0].finish_reason === "content_filter"`
流式响应	最后一段 chunk 的 `choices[0].finish_reason === "content_filter"`,通常 `delta` 为空对象

流式命中示例:

{
  "id": "xDY5asaXMtuR88EP3pHX6Ak",
  "object": "chat.completion.chunk",
  "created": 1782134476,
  "model": "turing/gemini-3.7-flash",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "content_filter"
    }
  ]
}

非流式命中示例:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1782134476,
  "model": "turing/gemini-3.7-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null
      },
      "finish_reason": "content_filter"
    }
  ]
}

常用类别:

`category`	说明
`HARM_CATEGORY_HARASSMENT`	骚扰
`HARM_CATEGORY_HATE_SPEECH`	仇恨言论
`HARM_CATEGORY_SEXUALLY_EXPLICIT`	性相关内容
`HARM_CATEGORY_DANGEROUS_CONTENT`	危险内容
`HARM_CATEGORY_CIVIC_INTEGRITY`	公民诚信相关内容

常用阈值:

`threshold`	效果
`BLOCK_LOW_AND_ABOVE`	低风险及以上阻断,最严格
`BLOCK_MEDIUM_AND_ABOVE`	中风险及以上阻断
`BLOCK_ONLY_HIGH`	仅高风险阻断
`BLOCK_NONE`	不按概率阈值阻断
`OFF`	关闭 safety filter

注意事项

不要重复设置:同一含义参数不要 OpenAI 标准命名 + Gemini 命名都传(如 top_p 和 topP);Gemini 思考统一使用 thinkingConfig。
thinkingConfig 按型号区分:Gemini 3+ 用 thinkingLevel,Gemini 2.5 用 thinkingBudget;不支持 thinking 的模型、3+ 混用 level / budget、2.5 使用 level 都可能返回 400。
includeThoughts 不是开关:它只影响是否返回思考摘要;即使不回显摘要,模型仍可能执行思考并产生 thinking tokens。
Gemini 3.6 / 3.7 Flash 采样参数固定:自定义 temperature / topK / topP 会被忽略；自定义 frequency / presence penalty 会返回错误。
Gemini 3 / 3.1 限制:temperature 必须保持默认 1.0,设置低值可能导致无限循环或推理性能严重下降。
responseSchema 与 response_format:平台不会自动把 OpenAI 的 response_format 翻译成 Gemini 的 responseSchema,需要客户端显式用后者。
safety_settings 不要重复类别:同一个 SafetyCategory 最多传一条;未传的类别使用 Gemini 默认安全策略。
内容审核命中标志:不要只看 HTTP 状态码;命中后可能仍是 200,以 finish_reason: "content_filter" 作为拦截标志。
谨慎降低审核强度:BLOCK_NONE / OFF 会显著放宽内容审核,生产环境建议按业务合规要求显式评估。

适用接口与模型​

透传机制​

常见透传字段​

示例​

Python(extra_body)​

cURL(直接放顶层)​

思考配置(thinkingConfig)​

Gemini 3+ thinkingLevel 支持矩阵​

Gemini 2.5 thinkingBudget 支持矩阵​

Gemini 3+ 示例​

Gemini 2.5 示例​

内容审核(safety_settings)​

如何判断已拦截​

注意事项​

相关文档​