Instructor v2 架构重构全解析从共享模块到 Provider 自持的注册表体系【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorInstructor 的核心目标始终如一为 LLM 提供结构化输出——定义 Pydantic 模型、创建 provider 客户端、请求结构化结果、收获校验过的 Python 对象。v2 是 Instructor 的一次大规模内部重写其公开目标刻意保守让老用户感觉不到陌生同时让库更容易扩展、更容易推理、更容易做类型检查。本文以docs/blog/posts/whats-new-in-v2.md为骨架结合 instructor/v2 目录下的真实源码与测试逐层拆解 v2 的五大变化、注册表分发机制、重试/Reask 的模块化拆分以及兼容性迁移的完整路径。读完你将掌握 v2 的内部心智模型、Provider 自持架构的落地方式以及新增 Provider 的标准操作流程。一句话看懂 V2V2 改变了五件事Provider 专属行为归 Provider 所有请求格式化、响应解析、Reask 逻辑不再散落在共享模块里而是随 provider 一起存放。运行时分发走注册表以(Provider, Mode)为键查找 handler取代单一大型共享路径中的条件分支。旧公开模块保留为兼容门面instructor/core、instructor/processing、instructor/dsl、instructor/validation等旧导入路径继续可用真实运行行为迁至instructor/v2。Provider 能力来自单一清单别名、handler 模块、支持/不支持的模式、旧模式归一化、公开工厂绑定、可选 SDK 要求全部记录在一个 manifest 中不再在路由与测试间重复维护。同步/异步/流式/Partial/公开返回类型的校验更加一致类型推断更可信更易于直接测试。用户视角熟悉的用法保持不变v2 的核心用法仍然是 Instructor 用户熟悉的模式import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int client instructor.from_provider(openai/gpt-5-nano) user client.create( messages[{role: user, content: Extract Jason, age 36.}], response_modelUser, )这是整个库的心脏定义一个 Pydantic 模型创建一个 provider 支撑的 Instructor 客户端请求结构化输出收获校验过的 Python 对象V2 被刻意设计为重试retries、Partial、Iterable、多模态输入、provider 专属的客户端工厂这些既有概念仍然可识别而不是被整体替换。from_provider仍是统一的公开路由入口位于 instructor/v2/auto_client.py接受provider/model-name格式的模型字符串并通过async_client参数决定返回同步的Instructor还是异步的AsyncInstructor其返回类型通过overload精确声明。引擎盖之下五大架构变化1. Provider 现在拥有自己的行为在 v1 中provider 专属的请求格式化、响应解析和 Reask 逻辑可能散布在共享模块的各个角落。增加一个 provider 往往意味着要在响应解析、重试逻辑、多模态处理、模式归一化和客户端搭建等若干互不相关的位置同时动刀。在 v2 中这些逻辑统一放在instructor/v2/providers/provider/一个 provider 包可以拥有客户端工厂client factories请求准备request preparation响应解析response parsing校验重试validation reasks流式抽取streaming extraction模板化templating多模态编码multimodal encodingusage 处理usage handling以 Anthropic 为例instructor/v2/providers/anthropic/ 目录下同时包含client.pyfrom_anthropic工厂与handlers.pyTOOLS / JSON / JSON_SCHEMA / PARALLEL_TOOLS 各模式的 handler 实现。AnthropicHandlerBase继承自共享的ModeHandler抽象基类四个具体 handler 分别以register_mode_handler装饰器注册。这给每个 provider 一个明确的家避免共享运行时模块慢慢变成巨大的 provider 交换机。2. 模式通过注册的 handler 分发V2 引入了一个以 provider 和 mode 为键的注册表。运行时不再走一条庞大的共享路径而是询问handlers mode_registry.get_handlers(provider, mode)这些 handler 定义了如何准备 provider 请求解析响应在校验失败后构建 Reask需要时抽取流式分片注册表的真实实现位于 instructor/v2/core/registry.pyModeRegistry内部用dict[tuple[Provider, Mode], ModeHandlers]存储 handler 集合同时维护一份_lazy_loaders字典支持惰性加载——首次访问某个(Provider, Mode)时才__import__对应 handler 模块保证导入 Instructor 时不会急切加载全部 provider SDK。每次 lookup 是 O(1) 的字典查找get_handlers一次取回全部 handlerrequest_handler、reask_handler、response_parser以及可选的stream_extractor、stream_extractor_async、message_converter、template_handler比逐个取更高效。注册表还提供查询 APIget_modes_for_provider(provider)、is_registered(provider, mode)、list_modes()、get_handler_class(provider, mode)并内置线程锁保护惰性加载的并发首次调用。全局单例mode_registry在模块导入时即通过_register_default_lazy_handlers()依据HANDLER_SPECS预注册所有内置 provider 的惰性加载器。3. 重试与 Reask 逻辑重新模块化Instructor 会重试失败的校验。这个行为至关重要但并非所有 provider 都想要同样的重试载荷。V2 把通用重试循环保留在共享运行时中而把provider 专属的 Reask 格式化移交给所属 provider 的 handler。正确的分工是共享编排保持共享线上格式wire-format行为保持本地化这对那些后续消息、工具载荷或结构化输出约定存在细微但重要差异的 provider 尤为关键。源码证据在 instructor/v2/core/retry.pyretry_sync_v2/retry_async_v2负责整体循环——用 tenacity 构建Retrying/AsyncRetrying实例stop_after_attempt(max_retries 1)可叠加timeout对应的stop_after_delay对ValidationError、JSONDecodeError、ResponseParsingError等可重试错误逐次调用 API、解析、失败时记录FailedAttempt然后调用注册表中的handlers.reask_handler(kwargs, response, exception)生成下一次请求的载荷耗尽尝试后抛出携带完整上下文的InstructorRetryException。整个循环不关心任何 provider 的线上格式——它只向 handler 要「下一次怎么改」。4. 兼容性是刻意设计的面对如此大范围的迁移升级阵痛是最现实的担忧。V2 走了相反的路线兼容性是显式的。旧公开模块例如instructor/core instructor/processing instructor/dsl instructor/validation在用户仍需要这些导入的地方保留为薄兼容门面thin compatibility facades真正的运行时行为迁至instructor/v2之下。这同时带来两个有用的性质既有导入路径尽可能继续可用新的实现工作有一个清晰的家同一思路也适用于旧模式。旧的 provider 专属模式名可以被归一化进更小的核心模式系统在保留行为的同时缩小长期维护面。归一化逻辑在 instructor/v2/core/registry.py 的normalize_mode中实现读取PROVIDER_SPECS[provider].legacy_modes把旧模式映射到核心模式若发生替换则通过Mode.warn_deprecated_mode发出一次性弃用警告。instructor/v2/core/mode.py 的DEPRECATED_TO_CORE表完整记录了映射关系例如ANTHROPIC_TOOLS - TOOLS、GEMINI_JSON - MD_JSON、PERPLEXITY_JSON - MD_JSON、FUNCTIONS - TOOLS、JSON_O1 - JSON_SCHEMA等并声明这些旧模式将在 v3.0 移除。5. Provider 能力来自单一 manifestV2 增加了一个 provider 规格层记录provider 别名aliaseshandler 模块handler modules支持的模式supported modes不支持的模式unsupported modes旧模式归一化legacy mode normalization公开工厂绑定public factory bindings可选 SDK 要求optional SDK requirements这一清单成为理解某个 provider 支持什么能力的唯一入口同时驱动测试与运行时接线从而减少重复列表、减少支持声明漂移的可能。实现位于 instructor/v2/core/provider_specs.pyProviderSpec是一个 frozen dataclass字段包括aliases、handler_module、supported_modes、unsupported_modes、legacy_modes、from_function、client_module、sdk_module、provider_string、basic_modes、async_modes等。PROVIDER_SPECS覆盖了 OpenAI、OpenAI 兼容系Anyscale、Together、Databricks、DeepSeek、OpenRouter、Anthropic、GenAI、Gemini、Cohere、Perplexity、xAI、Groq、Mistral、Fireworks、Cerebras、Writer、Bedrock、VertexAI、Azure OpenAI、Ollama、LiteLLM 等。由此派生的ALIAS_TO_PROVIDER别名 - Provider、PUBLIC_FACTORY_ATTRS工厂名 - 客户端模块与函数和HANDLER_SPECShandler 模块 - 支持模式全部由同一份 manifest 计算得出从结构上杜绝了「两处维护、一处过时」的问题。源码级调用链一次 create 请求的完整旅程把 v2 的五个变化串起来一次client.create(response_model...)的实际执行路径如下同步版异步版流程一致仅调用retry_async_v2Client.create() with response_model ↓ patch_v2() [注册表模式校验 同步/异步自动识别] ↓ new_create_sync() ├─ reject_async_validators / _validate_token_budget [参数与预算校验] ├─ 注入 default_model若未提供且可用 ├─ mode_registry.get_handlers(provider, mode) [注册表查找] ├─ handlers.request_handler(response_model, kwargs) [请求准备response_model - provider 格式] ├─ handlers.message_converter若存在[多模态消息转换] ├─ handle_templating [模板上下文注入] └─ retry_sync_v2() [重试循环] ├─ RegistryValidationMixin.validate_mode_registration() ├─ 每次尝试 │ ├─ 调用原始 API │ ├─ handlers.response_parser(response, response_model, ...) [解析] │ ├─ 成功 - _finalize_parsed_response附加 raw_response / total_usage并返回 │ └─ 失败ValidationError 等: │ ├─ 记录 FailedAttempt、检查 token 预算 │ ├─ handlers.reask_handler(kwargs, response, exception) [生成重试载荷] │ └─ 重试 └─ 超过最大尝试次数 - InstructorRetryException对应源码模式校验与包装逻辑在 instructor/v2/core/patch.py 的patch_v2通过is_async(func)自动识别同步/异步分别生成_create_sync_wrapper/_create_async_wrapper重试循环在 instructor/v2/core/retry.py请求准备、解析、Reask 三件套则由注册表返回的ModeHandlers提供。值得注意的实现细节patch_v2在包装时通过uuid4().hex生成每个包装函数的专属cache_scope作为默认cache_namespaceisolate_retry_kwargs会复制 messages 列表避免 Reask handler 的修改泄漏到调用方状态有专门的 tests/v2/test_messages_not_mutated.py 守护这一契约缓存键在重试可能修改请求前一次性计算配合 instructor/v2/core/cache_response.py 支持透明的响应缓存。Handler 系统协议、抽象基类与装饰器V2 的 handler 有两种写法类实现继承ModeHandler抽象基类或独立函数实现协议。核心协议定义在 instructor/v2/core/protocols.pyRequestHandler为某个模式准备请求 kwargsResponseParser把 API 响应解析为 Pydantic 模型ReaskHandler处理校验失败以支持重试StreamExtractor/AsyncStreamExtractor从流式响应中抽取 JSON 分片MessageConverter为 provider 转换多模态消息TemplateHandler向 provider 载荷应用模板上下文ModeHandler抽象基类instructor/v2/core/handler.py提供结构化实现方式典型形态from instructor.v2.core.handler import ModeHandler from pydantic import BaseModel from typing import Any class MyModeHandler(ModeHandler): Handler for a specific mode. def prepare_request( self, response_model: type[BaseModel] | None, kwargs: dict[str, Any], ) - tuple[type[BaseModel] | None, dict[str, Any]]: Prepare request kwargs for this mode. return response_model, kwargs def handle_reask( self, kwargs: dict[str, Any], response: Any, exception: Exception, ) - dict[str, Any]: Handle validation failure and prepare retry. return kwargs def parse_response( self, response: Any, response_model: type[BaseModel], validation_context: dict[str, Any] | None None, strict: bool | None None, ) - BaseModel: Parse API response into validated Pydantic model. return response_model.model_validate(...)注册方式register_mode_handler所有 handler 都必须通过register_mode_handler装饰器注册这是 v2 中唯一受支持的注册方式直接调用mode_registry.register()不被支持。from instructor.v2.core.decorators import register_mode_handler from instructor import Provider, Mode from instructor.v2.core.handler import ModeHandler register_mode_handler(Provider.ANTHROPIC, Mode.TOOLS) class AnthropicToolsHandler(ModeHandler): Handler automatically registered on import. def prepare_request(self, response_model, kwargs): return response_model, kwargs def handle_reask(self, kwargs, response, exception): return kwargs def parse_response(self, response, response_model, **kwargs): return response_model.model_validate(...)其工作原理见 instructor/v2/core/decorators.py装饰器实例化 handler 类优先尝试handler_class(modemode)失败则无参实例化并回填mode然后为每个目标 provider 调用mode_registry.register()把方法映射为协议函数handler.prepare_request→request_handlerhandler.handle_reask→reask_handlerhandler.parse_response→response_parserhandler.extract_streaming_json/extract_streaming_json_async→ 流式抽取器存在时handler.convert_messages→message_converter存在时handler.apply_templates→template_handler存在时好处模块被导入即自动注册无需手动调用、语法声明式、类型安全且同一个 handler 类可注册到多个兼容 provider——这正是 OpenAI 兼容系Anyscale、Together、Databricks、DeepSeek、Groq、Fireworks、Cerebras复用 instructor/v2/providers/openai/handlers.py 的实现方式装饰器的provider参数接受单个 Provider 或 Provider 的可迭代对象。异常体系与错误处理策略V2 异常统一继承自instructor.core.exceptions.InstructorError见 instructor/v2/core/exceptions.py 与 instructor/core/exceptions.pyRegistryError模式未注册或 handler 查找失败ValidationContextErrorcontext与validation_context参数冲突InstructorRetryException超过最大重试次数携带完整尝试上下文last_completion、n_attempts、total_usage、messages、create_kwargs、failed_attemptsRegistryValidationMixin提供内部校验工具patch_v2与retry_*_v2都会在进入实际调用前调用validate_mode_registration实现「fail fast」。错误处理策略可以概括为四点补丁期即做模式校验、context 冲突检测、各阶段带尝试编号的完整日志、异常链保留全部上下文。为什么这样更好新增 Provider 更容易路径清晰了添加 provider spec写入 instructor/v2/core/provider_specs.py 的PROVIDER_SPECS实现 provider handlerinstructor/v2/providers/provider/handlers.py用register_mode_handler装饰接线客户端工厂instructor/v2/providers/provider/client.py用patch_v2包装依赖共享的注册表与重试机制代码库不再要求每个新 provider 把行为穿过互不相关的共享模块。官方文档 instructor/v2/README.md 还提供了从 v1 迁移到 v2 的分步指南、四类常见迁移模式简单 provider、复杂 utils、多 API 函数、流式支持以及完整的迁移检查清单。既有 Provider 更容易做到功能完备流式、Partial、schema 转换、Reask 往往最能暴露一个 provider 集成「浅」的地方。V2 给了这些功能一个 provider 本地化的归宿因此更容易补齐实现而不是在共享工具里留下一个又一个一次性补丁。类型推断更可信v2 迁移还收紧了围绕以下对象的公开类型同步客户端sync clients异步客户端async clients部分流式partial streaming可迭代流式iterable streaming返回补全的辅助函数completion-returning helpersprovider 工厂返回类型这一点很重要因为 Instructor 用户常常依赖 IDE 来理解返回数据的形状。from_provider的overload声明、instructor/v2/core/patch.py 中的InstructorChatCompletionCreate/AsyncInstructorChatCompletionCreate协议、以及响应模型泛型T_Model共同保证了这一点。官方要求公开工厂应从具体客户端类或字面量标志推断同步/异步响应辅助函数应保留调用方的响应模型类型建议优先使用create_iterable()与create_partial()以获得精确的流式推断直接传response_modelIterable[...]/Partial[...]保留为兼容形式。这些保证由 tests/typing/test_public_surface.py 的可执行断言守护。导入保持轻量可选 provider SDK 不应成为所有人的隐性成本。v2 公开面使用惰性导出lazy exports与 provider 本地加载因此导入 Instructor 不会急切地把每个 provider 的依赖都拉进内存——注册表的register_lazy机制正是为此设计首次访问某(Provider, Mode)才导入对应 handler 模块。这对于一个要支持众多 provider、又不想强迫每个用户都进入最大依赖环境的库尤其重要。对贡献者意味着什么主要的习惯转变很简单把 provider 专属行为放进 provider 包让共享运行时模块保持 provider 无关尽量把可复用覆盖加入参数化的 v2 测试只有真正 provider 专属的行为才保留 provider 专属测试测试套件的组织也朝着更小、更可复用的结构推进一套参数化套件覆盖常见客户端行为一套覆盖 handler 注册一套覆盖共享的 provider/mode 分发期望只有行为确实独特时才放置 provider 专属测试文件仓库中的实际落点包括 tests/v2/test_handlers_parametrized.py参数化 handler 注册、tests/v2/test_client_unified.py统一客户端行为、tests/v2/test_provider_modes.pyprovider 模式矩阵、tests/v2/test_registry.py注册表契约等。运行 v2 全部测试只需pytest tests/v2/ -v这些参数化套件减少了重复的 provider 样板集中了共享的客户端与 handler 断言。一个具体的心智模型如果只记一张 v2 的图用这条链public factory - provider spec - provider client - registry lookup by provider mode - request / response / reask handlers - typed Instructor resultV1 让其中许多步骤隐式地工作。V2 保留了面向用户的简洁性但让实现形态清晰可见、可维护。instructor/v2/README.md的模块组织图进一步印证了这一点instructor/v2/ ├── core/ # 协议、注册表、装饰器、patch、retry、异常 │ ├── decorators.py # register_mode_handler │ ├── handler.py # ModeHandler 抽象基类 │ ├── patch.py # 补丁机制 │ ├── protocols.py # RequestHandler 等协议定义 │ ├── registry.py # 模式注册表实现 │ └── retry.py # 同步/异步重试逻辑 └── providers/ ├── anthropic/ # 参考实现client.py handlers.py └── ...这是破坏性变更吗迁移被设计成在可行时保留常见公开工作流与导入路径。这不代表没有代码移动——移动了很多。但迁移刻意围绕以下几点构建兼容门面compatibility facades归一化的旧模式normalized legacy modes保留的工厂名preserved factory names对既有结构化输出工作流的持续支持continued support for existing structured-output workflows主要的破坏性压力点在内部而非用户侧。库在「所有权边界」上更严格了因为那正是让公开 API 长期稳定的关键。从instructor/v2/README.md的迁移清单看OpenAI、Anthropic、GenAI、Gemini、VertexAI、Cohere、Mistral、Groq、Fireworks、Cerebras、Writer、xAI、Perplexity、Bedrock 以及 OpenAI 兼容系Anyscale、Together、Databricks、DeepSeek与 OpenRouter 均已完成 v2 实现剩余 v1 面主要集中在instructor/core/*与instructor/auto_client.py的兼容层。为什么是现在Instructor 已经从以 OpenAI 为中心的结构化输出助手成长为一个覆盖面很广的 provider 工具箱。这种成长是好事但实现需要追上产品表面。V2 就是让下一阶段更健康的清理更容易的 provider 工作更一致的功能对等更好的类型更少的重复路由逻辑更聚焦的测试更轻的导入如果你正考虑为 Instructor 贡献新 provider或想深入理解结构化输出库在「多 provider、多模式」压力下的架构取舍instructor/v2 目录与 instructor/v2/README.md 是继续探索的最佳起点。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考