Skip to main content

​
Gemini 结构化输出示例

以下示例展示如何使用Gemini API的结构化输出功能，通过 response_schema 参数确保输出符合指定的JSON Schema格式。

​
快速开始

只需要替换 <API-KEY> 为你的实际API密钥即可运行。 
curl -X POST "https://model-api.skyengine.com.cn/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "分析苹果公司的基本信息，包括公司名称、成立年份、创始人、主要业务等"
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 3000,
      "temperature": 0.1,
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "object",
        "properties": {
          "company_name": {
            "type": "string",
            "description": "公司名称"
          },
          "founded_year": {
            "type": "integer",
            "description": "成立年份"
          },
          "founders": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "创始人列表"
          },
          "main_business": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "主要业务领域"
          },
          "headquarters": {
            "type": "string",
            "description": "总部位置"
          }
        },
        "required": ["company_name", "founded_year", "founders", "main_business", "headquarters"]
      }
    }
  }'

​
Gemini结构化输出的特点

​
1. 原生支持JSON Schema

Gemini通过 responseSchema 参数原生支持JSON Schema验证：
  • 严格遵循: 输出严格遵循指定的schema结构
  • 类型验证: 自动验证数据类型和格式
  • 必填字段: 确保required字段不会缺失

​
2. 配置参数

{
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": { ... },
      "required": [ ... ]
    },
    "temperature": 0.1
  }
}

​
3. Schema支持的特性

  • 基本类型: string, number, integer, boolean, array, object
  • 约束条件: minimum, maximum, enum, items等
  • 嵌套结构: 支持复杂的嵌套对象和数组
  • 必填验证: required字段自动验证

​
结果示例

200
{
  "sdkHttpResponse": {
    "headers": {
      "Alt-Svc": [
        "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"
      ],
      "Content-Type": [
        "application/json; charset=UTF-8"
      ],
      "Date": [
        "Sun, 26 Oct 2025 12:39:00 GMT"
      ],
      "Server": [
        "scaffolding on HTTPServer2"
      ],
      "Vary": [
        "Origin",
        "X-Origin",
        "Referer"
      ],
      "X-Content-Type-Options": [
        "nosniff"
      ],
      "X-Frame-Options": [
        "SAMEORIGIN"
      ],
      "X-Xss-Protection": [
        "0"
      ]
    }
  },
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "{\"company_name\":\"Apple Inc.\",\"founded_year\":1976,\"founders\":[\"Steve Jobs\",\"Steve Wozniak\",\"Ronald Wayne\"],\"main_business\":[\"Consumer Electronics\",\"Software\",\"Online Services\"],\"headquarters\":\"Cupertino, California, United States\"}"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.12912105662482126
    }
  ],
  "createTime": "2025-10-26T12:38:59.637958Z",
  "modelVersion": "gemini-2.5-flash",
  "responseId": "fe4a5ffaf1524b37876a84f8686830ad",
  "usageMetadata": {
    "candidatesTokenCount": 56,
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 56
      }
    ],
    "promptTokenCount": 61,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 61
      }
    ],
    "thoughtsTokenCount": 108,
    "totalTokenCount": 225,
    "trafficType": "ON_DEMAND"
  }
}

​
高级Schema示例

​
1. 复杂嵌套结构

{
  "type": "object",
  "properties": {
    "user_profile": {
      "type": "object",
      "properties": {
        "personal_info": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "integer", "minimum": 0, "maximum": 120 },
            "location": {
              "type": "object",
              "properties": {
                "country": { "type": "string" },
                "city": { "type": "string" }
              }
            }
          }
        },
        "preferences": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "category": { "type": "string" },
              "rating": { "type": "number", "minimum": 1, "maximum": 5 }
            }
          }
        }
      }
    }
  }
}

​
2. 枚举值约束

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positive", "negative", "neutral"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["technology", "business", "science", "entertainment"]
      }
    }
  }
}

​
应用场景

​
数据提取和整理

  • 文档解析: 从非结构化文档中提取结构化信息
  • 表单填充: 自动填充复杂的结构化表单
  • 数据标准化: 将不同格式的数据统一为标准结构

​
分析和评估

  • 情感分析: 提供量化的情感分析结果
  • 产品评价: 结构化分析用户反馈和评价
  • 市场调研: 从调研数据中提取结构化洞察

​
业务应用

  • CRM系统: 从客户沟通中提取关键信息
  • 报告生成: 自动生成结构化的业务报告
  • 质量控制: 确保AI输出符合业务规范

​
最佳实践

​
1. Schema设计原则

  • 简洁明确: 避免过于复杂的嵌套结构
  • 类型明确: 为每个字段指定准确的类型
  • 约束合理: 设置合理的取值范围和枚举值
  • 描述清晰: 为每个字段提供清晰的描述

​
2. 性能优化

  • 低温度: 使用较低的temperature (0.1-0.3) 确保结构稳定
  • 合理长度: 避免过长的输出，合理设置maxOutputTokens
  • 字段验证: 在客户端验证返回的JSON结构

​
3. 错误处理

  • JSON解析: 妥善处理JSON解析异常
  • Schema验证: 验证返回数据是否符合预期schema
  • 降级处理: 提供schema验证失败时的降级策略

​
注意事项

  1. Schema复杂度: 过于复杂的schema可能影响生成质量
  2. 必填字段: required字段过多可能导致生成困难
  3. 数据类型: 确保schema中的类型定义准确
  4. 约束条件: 约束条件要合理，避免无法满足的限制
  5. 温度设置: 建议使用低温度以确保结构化输出的稳定性
  6. Token限制: 复杂结构可能需要更多token，注意设置合理的限制