Python调用Gemini Structured Outputs实现工单路由门禁
内容提要
本文介绍用 Python 调用 Gemini 结构化输出实现工单路由：通过 JSON Schema 限定 queue 和 priority 的枚举值，模型输出后由 safe_route 独立校验，越界即转人工复核。代码包含超时与异常降级，并强调 Schema 只约束格式、不保证事实正确，适合自动分流而非直接批准退款，需记录版本并抽样统计错分率。
延伸解读
Schema 与 safe_route 的双层防线
文章把可靠性拆成两层：SCHEMA 在模型侧缩小输出空间，safe_route 在服务端独立校验 queue 与 priority 是否越界。这种设计的意义在于，即使 API 承诺返回 JSON，也不能省略本地验证，因为 Schema 只约束格式，不保证事实正确。对读者而言，关键启示是任何自动分流链路都应在模型输出之后保留一道确定性检查，越界即转人工，而不是直接信任模型结果。
超时与降级：避免慢请求拖垮工作线程
代码中 timeout=20 的目的是不让一个慢请求占住 Web 工作线程，异常时统一返回 human_review。文章同时提醒生产环境还应设置 HTTP 客户端级超时、重试次数和熔断。这里值得注意的风险是超时后盲目重试，可能造成同一工单被重复创建。因此降级策略不只是兜底，更要与幂等或去重机制配合，否则自动化的收益会被重复处理抵消。
适用边界：自动分流而非自动批准
文章明确把该方案定位为“先分给谁处理”的自动化，不适合直接批准退款或关闭投诉。原因是模型可能给出看似合理的理由，但无法核验订单真伪等业务事实。读者应把模型输出视为路由建议，而非最终决策。对于分类错误代价高的字段，应保留人工复核环节，避免把格式合规误当成业务正确。
工程化记录与错分率抽样
文章建议记录原始文本、模型版本、schema 版本、路由结果和人工改判，并每周抽样计算错分率。这一做法的价值在于，当枚举或模型版本变更时，能追溯错分来源，而不是只看到最终结果。常见坑包括枚举改了却没同步服务端白名单，以及把模型理由直接展示给用户而泄露内部规则。记录与抽样是持续发现这些问题的前提。
Q&A
Gemini Structured Outputs 在工单路由中具体起什么作用？
它通过 JSON Schema 限定模型输出的字段和枚举值，让 queue 和 priority 等字段格式稳定，但只约束格式，不保证事实正确，业务规则仍需服务端校验。
为什么模型返回了合法 JSON 还需要 safe_route 再校验一次？
因为 Schema 只保证输出格式，不保证内容符合业务白名单。safe_route 独立检查 queue 和 priority 是否在允许集合内，越界就转人工复核，避免错误自动流转。
调用 Gemini 做工单分类时，代码里怎么处理超时和异常？
在 client.interactions.create 中设置 timeout=20，并用 try/except 捕获异常，一旦超时或调用失败就返回 human_review 并附带失败原因，防止慢请求占住线程。
用 Structured Outputs 做工单路由，常见的坑有哪些？
常见坑包括：Schema 不核验订单真伪；枚举改了没同步服务端白名单；超时后盲目重试导致重复创建工单；把模型理由直接展示给用户而泄露内部规则。
这种自动分流方案适合用在哪些场景，不适合用在哪些场景？
适合把“先分给谁处理”自动化，比如退款、账号、普通咨询的分流；不适合直接批准退款或关闭投诉，这些仍需人工介入。
工程化落地时，需要记录哪些信息来监控路由质量？
需要记录原始文本、模型版本、schema 版本、路由结果和人工改判，并每周抽样计算错分率，以便持续评估和调整。
