Gemini Structured Outputs 与 Function Calling：什么时候该用哪一个

本文是 Google Gemini 官方文档的中文实践笔记，示例做了简化，具体模型支持范围请以原文为准。

Structured Outputs 和 Function Calling 都会用到 JSON Schema，因此很容易被混为一谈。最简单的判断标准是：

• 只想规定最终答案的形状：使用 Structured Outputs。
• 希望模型请求你的程序执行动作：使用 Function Calling。

Structured Outputs 的典型场景

例如从用户反馈中提取情感与摘要，前端或数据库需要稳定字段：

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positive", "neutral", "negative"]
    },
    "summary": { "type": "string" }
  },
  "required": ["sentiment", "summary"]
}

结构化输出能保证 JSON 语法和受支持 schema 的形状，但不保证语义一定正确。例如日期可能格式合法却不符合业务时间范围，所以应用层仍必须验证。

Function Calling 的典型场景

当用户说“查询订单 123”，模型返回函数名与参数；真正访问数据库、鉴权和执行操作的仍然是你的代码。标准循环是：

1. 向模型提供工具声明。
2. 模型决定是否调用，并返回结构化参数。
3. 应用验证参数、权限和幂等性后执行。
4. 将工具结果返回模型，由模型形成最终答复。

工程边界

• Schema 使用明确类型、枚举和清晰 description，避免深层嵌套。
• 不把 schema 合法等同于业务合法。
• 写操作必须二次鉴权；金额、收件人等高风险字段要独立确认。
• 工具失败应返回结构化错误，让模型决定重试、换工具或解释失败。
• 为工具调用设置次数上限，防止循环和不可控费用。

如果一个流程既要调用工具又要输出固定 JSON，可先完成工具循环，再对最终响应应用结构化输出；是否能在单次调用中组合，要检查所用模型与 API 的当前支持状态。

原文：Google AI — Structured outputs