Gemini 3 结构化输出与工具调用怎么一起验收：schema、工具结果和失败分支

做订单客服场景的AI落地时，经常会碰到一个两头难的问题：模型既要调用后台订单查询接口拿实时数据，又要直接输出符合前端渲染规范的结构化JSON。如果只给模型约束最终输出的JSON规则，很容易在中间的工具调用环节出问题，比如传错参数、越权查别的用户订单；反过来只做工具调用校验，又可能最后一步生成缺字段、类型错的响应，直接打崩前端渲染逻辑。跑下来最稳妥的验收逻辑是拆成两段独立协议，先把工具调用的全流程验透，再验收最终的结构化输出环节。

先把两个协议阶段拆开

在 Gemini 3 的工具链里，模型可以先返回一个函数调用步骤，应用拿着函数名和参数去执行自己的业务逻辑，再把工具结果交回模型。结构化输出约束的是最后给用户的结果，例如订单卡片需要固定的 status、message 和 next_action 字段。

这两个约束的责任边界不同。模型提出的 order_id 仍然要经过服务端权限和格式检查，工具返回的订单状态也不能因为模型要求某个字段就被“补写”。最终 JSON 通过 schema，只能说明形状合格，不能证明订单真的存在。

先验收工具调用，再交回可信结果

把订单查询工具声明成窄接口，参数只保留业务确实需要的字段：

{
  "type": "function",
  "name": "lookup_order",
  "description": "查询当前登录用户的一笔订单状态",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "订单号" }
    },
    "required": ["order_id"]
  }
}

收到模型的调用步骤后，服务端至少做四次核对：工具名是否在白名单中，参数是否是对象，订单号是否符合本系统格式，当前用户是否拥有这笔订单。任何一项不通过，都不要把原始参数直接交给数据库层。

type LookupArgs struct {
    OrderID string `json:"order_id"`
}

func checkLookup(a LookupArgs, userID string) error {
    if !orderIDPattern.MatchString(a.OrderID) {
        return errors.New("invalid order id")
    }
    if !canReadOrder(userID, a.OrderID) {
        return errors.New("order is not visible to this user")
    }
    return nil
}

工具结果也要带上明确的状态，不要把“查不到”“权限拒绝”和“依赖超时”都编码成空对象。模型可以据此生成不同的用户提示，监控系统也能区分业务缺失和系统故障。

最终 schema 只描述可渲染的回答

工具结果回传后，最终响应可以使用结构化输出约束成前端需要的形状：

{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["found", "not_found", "unavailable"] },
    "message": { "type": "string" },
    "next_action": { "type": "string" }
  },
  "required": ["status", "message", "next_action"],
  "additionalProperties": false
}

这里的枚举值是产品协议，不是模型建议。应用收到结果后仍要再次检查：status=found 时是否确实有订单查询成功证据，status=unavailable 时是否记录了依赖错误，next_action 是否属于前端允许的动作集合。不要把 schema 校验当成业务授权。

五条测试路径能抓住大多数联调问题

测试日志建议同时保存请求关联 ID、工具调用 ID、工具结果状态和最终校验结果。不要把订单号、访问令牌或完整用户隐私写入普通调试日志；验收需要的字段可以做脱敏摘要。

失败时怎么回退，别让模型替服务端做决定

工具返回超时，应用可以给模型一个结构化的 unavailable 工具结果，让模型生成可读提示；如果模型二次生成仍超时，就由应用直接返回固定回退文案。工具参数校验失败时，更适合在模型调用前结束本轮请求，因为这时继续对话只会重复发送同一个坏参数。

最终 schema 校验失败时不要自动把原文当 JSON 解析后“修补”字段。记录失败原因，保留安全的用户提示，并把样本加入回归集。这样能区分模型输出变化、schema 变更和工具协议变更，而不是用一次字符串替换掩盖问题。

上线前的最小验收清单

• 工具声明中的名称、参数和必填项与服务端白名单一致。
• 服务端在工具执行前完成格式、权限和资源范围检查。
• 工具成功、空结果、权限拒绝、依赖超时都有明确状态。
• 最终结构化输出通过 schema 后，仍执行业务字段交叉检查。
• 拒答、解析失败和超时都有不依赖模型的安全回退。
• 日志可以按关联 ID 串起一轮调用，同时避免记录敏感原文。

相关问题

结构化输出通过后还需要 JSON 解析吗？

需要。生产代码仍应检查响应是否存在、是否能解析，以及关键业务字段是否与工具结果一致。schema 是第一道形状检查，不是业务事实证明。

工具调用失败时能不能让模型猜一个结果？

不应该。订单、库存、余额这类事实数据必须来自可信服务；模型最多解释失败原因，不能补造状态。

为什么测试里要单独覆盖多余字段？

多余字段可能让前端误把模型临时生成的内容当成产品协议。把额外字段拒绝或显式丢弃，能让接口变更更容易发现。

总结

Gemini 3 的工具调用与结构化输出应该分段验收：工具阶段守住白名单、参数和权限，结果阶段守住状态语义，最终阶段再守住 JSON 形状和业务一致性。把五条失败路径放进回归测试，模型或 SDK 升级时才有可比较的证据。