Python调用Gemini Structured Outputs实现工单路由门禁

客服工单最怕的不是模型"答错一句话",而是它给出一段看起来合理的说明,程序却从中猜错优先级。通俗做法是:要求模型只交 JSON(JavaScript Object Notation,轻量数据格式),再让代码验证它。Gemini API 的 Structured Outputs 能按 JSON Schema 生成结果;本篇用 Python 把退款、账号和普通咨询分流,并在模型输出越界时拒绝自动流转。你会得到一条能复制、能超时、能降级的最小链路。

为什么不直接解析一段自然语言

结构化输出的作用是规定"输出长什么样",不是保证事实正确。Schema 让字段和枚举更稳定;业务规则仍要由服务端负责。本文把 priority 限在 low、normal、high,把 queue 限在三个队列。模型若返回未知值,程序转到人工队列。当前官方文档把它用于抽取、分类和 Agent 工作流,并通过 response_format 的 application/json 与 schema 配置。

flowchart LR A[工单文本] --> B[Gemini JSON Schema] B --> C[解析JSON] C --> D{枚举与业务规则} D -->|通过| E[进入对应队列] D -->|失败/超时| F[人工复核队列]

环境准备

使用 Python 3.10+。安装依赖:python -m pip install google-genai。把密钥放入环境变量:export GEMINI_API_KEY='你的密钥'。模型名示例为文档中的 gemini-3.8-flash;你的账号可用模型与配额仍需在控制台确认。保存为 ticket_router.py,运行 python ticket_router.py。示例未在本次任务中实际调用线上 API;本地仅完成语法检查,目标环境安装依赖后应再作一次无敏感数据的联调。

python 复制代码
import json
import os
from google import genai

ALLOWED_QUEUES = {"refund", "account", "general"}
ALLOWED_PRIORITY = {"low", "normal", "high"}
SCHEMA = {"type": "object", "properties": {
    "queue": {"type": "string", "enum": sorted(ALLOWED_QUEUES)},
    "priority": {"type": "string", "enum": sorted(ALLOWED_PRIORITY)},
    "reason": {"type": "string"}},
    "required": ["queue", "priority", "reason"]}

def safe_route(raw: str) -> dict:
    try:
        data = json.loads(raw)
    except json.JSONDecodeError:
        return {"queue": "human_review", "reason": "JSON无法解析"}
    if data.get("queue") not in ALLOWED_QUEUES:
        return {"queue": "human_review", "reason": "未知队列"}
    if data.get("priority") not in ALLOWED_PRIORITY:
        return {"queue": "human_review", "reason": "未知优先级"}
    return data

def classify(ticket: str) -> dict:
    if not os.getenv("GEMINI_API_KEY"):
        return {"queue": "human_review", "reason": "缺少GEMINI_API_KEY"}
    client = genai.Client()
    try:
        result = client.interactions.create(
            model="gemini-3.8-flash", input=ticket,
            response_format={"type": "text", "mime_type": "application/json",
                             "schema": SCHEMA}, timeout=20)
        return safe_route(result.output_text)
    except Exception as exc:
        return {"queue": "human_review", "reason": f"调用失败: {type(exc).__name__}"}

if __name__ == "__main__":
    print(classify("订单重复扣款,请尽快退款"))
    assert safe_route('{"queue":"refund","priority":"high","reason":"重复扣款"}')["queue"] == "refund"

代码分两层:SCHEMA 提前缩小模型输出空间;safe_route 再做独立验证,不能因为 API 承诺 JSON 就省略它。timeout=20 是为了不让一个慢请求占住 Web 工作线程;生产环境还应设置 HTTP 客户端级超时、重试次数和熔断。genai.Client() 从环境读取密钥,不要把密钥写进仓库。

预期输出(有密钥且调用成功时)类似 {'queue': 'refund', 'priority': 'high', 'reason': '...'};没配密钥则是人工复核。最常见的坑有:一,Schema 只约束格式,不会自动核验订单真伪;二,枚举改了却没同步服务端白名单;三,超时后盲目重试,造成同一工单被重复创建;四,把模型理由直接展示给用户而泄露内部规则。

适合把"先分给谁处理"自动化,不适合直接批准退款或关闭投诉。工程化时,把原始文本、模型版本、schema 版本、路由结果和人工改判一起记录;每周抽样计算错分率。5分钟实践:新增 security 队列,并写一个断言确保模型返回 delete_database 时永远进入 human_review。

你的工单里,哪一个字段一旦分类错就不该自动流转?

关注「蜗牛聊AI」,一起看懂技术变化背后的真正机会。


本文首发于 java4u.cn,转载请注明出处。

相关推荐
7177777 小时前
国内 AI 研发效能工具怎么选:2026 年基于公开信息的选型框架与 Gitee 实践
人工智能·gitee
Csvn7 小时前
换供应商要改一遍代码?把模型接入收进一层网关(C04)
人工智能·aigc·agent
孟健8 小时前
开源AutoClip切直播:1小时48分出19段,整月API只花0.08元
人工智能·开源·aigc
翰墨之道8 小时前
AI日报:豆包工作ARR超20亿,GPT-6.2跑分与实测割裂
人工智能·gpt·数据挖掘
Maynor9968 小时前
Trymodel 使用介绍:一个平台同时用 Claude、GPT、Gemini 和 Grok
人工智能·gpt·ai·程序员·教程·claude·语音
字节跳动视频云技术团队9 小时前
接大模型别再自己配 Key、搭代理了,火山引擎 IGA Pages 一步搞定
人工智能
阿里云大数据AI技术9 小时前
EMR Serverless StarRocks 产品介绍:从统一 OLAP 走向多模态分析与检索
人工智能
Forget the Dream10 小时前
Spring AI 2.0 系列(二):第一个 ChatClient——从注入到一次完整调用
java·人工智能·spring boot·ai·springai
郝学胜-神的一滴11 小时前
Effective Python 条款35:用类封装替代生成器异常注入
开发语言·人工智能·python·金融·pandas·scikit-learn·matplotlib
火山引擎开发者社区11 小时前
豆包工作,3 个月,800 万,20 亿
人工智能