Gemini 结构化输出实战：使用 Instructor 与 Google GenAI SDK 构建类型安全的数据提取-北京尧图网络

Gemini 结构化输出实战使用 Instructor 与 Google GenAI SDK 构建类型安全的数据提取【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本指南以 Instructor 的 Google 集成为主线讲解如何基于 Google 官方推荐的google-genaiSDK用from_provider(google/model)一行初始化客户端通过 Pydantic 响应模型从 Gemini 模型中稳定提取结构化数据并覆盖同步/异步、嵌套模型、generation_config参数调优、多模态图片输入、安全设置、流式输出与旧 SDK 迁移等完整场景。读完本文你将掌握在 Instructor 中正确选用 Gemini 前缀与 Mode、配置生成参数、处理图片与安全阈值以及规避 Union 类型等已知限制的实战能力。前置准备安装与 Provider 前缀选择Google 的 GenAI SDKgoogle-genai是访问 Gemini 模型的推荐方式它为 Gemini API 与 Vertex AI 提供了统一接口。Instructor 通过instructor[google-genai]附加依赖安装pip install instructor[google-genai]在 Instructor 中同一个 SDK 存在三条前缀路径选择前先明确差异原文档明确建议前缀状态底层 SDK说明google/model推荐google-genai当前 SDK面向 Gemini API搭配vertexaiTrue可切换至 Vertex AIvertexai/model已弃用—请迁移到google/modelvertexaiTruegemini/model遗留google-generativeai旧包请迁移到google/model从源码上看from_provider在 instructor/v2/auto_client.py 中按provider/model-name格式解析前缀约 L108-L115并由 _build_google 负责 Google 分支的客户端构建。该分支会从kwargs中弹出vertexai标志默认False从GOOGLE_API_KEY环境变量读取密钥并透传project、location、credentials、http_options等客户端级参数随后统一调用instructor.from_genai(client, mode..., use_async..., model...)。快速上手同步结构化提取定义一个 Pydantic 模型作为输出契约用from_provider创建客户端即可通过client.create完成提取import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int # Using from_provider (recommended) client instructor.from_provider( google/gemini-3.8-flash, ) resp client.create( response_modelUser, messages[ { role: user, content: Extract Jason is 25 years old., } ], ) print(resp) # User(nameJason, age25)其底层调用链清晰可循from_genai定义于 instructor/v2/providers/genai/client.py将google.genai.Client包装为 Instructor 客户端通过patch_v2注册对应模式的请求处理器处理器负责把 OpenAI 风格的messages转换为 GenAI 的contents格式见 handlers.py 中_convert_messages_to_contents再调用client.models.generate_content完成请求。messages参数也可以是纯字符串或google.genai.types.Content对象Instructor 均能兼容。模型名按你所使用的 Gemini 实际命名传入即可仓库其他文档与示例中常见的有google/gemini-2.5-flash、google/gemini-pro参见 docs/integrations/genai.md 与 docs/concepts/from_provider.md。异步支持Instructor 对 Google GenAI SDK 提供完整的异步支持。使用async_clientTrue创建异步客户端配合await client.create(...)调用import instructor from pydantic import BaseModel import asyncio class User(BaseModel): name: str age: int async def extract_user(): client instructor.from_provider( google/gemini-3.8-flash, async_clientTrue, ) user await client.create( messages[ { role: user, content: Extract Jason is 25 years old., } ], response_modelUser, ) return user # Run async function user asyncio.run(extract_user()) print(user) # User(nameJason, age25)注意使用异步客户端时务必在调用它的同一事件循环内声明客户端。否则会触发大量事件循环相关的错误如RuntimeError。从源码可见异步包装器通过client.aio.models.generate_content发起调用client.py异步客户端与事件循环绑定紧密。配置选项generation_config 参数详解你可以通过generation_config字典定制模型行为控制随机性、输出长度与采样方式。常用参数如下参数作用取值范围 / 说明temperature控制输出随机性0.0~1.0值越高越发散max_tokens最大生成 token 数正整数受模型上下文限制top_pNucleus核采样参数0.0~1.0top_k仅考虑概率最高的前 K 个 token正整数import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int client instructor.from_provider( google/gemini-3.8-flash, modeinstructor.Mode.JSON, ) resp client.create( response_modelUser, messages[ { role: user, content: Extract Jason is 25 years old., }, ], generation_config{ temperature: 0.5, max_tokens: 1000, top_p: 1, top_k: 32, }, ) print(resp)从源码看Instructor 会在 request.py 的update_genai_kwargs中将这些“OpenAI 风格”参数映射为 GenAI 的GenerateContentConfig字段映射表如下这意味着你无需学习两套命名max_tokens→max_output_tokenstemperature→temperaturen→candidate_counttop_p→top_pstop→stop_sequencesseed→seedpresence_penalty→presence_penaltyfrequency_penalty→frequency_penalty此外handlers.py的_cleanup_provider_kwargs与两个 Handler 的prepare_request也会将散落在顶层kwargs中的max_tokens、temperature、top_p、seed等参数统一收拢进generation_config再合并进config发送给 SDK。值得注意的细节当响应因max_tokens截断finish_reason MAX_TOKENS而无法完整解析时Instructor 会抛出IncompleteOutputException而非返回带有字段默认值的残缺对象见 handlers.py。这能避免“模型其实没生成某字段却与模型主动选择的值无法区分”的坑。多模态输入与图片安全设置Gemini 是多模态模型Instructor 通过统一的Image、Audio、PDF对象封装媒体输入。以图片为例可使用Image.autodetect支持本地路径、HTTP URL、gs://地址与 base64见 instructor/v2/core/multimodal.py或显式的Image.from_url/Image.from_path/Image.from_base64。Google GenAI 对图片输入使用一套独立的危害类别例如HARM_CATEGORY_IMAGE_HATE。当请求包含图片内容时Instructor 会自动处理在请求配置中使用图片专属的类别将你为文本类别如HARM_CATEGORY_HATE_SPEECH传入的阈值映射到对应的图片类别如HARM_CATEGORY_IMAGE_HATE。这样可以避免同时传safety_settings与图片时出现400 INVALID_ARGUMENT错误。import instructor from google.genai.types import HarmBlockThreshold, HarmCategory from instructor.processing.multimodal import Image from pydantic import BaseModel class Result(BaseModel): summary: str client instructor.from_provider(google/gemini-3.8-flash) result client.create( response_modelResult, messages[ { role: user, content: [ Describe the image in one sentence., Image.autodetect(path/to/image.png), ], } ], # You can still pass text categories. Instructor will map them for image inputs. safety_settings{ HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, }, ) print(result)源码层面request.py中update_genai_kwargs对safety_settings的处理逻辑L35-L65会默认将所有文本类别的阈值置为HarmBlockThreshold.OFF再以用户传入的字典逐类别覆盖图片请求时剔除HARM_CATEGORY_IMAGE_*前缀的类别交由 GenAI SDK 的图片专用处理。底层媒体编码器位于 instructor/v2/providers/genai/multimodal.py其中image_to_genai对gs://、HTTP URL、base64 分别生成对应的Part.from_bytes。嵌套结构提取结构化输出的价值在于可以提取任意复杂的嵌套对象。定义一个含列表嵌套字段的 Pydantic 模型Gemini 会一次性返回完整的嵌套结构import instructor from pydantic import BaseModel class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: list[Address] client instructor.from_provider( google/gemini-3.8-flash, ) user client.create( messages[ { role: user, content: Extract: Jason is 25 years old. He lives at 123 Main St, New York, USA and has a summer house at 456 Beach Rd, Miami, USA , }, ], response_modelUser, ) print(user) # { # name: Jason, # age: 25, # addresses: [ # { # street: 123 Main St, # city: New York, # country: USA # }, # { # street: 456 Beach Rd, # city: Miami, # country: USA # } # ] # }底层实现中Handler 会把 Pydantic 模型经model_json_schema()转换为 Gemini 的Schema工具函数位于 instructor/v2/providers/gemini/utils.py 与map_to_genai_schemaJSON模式下直接作为response_schema下发handlers.py保证输出结构与模型定义严格对齐。流式输出Instructor 提供两种流式方案按需选用Iterables流式提取同一类型的多个对象例如从一段文本中提取多个用户Partial Streaming流式处理单个对象边生成边消费部分结果。Partials部分流式create_partial返回一个生成器随着 token 逐步到达字段会从None逐渐填充完整import instructor from pydantic import BaseModel client instructor.from_provider( google/gemini-3.8-flash, ) class User(BaseModel): name: str age: int bio: str user client.create_partial( messages[ { role: user, content: Create a user profile for Jason and 1 sentence bio, age 25, }, ], response_modelUser, ) for user_partial in user: print(user_partial) # nameNone ageNone bioNone # nameNone age25 bioJason is a great guy # nameJason age25 bioJason is a great guyIterable迭代流式create_iterable从单个响应中逐个产出同类型对象import instructor from pydantic import BaseModel client instructor.from_provider( google/gemini-3.8-flash, ) class User(BaseModel): name: str age: int # Extract multiple users from text users client.create_iterable( messages[ { role: user, content: Extract users: 1. Jason is 25 years old 2. Sarah is 30 years old 3. Mike is 28 years old , }, ], response_modelUser, ) for user in users: print(user) # nameJason age25 # nameSarah age30 # nameMike age28流式的底层逻辑同样位于 handlers.pyextract_streaming_json逐块抽取 JSONTOOLS模式下取function_call.argsJSON模式下取文本再由from_streaming_response增量构建 Pydantic 对象L210-L322。异步场景使用create_partial/create_iterableasync for同样可行相关完整示例见 docs/integrations/genai.md。补充说明GenAI 的Mode.TOOLS函数调用与流式存在兼容性约束若需流式请优先使用Mode.JSON或显式使用Partial[YourModel]。已知限制Union 类型Gemini 与 Instructor 配合时存在以下已知限制Union 类型Gemini 不支持 Union 类型Optional除外。请改用独立响应模型或Literal类型X | None形式的可选字段可以正常工作Union 流式Iterable 流式不支持 Union 类型。这些限制是 Gemini 平台特有的不影响 OpenAI、Anthropic 等其他 Provider。仓库的测试会自动跳过 Gemini 的这些特性以避免失败。可参考 docs/integrations/genai.md 中的 Union 注意事项以及 instructor/v2/providers/gemini/utils.py 中 Schema 转换对anyOf仅接受单类型 null组合的处理逻辑。Instructor ModesTOOLS 与 JSON针对 Gemini 的不同响应机制Instructor 提供两种通用模式模式实现机制说明instructor.Mode.TOOLSGemini 函数调用tool callingAPI默认模式将响应模型声明为 FunctionDeclarationinstructor.Mode.JSONGemini 的 JSON Schema 模式通过response_schema强制 JSON 输出向后兼容遗留的 Provider 专属模式如Mode.GENAI_TOOLS、Mode.GENAI_JSON、Mode.GENAI_STRUCTURED_OUTPUTS已弃用会发出警告并自动映射到通用模式Mode.TOOLS、Mode.JSON。映射表定义在 instructor/v2/core/mode.py 的DEPRECATED_TO_CORE中。模式选择使用from_provider时Instructor 会根据 Provider 与模型能力自动选择合适模式一般无需手动指定from_provider(google/...)的默认模式为Mode.TOOLS见 auto_client.py。TOOLS模式下GenAIToolsHandlerhandlers.py将 Pydantic 模型构造成FunctionDeclaration并通过ToolConfig(FunctionCallingConfigMode.ANY)强制模型只调用该函数JSON模式下GenAIStructuredOutputsHandlerL455-L523则设置response_mime_type: application/json与response_schema。两种模式下Pydantic 校验失败都会触发自动 reask重试将错误信息回传给模型修正。另外TOOLS模式会自动过滤 Gemini 响应中的思考片段thought parts避免内部推理内容干扰结构化解析——这在 Gemini 2.5 及以上默认开启思考的模型中尤为重要。可用模型概览Google 提供多款 Gemini 模型供不同场景选择Gemini Flash通用目的推理速度快适合高频提取Gemini Pro高级推理与多模态适合复杂任务Gemini Flash-8b轻量、性价比高适合大规模低成本调用。具体以 Google 当前可用的模型名为准如仓库中广泛使用的google/gemini-2.5-flash传入from_provider(google/model)即可。多模态能力延伸Gemini 的多模态图片、音频、PDF、视频是 Instructor 集成的重点场景仓库提供了多篇深入指南使用 Gemini 提取旅行视频推荐用 Gemini 解析 PDF用 Gemini 生成 PDF 引用这些文章展示了Image、Audio、PDF、PDFWithGenaiFile配合 Gemini Files API与create/create_partial的组合用法多模态媒体的统一加载 APIURL / 本地路径 / base64 / 自动检测实现在 instructor/v2/core/multimodal.pyProvider 专属编码在 instructor/v2/providers/genai/multimodal.py。开启autodetect_imagesTrue后字符串形式的文件路径与 URL 会在请求中自动转换为媒体 Part。从旧 SDK 迁移从 google-generativeai 迁移如果你仍在使用旧的google-generativeai包gemini/前缀# 旧方式已弃用 import instructor client instructor.from_provider( google/gemini-3.8-flash, modeinstructor.Mode.JSON, )推荐迁移方式import instructor # 方式一使用 from_provider推荐 client instructor.from_provider(google/gemini-3.8-flash) # 方式二直接使用 from_genai遗留/进阶用法 from google import genai from instructor import from_genai client from_genai(genai.Client())from_genai接收一个原生google.genai.Client实例并返回 Instructor 客户端instructor/v2/providers/genai/client.py适合需要保留 Google 原生请求格式或已有genai.Client实例的场景。它也要求传入的必须是google.genai.Client实例否则会抛出ClientError。Vertex AI 迁移Vertex AI 用户的迁移路径类似# 旧方式已弃用 import instructor import vertexai vertexai.init(projectyour-project, locationus-central1) client instructor.from_provider( google/gemini-3.8-flash, vertexaiTrue, modeinstructor.Mode.TOOLS, )推荐方式import instructor # 方式一使用 from_provider推荐 client instructor.from_provider( vertexai/gemini-3.8-flash, projectyour-project, locationus-central1 ) # 方式二使用 from_genai vertexaiTrue遗留/进阶用法 from google import genai from instructor import from_genai client from_genai( genai.Client(vertexaiTrue, projectyour-project, locationus-central1) )_build_google会从kwargs提取project、location、credentials等参数并透传给genai.Client(vertexai...)auto_client.py因此通过from_provider传vertexaiTrue、project、location即可无缝切换 Gemini API 与 Vertex AI。相关资源快速上手快速开始指南from_provider 详解客户端配置的详细说明Instructor 核心概念与类型校验指南多模态示例视觉与多模态处理各 Provider 示例所有 Provider 的快速示例更新与兼容性说明Instructor 会持续跟进 Google 最新 API 版本升级前请查阅变更日志【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Gemini 结构化输出实战：使用 Instructor 与 Google GenAI SDK 构建类型安全的数据提取

相关推荐

React 进阶概念实战指南：PropTypes、Styled Components、Redux、Context API 与自定义 Hooks（cu/curriculum 课程精讲）

LangChain4j 集成 Tavily Web Search Engine：配置、API 与源码级原理详解

使用 AWS CLI 的 associate-external-connection 命令为 CodeArtifact 仓库添加外部连接

更多资讯

抖音批量下载完整指南：douyin-downloader 配置、参数与常见问题

cleanlab benchmarking 噪声标签合成指南：noise_generation 模块全解析

LunaTranslator 大模型翻译接口实战指南：通用接口参数、多密钥轮询与 SakuraLLM 离线翻译模型

Wasp 子目录部署完全指南：正确配置 `client.baseDir` 与 `WASP_WEB_CLIENT_URL`

Python反序列化漏洞从原理到防御：pickle模块攻防实战全解析

GESP C++二级考试备考指南与核心考点解析

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？