Instructor 结构化输出校验实战用 Pydantic 与自动重试保证 LLM 数据质量【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本篇技术指南围绕 Instructor 的验证Validation体系展开讲解如何让 GPT-4、Claude、Gemini 等模型输出满足业务约束的结构化数据从基础类型校验、字段约束到自动重试Reask机制、自定义校验器与错误处理。读完本文你将掌握一套从模型生成到数据入库之间可靠的质量关卡并能直接在项目中落地可复用的验证代码。为什么 LLM 输出校验如此关键大模型本质上是概率系统即使使用了函数调用或 JSON 模式其输出仍然可能缺字段、类型错乱、数值越界甚至一本正经地编造不符合业务规则的内容。在将结构化数据送入下游系统之前校验承担着三重职责数据完整性Data IntegrityLLM 输出包含所有必需字段且格式正确业务合规Business Compliance抽取结果满足领域规则与约束如年龄下限、价格为正生产可靠性Production Reliability响应在进入系统前达到质量门槛而不是把脏数据流进数据库再补救。Instructor 把这条质量流水线内建在了client.create()的调用链中其校验流程可以概括为┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ LLM │ - │ Instructor │ - │ Validated │ │ Generates │ │ Validates │ │ Structured │ │ Response │ │ Structure │ │ Data │ └─────────────┘ └──────────────┘ └─────────────┘ │ │ If validation fails ▼ ┌─────────────┐ │ Retry with │ │ Feedback │ └─────────────┘基础校验示例定义模型自动验证Instructor 的核心思想是响应模型即校验规则你定义一个 Pydantic 模型response_model参数同时承担 JSON Schema 生成、类型检查与约束校验三重职责。from pydantic import BaseModel, Field import instructor # 为 LLM 抽取定义校验规则 class UserProfile(BaseModel): name: str age: int Field(ge13, descriptionUsers age in years) # 抽取并校验 LLM 输出 client instructor.from_provider(openai/gpt-5-nano) response client.create( modelgpt-5.4-mini, # 同样适用于 GPT-4、Claude、Gemini messages[ {role: user, content: My name is Jane Smith and Im 25 years old.} ], response_modelUserProfile # 自动校验 ) print(fUser: {response.name}, Age: {response.age})这个示例背后发生了三件事也正是本教程的三个关键特性约束校验Constraint Validationage必须 ≥ 13 岁低于此值直接判定失败自动重试Automatic Retry一旦 LLM 输出未通过校验Instructor 会把错误信息拼回上下文让模型带着反馈重新生成类型安全Type Safety保证 LLM 返回正确的数据类型如age一定是整数而非字符串或空值。常用校验规则速查表在写业务模型时下面这张表覆盖了绝大多数基础校验需求校验示例作用类型检查age: int确保值是整数必填字段name: str字段必须存在可选字段middle_name: Optional[str] None字段可以缺失最小值age: int Field(ge18)值必须 ≥ 18最大值rating: float Field(le5.0)值必须 ≤ 5.0字符串长度username: str Field(min_length3)字符串至少 3 个字符更完整的字段约束能力如pattern正则、max_length、gt/lt等可参考 字段概念文档Field()内的description建议始终填写它会进入发送给 LLM 的 JSON Schema帮助模型更准确地生成。校验流水线的五步工作原理Instructor 的 LLM 校验管线由 重试实现 承载其执行流程可拆解为五步LLM 生成LLM Generation模型按响应模型对应的 Schema 产出结构化输出Schema 匹配Schema MatchingInstructor 将 LLM 响应映射到你的 Pydantic 模型校验检查Validation CheckPydantic 依据约束对数据进行验证智能重试Smart Retry失败时错误信息连同上下文一起回传给 LLM 让其修正成功或超限Success or Timeout直到产出合法输出或耗尽重试次数抛出异常。从源码看retry_sync_v2/retry_async_v2见 instructor/v2/core/retry.py中定义了一个可重试异常集合涵盖 Pydantic 的ValidationError、json.JSONDecodeError、ResponseParsingError等只要解析或校验抛出的错误属于这些类型就通过handlers.reask_handler把异常信息注入下一次请求的 kwargs 并继续循环循环次数由max_retries 1决定stop_after_attempt(max(max_retries, 0) 1)即初始请求加max_retries次重试。用自定义错误消息引导 LLM 修正重试的价值取决于反馈质量。默认情况下Instructor 会把 Pydantic 的原始错误文本回传更专业的做法是利用json_schema_extra中的error_msg为每个字段定制一条面向 LLM 的、可读性强的错误消息from pydantic import BaseModel, Field class Product(BaseModel): name: str price: float Field( gt0, descriptionProduct price in USD, json_schema_extra{error_msg: Price must be greater than zero} )当price校验失败时这条自定义消息会作为修正指令出现在重试请求中让模型明确知道哪里错了、应该怎么改而不是面对一长串难以理解的 Pydantic 内部报错。关于错误消息如何被拼接到重试上下文中可参考 Reask 验证概念文档 中给出的内部消息组装逻辑kwargs[messages].append(response.choices[0].message) kwargs[messages].append( { role: user, content: fPlease correct the function call; errors encountered:\n{e}, } )进阶代码校验 vs LLM 语义校验代码级校验Rule-basedPydantic 的field_validator/model_validator适合表达客观、可程序化的规则from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int field_validator(age) classmethod def validate_age(cls, v): if v 0: raise ValueError(Age cannot be negative) return v校验器抛出ValueError即可让整个模型实例化失败Instructor 会捕获该异常进入重试循环。多字段联动的规则如离职日期不得早于入职日期可参考 自定义校验器教程 中的model_validator(modeafter)写法字段级与模型级校验的完整用法见 字段级校验教程。LLM 语义校验Semantic Validation当规则主观、需要语义理解时如内容合规、语气审查使用llm_validator让另一个 LLM 充当校验器from typing import Annotated from pydantic import BaseModel, BeforeValidator import instructor from instructor import llm_validator client instructor.from_provider(openai/gpt-4.1-mini) class ContentReview(BaseModel): title: str content: Annotated[ str, BeforeValidator( llm_validator( Content must be family-friendly and not contain profanity, clientclient, ) ), ]llm_validator生成的错误消息由 LLM 生成而非代码写死因此对重试环节更具指导性。它特别适合主观标准风格、语气、得体性、上下文依赖元素间关系、难以程序化表达的多因素联合判断。注意语义校验会额外产生 API 调用与延迟应仅用于高价值校验点简单的客观约束请交给普通校验器。完整模式见 语义校验概念文档。重试机制的配置与失败处理配置重试参数在初始化客户端或调用create时可通过参数控制重试行为import instructor client instructor.from_provider( openai/gpt-4o, max_retries3, # 最大重试次数 retry_if_parsing_failsTrue, # JSON 解析失败时重试 throw_errorTrue # 全部重试失败后抛出异常 )选项说明默认值max_retries最大重试次数总尝试次数为 max_retries 10retry_if_parsing_failsJSON 解析失败时是否重试Truethrow_error所有重试失败后是否抛出异常True重试参数既可以在from_provider初始化时统一设置也可以在每次create()调用时按需覆盖例如给简单任务设置max_retries0给高价值任务设置max_retries3。捕获重试失败当所有重试都失败时Instructor 抛出InstructorRetryException其中包含每次尝试的详细信息详见 异常定义 中的FailedAttempt与InstructorRetryExceptionfrom instructor.core.exceptions import InstructorRetryException try: response client.create( modelgpt-5.4-mini, messages[{role: user, content: Product: Invalid data}], response_modelProduct, max_retries3 ) except InstructorRetryException as e: print(fFailed after {e.n_attempts} attempts) print(fTotal usage: {e.total_usage}) # 查看每次失败尝试的细节 for attempt in e.failed_attempts: print(fAttempt {attempt.attempt_number}: {attempt.exception}) if attempt.completion: print(fRaw response: {attempt.completion})InstructorRetryException提供的关键信息包括failed_attemptsFailedAttempt列表每项含attempt_number重试序号、exception具体异常、completion失败的原始 LLM 响应n_attempts总尝试次数total_usage所有尝试累计的 token 消耗last_completion最后一次失败的响应messages完整对话历史便于复盘。注意仓库中 instructor/exceptions.py 已标记为 deprecated官方建议从instructor.core即from instructor.core.exceptions import ...导入异常类型。此外从源码看instructor/v2/core/retry.py当前重试还支持token_budget累计 token 预算控制超过预算会抛出TokenBudgetError适合为反复重试导致账单失控的场景设置硬性上限。更多回退策略见 错误处理概念文档。重试期间的反馈消息重试时发送给 LLM 的反馈大致长这样帮助模型明确修复目标The following errors occurred during validation: - price: ensure this value is greater than 0 - name: Product name must be at least 3 characters Please fix these errors and ensure the response is valid.重试的局限成本与延迟每次重试都会消耗 token 和等待时间顽固错误某些校验失败如要求模型输出原文中不存在的引用模型可能始终无法修正模型能力边界部分模型在特定校验上会持续失败此时应降低约束强度或换用更强的模型。业务场景这些校验规则如何落地年龄核验age: int Field(ge13, le120)确保抽取的年龄落在合法区间价格校验price: float Field(gt0)杜绝负价格进入订单系统邮箱格式email: str Field(patternr^[a-zA-Z0-9._%-][a-zA-Z0-9.-]\.[a-zA-Z]{2,}$)日期约束model_validator校验入住/退房日期的先后关系业务规则通过field_validator/ 上下文注入实现领域专属约束。其中日期先后房间类型与入住人数联动这类跨字段校验的完整示例见 字段级校验教程而抽取出的引文必须逐字出现在源文本中这种强上下文校验可通过context参数 ValidationInfo实现参考 Reask 验证概念文档 中的QuoteExtraction示例与 精确引文示例。校验最佳实践从简开始先做基础类型校验再逐步叠加复杂规则避免一开始就把 Schema 塞满约束导致模型频繁失败善用类型注解为每个字段明确类型让 Pydantic 与 LLM 都心里有数给约束写文档Field(description...)会进入发送给模型的 Schema显著提升一次通过率选对校验类型客观标准用规则校验零成本主观/上下文标准用语义校验有成本正确处理错误生产环境务必捕获InstructorRetryException并对ValidationError建立监控告警评估重试成本语义校验涉及额外 LLM 调用谨慎用于高频低价值路径控制 token 消耗如需精简错误消息可使用 instructor/utils/core.py 中的disable_pydantic_error_url()通过设置PYDANTIC_ERRORS_INCLUDE_URL0移除 Pydantic 错误消息末尾的文档链接从而减少重试时占用的 token。继续深入自定义校验器教程构建针对 LLM 输出的复杂校验逻辑多字段联动、数据清洗、外部服务校验重试机制教程配置 Instructor 如何处理校验失败含渐进式校验进阶模式字段级校验教程为 LLM 响应中的单个字段定义专属规则验证概念文档校验流程总览、异步校验器限制、嵌套校验与最佳实践语义校验概念文档基于 LLM 的语义校验模式。掌握这些校验手段你的 LLM 应用就能把模型偶尔出错从隐患变成可控流程——让每一次进入系统的结构化数据都经过质量关卡从而真正达到生产级可靠。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Instructor 结构化输出校验实战用 Pydantic 与自动重试保证 LLM 数据质量【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本篇技术指南围绕 Instructor 的验证Validation体系展开讲解如何让 GPT-4、Claude、Gemini 等模型输出满足业务约束的结构化数据从基础类型校验、字段约束到自动重试Reask机制、自定义校验器与错误处理。读完本文你将掌握一套从模型生成到数据入库之间可靠的质量关卡并能直接在项目中落地可复用的验证代码。为什么 LLM 输出校验如此关键大模型本质上是概率系统即使使用了函数调用或 JSON 模式其输出仍然可能缺字段、类型错乱、数值越界甚至一本正经地编造不符合业务规则的内容。在将结构化数据送入下游系统之前校验承担着三重职责数据完整性Data IntegrityLLM 输出包含所有必需字段且格式正确业务合规Business Compliance抽取结果满足领域规则与约束如年龄下限、价格为正生产可靠性Production Reliability响应在进入系统前达到质量门槛而不是把脏数据流进数据库再补救。Instructor 把这条质量流水线内建在了client.create()的调用链中其校验流程可以概括为┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ LLM │ - │ Instructor │ - │ Validated │ │ Generates │ │ Validates │ │ Structured │ │ Response │ │ Structure │ │ Data │ └─────────────┘ └──────────────┘ └─────────────┘ │ │ If validation fails ▼ ┌─────────────┐ │ Retry with │ │ Feedback │ └─────────────┘基础校验示例定义模型自动验证Instructor 的核心思想是响应模型即校验规则你定义一个 Pydantic 模型response_model参数同时承担 JSON Schema 生成、类型检查与约束校验三重职责。from pydantic import BaseModel, Field import instructor # 为 LLM 抽取定义校验规则 class UserProfile(BaseModel): name: str age: int Field(ge13, descriptionUsers age in years) # 抽取并校验 LLM 输出 client instructor.from_provider(openai/gpt-5-nano) response client.create( modelgpt-5.4-mini, # 同样适用于 GPT-4、Claude、Gemini messages[ {role: user, content: My name is Jane Smith and Im 25 years old.} ], response_modelUserProfile # 自动校验 ) print(fUser: {response.name}, Age: {response.age})这个示例背后发生了三件事也正是本教程的三个关键特性约束校验Constraint Validationage必须 ≥ 13 岁低于此值直接判定失败自动重试Automatic Retry一旦 LLM 输出未通过校验Instructor 会把错误信息拼回上下文让模型带着反馈重新生成类型安全Type Safety保证 LLM 返回正确的数据类型如age一定是整数而非字符串或空值。常用校验规则速查表在写业务模型时下面这张表覆盖了绝大多数基础校验需求校验示例作用类型检查age: int确保值是整数必填字段name: str字段必须存在可选字段middle_name: Optional[str] None字段可以缺失最小值age: int Field(ge18)值必须 ≥ 18最大值rating: float Field(le5.0)值必须 ≤ 5.0字符串长度username: str Field(min_length3)字符串至少 3 个字符更完整的字段约束能力如pattern正则、max_length、gt/lt等可参考 字段概念文档Field()内的description建议始终填写它会进入发送给 LLM 的 JSON Schema帮助模型更准确地生成。校验流水线的五步工作原理Instructor 的 LLM 校验管线由 重试实现 承载其执行流程可拆解为五步LLM 生成LLM Generation模型按响应模型对应的 Schema 产出结构化输出Schema 匹配Schema MatchingInstructor 将 LLM 响应映射到你的 Pydantic 模型校验检查Validation CheckPydantic 依据约束对数据进行验证智能重试Smart Retry失败时错误信息连同上下文一起回传给 LLM 让其修正成功或超限Success or Timeout直到产出合法输出或耗尽重试次数抛出异常。从源码看retry_sync_v2/retry_async_v2见 instructor/v2/core/retry.py中定义了一个可重试异常集合涵盖 Pydantic 的ValidationError、json.JSONDecodeError、ResponseParsingError等只要解析或校验抛出的错误属于这些类型就通过handlers.reask_handler把异常信息注入下一次请求的 kwargs 并继续循环循环次数由max_retries 1决定stop_after_attempt(max(max_retries, 0) 1)即初始请求加max_retries次重试。用自定义错误消息引导 LLM 修正重试的价值取决于反馈质量。默认情况下Instructor 会把 Pydantic 的原始错误文本回传更专业的做法是利用json_schema_extra中的error_msg为每个字段定制一条面向 LLM 的、可读性强的错误消息from pydantic import BaseModel, Field class Product(BaseModel): name: str price: float Field( gt0, descriptionProduct price in USD, json_schema_extra{error_msg: Price must be greater than zero} )当price校验失败时这条自定义消息会作为修正指令出现在重试请求中让模型明确知道哪里错了、应该怎么改而不是面对一长串难以理解的 Pydantic 内部报错。关于错误消息如何被拼接到重试上下文中可参考 Reask 验证概念文档 中给出的内部消息组装逻辑kwargs[messages].append(response.choices[0].message) kwargs[messages].append( { role: user, content: fPlease correct the function call; errors encountered:\n{e}, } )进阶代码校验 vs LLM 语义校验代码级校验Rule-basedPydantic 的field_validator/model_validator适合表达客观、可程序化的规则from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int field_validator(age) classmethod def validate_age(cls, v): if v 0: raise ValueError(Age cannot be negative) return v校验器抛出ValueError即可让整个模型实例化失败Instructor 会捕获该异常进入重试循环。多字段联动的规则如离职日期不得早于入职日期可参考 自定义校验器教程 中的model_validator(modeafter)写法字段级与模型级校验的完整用法见 字段级校验教程。LLM 语义校验Semantic Validation当规则主观、需要语义理解时如内容合规、语气审查使用llm_validator让另一个 LLM 充当校验器from typing import Annotated from pydantic import BaseModel, BeforeValidator import instructor from instructor import llm_validator client instructor.from_provider(openai/gpt-4.1-mini) class ContentReview(BaseModel): title: str content: Annotated[ str, BeforeValidator( llm_validator( Content must be family-friendly and not contain profanity, clientclient, ) ), ]llm_validator生成的错误消息由 LLM 生成而非代码写死因此对重试环节更具指导性。它特别适合主观标准风格、语气、得体性、上下文依赖元素间关系、难以程序化表达的多因素联合判断。注意语义校验会额外产生 API 调用与延迟应仅用于高价值校验点简单的客观约束请交给普通校验器。完整模式见 语义校验概念文档。重试机制的配置与失败处理配置重试参数在初始化客户端或调用create时可通过参数控制重试行为import instructor client instructor.from_provider( openai/gpt-4o, max_retries3, # 最大重试次数 retry_if_parsing_failsTrue, # JSON 解析失败时重试 throw_errorTrue # 全部重试失败后抛出异常 )选项说明默认值max_retries最大重试次数总尝试次数为 max_retries 10retry_if_parsing_failsJSON 解析失败时是否重试Truethrow_error所有重试失败后是否抛出异常True重试参数既可以在from_provider初始化时统一设置也可以在每次create()调用时按需覆盖例如给简单任务设置max_retries0给高价值任务设置max_retries3。捕获重试失败当所有重试都失败时Instructor 抛出InstructorRetryException其中包含每次尝试的详细信息详见 异常定义 中的FailedAttempt与InstructorRetryExceptionfrom instructor.core.exceptions import InstructorRetryException try: response client.create( modelgpt-5.4-mini, messages[{role: user, content: Product: Invalid data}], response_modelProduct, max_retries3 ) except InstructorRetryException as e: print(fFailed after {e.n_attempts} attempts) print(fTotal usage: {e.total_usage}) # 查看每次失败尝试的细节 for attempt in e.failed_attempts: print(fAttempt {attempt.attempt_number}: {attempt.exception}) if attempt.completion: print(fRaw response: {attempt.completion})InstructorRetryException提供的关键信息包括failed_attemptsFailedAttempt列表每项含attempt_number重试序号、exception具体异常、completion失败的原始 LLM 响应n_attempts总尝试次数total_usage所有尝试累计的 token 消耗last_completion最后一次失败的响应messages完整对话历史便于复盘。注意仓库中 instructor/exceptions.py 已标记为 deprecated官方建议从instructor.core即from instructor.core.exceptions import ...导入异常类型。此外从源码看instructor/v2/core/retry.py当前重试还支持token_budget累计 token 预算控制超过预算会抛出TokenBudgetError适合为反复重试导致账单失控的场景设置硬性上限。更多回退策略见 错误处理概念文档。重试期间的反馈消息重试时发送给 LLM 的反馈大致长这样帮助模型明确修复目标The following errors occurred during validation: - price: ensure this value is greater than 0 - name: Product name must be at least 3 characters Please fix these errors and ensure the response is valid.重试的局限成本与延迟每次重试都会消耗 token 和等待时间顽固错误某些校验失败如要求模型输出原文中不存在的引用模型可能始终无法修正模型能力边界部分模型在特定校验上会持续失败此时应降低约束强度或换用更强的模型。业务场景这些校验规则如何落地年龄核验age: int Field(ge13, le120)确保抽取的年龄落在合法区间价格校验price: float Field(gt0)杜绝负价格进入订单系统邮箱格式email: str Field(patternr^[a-zA-Z0-9._%-][a-zA-Z0-9.-]\.[a-zA-Z]{2,}$)日期约束model_validator校验入住/退房日期的先后关系业务规则通过field_validator/ 上下文注入实现领域专属约束。其中日期先后房间类型与入住人数联动这类跨字段校验的完整示例见 字段级校验教程而抽取出的引文必须逐字出现在源文本中这种强上下文校验可通过context参数 ValidationInfo实现参考 Reask 验证概念文档 中的QuoteExtraction示例与 精确引文示例。校验最佳实践从简开始先做基础类型校验再逐步叠加复杂规则避免一开始就把 Schema 塞满约束导致模型频繁失败善用类型注解为每个字段明确类型让 Pydantic 与 LLM 都心里有数给约束写文档Field(description...)会进入发送给模型的 Schema显著提升一次通过率选对校验类型客观标准用规则校验零成本主观/上下文标准用语义校验有成本正确处理错误生产环境务必捕获InstructorRetryException并对ValidationError建立监控告警评估重试成本语义校验涉及额外 LLM 调用谨慎用于高频低价值路径控制 token 消耗如需精简错误消息可使用 instructor/utils/core.py 中的disable_pydantic_error_url()通过设置PYDANTIC_ERRORS_INCLUDE_URL0移除 Pydantic 错误消息末尾的文档链接从而减少重试时占用的 token。继续深入自定义校验器教程构建针对 LLM 输出的复杂校验逻辑多字段联动、数据清洗、外部服务校验重试机制教程配置 Instructor 如何处理校验失败含渐进式校验进阶模式字段级校验教程为 LLM 响应中的单个字段定义专属规则验证概念文档校验流程总览、异步校验器限制、嵌套校验与最佳实践语义校验概念文档基于 LLM 的语义校验模式。掌握这些校验手段你的 LLM 应用就能把模型偶尔出错从隐患变成可控流程——让每一次进入系统的结构化数据都经过质量关卡从而真正达到生产级可靠。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
