尧图网站建设 ![Instructor 字段级流式输出实战：用 Partial[T] 实现响应模型的实时增量快照](http://pic.xiahunao.cn/yaotu/Instructor 字段级流式输出实战：用 Partial[T] 实现响应模型的实时增量快照)
Instructor 字段级流式输出实战用 Partial[T] 实现响应模型的实时增量快照【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor结构化输出的最大痛点之一是等待:LLM 必须把整个 JSON 生成完毕,你才能完成一次校验与解析。Instructor 提供的字段级流式输出(Partial Response Streaming)打破了这一限制:它把响应模型拆解为一个个增量快照,每个快照都是当前已生成字段的即时可用对象,非常适合实时渲染 UI 组件、边生成边展示提取结果等场景。本文将基于docs/examples/partial_streaming.md的核心思路,结合仓库源码深入讲解Partial[T]的底层机制、create_partial的完整用法、异步流式与并发场景下的注意事项,让你能直接在生产代码中落地这套模式。字段级流式输出:随着 token 不断流入,响应模型按字段逐步填充,控制台中的对象快照实时更新什么是字段级流式输出传统做法下,我们从模型拿到的是逐 token 的文本增量。以User模型为例:from pydantic import BaseModel class User(BaseModel): name: str age: int如果直接流式接收 JSON,在对象完整返回之前我们无法可靠地解析:{name: Jo {name: John, ag {name: John, age: {name: John, age: 25} # Completed字段级流式的核心变化在于:每个流式快照都是一个可用的 Pydantic 模型实例,已生成的字段被解析为真实值,尚未生成的字段以None占位。上面四段文本对应的快照分别是:{name: Jo User(nameJo, ageNone) {name: John, ag User(nameJohn, ageNone) {name: John, age: User(nameJohn, ageNone) {name: John, age: 25} User(nameJohn, age25)Instructor 实现这一能力的方式,是提供Partial[T]泛型:它会动态创建一个新类,把原模型的所有字段都转换为Optional,使部分填充成为合法状态。该机制正是docs/examples/partial_streaming.md与 concepts/partial.md 共同描述的核心模式。Partial[T] 的底层实现机制Partial[T]并不是一个普通的可实例化类,而是一个类型工厂。在源码 instructor/v2/dsl/partial.py 中,Partial明确禁止直接实例化与继承:__new__直接抛出TypeError(Cannot instantiate abstract Partial class.);__init_subclass__抛出TypeError(fCannot subclass ...Partial);真正的魔法在__class_getitem__(即Partial[SomeModel]时触发)。其工作流程可以概括为三步:遍历字段递归改写:对每个字段,_wrap_models会深拷贝FieldInfo(见_make_field_optional),把原始注解包装成Optional[...];若字段本身是嵌套的BaseModel,则递归生成Partial[子模型],从而保证嵌套模型同样获得可选字段;动态建类:通过create_model生成名为Partial{原模型名}的新类(如PartialMeetingInfo),并以(wrapped_class, PartialBase)作为基类;保存原模型引用:新类通过_original_model属性持有对原始模型的引用,用于流结束时对完整 JSON 做最终校验。为了应对TreeNode - children: List[TreeNode]这类自引用模型,__class_getitem__借助ContextVar维护一个_processing_models集合,递归处理中遇到已在处理的模型会直接返回原类型,从而避免无限递归。此外,get_partial_model()(位于PartialBase)会把所有字段改为可选并生成缓存的部分模型,该部分模型同样携带_original_model引用。值得注意,instructor/dsl/partial.py仅是兼容导出层,实际逻辑全部由 instructor/v2/dsl/partial.py 承载。快速上手:会议信息实时提取下面是最具代表性的实战示例:从一段会议记录文本中提取与会者列表与会议要素,并把结果实时打印到终端(该示例取自docs/examples/partial_streaming.md,可直接复制运行):import instructor from pydantic import BaseModel from typing import List client instructor.from_provider(openai/gpt-5-nano) text_block In our recent online meeting, participants from various backgrounds joined to discuss the upcoming tech conference. The names and contact details of the participants were as follows: - Name: John Doe, Email: johndoeemail.com, Twitter: TechGuru44 - Name: Jane Smith, Email: janesmithemail.com, Twitter: DigitalDiva88 - Name: Alex Johnson, Email: alexjemail.com, Twitter: CodeMaster2023 During the meeting, we agreed on several key points. The conference will be held on March 15th, 2024, at the Grand Tech Arena located at 4521 Innovation Drive. Dr. Emily Johnson, a renowned AI researcher, will be our keynote speaker. The budget for the event is set at $50,000, covering venue costs, speaker fees, and promotional activities. Each participant is expected to contribute an article to the conference blog by February 20th. A follow-up meetingis scheduled for January 25th at 3 PM GMT to finalize the agenda and confirm the list of speakers. class User(BaseModel): name: str email: str twitter: str class MeetingInfo(BaseModel): users: List[User] date: str location: str budget: int deadline: str PartialMeetingInfo instructor.Partial[MeetingInfo] extraction_stream client.create( modelgpt-5.4-mini, response_modelPartialMeetingInfo, messages[ { role: user, content: fGet the information about the meeting and the users {text_block}, }, ], streamTrue, ) # type: ignore from rich.console import Console console Console() for extraction in extraction_stream: obj extraction.model_dump() console.clear() console.print(obj)代码要点说明:instructor.Partial[MeetingInfo]会生成PartialMeetingInfo,其中users这一List[User]字段同样被改造为尚未完整时以None或空结构占位;传streamTrue后,client.create返回的是一个生成器(Generator),每次迭代产生一个增量快照,可直接调用.model_dump()序列化给前端;流式结束后,extraction_stream的最后一个产出就是完整提取结果,可直接调用extraction.model_dump_json(indent2)输出格式化 JSON,得到类似如下的最终对象:{ users: [ { name: John Doe, email: johndoeemail.com, twitter: TechGuru44 }, { name: Jane Smith, email: janesmithemail.com, twitter: DigitalDiva88 }, { name: Alex Johnson, email: alexjemail.com, twitter: CodeMaster2023 } ], date: March 15th, 2024, location: Grand Tech Arena, 4521 Innovation Drive, budget: 50000, deadline: February 20th }仓库中还提供了两份更精简的可运行参考:examples/partial_streaming/run.py:使用client.chat.completions.create_partial(modelgpt-4, response_modelUser, ...)直接返回生成器并逐块打印,是最小的完整样例;examples/partial_streaming/benchmark.py:对比原始流式 结束时整体校验与字段级部分流式两种路径的吞吐差异。流式过程中的快照语义:每个 yield 都是可用对象理解字段级流式,关键是抓住快照二字。在PartialBase.model_from_chunks的实现中(见 instructor/v2/dsl/partial.py),整个过程是:累积原始文本 chunk(通过stream_extractor提取增量,并用remove_control_chars清理控制字符);调用process_potential_object对当前累积的 JSON 片段做完整性感知处理;每处理一次就yield一次当前快照对象。所以:生成器迭代多少次,你就得到多少个对象快照;最后一个快照必然是完整对象。这意味着你可以把迭代体直接写成每收到一个快照就刷新一次 UI,无需自己维护状态机。从测试用例可以看到该语义已被系统性地验证,例如 tests/v2/test_iterable_streaming.py、tests/coverage/test_dsl_partial_coverage.py 等覆盖了Partial[Envelope]等嵌套流式场景。底层原理:基于 JSON 完整性的分阶段校验已生成字段被解析、未生成字段为 None是如何实现的?关键在于 v2 运行时引入了completeness-based validation(基于完整性的校验),核心代码在 instructor/v2/dsl/json_tracker.py:解析使用jiter的partial_modetrailing-strings,允许在 JSON 不完整时仍能解析出部分结构;JsonCompleteness.analyze()先尝试严格解析:若成功说明整个 JSON 已闭合,所有路径标记为完整;若失败则进入兄弟节点启发式——某个值如果存在下一个兄弟节点,说明解析器为了找到下一个键值必须已完整解析它,因此该路径必然完整,而最后一个兄弟节点的完成度待定;is_path_complete(path)用点路径(如user.address.city、items[0])查询某个子结构是否已闭合。process_potential_object则据此分派:若根对象已完整且有数据,直接调用original_model.model_validate(parsed)做完整校验,产出最终对象;若对象尚不完整,则用model_construct()跳过校验、直接构造部分对象:对已完整的嵌套字段做校验,未生成的字段以None(必需字段)或默认值(可选字段)填充,嵌套模型递归走同样的_build_partial_object逻辑。流结束时还有一个收尾动作:model_from_chunks会先调用is_json_complete判断累积 JSON 是否结构完整,只有完整时才用_original_model.model_validate(...)做最终校验;若流在对象中途结束(JSON 不完整),则跳过最终校验,避免把合法为 null 的字段误判为缺失。这也是为什么流式模式下不适合在模型上挂普通验证器——验证无法在流式过程中对未完成的快照生效(详见下文注意事项)。Literal 字段与验证器的注意事项docs/examples/partial_streaming.md及 concepts/partial.md 都强调了两类限制:1. Literal / Enum 字段早期实现中,流式过程中遇到未完成的 Literal 值(如adm尚未拼成admin)会导致jiter抛错,因此文档建议模型混入PartialLiteralMixin:from typing import Literal from pydantic import BaseModel from instructor.dsl.partial import PartialLiteralMixin class User(BaseModel, PartialLiteralMixin): name: str age: int category: Literal[admin, user, guest]但需要指出:当前仓库源码中PartialLiteralMixin已被标记为废弃(DeprecationWarning,见 instructor/v2/dsl/partial.py)。由于引入了完整性感知校验——不完整 JSON 不做校验、原样存值,完整 JSON 才走完整校验——Literal 与 Enum 已在流式过程中被自动处理。新代码无需再混入该 Mixin,可直接安全移除。2. 验证器支持受限!!! warning Limited Validator SupportDue to the streaming nature of the response model, we do not support validators since they would not be able to be applied to the streaming response.即:由于每个流式快照都是部分填充的模型,字段级验证器无法对半成品施加约束,因此流式响应模型不支持验证器。若你的业务强依赖校验与重试,应改用非流式路径或在流结束后对最终对象单独校验。异步流式输出当你的应用基于asyncio,希望边接收边处理结果时,可以使用async_clientTrue创建客户端,并用async for迭代生成器。以下为docs/concepts/partial.md提供的完整异步示例:import instructor from pydantic import BaseModel client instructor.from_provider( openai/gpt-5-nano, async_clientTrue, ) class User(BaseModel): name: str age: int async def print_partial_results(): user client.create_partial( response_modelUser, max_retries2, streamTrue, messages[ {role: user, content: Jason is 12 years old}, ], ) async for m in user: print(m) # nameNone ageNone # nameNone ageNone # nameNone ageNone # name ageNone # nameJason ageNone # nameJason ageNone # nameJason ageNone # nameJason ageNone # nameJason age12 # nameJason age12 import asyncio asyncio.run(print_partial_results())注意输出序列中的一个细节:name先出现空字符串,再填充为Jason,随后age从None变为12——这正是字段按生成顺序逐步填充的直观体现。异步路径在PartialBase.from_streaming_response_async与model_from_chunks_async中实现(同样位于 instructor/v2/dsl/partial.py),逻辑与同步版本一一对应。并发请求与直接调用 handler 的注意事项docs/concepts/partial.md还专门讨论了并发与底层调用的边界行为,归纳如下:stream 标志显式传递:核心运行时会把每个请求的stream布尔值显式传给 handler。OpenAI 兼容、Anthropic、Mistral 与 xAI 的 mode handler 都会尊重该值,即使同模型的其他请求曾以流式准备、失败或取消,也不会互相污染;该规则不改变各 provider 的事件格式或输出类型。直接调用parse_response:当多个请求重叠地直接调用 handler 时,应显式传入streamTrue或streamFalse。省略stream会走prepare_request中遗留的一次性推理回退路径,该回退以模型类为键,无法区分使用同一模型类的重叠调用;显式解析还会清除挂起的遗留标记,因此对同一模型的并发调用不要混用显式与隐式两种解析方式。同步与异步的校验时机差异:同步部分流式会物化其结果,验证错误可能在parse_response内部抛出;异步部分流式则在迭代过程中校验。关闭生成器 ≠ 关闭底层流:提前关闭已解析的生成器,并不保证会关闭底层 SDK 流。请按 SDK 的属主契约自行持有并关闭源流;在等待源流期间发生取消,会向该源传播。上述路由规则针对各 provider 的 registry mode handler;原生 xAI 客户端拥有独立的 SDK 流式路径,不受此规则影响。异步请求准备阶段仍会同步执行缓存与媒体操作,本次改造并未把这些操作卸载或改变远端媒体连接检查。性能开销:值得了解的量化视角字段级流式相比原始流式 结束时一次性解析多出了逐 chunk 的解析与建对象开销。仓库中的 examples/partial_streaming/benchmark.py 用 tiktoken 统计 token 数、以 tokens/sec 衡量吞吐,并对同一模型做多轮平均。文件内注释记录的实测数据约为:原始流式约 35.7 tokens/sec,部分流式约 31.6 tokens/sec,即开销因子约 0.88x(即部分流式吞吐约为原始的 88%)。请注意这是该脚本在特定模型与网络条件下的历史运行结果,实际数值会因模型、延迟与负载而异——建议把它当作存在可观但可接受的开销的参考,而非绝对性能承诺。更多流式能力字段级流式只是 Instructor 流式体系的一员,若想覆盖更多场景,可继续阅读仓库内相关文档:Streaming Lists:流式产出已完整对象的集合;Streaming Basics:流式概念入门;Iterable Streaming:一次流式产出多个对象;Raw Response:直接访问 LLM 原始响应。小结字段级流式输出把结构化输出从等待一个完整 JSON升级为持续接收可用快照,让聊天式 UI、实时仪表盘、边生成边校验的 Agent 工作流成为可能。核心要点回顾:Partial[T]动态生成全字段可选的模型,嵌套模型递归改造,自引用模型有防递归保护;生成器的每个 yield 都是可用快照,最后一个 yield 是完整对象;底层通过JsonCompleteness jiter 的trailing-strings模式实现完整才校验、不完整则跳过校验的分阶段处理;PartialLiteralMixin已废弃,Literal/Enum 由完整性校验自动处理;流式模式不支持验证器;并发调用时显式传递stream布尔值,并自行管理底层 SDK 流的生命周期;异步场景使用async_clientTrue与async for即可获得同样的快照体验。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Instructor 字段级流式输出实战：用 Partial[T] 实现响应模型的实时增量快照
Instructor 字段级流式输出实战用 Partial[T] 实现响应模型的实时增量快照【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor结构化输出的最大痛点之一是等待:LLM 必须把整个 JSON 生成完毕,你才能完成一次校验与解析。Instructor 提供的字段级流式输出(Partial Response Streaming)打破了这一限制:它把响应模型拆解为一个个增量快照,每个快照都是当前已生成字段的即时可用对象,非常适合实时渲染 UI 组件、边生成边展示提取结果等场景。本文将基于docs/examples/partial_streaming.md的核心思路,结合仓库源码深入讲解Partial[T]的底层机制、create_partial的完整用法、异步流式与并发场景下的注意事项,让你能直接在生产代码中落地这套模式。字段级流式输出:随着 token 不断流入,响应模型按字段逐步填充,控制台中的对象快照实时更新什么是字段级流式输出传统做法下,我们从模型拿到的是逐 token 的文本增量。以User模型为例:from pydantic import BaseModel class User(BaseModel): name: str age: int如果直接流式接收 JSON,在对象完整返回之前我们无法可靠地解析:{name: Jo {name: John, ag {name: John, age: {name: John, age: 25} # Completed字段级流式的核心变化在于:每个流式快照都是一个可用的 Pydantic 模型实例,已生成的字段被解析为真实值,尚未生成的字段以None占位。上面四段文本对应的快照分别是:{name: Jo User(nameJo, ageNone) {name: John, ag User(nameJohn, ageNone) {name: John, age: User(nameJohn, ageNone) {name: John, age: 25} User(nameJohn, age25)Instructor 实现这一能力的方式,是提供Partial[T]泛型:它会动态创建一个新类,把原模型的所有字段都转换为Optional,使部分填充成为合法状态。该机制正是docs/examples/partial_streaming.md与 concepts/partial.md 共同描述的核心模式。Partial[T] 的底层实现机制Partial[T]并不是一个普通的可实例化类,而是一个类型工厂。在源码 instructor/v2/dsl/partial.py 中,Partial明确禁止直接实例化与继承:__new__直接抛出TypeError(Cannot instantiate abstract Partial class.);__init_subclass__抛出TypeError(fCannot subclass ...Partial);真正的魔法在__class_getitem__(即Partial[SomeModel]时触发)。其工作流程可以概括为三步:遍历字段递归改写:对每个字段,_wrap_models会深拷贝FieldInfo(见_make_field_optional),把原始注解包装成Optional[...];若字段本身是嵌套的BaseModel,则递归生成Partial[子模型],从而保证嵌套模型同样获得可选字段;动态建类:通过create_model生成名为Partial{原模型名}的新类(如PartialMeetingInfo),并以(wrapped_class, PartialBase)作为基类;保存原模型引用:新类通过_original_model属性持有对原始模型的引用,用于流结束时对完整 JSON 做最终校验。为了应对TreeNode - children: List[TreeNode]这类自引用模型,__class_getitem__借助ContextVar维护一个_processing_models集合,递归处理中遇到已在处理的模型会直接返回原类型,从而避免无限递归。此外,get_partial_model()(位于PartialBase)会把所有字段改为可选并生成缓存的部分模型,该部分模型同样携带_original_model引用。值得注意,instructor/dsl/partial.py仅是兼容导出层,实际逻辑全部由 instructor/v2/dsl/partial.py 承载。快速上手:会议信息实时提取下面是最具代表性的实战示例:从一段会议记录文本中提取与会者列表与会议要素,并把结果实时打印到终端(该示例取自docs/examples/partial_streaming.md,可直接复制运行):import instructor from pydantic import BaseModel from typing import List client instructor.from_provider(openai/gpt-5-nano) text_block In our recent online meeting, participants from various backgrounds joined to discuss the upcoming tech conference. The names and contact details of the participants were as follows: - Name: John Doe, Email: johndoeemail.com, Twitter: TechGuru44 - Name: Jane Smith, Email: janesmithemail.com, Twitter: DigitalDiva88 - Name: Alex Johnson, Email: alexjemail.com, Twitter: CodeMaster2023 During the meeting, we agreed on several key points. The conference will be held on March 15th, 2024, at the Grand Tech Arena located at 4521 Innovation Drive. Dr. Emily Johnson, a renowned AI researcher, will be our keynote speaker. The budget for the event is set at $50,000, covering venue costs, speaker fees, and promotional activities. Each participant is expected to contribute an article to the conference blog by February 20th. A follow-up meetingis scheduled for January 25th at 3 PM GMT to finalize the agenda and confirm the list of speakers. class User(BaseModel): name: str email: str twitter: str class MeetingInfo(BaseModel): users: List[User] date: str location: str budget: int deadline: str PartialMeetingInfo instructor.Partial[MeetingInfo] extraction_stream client.create( modelgpt-5.4-mini, response_modelPartialMeetingInfo, messages[ { role: user, content: fGet the information about the meeting and the users {text_block}, }, ], streamTrue, ) # type: ignore from rich.console import Console console Console() for extraction in extraction_stream: obj extraction.model_dump() console.clear() console.print(obj)代码要点说明:instructor.Partial[MeetingInfo]会生成PartialMeetingInfo,其中users这一List[User]字段同样被改造为尚未完整时以None或空结构占位;传streamTrue后,client.create返回的是一个生成器(Generator),每次迭代产生一个增量快照,可直接调用.model_dump()序列化给前端;流式结束后,extraction_stream的最后一个产出就是完整提取结果,可直接调用extraction.model_dump_json(indent2)输出格式化 JSON,得到类似如下的最终对象:{ users: [ { name: John Doe, email: johndoeemail.com, twitter: TechGuru44 }, { name: Jane Smith, email: janesmithemail.com, twitter: DigitalDiva88 }, { name: Alex Johnson, email: alexjemail.com, twitter: CodeMaster2023 } ], date: March 15th, 2024, location: Grand Tech Arena, 4521 Innovation Drive, budget: 50000, deadline: February 20th }仓库中还提供了两份更精简的可运行参考:examples/partial_streaming/run.py:使用client.chat.completions.create_partial(modelgpt-4, response_modelUser, ...)直接返回生成器并逐块打印,是最小的完整样例;examples/partial_streaming/benchmark.py:对比原始流式 结束时整体校验与字段级部分流式两种路径的吞吐差异。流式过程中的快照语义:每个 yield 都是可用对象理解字段级流式,关键是抓住快照二字。在PartialBase.model_from_chunks的实现中(见 instructor/v2/dsl/partial.py),整个过程是:累积原始文本 chunk(通过stream_extractor提取增量,并用remove_control_chars清理控制字符);调用process_potential_object对当前累积的 JSON 片段做完整性感知处理;每处理一次就yield一次当前快照对象。所以:生成器迭代多少次,你就得到多少个对象快照;最后一个快照必然是完整对象。这意味着你可以把迭代体直接写成每收到一个快照就刷新一次 UI,无需自己维护状态机。从测试用例可以看到该语义已被系统性地验证,例如 tests/v2/test_iterable_streaming.py、tests/coverage/test_dsl_partial_coverage.py 等覆盖了Partial[Envelope]等嵌套流式场景。底层原理:基于 JSON 完整性的分阶段校验已生成字段被解析、未生成字段为 None是如何实现的?关键在于 v2 运行时引入了completeness-based validation(基于完整性的校验),核心代码在 instructor/v2/dsl/json_tracker.py:解析使用jiter的partial_modetrailing-strings,允许在 JSON 不完整时仍能解析出部分结构;JsonCompleteness.analyze()先尝试严格解析:若成功说明整个 JSON 已闭合,所有路径标记为完整;若失败则进入兄弟节点启发式——某个值如果存在下一个兄弟节点,说明解析器为了找到下一个键值必须已完整解析它,因此该路径必然完整,而最后一个兄弟节点的完成度待定;is_path_complete(path)用点路径(如user.address.city、items[0])查询某个子结构是否已闭合。process_potential_object则据此分派:若根对象已完整且有数据,直接调用original_model.model_validate(parsed)做完整校验,产出最终对象;若对象尚不完整,则用model_construct()跳过校验、直接构造部分对象:对已完整的嵌套字段做校验,未生成的字段以None(必需字段)或默认值(可选字段)填充,嵌套模型递归走同样的_build_partial_object逻辑。流结束时还有一个收尾动作:model_from_chunks会先调用is_json_complete判断累积 JSON 是否结构完整,只有完整时才用_original_model.model_validate(...)做最终校验;若流在对象中途结束(JSON 不完整),则跳过最终校验,避免把合法为 null 的字段误判为缺失。这也是为什么流式模式下不适合在模型上挂普通验证器——验证无法在流式过程中对未完成的快照生效(详见下文注意事项)。Literal 字段与验证器的注意事项docs/examples/partial_streaming.md及 concepts/partial.md 都强调了两类限制:1. Literal / Enum 字段早期实现中,流式过程中遇到未完成的 Literal 值(如adm尚未拼成admin)会导致jiter抛错,因此文档建议模型混入PartialLiteralMixin:from typing import Literal from pydantic import BaseModel from instructor.dsl.partial import PartialLiteralMixin class User(BaseModel, PartialLiteralMixin): name: str age: int category: Literal[admin, user, guest]但需要指出:当前仓库源码中PartialLiteralMixin已被标记为废弃(DeprecationWarning,见 instructor/v2/dsl/partial.py)。由于引入了完整性感知校验——不完整 JSON 不做校验、原样存值,完整 JSON 才走完整校验——Literal 与 Enum 已在流式过程中被自动处理。新代码无需再混入该 Mixin,可直接安全移除。2. 验证器支持受限!!! warning Limited Validator SupportDue to the streaming nature of the response model, we do not support validators since they would not be able to be applied to the streaming response.即:由于每个流式快照都是部分填充的模型,字段级验证器无法对半成品施加约束,因此流式响应模型不支持验证器。若你的业务强依赖校验与重试,应改用非流式路径或在流结束后对最终对象单独校验。异步流式输出当你的应用基于asyncio,希望边接收边处理结果时,可以使用async_clientTrue创建客户端,并用async for迭代生成器。以下为docs/concepts/partial.md提供的完整异步示例:import instructor from pydantic import BaseModel client instructor.from_provider( openai/gpt-5-nano, async_clientTrue, ) class User(BaseModel): name: str age: int async def print_partial_results(): user client.create_partial( response_modelUser, max_retries2, streamTrue, messages[ {role: user, content: Jason is 12 years old}, ], ) async for m in user: print(m) # nameNone ageNone # nameNone ageNone # nameNone ageNone # name ageNone # nameJason ageNone # nameJason ageNone # nameJason ageNone # nameJason ageNone # nameJason age12 # nameJason age12 import asyncio asyncio.run(print_partial_results())注意输出序列中的一个细节:name先出现空字符串,再填充为Jason,随后age从None变为12——这正是字段按生成顺序逐步填充的直观体现。异步路径在PartialBase.from_streaming_response_async与model_from_chunks_async中实现(同样位于 instructor/v2/dsl/partial.py),逻辑与同步版本一一对应。并发请求与直接调用 handler 的注意事项docs/concepts/partial.md还专门讨论了并发与底层调用的边界行为,归纳如下:stream 标志显式传递:核心运行时会把每个请求的stream布尔值显式传给 handler。OpenAI 兼容、Anthropic、Mistral 与 xAI 的 mode handler 都会尊重该值,即使同模型的其他请求曾以流式准备、失败或取消,也不会互相污染;该规则不改变各 provider 的事件格式或输出类型。直接调用parse_response:当多个请求重叠地直接调用 handler 时,应显式传入streamTrue或streamFalse。省略stream会走prepare_request中遗留的一次性推理回退路径,该回退以模型类为键,无法区分使用同一模型类的重叠调用;显式解析还会清除挂起的遗留标记,因此对同一模型的并发调用不要混用显式与隐式两种解析方式。同步与异步的校验时机差异:同步部分流式会物化其结果,验证错误可能在parse_response内部抛出;异步部分流式则在迭代过程中校验。关闭生成器 ≠ 关闭底层流:提前关闭已解析的生成器,并不保证会关闭底层 SDK 流。请按 SDK 的属主契约自行持有并关闭源流;在等待源流期间发生取消,会向该源传播。上述路由规则针对各 provider 的 registry mode handler;原生 xAI 客户端拥有独立的 SDK 流式路径,不受此规则影响。异步请求准备阶段仍会同步执行缓存与媒体操作,本次改造并未把这些操作卸载或改变远端媒体连接检查。性能开销:值得了解的量化视角字段级流式相比原始流式 结束时一次性解析多出了逐 chunk 的解析与建对象开销。仓库中的 examples/partial_streaming/benchmark.py 用 tiktoken 统计 token 数、以 tokens/sec 衡量吞吐,并对同一模型做多轮平均。文件内注释记录的实测数据约为:原始流式约 35.7 tokens/sec,部分流式约 31.6 tokens/sec,即开销因子约 0.88x(即部分流式吞吐约为原始的 88%)。请注意这是该脚本在特定模型与网络条件下的历史运行结果,实际数值会因模型、延迟与负载而异——建议把它当作存在可观但可接受的开销的参考,而非绝对性能承诺。更多流式能力字段级流式只是 Instructor 流式体系的一员,若想覆盖更多场景,可继续阅读仓库内相关文档:Streaming Lists:流式产出已完整对象的集合;Streaming Basics:流式概念入门;Iterable Streaming:一次流式产出多个对象;Raw Response:直接访问 LLM 原始响应。小结字段级流式输出把结构化输出从等待一个完整 JSON升级为持续接收可用快照,让聊天式 UI、实时仪表盘、边生成边校验的 Agent 工作流成为可能。核心要点回顾:Partial[T]动态生成全字段可选的模型,嵌套模型递归改造,自引用模型有防递归保护;生成器的每个 yield 都是可用快照,最后一个 yield 是完整对象;底层通过JsonCompleteness jiter 的trailing-strings模式实现完整才校验、不完整则跳过校验的分阶段处理;PartialLiteralMixin已废弃,Literal/Enum 由完整性校验自动处理;流式模式不支持验证器;并发调用时显式传递stream布尔值,并自行管理底层 SDK 流的生命周期;异步场景使用async_clientTrue与async for即可获得同样的快照体验。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考