3分钟上手：用Gemini API把长文本变成结构化JSON数据

你是不是经常需要从大量文字中提取关键信息？比如从客户反馈中找出核心问题，或者从产品文档中提取功能点？传统的手工整理方式耗时耗力，今天我来分享一个高效解决方案——使用Gemini API的JSON文本摘要功能。## 快速体验：从故事到结构化数据让我用一个实际案例带你感受一下。假设你有一篇奇幻故事，想快速提取其中的角色、地点和情节概要。传统的做法是手动阅读并整理，但有了Gemini API，整

侯彬颖Butterfly

328人浏览 · 2026-03-31 13:17:19

侯彬颖Butterfly · 2026-03-31 13:17:19 发布

3分钟上手：用Gemini API把长文本变成结构化JSON数据

【免费下载链接】cookbook Examples and guides for using the Gemini API 项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook

你是不是经常需要从大量文字中提取关键信息？比如从客户反馈中找出核心问题，或者从产品文档中提取功能点？传统的手工整理方式耗时耗力，今天我来分享一个高效解决方案——使用Gemini API的JSON文本摘要功能。

快速体验：从故事到结构化数据

让我用一个实际案例带你感受一下。假设你有一篇奇幻故事，想快速提取其中的角色、地点和情节概要。传统的做法是手动阅读并整理，但有了Gemini API，整个过程只需要几行代码。

首先，我们定义需要提取的数据结构：

from typing_extensions import TypedDict

# 定义角色信息结构
class Character(TypedDict):
  name: str          # 角色名称
  description: str   # 角色描述
  alignment: str     # 阵营（如：Good, Neutral, Evil）

# 定义地点信息结构  
class Location(TypedDict):
  name: str          # 地点名称
  description: str   # 地点描述

# 定义完整的文本摘要结构
class TextSummary(TypedDict):
  synopsis: str             # 故事概要
  genres: list[str]        # 故事类型
  locations: list[Location] # 地点列表
  characters: list[Character] # 角色列表

这段代码定义了我们要从文本中提取的信息模板。就像给AI一个"填空题"的答题卡，告诉它我们需要哪些信息，以及这些信息应该是什么格式。

核心概念：结构化摘要的魅力

Gemini API的JSON模式最强大的地方在于，它不仅仅是"总结"文本，而是"理解并结构化"文本。想象一下，你给AI一篇1000字的文章，它不仅能告诉你文章讲了什么，还能把文章中的关键元素分门别类地整理好。

这种能力来自于Gemini对自然语言的深度理解。当你指定response_mime_type: "application/json"时，你其实是在告诉AI："请用JSON格式回答我，并且按照我定义的结构来组织信息。"

实战演练：三步完成文本结构化

第一步：准备你的文本

文本可以是任何内容——新闻报道、产品说明、用户评论，甚至是像我们例子中的奇幻故事。在examples/json_capabilities/Text_Summarization.ipynb中，我们让AI生成一个关于寻找失落之城的故事：

prompt = "Generate a 10 paragraph fantasy story. Include at least 2 named characters and 2 named locations."
response = client.models.generate_content(
    model=MODEL_ID,
    contents=prompt
)
story = response.text

第二步：调用API进行结构化摘要

现在，我们让AI根据之前定义的结构来提取信息：

summary_prompt = f"Generate summary of the story. With a list of genres locations and characters.\n\n{story}"

response = client.models.generate_content(
    model=MODEL_ID,
    contents=summary_prompt,
    config={
        "response_mime_type": "application/json",
        "response_schema": TextSummary
    }
)

注意这里的response_schema参数，它告诉AI必须按照我们定义的TextSummary结构来组织返回的数据。

第三步：解析和使用结果

API返回的结果可以直接转换成Python字典：

from pprint import pprint
pprint(response.parsed)

你会得到这样的结构化数据：

{
  "characters": [
    {
      "alignment": "Good",
      "description": "A cartographer and adventurer seeking the lost city of Eldoria.",
      "name": "Elara"
    },
    {
      "alignment": "Neutral", 
      "description": "A creature of stone and shadow tasked with protecting the secrets of Eldoria.",
      "name": "Guardian of the Hidden Passage"
    }
  ],
  "genres": ["Fantasy", "Adventure"],
  "locations": [
    {
      "description": "A treacherous mountain range with jagged peaks, dangerous paths, and a hidden passage to Eldoria.",
      "name": "Dragon's Tooth Mountains"
    },
    {
      "description": "A legendary, vanished civilization rumored to hold unimaginable riches and powerful magic.",
      "name": "Eldoria (Lost City)"
    }
  ],
  "synopsis": "Elara, a cartographer and adventurer, seeks the lost city of Eldoria..."
}

常见误区：避开这些坑

误区一：结构定义过于复杂

新手常犯的错误是定义过于复杂的结构。记住，AI需要明确的指引。如果你的结构嵌套太深或字段太多，AI可能会混淆。从简单的结构开始，逐步增加复杂度。

误区二：期望AI理解未定义的字段

如果你在结构定义中只定义了name和description，就不要期望AI会自动添加age或birthday字段。AI会严格按照你定义的结构来填充数据。

误区三：忽略错误处理

API调用可能会失败，返回的数据可能不完整。在实际应用中，一定要添加适当的错误处理：

try:
    response = client.models.generate_content(
        model=MODEL_ID,
        contents=prompt,
        config={
            "response_mime_type": "application/json",
            "response_schema": TextSummary
        }
    )
    if response.parsed:
        # 处理成功的数据
        process_summary(response.parsed)
    else:
        # 处理解析失败的情况
        handle_parsing_error(response)
except Exception as e:
    # 处理API调用异常
    handle_api_error(e)

进阶技巧：让结构化摘要更强大

技巧一：结合其他API功能

Gemini API的JSON模式可以和其他功能结合使用。比如，你可以先用response_schema提取结构化信息，然后再用这些信息作为其他API调用的输入。

技巧二：处理多语言文本

这个功能不仅限于英文。你可以用中文、日文、法文等任何Gemini支持的语言来生成结构化摘要。只需要确保你的提示词和目标语言一致。

技巧三：批量处理文档

当你需要处理大量文档时，可以结合项目中的其他示例，比如examples/json_capabilities/Entity_Extraction_JSON.ipynb中的实体提取技术，构建一个完整的文档处理流水线。

扩展应用：不只是故事摘要

虽然我们以奇幻故事为例，但这个技术的应用场景远不止于此：

产品评论分析：从用户评论中提取产品优缺点、使用场景、改进建议
新闻摘要：从新闻报道中提取事件、人物、地点、时间等关键信息
技术文档整理：从API文档中提取函数、参数、返回值信息
会议纪要生成：从会议录音转文字中提取议题、决定、待办事项

图片说明：Gemini API的JSON摘要功能就像一座精心设计的城堡——外部是复杂的自然语言文本，内部是结构化的JSON数据。每个"房间"（JSON字段）都有明确的用途，AI作为"建筑师"负责将杂乱的信息整理成有序的结构。

硬件集成：从文本到物理世界

更有趣的是，你还可以将文本摘要与物理设备结合。比如，你可以用Gemini API分析用户的语音指令，然后控制物联网设备。在examples/iot/esp32/voice_led_controller/目录中，有一个通过语音控制LED的示例项目。

图片说明：这张接线图展示了如何将ESP32开发板与LED灯带、声音传感器等组件连接。结合Gemini API的文本理解能力，你可以构建一个系统：用户说出"打开客厅的灯"，AI理解指令并提取关键信息（动作：打开，位置：客厅，设备：灯），然后通过API控制相应的硬件。

下一步行动：开始你的结构化之旅

现在你已经了解了Gemini API JSON文本摘要的核心概念和基本用法。要深入学习和实践，我建议：

克隆项目并运行示例：

git clone https://gitcode.com/GitHub_Trending/coo/cookbook
cd cookbook/examples/json_capabilities

修改示例代码：尝试用你自己的文本来替换示例中的奇幻故事，看看AI能提取出什么信息
探索其他JSON功能：项目中的examples/json_capabilities/目录还包含了情感分析、文本分类等其他JSON相关任务
结合硬件项目：如果你对物联网感兴趣，可以尝试将文本摘要功能与examples/iot/esp32/voice_led_controller/中的硬件项目结合

记住，最好的学习方式是动手实践。从简单的文本开始，逐步增加复杂度，你会发现Gemini API的JSON模式是一个极其强大的工具，能够将非结构化的文字世界转化为结构化的数据宝藏。

【免费下载链接】cookbook Examples and guides for using the Gemini API 项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook