Instructor 结构化输出实战用 Pydantic 让任意 LLM 返回可靠 JSON【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorInstructorstructured outputs for llms是一个围绕 Pydantic 构建的 Python 库你只需定义一个 Pydantic 模型把自然语言交给任意主流 LLM即可直接拿回经过校验、类型安全的结构化对象——无需手写 JSON Schema、无需解析响应、无需自己实现重试与错误处理。本指南以仓库根目录的 README.md 为主体结合源码、示例与测试带你从零掌握 Instructor 的统一接口、自动重试、流式输出与嵌套对象提取并理解其底层实现原理。读完你将能够用一条 API 在 OpenAI / Anthropic / Google / Ollama 等提供商之间无缝切换完成结构化抽取并借助 Pydantic 校验与自动重试把抽取可靠性提升到生产级。Instructor 是什么定义模型剩下的交给库Instructor 的核心设计极其简单——Define what you want, extract it from natural language。仓库根目录的 README.md 用一段可运行代码完整展示了这一体验import instructor from pydantic import BaseModel # Define what you want class User(BaseModel): name: str age: int # Extract it from natural language client instructor.from_provider(openai/gpt-4o-mini) user client.chat.completions.create( response_modelUser, messages[{role: user, content: John is 25 years old}], ) print(user) # User(nameJohn, age25)就这样。没有 JSON 解析、没有错误处理、没有重试逻辑——定义好模型就能拿到结构化数据。返回值user就是真正的User实例天然具备类型提示、IDE 自动补全与 Pydantic 的全部校验能力。值得一提的是README 同时给出了生态定位Instructor 专注快速抽取、保持 schema-first 流程简单廉价如果应用需要更丰富的 Agent 运行能力内置可观测性、可回放数据集、评测与生产仪表盘官方建议选用 Pydantic 团队基于同一套 Pydantic 模型打造的 PydanticAI Agent 运行时。两者共用 Pydantic 模型可以从 Instructor 风格工作流平滑扩展。为什么需要 Instructor手动管 JSON 的五个痛点README 总结了从 LLM 拿结构化数据的难点编写复杂的 JSON Schema处理校验错误重试失败的抽取解析非结构化响应适配不同提供商的 APIInstructor 用一个简单接口解决以上全部问题。下面是 README 中的对照示例左边是裸调用 OpenAI API 的繁琐流程右边是 Instructor 的等价实现无 Instructor用 Instructor手写tools与function.parameters的 JSON Schema手动从tool_calls里抠出参数再手写校验逻辑处理缺失字段定义 Pydantic 模型 传入response_model一步到位拿到已校验、已类型化的对象# Without Instructor: 手写 schema、手动解析、手动校验 response openai.chat.completions.create( modelgpt-5.4-mini, messages[{role: user, content: ...}], tools[ { type: function, function: { name: extract_user, parameters: { type: object, properties: { name: {type: string}, age: {type: integer}, }, }, }, } ], ) # 手动解析 tool_call response.choices[0].message.tool_calls[0] user_data json.loads(tool_call.function.arguments) # 手动校验 if name not in user_data: # Handle error... pass# With Instructor client instructor.from_provider(openai/gpt-5.4-mini) user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], ) # Thats it! user is validated and typed秒级安装README 提供了三种安装方式任选其一pip install instructoruv add instructor poetry add instructor仓库内 requirements.txt、requirements-doc.txt 与 pyproject.toml 是当前版本__version__ 1.17.1见 instructor/init.py的依赖清单与打包配置。注意各提供商 SDK如openai、anthropic、google-genai按需安装即可——Instructor 的顶层导出采用惰性导入_LAZY_IMPORTS机制见 instructor/init.py未安装对应 SDK 时只是不暴露相关from_*工厂不影响库本身导入。统一的多提供商接口from_provider全解析README 强调用同一段代码、同一个 API 对接任意 LLM 提供商# OpenAI client instructor.from_provider(openai/gpt-4o) # Anthropic client instructor.from_provider(anthropic/claude-3-5-sonnet) # Google client instructor.from_provider(google/gemini-pro) # Ollama (local) client instructor.from_provider(ollama/llama3.2) # With API keys directly (no environment variables needed) client instructor.from_provider(openai/gpt-4o, api_keysk-...) client instructor.from_provider(anthropic/claude-3-5-sonnet, api_keysk-ant-...) client instructor.from_provider(groq/llama-3.1-8b-instant, api_keygsk_...) # All use the same API! user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], )调用格式与内部路由从源码看from_provider的真正实现在 instructor/v2/auto_client.pyinstructor/auto_client.py 只是它的兼容转发层。其核心逻辑为模型字符串必须是provider/model-name格式用model.split(/, 1)拆分instructor/v2/auto_client.py通过_PROVIDER_BUILDERS注册表按 provider 名找到对应的构建函数如_build_openai、_build_anthropic、_build_ollama等支持openai、anyscale、together、azure_openai、databricks、anthropic、google、gemini、mistral、cohere、perplexity、groq、writer、bedrock、cerebras、fireworks、vertexai、generative-ai、ollama、deepseek、xai、openrouter、litellm共 23 个条目instructor/v2/auto_client.py若格式非法或 provider 不受支持会抛出ConfigurationError并明确列出所有受支持的 provider每个构建器负责实例化对应提供商 SDK 的客户端同步或异步再调用 v2 的from_*工厂完成 patching。常用参数源码签名from_provider的签名instructor/v2/auto_client.py暴露了四个关键参数参数说明默认行为modelprovider/model-name字符串如openai/gpt-4必填async_client是否返回异步客户端AsyncInstructorFalsecache可选缓存适配器如AutoCache、RedisCache实现透明响应缓存Nonemode覆盖该 provider 的默认 Mode不传则使用各 provider 推荐模式各 provider 各异**kwargs会透传给 provider 的客户端工厂包括api_key、base_url、timeout、max_retries、organization、default_headers等。README 强调api_key可以直接传入而无需设置环境变量其余配置则同时支持环境变量兜底例如 Azure 需要AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINTinstructor/v2/auto_client.pyDatabricks 支持DATABRICKS_TOKEN/DATABRICKS_HOSTinstructor/v2/auto_client.pyPerplexity、DeepSeek、OpenRouter 分别读取PERPLEXITY_API_KEY、DEEPSEEK_API_KEY、OPENROUTER_API_KEY。各 provider 的默认模式Mode枚举定义在 instructor/v2/core/mode.py每个模式决定请求如何格式化、响应如何解析。从构建器源码可以总结出默认模式规则OpenAI 及其兼容系Azure、Databricks、DeepSeek、OpenRouter、Groq、xAI、Cohere 等默认Mode.TOOLS本地 Ollama按模型名自动判断——llama3.1/3.2/4、mistral-nemo、qwen2.5/3等支持 function calling 的模型用Mode.TOOLS否则回退Mode.JSONinstructor/v2/auto_client.pyGoogle GenAIgoogleprovider默认Mode.TOOLS旧版 Geminigeminiprovider默认Mode.MD_JSON。Mode还提供tool_modes()、json_modes()、parallel_modes()三个分类辅助方法并内置了旧模式到核心模式的废弃映射DEPRECATED_TO_CORE例如Mode.FUNCTIONS、Mode.TOOLS_STRICT统一迁移到Mode.TOOLSANTHROPIC_*系列也逐步收敛到通用模式。生产级特性一自动重试抽取最怕模型返回了不满足约束的 JSON。Instructor 的做法是校验失败时把错误信息回填给模型自动发起下一次请求。README 的示例from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int field_validator(age) def validate_age(cls, v): if v 0: raise ValueError(Age must be positive) return v # Instructor automatically retries when validation fails user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], max_retries3, )底层实现registry 处理器 tenacity重试逻辑位于 instructor/v2/core/retry.py要点如下max_retries默认值为3见 instructor/v2/core/client.py 中create系列方法签名内部使用tenacity的Retrying/AsyncRetryingmax_retries为整数时映射为stop_after_attempt(max_retries 1)并可叠加stop_after_delay(timeout)也可直接传入Retrying/AsyncRetrying实例完全自定义重试策略只有_RETRYABLE_PARSE_ERRORSValidationError、JSONDecodeError、AsyncValidationError、ResponseParsingError才触发重试instructor/v2/core/retry.py每次失败后调用 registry 的reask_handler把错误信息写回kwargs即reask机制然后基于修正后的参数重发请求重试期间自动聚合 token 用量_usage_snapshot/update_total_usage并在尝试耗尽时抛出携带failed_attempts、messages、create_kwargs的InstructorRetryException便于上层诊断还支持token_budget预算控制累计 token 超限会立即终止重试并抛出TokenBudgetErrorinstructor/v2/core/budget.py。Pydantic 的字段校验器field_validator、模型校验器乃至跨字段约束都可以直接用于驱动 reask相关机制在 docs/concepts/validation.md 与 docs/concepts/reask_validation.md 有系统讲解仓库测试 tests/v2/test_retry_runtime.py 则验证了重试流程与预算控制的行为。生产级特性二流式输出 Partial长输出场景下用户希望边生成边看到结果。Instructor 提供Partial[T]包装器字段在未填满前为None随流式推进逐步补全from instructor import Partial for partial_user in client.chat.completions.create( response_modelPartial[User], messages[{role: user, content: ...}], streamTrue, ): print(partial_user) # User(nameNone, ageNone) # User(nameJohn, ageNone) # User(nameJohn, age25)实现原理基于 JSON 完整度的部分校验Partial[T]定义在 instructor/v2/dsl/partial.py底层先把模型字段全部转成可选MakeFieldsOptional配合jiter的partial_mode解析不完整 JSON关键创新是completeness-based validationinstructor/v2/dsl/partial.py用JsonCompleteness追踪 JSON 是否闭合——JSON 不完整时跳过校验、用model_construct构建部分对象JSON 一旦完整闭合立刻按原始模型做全量校验因此Literal、Enum等严格类型在流式过程中不会被误报错误旧方案需要PartialLiteralMixin如今已标记废弃见 instructor/v2/dsl/partial.py自引用模型如树结构通过ContextVar隔离的处理集合避免无限递归instructor/v2/dsl/partial.py。流式还支持嵌套结构、列表与异步生成器可参考 docs/concepts/partial.md、docs/learning/streaming/basics.md 以及测试 tests/v2/test_iterable_streaming.py、tests/dsl/test_partial.py。生产级特性三嵌套对象结构化抽取的价值在复杂场景尤为明显。README 展示了多级嵌套模型from typing import List class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: List[Address] # Instructor handles nested objects automatically user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], )模型嵌套、List[T]容器、Optional字段、枚举与 Union 等 Pydantic 类型能力均被 Instructor 完整保留。schema 生成逻辑位于 instructor/v2/core/schema.py按提供商分别产出generate_openai_schema/generate_anthropic_schema/generate_gemini_schema三种格式再由各 provider 的处理器组装进请求。仓库中的真实用例非常多例如 examples/knowledge-graph/run.py 抽取多跳知识图谱、examples/query_planner_execution/query_planner_execution.py 抽取执行计划、examples/resolving-complex-entities/run.py 处理复杂实体消解均可直接复制改造。实战参考从仓库示例开始一个完整的抽取脚本仓库 examples/simple-extraction/user.py 给出了一个可运行的完整示例含可选字段与输出序列化import instructor from openai import OpenAI from pydantic import BaseModel, Field from typing import Optional client instructor.from_openai(OpenAI()) class UserDetail(BaseModel): age: int name: str role: Optional[str] Field(defaultNone) def get_user_detail(string) - UserDetail: return client.chat.completions.create( modelgpt-4o-mini, response_modelUserDetail, messages[ { role: user, content: fGet user details for {string}, }, ], ) # type: ignore user get_user_detail(Jason is 25 years old) print(user.model_dump_json(indent2)) # { # age: 25, # name: Jason, # role: null # }注意两点返回对象可以直接调用 Pydantic 的model_dump_json()等序列化方法该示例文件也揭示了一个常见陷阱当输入文本与目标实体无关时如User not found模型仍可能幻觉出一个符合 schema 的默认结果——这正是需要结合 Pydantic 校验、llm_validator或领域约束做二次把关的场景参考 examples/validators/ 与 instructor/v2/validation/llm_validators.py。更多抄作业入口入门三件套docs/getting-started.md、docs/installation.md、docs/concepts/usage.md概念手册docs/concepts/index.md覆盖重试、校验、部分、迭代、Maybe、并行、多模态、缓存等示例大全docs/examples/examples.md 与 examples/ 下的几十个可直接运行脚本分类、批量、批处理 API、流式、评测、知识图谱、PII、SQL 安全生成等各提供商集成指南docs/integrations/index.md。多语言生态README 指出 Instructor 的简单 API 已被移植到多种语言Python原始实现、TypeScript、Ruby、Go、Elixir、Rust。仓库内另有 docs/start-here.md 与 docs/repository-overview.md 对项目结构与学习路线做了整体梳理。与其他方案的取舍README 给出了三组对比视角供选型参考对比裸 JSON 模式Instructor 自动完成校验、重试、流式与嵌套对象支持无需手写 schema对比 LangChain / LlamaIndexInstructor 专注结构化抽取这一件事更轻量、更易调试对比自研方案项目经历大量开发者打磨覆盖了诸多你没预料到的边界情况。核心取舍原则始终是需要 Agent 编排、工具调用、评测与追踪这类运行时能力时考虑 PydanticAI两者共享 Pydantic 模型需要最简 schema-first 抽取流程时Instructor 是直接的答案。贡献与开源协议Instructor 欢迎社区贡献README 中指向 good first issues 入口并以 MIT 协议开源详见仓库根目录 LICENSE。贡献流程与开发规范可参考 CONTRIBUTING.md、docs/contributing.md 与 AGENT.md。README 同时自述该项目已被大量开发者与公司在生产环境中使用仓库以 CHANGELOG.md 持续记录演进具体数据请以官方发布渠道为准。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Instructor 结构化输出实战：用 Pydantic 让任意 LLM 返回可靠 JSON
Instructor 结构化输出实战用 Pydantic 让任意 LLM 返回可靠 JSON【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorInstructorstructured outputs for llms是一个围绕 Pydantic 构建的 Python 库你只需定义一个 Pydantic 模型把自然语言交给任意主流 LLM即可直接拿回经过校验、类型安全的结构化对象——无需手写 JSON Schema、无需解析响应、无需自己实现重试与错误处理。本指南以仓库根目录的 README.md 为主体结合源码、示例与测试带你从零掌握 Instructor 的统一接口、自动重试、流式输出与嵌套对象提取并理解其底层实现原理。读完你将能够用一条 API 在 OpenAI / Anthropic / Google / Ollama 等提供商之间无缝切换完成结构化抽取并借助 Pydantic 校验与自动重试把抽取可靠性提升到生产级。Instructor 是什么定义模型剩下的交给库Instructor 的核心设计极其简单——Define what you want, extract it from natural language。仓库根目录的 README.md 用一段可运行代码完整展示了这一体验import instructor from pydantic import BaseModel # Define what you want class User(BaseModel): name: str age: int # Extract it from natural language client instructor.from_provider(openai/gpt-4o-mini) user client.chat.completions.create( response_modelUser, messages[{role: user, content: John is 25 years old}], ) print(user) # User(nameJohn, age25)就这样。没有 JSON 解析、没有错误处理、没有重试逻辑——定义好模型就能拿到结构化数据。返回值user就是真正的User实例天然具备类型提示、IDE 自动补全与 Pydantic 的全部校验能力。值得一提的是README 同时给出了生态定位Instructor 专注快速抽取、保持 schema-first 流程简单廉价如果应用需要更丰富的 Agent 运行能力内置可观测性、可回放数据集、评测与生产仪表盘官方建议选用 Pydantic 团队基于同一套 Pydantic 模型打造的 PydanticAI Agent 运行时。两者共用 Pydantic 模型可以从 Instructor 风格工作流平滑扩展。为什么需要 Instructor手动管 JSON 的五个痛点README 总结了从 LLM 拿结构化数据的难点编写复杂的 JSON Schema处理校验错误重试失败的抽取解析非结构化响应适配不同提供商的 APIInstructor 用一个简单接口解决以上全部问题。下面是 README 中的对照示例左边是裸调用 OpenAI API 的繁琐流程右边是 Instructor 的等价实现无 Instructor用 Instructor手写tools与function.parameters的 JSON Schema手动从tool_calls里抠出参数再手写校验逻辑处理缺失字段定义 Pydantic 模型 传入response_model一步到位拿到已校验、已类型化的对象# Without Instructor: 手写 schema、手动解析、手动校验 response openai.chat.completions.create( modelgpt-5.4-mini, messages[{role: user, content: ...}], tools[ { type: function, function: { name: extract_user, parameters: { type: object, properties: { name: {type: string}, age: {type: integer}, }, }, }, } ], ) # 手动解析 tool_call response.choices[0].message.tool_calls[0] user_data json.loads(tool_call.function.arguments) # 手动校验 if name not in user_data: # Handle error... pass# With Instructor client instructor.from_provider(openai/gpt-5.4-mini) user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], ) # Thats it! user is validated and typed秒级安装README 提供了三种安装方式任选其一pip install instructoruv add instructor poetry add instructor仓库内 requirements.txt、requirements-doc.txt 与 pyproject.toml 是当前版本__version__ 1.17.1见 instructor/init.py的依赖清单与打包配置。注意各提供商 SDK如openai、anthropic、google-genai按需安装即可——Instructor 的顶层导出采用惰性导入_LAZY_IMPORTS机制见 instructor/init.py未安装对应 SDK 时只是不暴露相关from_*工厂不影响库本身导入。统一的多提供商接口from_provider全解析README 强调用同一段代码、同一个 API 对接任意 LLM 提供商# OpenAI client instructor.from_provider(openai/gpt-4o) # Anthropic client instructor.from_provider(anthropic/claude-3-5-sonnet) # Google client instructor.from_provider(google/gemini-pro) # Ollama (local) client instructor.from_provider(ollama/llama3.2) # With API keys directly (no environment variables needed) client instructor.from_provider(openai/gpt-4o, api_keysk-...) client instructor.from_provider(anthropic/claude-3-5-sonnet, api_keysk-ant-...) client instructor.from_provider(groq/llama-3.1-8b-instant, api_keygsk_...) # All use the same API! user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], )调用格式与内部路由从源码看from_provider的真正实现在 instructor/v2/auto_client.pyinstructor/auto_client.py 只是它的兼容转发层。其核心逻辑为模型字符串必须是provider/model-name格式用model.split(/, 1)拆分instructor/v2/auto_client.py通过_PROVIDER_BUILDERS注册表按 provider 名找到对应的构建函数如_build_openai、_build_anthropic、_build_ollama等支持openai、anyscale、together、azure_openai、databricks、anthropic、google、gemini、mistral、cohere、perplexity、groq、writer、bedrock、cerebras、fireworks、vertexai、generative-ai、ollama、deepseek、xai、openrouter、litellm共 23 个条目instructor/v2/auto_client.py若格式非法或 provider 不受支持会抛出ConfigurationError并明确列出所有受支持的 provider每个构建器负责实例化对应提供商 SDK 的客户端同步或异步再调用 v2 的from_*工厂完成 patching。常用参数源码签名from_provider的签名instructor/v2/auto_client.py暴露了四个关键参数参数说明默认行为modelprovider/model-name字符串如openai/gpt-4必填async_client是否返回异步客户端AsyncInstructorFalsecache可选缓存适配器如AutoCache、RedisCache实现透明响应缓存Nonemode覆盖该 provider 的默认 Mode不传则使用各 provider 推荐模式各 provider 各异**kwargs会透传给 provider 的客户端工厂包括api_key、base_url、timeout、max_retries、organization、default_headers等。README 强调api_key可以直接传入而无需设置环境变量其余配置则同时支持环境变量兜底例如 Azure 需要AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINTinstructor/v2/auto_client.pyDatabricks 支持DATABRICKS_TOKEN/DATABRICKS_HOSTinstructor/v2/auto_client.pyPerplexity、DeepSeek、OpenRouter 分别读取PERPLEXITY_API_KEY、DEEPSEEK_API_KEY、OPENROUTER_API_KEY。各 provider 的默认模式Mode枚举定义在 instructor/v2/core/mode.py每个模式决定请求如何格式化、响应如何解析。从构建器源码可以总结出默认模式规则OpenAI 及其兼容系Azure、Databricks、DeepSeek、OpenRouter、Groq、xAI、Cohere 等默认Mode.TOOLS本地 Ollama按模型名自动判断——llama3.1/3.2/4、mistral-nemo、qwen2.5/3等支持 function calling 的模型用Mode.TOOLS否则回退Mode.JSONinstructor/v2/auto_client.pyGoogle GenAIgoogleprovider默认Mode.TOOLS旧版 Geminigeminiprovider默认Mode.MD_JSON。Mode还提供tool_modes()、json_modes()、parallel_modes()三个分类辅助方法并内置了旧模式到核心模式的废弃映射DEPRECATED_TO_CORE例如Mode.FUNCTIONS、Mode.TOOLS_STRICT统一迁移到Mode.TOOLSANTHROPIC_*系列也逐步收敛到通用模式。生产级特性一自动重试抽取最怕模型返回了不满足约束的 JSON。Instructor 的做法是校验失败时把错误信息回填给模型自动发起下一次请求。README 的示例from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int field_validator(age) def validate_age(cls, v): if v 0: raise ValueError(Age must be positive) return v # Instructor automatically retries when validation fails user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], max_retries3, )底层实现registry 处理器 tenacity重试逻辑位于 instructor/v2/core/retry.py要点如下max_retries默认值为3见 instructor/v2/core/client.py 中create系列方法签名内部使用tenacity的Retrying/AsyncRetryingmax_retries为整数时映射为stop_after_attempt(max_retries 1)并可叠加stop_after_delay(timeout)也可直接传入Retrying/AsyncRetrying实例完全自定义重试策略只有_RETRYABLE_PARSE_ERRORSValidationError、JSONDecodeError、AsyncValidationError、ResponseParsingError才触发重试instructor/v2/core/retry.py每次失败后调用 registry 的reask_handler把错误信息写回kwargs即reask机制然后基于修正后的参数重发请求重试期间自动聚合 token 用量_usage_snapshot/update_total_usage并在尝试耗尽时抛出携带failed_attempts、messages、create_kwargs的InstructorRetryException便于上层诊断还支持token_budget预算控制累计 token 超限会立即终止重试并抛出TokenBudgetErrorinstructor/v2/core/budget.py。Pydantic 的字段校验器field_validator、模型校验器乃至跨字段约束都可以直接用于驱动 reask相关机制在 docs/concepts/validation.md 与 docs/concepts/reask_validation.md 有系统讲解仓库测试 tests/v2/test_retry_runtime.py 则验证了重试流程与预算控制的行为。生产级特性二流式输出 Partial长输出场景下用户希望边生成边看到结果。Instructor 提供Partial[T]包装器字段在未填满前为None随流式推进逐步补全from instructor import Partial for partial_user in client.chat.completions.create( response_modelPartial[User], messages[{role: user, content: ...}], streamTrue, ): print(partial_user) # User(nameNone, ageNone) # User(nameJohn, ageNone) # User(nameJohn, age25)实现原理基于 JSON 完整度的部分校验Partial[T]定义在 instructor/v2/dsl/partial.py底层先把模型字段全部转成可选MakeFieldsOptional配合jiter的partial_mode解析不完整 JSON关键创新是completeness-based validationinstructor/v2/dsl/partial.py用JsonCompleteness追踪 JSON 是否闭合——JSON 不完整时跳过校验、用model_construct构建部分对象JSON 一旦完整闭合立刻按原始模型做全量校验因此Literal、Enum等严格类型在流式过程中不会被误报错误旧方案需要PartialLiteralMixin如今已标记废弃见 instructor/v2/dsl/partial.py自引用模型如树结构通过ContextVar隔离的处理集合避免无限递归instructor/v2/dsl/partial.py。流式还支持嵌套结构、列表与异步生成器可参考 docs/concepts/partial.md、docs/learning/streaming/basics.md 以及测试 tests/v2/test_iterable_streaming.py、tests/dsl/test_partial.py。生产级特性三嵌套对象结构化抽取的价值在复杂场景尤为明显。README 展示了多级嵌套模型from typing import List class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: List[Address] # Instructor handles nested objects automatically user client.chat.completions.create( response_modelUser, messages[{role: user, content: ...}], )模型嵌套、List[T]容器、Optional字段、枚举与 Union 等 Pydantic 类型能力均被 Instructor 完整保留。schema 生成逻辑位于 instructor/v2/core/schema.py按提供商分别产出generate_openai_schema/generate_anthropic_schema/generate_gemini_schema三种格式再由各 provider 的处理器组装进请求。仓库中的真实用例非常多例如 examples/knowledge-graph/run.py 抽取多跳知识图谱、examples/query_planner_execution/query_planner_execution.py 抽取执行计划、examples/resolving-complex-entities/run.py 处理复杂实体消解均可直接复制改造。实战参考从仓库示例开始一个完整的抽取脚本仓库 examples/simple-extraction/user.py 给出了一个可运行的完整示例含可选字段与输出序列化import instructor from openai import OpenAI from pydantic import BaseModel, Field from typing import Optional client instructor.from_openai(OpenAI()) class UserDetail(BaseModel): age: int name: str role: Optional[str] Field(defaultNone) def get_user_detail(string) - UserDetail: return client.chat.completions.create( modelgpt-4o-mini, response_modelUserDetail, messages[ { role: user, content: fGet user details for {string}, }, ], ) # type: ignore user get_user_detail(Jason is 25 years old) print(user.model_dump_json(indent2)) # { # age: 25, # name: Jason, # role: null # }注意两点返回对象可以直接调用 Pydantic 的model_dump_json()等序列化方法该示例文件也揭示了一个常见陷阱当输入文本与目标实体无关时如User not found模型仍可能幻觉出一个符合 schema 的默认结果——这正是需要结合 Pydantic 校验、llm_validator或领域约束做二次把关的场景参考 examples/validators/ 与 instructor/v2/validation/llm_validators.py。更多抄作业入口入门三件套docs/getting-started.md、docs/installation.md、docs/concepts/usage.md概念手册docs/concepts/index.md覆盖重试、校验、部分、迭代、Maybe、并行、多模态、缓存等示例大全docs/examples/examples.md 与 examples/ 下的几十个可直接运行脚本分类、批量、批处理 API、流式、评测、知识图谱、PII、SQL 安全生成等各提供商集成指南docs/integrations/index.md。多语言生态README 指出 Instructor 的简单 API 已被移植到多种语言Python原始实现、TypeScript、Ruby、Go、Elixir、Rust。仓库内另有 docs/start-here.md 与 docs/repository-overview.md 对项目结构与学习路线做了整体梳理。与其他方案的取舍README 给出了三组对比视角供选型参考对比裸 JSON 模式Instructor 自动完成校验、重试、流式与嵌套对象支持无需手写 schema对比 LangChain / LlamaIndexInstructor 专注结构化抽取这一件事更轻量、更易调试对比自研方案项目经历大量开发者打磨覆盖了诸多你没预料到的边界情况。核心取舍原则始终是需要 Agent 编排、工具调用、评测与追踪这类运行时能力时考虑 PydanticAI两者共享 Pydantic 模型需要最简 schema-first 抽取流程时Instructor 是直接的答案。贡献与开源协议Instructor 欢迎社区贡献README 中指向 good first issues 入口并以 MIT 协议开源详见仓库根目录 LICENSE。贡献流程与开发规范可参考 CONTRIBUTING.md、docs/contributing.md 与 AGENT.md。README 同时自述该项目已被大量开发者与公司在生产环境中使用仓库以 CHANGELOG.md 持续记录演进具体数据请以官方发布渠道为准。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考