使用 Instructor 与 Fireworks 生成结构化输出完整实战指南【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本指南围绕 Instructor 对 Fireworks AI 的官方集成docs/integrations/fireworks.md展开讲解如何在 Fireworks 上以类型安全的方式获取经过校验的结构化输出。读完本文你将掌握通过pip install instructor[fireworks-ai]完成环境搭建、用instructor.from_provider()一行代码初始化客户端、实现同步/异步提取与嵌套对象解析、使用create_partial做增量流式解析、用create_iterable批量抽取多个对象以及理解MD_JSON与TOOLS两种模式的底层差异。为什么在 Fireworks 上使用 InstructorFireworks AI 提供高效、低成本且具备企业级可靠性的模型推理服务。Instructor 在其之上叠加了 structured outputs结构化输出能力你只需用 PydanticBaseModel声明目标结构Instructor 就会接管提示词编排 → 模型调用 → 原始响应解析 → Pydantic 校验整条链路最终直接返回类型安全的 Python 对象而不是裸字符串。从仓库源码看Fireworks 走的是 OpenAI 兼容的 API 路线因此其接入实现与 OpenAI 完全同构在 instructor/v2/providers/fireworks/client.py 中工厂函数from_fireworks直接复用 OpenAI 的 handlerfrom instructor.v2.providers.openai import handlers并将底层的client.chat.completions.create或异步版client.chat.completions.acreate作为create入口交给patch_v2进行统一包装instructor/v2/providers/fireworks/client.py。快速开始安装与初始化安装Fireworks 的官方 SDK 是fireworks-aiInstructor 通过 extra 依赖声明了版本约束参见 pyproject.tomlfireworks-ai [fireworks-ai1.0.0,0.15.4]因此推荐一条命令安装pip install instructor[fireworks-ai]两种初始化方式Instructor 提供了两种等价的接入方式方式一字符串模型名自动路由推荐本文示例均采用import instructor client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5)instructor.from_provider()会解析provider/model格式的字符串自动完成 Fireworks SDK 客户端的构建与 patch。其实现位于 instructor/v2/auto_client.py模型名必须以fireworks/为前缀之后的部分这里是accounts/fireworks/models/kimi-k2p5才是真正的模型 ID。构建逻辑在_build_fireworks中会根据async_client参数创建Fireworks或AsyncFireworks实例并透传api_key等 kwargsinstructor/v2/auto_client.py。方式二先建 SDK 客户端再 patchfrom fireworks.client import Fireworks import instructor client Fireworks() # 从环境变量读取 FIREWORKS_API_KEY client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5, ...)无论哪种方式底层最终都会走到instructor.v2.providers.fireworks.client.from_fireworksinstructor/v2/providers/fireworks/client.py。该函数会校验三件事fireworks-ai是否已安装未安装时抛出ClientError并提示pip install fireworks-aiinstructor/v2/providers/fireworks/client.py传入的mode是否为 Fireworks 注册过的模式否则抛出ModeError并列出可用模式instructor/v2/providers/fireworks/client.pyclient是否为Fireworks/AsyncFireworks实例否则抛出ClientErrorinstructor/v2/providers/fireworks/client.py。另外旧版导入路径instructor.providers.fireworks.client依然可用它通过 instructor/providers/_compat.py 的兼容层转发到 v2 实现保证历史代码不失效。同步示例最简单的用户信息提取from fireworks.client import Fireworks import instructor from pydantic import BaseModel # 初始化客户端 client Fireworks() # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class User(BaseModel): name: str age: int # 创建结构化输出 user client.create( messages[ { role: user, content: Extract: Jason is 25 years old, } ], response_modelUser, ) print(user) # User(nameJason, age25)整个流程非常直观response_modelUser声明目标结构client.create(...)返回的就是一个已经通过 Pydantic 校验的User实例。类型错误例如模型把age输出成非数字会被 Instructor 拦截并触发重试机制而不是让脏数据流进业务代码。异步示例并发场景下的结构化提取异步客户端适合高并发场景。只需在from_provider中传入async_clientTrueimport instructor from pydantic import BaseModel import asyncio client instructor.from_provider( fireworks/accounts/fireworks/models/kimi-k2p5, async_clientTrue, ) class User(BaseModel): name: str age: int async def extract_user(): user await client.create( messages[ { role: user, content: Extract: Jason is 25 years old, } ], response_modelUser, ) return user # 运行异步函数 user asyncio.run(extract_user()) print(user) # User(nameJason, age25)从源码看async_clientTrue时_build_fireworks会构造AsyncFireworks实例instructor/v2/auto_client.py而from_fireworks会对异步客户端返回AsyncInstructor并包装client.chat.completions.acreate作为底层创建函数instructor/v2/providers/fireworks/client.py。嵌套结构提取复杂对象实际业务中数据结构往往不是扁平的。Instructor 对嵌套 Pydantic 模型开箱即用import instructor from pydantic import BaseModel # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: list[Address] # 创建包含嵌套对象的结构化输出 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 # } # ] # }User.addresses被声明为list[Address]Instructor 会按 JSON Schema 把模型的 schema 传递给 Fireworks模型返回的每个地址条目都会独立经过Address校验。更多嵌套与列表技巧可参考 docs/concepts/models.md 与 docs/concepts/lists.md。流式输出两种场景两种方案Instructor 提供两种流式能力适用场景完全不同Iterables可迭代对象适合流式返回同一类型的对象列表例如从一段文本中批量提取多个用户Partial Streaming部分流式适合流式返回单个对象让你在完整响应到达之前就立即开始处理已到达的字段。Partial Streaming边生成边解析单个对象import instructor from pydantic import BaseModel # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class User(BaseModel): name: str age: int bio: str user client.create_partial( messages[ { role: user, content: Create a user profile for Jason 1 sentence bio, age 25, }, ], response_modelUser, ) for user_partial in user: print(user_partial) # nameNone ageNone bioNone # nameJason ageNone bioNone # nameJason age25 bioWhen hes # nameJason age25 bioWhen hes not working as a graphic designer, Jason can usually be found trying out new craft beers or attempting to cook something other than ramen noodles.注意create_partial返回的是一个可迭代对象每次迭代产出的都是部分完成的User尚未到达的字段为None已到达的字段逐步被填充。你可以在模型输出到一半时就渲染 UI、做前置校验或提前终止无意义的请求。底层机制可参考 instructor/dsl/partial.py 的实现它是 Instructor 的 partial 数据结构的核心。Iterables一次性抽取多个对象import instructor from pydantic import BaseModel # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class User(BaseModel): name: str age: int # 从文本中提取多个用户 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 age28create_iterable同样返回可迭代对象但每个元素都是一个完整、独立的User实例。关于两种流式方案的更多细节可继续阅读 docs/concepts/partial.md 与 docs/concepts/iterable.md。生产环境提醒在实现任何流式功能之前务必确认所用模型对 streaming 的具体支持情况与限制例如工具调用流式行为、token 边界等并在生产环境做好充分验证。Instructor ModesTOOLS 与 MD_JSONFireworks 支持两种响应模型对应 Instructor 的两种模式instructor.Mode.MD_JSON将模型的原始文本补全解析为 Pydantic 对象。适用于模型不支持工具调用、或你希望模型直接以 JSON 格式作答的场景instructor.Mode.TOOLS使用 Fireworks 的工具调用function/tool callingAPI 返回结构化输出是默认且推荐的方式。从源码看Fireworks 的完整模式支持定义在 instructor/v2/core/provider_specs.py支持TOOLS、JSON_SCHEMA、MD_JSON三种模式同步/异步均可PARALLEL_TOOLS、RESPONSES_TOOLS两种模式不被支持历史遗留模式FIREWORKS_TOOLS、FIREWORKS_JSON会被归一化为TOOLS与MD_JSONlegacy_modes字段保证旧代码兼容。from_fireworks内部会调用normalize_mode(Provider.FIREWORKS, mode)完成归一化并通过mode_registry.is_registered校验模式是否已为该 provider 注册instructor/v2/providers/fireworks/client.py。模式映射关系定义于 instructor/v2/core/mode.py即FIREWORKS_TOOLS → TOOLS、FIREWORKS_JSON → MD_JSON。因此显式指定模式与默认行为等价import instructor client instructor.from_provider( fireworks/accounts/fireworks/models/kimi-k2p5, modeinstructor.Mode.TOOLS, # 默认即 TOOLS )关于模式的横向对比可参考 docs/modes-comparison.md。架构理解Fireworks 在 Instructor 中的接入方式结合仓库代码Fireworks 的接入可以总结为一条清晰的分层链路入口层instructor.from_provider(fireworks/...)按字符串前缀路由到_build_fireworksinstructor/v2/auto_client.py负责实例化Fireworks/AsyncFireworks并透传api_key等参数工厂层from_fireworksinstructor/v2/providers/fireworks/client.py校验依赖、模式与客户端类型选出底层create函数同步为client.chat.completions.create异步为acreate交给patch_v2handler 层Fireworks 由于与 OpenAI API 兼容直接复用 OpenAI 的 handlerinstructor/v2/providers/openai/handlers.py 注册了Provider.FIREWORKS对应的 TOOLS / JSON 处理逻辑registry 层mode_registry与provider_specs共同决定哪些模式对 Fireworks 生效、旧模式如何归一化。正因为这一分层设计Instructor 能对 Fireworks 提供与 OpenAI 一致的 API 体验你只需要记住from_providercreate/create_partial/create_iterable几个入口即可在同步、异步、流式三种形态间自由切换。延伸阅读核心概念docs/concepts/index.md类型校验指南docs/concepts/validation.md高级用法示例docs/examples/index.md模式对比docs/modes-comparison.md集成清单docs/integrations/index.mdInstructor 会持续跟进 Fireworks 的最新 API 版本并保持兼容具体更新可查阅仓库根目录的 CHANGELOG.md。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Instructor 与 Fireworks 生成结构化输出：完整实战指南
使用 Instructor 与 Fireworks 生成结构化输出完整实战指南【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本指南围绕 Instructor 对 Fireworks AI 的官方集成docs/integrations/fireworks.md展开讲解如何在 Fireworks 上以类型安全的方式获取经过校验的结构化输出。读完本文你将掌握通过pip install instructor[fireworks-ai]完成环境搭建、用instructor.from_provider()一行代码初始化客户端、实现同步/异步提取与嵌套对象解析、使用create_partial做增量流式解析、用create_iterable批量抽取多个对象以及理解MD_JSON与TOOLS两种模式的底层差异。为什么在 Fireworks 上使用 InstructorFireworks AI 提供高效、低成本且具备企业级可靠性的模型推理服务。Instructor 在其之上叠加了 structured outputs结构化输出能力你只需用 PydanticBaseModel声明目标结构Instructor 就会接管提示词编排 → 模型调用 → 原始响应解析 → Pydantic 校验整条链路最终直接返回类型安全的 Python 对象而不是裸字符串。从仓库源码看Fireworks 走的是 OpenAI 兼容的 API 路线因此其接入实现与 OpenAI 完全同构在 instructor/v2/providers/fireworks/client.py 中工厂函数from_fireworks直接复用 OpenAI 的 handlerfrom instructor.v2.providers.openai import handlers并将底层的client.chat.completions.create或异步版client.chat.completions.acreate作为create入口交给patch_v2进行统一包装instructor/v2/providers/fireworks/client.py。快速开始安装与初始化安装Fireworks 的官方 SDK 是fireworks-aiInstructor 通过 extra 依赖声明了版本约束参见 pyproject.tomlfireworks-ai [fireworks-ai1.0.0,0.15.4]因此推荐一条命令安装pip install instructor[fireworks-ai]两种初始化方式Instructor 提供了两种等价的接入方式方式一字符串模型名自动路由推荐本文示例均采用import instructor client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5)instructor.from_provider()会解析provider/model格式的字符串自动完成 Fireworks SDK 客户端的构建与 patch。其实现位于 instructor/v2/auto_client.py模型名必须以fireworks/为前缀之后的部分这里是accounts/fireworks/models/kimi-k2p5才是真正的模型 ID。构建逻辑在_build_fireworks中会根据async_client参数创建Fireworks或AsyncFireworks实例并透传api_key等 kwargsinstructor/v2/auto_client.py。方式二先建 SDK 客户端再 patchfrom fireworks.client import Fireworks import instructor client Fireworks() # 从环境变量读取 FIREWORKS_API_KEY client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5, ...)无论哪种方式底层最终都会走到instructor.v2.providers.fireworks.client.from_fireworksinstructor/v2/providers/fireworks/client.py。该函数会校验三件事fireworks-ai是否已安装未安装时抛出ClientError并提示pip install fireworks-aiinstructor/v2/providers/fireworks/client.py传入的mode是否为 Fireworks 注册过的模式否则抛出ModeError并列出可用模式instructor/v2/providers/fireworks/client.pyclient是否为Fireworks/AsyncFireworks实例否则抛出ClientErrorinstructor/v2/providers/fireworks/client.py。另外旧版导入路径instructor.providers.fireworks.client依然可用它通过 instructor/providers/_compat.py 的兼容层转发到 v2 实现保证历史代码不失效。同步示例最简单的用户信息提取from fireworks.client import Fireworks import instructor from pydantic import BaseModel # 初始化客户端 client Fireworks() # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class User(BaseModel): name: str age: int # 创建结构化输出 user client.create( messages[ { role: user, content: Extract: Jason is 25 years old, } ], response_modelUser, ) print(user) # User(nameJason, age25)整个流程非常直观response_modelUser声明目标结构client.create(...)返回的就是一个已经通过 Pydantic 校验的User实例。类型错误例如模型把age输出成非数字会被 Instructor 拦截并触发重试机制而不是让脏数据流进业务代码。异步示例并发场景下的结构化提取异步客户端适合高并发场景。只需在from_provider中传入async_clientTrueimport instructor from pydantic import BaseModel import asyncio client instructor.from_provider( fireworks/accounts/fireworks/models/kimi-k2p5, async_clientTrue, ) class User(BaseModel): name: str age: int async def extract_user(): user await client.create( messages[ { role: user, content: Extract: Jason is 25 years old, } ], response_modelUser, ) return user # 运行异步函数 user asyncio.run(extract_user()) print(user) # User(nameJason, age25)从源码看async_clientTrue时_build_fireworks会构造AsyncFireworks实例instructor/v2/auto_client.py而from_fireworks会对异步客户端返回AsyncInstructor并包装client.chat.completions.acreate作为底层创建函数instructor/v2/providers/fireworks/client.py。嵌套结构提取复杂对象实际业务中数据结构往往不是扁平的。Instructor 对嵌套 Pydantic 模型开箱即用import instructor from pydantic import BaseModel # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: list[Address] # 创建包含嵌套对象的结构化输出 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 # } # ] # }User.addresses被声明为list[Address]Instructor 会按 JSON Schema 把模型的 schema 传递给 Fireworks模型返回的每个地址条目都会独立经过Address校验。更多嵌套与列表技巧可参考 docs/concepts/models.md 与 docs/concepts/lists.md。流式输出两种场景两种方案Instructor 提供两种流式能力适用场景完全不同Iterables可迭代对象适合流式返回同一类型的对象列表例如从一段文本中批量提取多个用户Partial Streaming部分流式适合流式返回单个对象让你在完整响应到达之前就立即开始处理已到达的字段。Partial Streaming边生成边解析单个对象import instructor from pydantic import BaseModel # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class User(BaseModel): name: str age: int bio: str user client.create_partial( messages[ { role: user, content: Create a user profile for Jason 1 sentence bio, age 25, }, ], response_modelUser, ) for user_partial in user: print(user_partial) # nameNone ageNone bioNone # nameJason ageNone bioNone # nameJason age25 bioWhen hes # nameJason age25 bioWhen hes not working as a graphic designer, Jason can usually be found trying out new craft beers or attempting to cook something other than ramen noodles.注意create_partial返回的是一个可迭代对象每次迭代产出的都是部分完成的User尚未到达的字段为None已到达的字段逐步被填充。你可以在模型输出到一半时就渲染 UI、做前置校验或提前终止无意义的请求。底层机制可参考 instructor/dsl/partial.py 的实现它是 Instructor 的 partial 数据结构的核心。Iterables一次性抽取多个对象import instructor from pydantic import BaseModel # 启用 instructor patches client instructor.from_provider(fireworks/accounts/fireworks/models/kimi-k2p5) class User(BaseModel): name: str age: int # 从文本中提取多个用户 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 age28create_iterable同样返回可迭代对象但每个元素都是一个完整、独立的User实例。关于两种流式方案的更多细节可继续阅读 docs/concepts/partial.md 与 docs/concepts/iterable.md。生产环境提醒在实现任何流式功能之前务必确认所用模型对 streaming 的具体支持情况与限制例如工具调用流式行为、token 边界等并在生产环境做好充分验证。Instructor ModesTOOLS 与 MD_JSONFireworks 支持两种响应模型对应 Instructor 的两种模式instructor.Mode.MD_JSON将模型的原始文本补全解析为 Pydantic 对象。适用于模型不支持工具调用、或你希望模型直接以 JSON 格式作答的场景instructor.Mode.TOOLS使用 Fireworks 的工具调用function/tool callingAPI 返回结构化输出是默认且推荐的方式。从源码看Fireworks 的完整模式支持定义在 instructor/v2/core/provider_specs.py支持TOOLS、JSON_SCHEMA、MD_JSON三种模式同步/异步均可PARALLEL_TOOLS、RESPONSES_TOOLS两种模式不被支持历史遗留模式FIREWORKS_TOOLS、FIREWORKS_JSON会被归一化为TOOLS与MD_JSONlegacy_modes字段保证旧代码兼容。from_fireworks内部会调用normalize_mode(Provider.FIREWORKS, mode)完成归一化并通过mode_registry.is_registered校验模式是否已为该 provider 注册instructor/v2/providers/fireworks/client.py。模式映射关系定义于 instructor/v2/core/mode.py即FIREWORKS_TOOLS → TOOLS、FIREWORKS_JSON → MD_JSON。因此显式指定模式与默认行为等价import instructor client instructor.from_provider( fireworks/accounts/fireworks/models/kimi-k2p5, modeinstructor.Mode.TOOLS, # 默认即 TOOLS )关于模式的横向对比可参考 docs/modes-comparison.md。架构理解Fireworks 在 Instructor 中的接入方式结合仓库代码Fireworks 的接入可以总结为一条清晰的分层链路入口层instructor.from_provider(fireworks/...)按字符串前缀路由到_build_fireworksinstructor/v2/auto_client.py负责实例化Fireworks/AsyncFireworks并透传api_key等参数工厂层from_fireworksinstructor/v2/providers/fireworks/client.py校验依赖、模式与客户端类型选出底层create函数同步为client.chat.completions.create异步为acreate交给patch_v2handler 层Fireworks 由于与 OpenAI API 兼容直接复用 OpenAI 的 handlerinstructor/v2/providers/openai/handlers.py 注册了Provider.FIREWORKS对应的 TOOLS / JSON 处理逻辑registry 层mode_registry与provider_specs共同决定哪些模式对 Fireworks 生效、旧模式如何归一化。正因为这一分层设计Instructor 能对 Fireworks 提供与 OpenAI 一致的 API 体验你只需要记住from_providercreate/create_partial/create_iterable几个入口即可在同步、异步、流式三种形态间自由切换。延伸阅读核心概念docs/concepts/index.md类型校验指南docs/concepts/validation.md高级用法示例docs/examples/index.md模式对比docs/modes-comparison.md集成清单docs/integrations/index.mdInstructor 会持续跟进 Fireworks 的最新 API 版本并保持兼容具体更新可查阅仓库根目录的 CHANGELOG.md。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考