Gemini 结构化 JSON 输出实战:可解析结果落地业务
首页 / 文章 / 技术教程 / Gemini 结构化 JSON 输出实战:可解析结果落地业务
Gemini 结构化 JSON:电商/发票/工单场景、Pydantic 校验重试与站内互链。智枢ZhiShu OpenAI 兼容接口实战。
作者:智枢 ZhiShu · 发布:2026-10-19 · 更新:2026-11-14
一、为什么业务要「结构化输出」? 电商商品参数提取、财务发票字段解析、客服工单自动分类——这些场景里,聊天框散文没用,业务系统必须吃 可解析的 JSON 。若模型写成「好的,结果如下:…」再夹 Markdown,前端 JSON.parse 就会炸。 本文将基于面向开发者的 OpenAI 兼容 AI API 网关—— 智枢ZhiShu / Itzyk API(api.itzyk.top) ,演示如何通过 https://api.itzyk.top/v1 的 /v1/chat/completions ,用 system 约束 + 少样本 + Pydantic/校验重试 (以及可选的 response format )把 Gemini 输出钉死为业务对象。默认模型: gemini-3.6-flash 。 适用业务场景(先对号入座) | 场景 | 典型字段 | 失败代价 | |------|----------|----------| | 电商商品参数提取 | 品牌、规格、材质、价格区间 | 脏数据进检索/比价 | | 财务发票结构化 | 销方、税号、金额、税率、开票日 | 对账与进项抵扣出错 | | 客服工单自动分类 | sentiment、category、priority、need human | 错分流、漏人工 | 事实锚点:结构化 JSON 走 /v1/chat/completions ;Base URL https://api.itzyk.top/v1 ;可用提示约束或 response format 。 若只想先跑通对话,见 五分钟上手 https://api.itzyk.top/articles/how-to-use-gemini 。若要调外部 API,见 Function Calling 实战 https://api.itzyk.top/articles/gemini-function-calling-tools-guide 。超长 PDF 先切片再抽 JSON,见 长上下文应用 https://api.itzyk.top/articles/gemini-long-context-document-guide 。 --- 二、三种落地档位(从稳到炫) | 档位 | 做法 | 适用 | |------|------|------| | A. 提示词约束 | system 规定「只输出 JSON,无 Markdown」+ 字段表 | 大多数业务,立刻可用 | | B. 校验重试 | 解析失败则把错误回灌再调一次 | 生产必做 | | C. response format | 若 SDK/上游支持 json object | 能开则开,仍建议本地校验 | 无论哪一档, 业务代码都要以本地 schema 校验为准 ,不要盲目信任模型。Itzyk计费按实际 Token;重试会多花一次调用,但比脏数据进库便宜。 准备 控制台:Itzyk控制台 。模型与价格:服务页、价格页。 --- 三、先写死 Schema,再写 Prompt 以「用户反馈分类」为例 规则 - 字段少、类型死;枚举写死,避免自由标签爆炸。 - summary 限长度(如 ≤40 字),避免超长文本拖费用。 - 布尔、数字不要用中文「是/否」。 System 示例 --- 四、Python:生成 → 解析 → 校验 → 最多重试一次 " : text = re.sub r"^ ", "", text return json.loads text def validate obj: dict - dict: if obj.get "sentiment" not in ALLOWED SENT: raise ValueError "bad sentiment" if obj.get "category" not in ALLOWED CAT: raise ValueError "bad category" p = int obj "priority" if not 1 80: raise ValueError "bad summary" return { "sentiment": obj "sentiment" , "category": obj "category" , "priority": p, "summary": summary :40 , "need human": bool obj.get "need human" , } def classify feedback: str - dict: messages = {"role": "system", "content": SCHEMA HINT}, {"role": "user", "content": feedback}, last err = None for attempt in range 2 : kwargs = dict model=MODEL, messages=messages, temperature=0.2 若当前环境支持,可取消下一行注释增强约束 kwargs "response format" = {"type": "json object"} resp = client.chat.completions.create kwargs raw = resp.choices 0 .message.content or "" try: return validate extract json raw except Exception as e: last err = e messages.append {"role": "assistant", "content": raw} messages.append { "role": "user", "content": f"输出不合规:{e}。请只输出修正后的 JSON。", } raise RuntimeError f"classify failed: {last err}" print classify "充值扣了两次钱,发票也没开,很着急" json 围栏再 parse。 - 校验失败时把错误原因喂回去,通常第二次就能修。 - 两次仍失败:记日志、入人工队列,不要静默丢弃。 4.1 用 Pydantic 做生产级校验(推荐) 手工 if 容易漏字段;用 Pydantic 把 schema 写成类型,失败信息可直接回灌模型: " : text = re.sub r"^ ", "", text return json.loads text def classify pydantic feedback: str - FeedbackTicket: messages = {"role": "system", "content": SCHEMA HINT}, {"role": "user", "content": feedback}, last err = None for in range 2 : raw = client.chat.completions.create model=MODEL, messages=messages, temperature=0.2 .choices 0 .message.content or "" try: return FeedbackTicket.model validate extract json raw except json.JSONDecodeError, ValidationError as e: last err = e messages += {"role": "assistant", "content": raw}, {"role": "user", "content": f"输出不合规:{e}。请只输出修正后的 JSON。"}, raise RuntimeError f"classify failed: {last err}" print classify pydantic "充值扣了两次钱,发票也没开,很着急" .model dump js import OpenAI from "openai"; const client = new OpenAI { apiKey: process.env.ZHISHU API KEY, baseURL: process.env.ZHISHU BASE || "https://api.itzyk.top/v1", } ; function extractJson text { let t = text || "" .trim ; if t.startsWith " ?:json ?\s /i, "" .replace /\s 把 classify 挂到 Express 路由后,前端只消费对象字段,不再解析自然语言。 --- 六、和 Function Calling 怎么选? | 需求 | 更合适 | |------|--------| | 要从文本抽字段、打标签、打分 | 结构化 JSON | | 要查库、调 HTTP、改状态 | Function Calling | | 两者都有 | 先工具拿事实,再结构化汇总;或工具返回已是 JSON,模型只写用户可读摘要 | 不要把「查订单」做成纯 JSON 提示词——模型会编造单号状态。事实来源必须走工具或你们自己的 API。 --- 七、流式输出怎么拿 JSON? 流式适合聊天 UI;对结构化任务, 优先非流式 ,等完整 co
本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。