Gemini API JSON文本摘要实战指南：一次调用把长文变成结构化数据
【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook
处理小说、报告、产品描述这类长材料时，你多半要人肉通读再整理要点。cookbook 项目里的 json_capabilities 示例集，给出了用 Gemini API 做 JSON 文本摘要的现成做法：长文进去，结构化 JSON 数据出来。
🧭 先搞清楚它解决了什么问题
这个功能解决的是"长文进程序"的问题。手动从一篇十章的奇幻故事里摘出人物、地名和情节主线很耗时间；模型直接生成的摘要又是自然语言，没法做条件查询和统计。Gemini API 的 JSON 输出让你先声明要什么数据结构，模型再按结构填内容。拿到手的是一个标准字典：synopsis、genres、locations、characters 各占各的字段，可以直接写进数据库，也能喂给流水线的下一环节。
⚙️ 环境与密钥准备
先装官方 SDK：
pip install -U "google-genai>=1.0.0"命令跑完无报错即依赖就绪。然后用环境变量初始化客户端，密钥的获取方式和 Colab 里的 Secret 配置细节，见 quickstarts/Authentication.ipynb。
import os from google import genai client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])这一步没抛异常，说明密钥配置成功；如果报 KeyError，回头检查环境变量名是否拼写正确。
📝 核心流程演示
先告诉模型要输出什么结构
第一件事是定义结果的"形状"。这里声明三个 TypedDict：每个角色带名字、描述、善恶倾向三个字段；每个地点带名字和描述；顶层 TextSummary 再挂上 synopsis 和类型列表。
from typing_extensions import TypedDict class Character(TypedDict): name: str description: str alignment: str class Location(TypedDict): name: str description: str class TextSummary(TypedDict): synopsis: str genres: list[str] locations: list[Location] characters: list[Character]schema 只定义一次，换输入文本时这段代码完全不用动。用 TypedDict 而不是手写 JSON 字符串的原因也在这：SDK 会把它转成标准 JSON Schema 传给模型，约束是硬性的；而靠在 prompt 里请求"请输出 JSON"，模型未必照办。
发起调用时只改两个参数
调用本身没什么变化，关键在 config 里的两个参数：response_mime_type设为application/json声明输出格式；response_schema传入刚定义的 TextSummary，约束字段结构。模型只允许按这个结构输出。
response = client.models.generate_content( model="gemini-3.7-flash", contents=f"Generate a summary of the following story: {story}", config={ "response_mime_type": "application/json", "response_schema": TextSummary, } )示例 notebook 里 story 先由模型生成；本地跑的时候，把它换成你自己的长文本即可。文本特别长时，可换 notebook 备选的更大模型。
结果一行代码取出来
响应文本此时已经是合法 JSON，不需要自己解析。response.parsed会由 SDK 直接转成 Python 字典。
from pprint import pprint pprint(response.parsed)预期看到与 schema 一一对应的四个字段，例如：
{'synopsis': 'Elara, a cartographer and adventurer, seeks the lost city of Eldoria, ...', 'genres': ['Fantasy', 'Adventure'], 'characters': [{'name': 'Elara', 'alignment': 'Good', 'description': 'A cartographer...'}], 'locations': [{'name': "Dragon's Tooth Mountains", ...}]}检查每个字段都有值、没有混进多余的自然语言，通过后这个字典就能直接入库。
🗺️ 换个场景试试
整套流程可以平移到其他文本类型，只需要改 prompt 和 schema：
- 新闻摘要：schema 改成 title、date、key_points，让模型抽出标题、时间节点与核心事实。
- 研报要点：声明 conclusion、data_source、risk_notice 字段，输出可直接作为后续报告生成流程的输入。
- 商品描述解析：声明 product_name、price、specs、target_audience，一次调用把详情页的散乱文案理清。
代码流程原封不动，变的只有 schema 类和那句 prompt。
⚠️ 踩坑速查
- 密钥未设置：环境变量里没有 GEMINI_API_KEY 时，
genai.Client初始化会直接抛错，先查变量名和拼写。 - schema 类型不匹配：TypedDict 的字段类型要和内容对得上。price 是小数却声明成 str、列表字段没写成
list[...]并指定元素类型，都会导致校验失败。 - 返回 JSON 被截断：输入文本过长时模型可能只输出部分内容，
response.parsed解析会报错。把长文分片发送，或换上下文更大的模型。
🔗 延伸阅读
- examples/json_capabilities/Text_Summarization.ipynb — 完整示例 notebook，含故事生成
- quickstarts/JSON_mode.ipynb — JSON 输出模式基础用法
- examples/json_capabilities/Entity_Extraction_JSON.ipynb — 实体抽取变体，同一套手法
- quickstarts/Authentication.ipynb — 密钥获取与 Colab 配置
到这里，"声明 schema、改两个参数、parsed 取出"这条链路就能让你把长文变成结构化数据。下次再遇到文本解析需求，改一下 schema 就能开工：
git clone https://gitcode.com/GitHub_Trending/coo/cookbook【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
