Gemini JSON Mode API - Gemini Pro 生成经过验证的 JSON。基于 Schema 的结构化输出，可靠数据提取和类型安全的 AI 响应。

结构化输出 (JSON Mode)

通过定义 JSON Schema，从 Gemini 模型生成结构化数据输出。这对于数据提取、构建 API 或任何需要一致输出格式的场景非常有用。

支持的模型: 所有 Gemini 1.5+ 模型都支持结构化输出。

工作原理

将 responseMimeType 设置为 application/json，并提供 responseSchema 来定义预期的输出结构。

基础示例

curl -X POST "https://api.uniterouter.ai/v1beta/models/gemini-2.0-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $UNITEROUTER_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "列出3种流行的编程语言及其用途"}]
      }
    ],
    "generationConfig": {
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "useCase": {"type": "string"},
            "difficulty": {"type": "string", "enum": ["easy", "medium", "hard"]}
          },
          "required": ["name", "useCase", "difficulty"]
        }
      }
    }
  }'

import google.generativeai as genai

genai.configure(
    api_key="your_uniterouter_api_key",
    transport="rest",
    client_options={"api_endpoint": "api.uniterouter.ai"}
)

model = genai.GenerativeModel("gemini-2.0-flash")

response = model.generate_content(
    "列出3种流行的编程语言及其用途",
    generation_config=genai.GenerationConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "useCase": {"type": "string"},
                    "difficulty": {"type": "string", "enum": ["easy", "medium", "hard"]}
                },
                "required": ["name", "useCase", "difficulty"]
            }
        }
    )
)

import json
data = json.loads(response.text)
print(data)

import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("your_uniterouter_api_key", {
  baseUrl: "https://api.uniterouter.ai"
});

const model = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: {
      type: SchemaType.ARRAY,
      items: {
        type: SchemaType.OBJECT,
        properties: {
          name: { type: SchemaType.STRING },
          useCase: { type: SchemaType.STRING },
          difficulty: { type: SchemaType.STRING, enum: ["easy", "medium", "hard"] }
        },
        required: ["name", "useCase", "difficulty"]
      }
    }
  }
});

const result = await model.generateContent("列出3种流行的编程语言及其用途");
const data = JSON.parse(result.response.text());
console.log(data);

响应示例

[
  {
    "name": "Python",
    "useCase": "数据科学、机器学习、Web 开发",
    "difficulty": "easy"
  },
  {
    "name": "JavaScript",
    "useCase": "Web 开发、前端和后端",
    "difficulty": "medium"
  },
  {
    "name": "Rust",
    "useCase": "系统编程、高性能应用",
    "difficulty": "hard"
  }
]

GenerationConfig 参数

参数	类型	描述
`responseMimeType`	string	结构化输出必须设为 `application/json`
`responseSchema`	object	OpenAPI 兼容的 JSON Schema
`responseJsonSchema`	object	替代方案：完整 JSON Schema 支持

支持的 Schema 属性

属性	描述
`type`	`object`, `array`, `string`, `number`, `integer`, `boolean`
`properties`	对象属性定义
`items`	数组项 schema
`required`	必需属性名称
`enum`	字符串/数字的允许值
`minimum` / `maximum`	数字约束
`minItems` / `maxItems`	数组长度约束
`description`	字段描述（帮助模型理解）

枚举模式

对于简单分类任务，使用 text/x.enum：

response = model.generate_content(
    "分析这句话的情感: '我非常喜欢这个产品！'",
    generation_config=genai.GenerationConfig(
        response_mime_type="text/x.enum",
        response_schema={
            "type": "string",
            "enum": ["positive", "negative", "neutral"]
        }
    )
)
print(response.text)  # "positive"

最佳实践

使用描述 - 为 schema 属性添加 description 以引导模型
保持简单 - 复杂的嵌套 schema 可能降低准确性
验证输出 - 始终验证 JSON 输出是否匹配 schema
使用枚举 - 对于分类数据，使用 enum 约束输出

结构化输出