使用 Instructor 与 Cerebras 硬件加速模型构建类型安全的结构化输出【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorCerebras 面向高性能计算环境提供硬件加速 AI 模型而 Instructor 负责把模型的原始输出转换为经过 Pydantic 校验的类型安全响应。本文以 docs/integrations/cerebras.md 为骨架结合仓库源码完整讲解从安装、请求参数、同步/异步调用到流式与 Hooks 的 Cerebras 集成实战读完即可在 Cerebras 上落地可靠的结构化数据提取。Cerebras 与 Instructor 的组合价值Cerebras 提供硬件加速的推理服务模型走 OpenAI 兼容的 Chat Completions 接口Instructor 在此基础上补齐了结构化这一环——通过 Pydantic 模型定义输出 Schema由客户端负责把模型响应解析、校验并重试最终返回BaseModel实例而非字符串。两者的分工让开发者可以只关注我要什么结构而把 JSON 解析、字段校验、错误重试等脏活交给 Instructor。从源码看Cerebras 在 Instructor 中属于注册在案的官方 providerinstructor/v2/core/provider_specs.py中为其登记了别名cerebras、SDK 模块cerebras.cloud.sdk以及支持的运行模式详见后文模式详解因此既可以通过instructor.from_provider(cerebras/...)一行式创建客户端也可以手动构造 Cerebras SDK 客户端后再交给from_cerebras。快速开始安装安装带 Cerebras 支持的 Instructorpip install instructor[cerebras_cloud_sdk]该 extra 会拉取cerebras-cloud-sdk。如果 SDK 缺失from_cerebras工厂会直接抛出ClientError提示先执行pip install cerebras-cloud-sdk见 instructor/v2/providers/cerebras/client.py。调用时需要 Cerebras API Key。使用from_provider创建客户端时工厂会构造Cerebras(api_keyapi_key)或AsyncCerebras(api_keyapi_key)见 instructor/v2/auto_client.pyAPI Key 默认来自CEREBRAS_API_KEY环境变量tests/llm/shared_config.py中即为该 provider 登记了此变量名。Cerebras 请求参数详解client.create(...)中的额外关键字参数会被 Instructor 原样转发给 Cerebras SDK因此无需退回泛化的 OpenAI 客户端即可使用 Cerebras 专属请求参数。官方文档给出如下示例import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int client instructor.from_provider(cerebras/gpt-oss-120b) resp client.create( messages[{role: user, content: Return a short user record.}], response_modelUser, max_completion_tokens256, reasoning_effortnone, seed42, )需要特别留意的参数约束max_completion_tokens是规范的输出长度上限兼容别名max_tokens会被单独转发因此同一个请求中不要同时发送这两个字段否则可能产生歧义。temperature、top_p、stop、response_format、parallel_tool_calls、log probabilitieslogprobs以及各类 penalties 等 Cerebras 参数在所选模型支持的前提下都可以按同样方式传入。从源码机制上看from_cerebras工厂取出的是client.chat.completions.create再经由patch_v2包装后作为 Instructor 的create使用instructor/v2/providers/cerebras/client.py因此请求参数的自然透传是这一设计带来的直接结果。关于当前请求 Schema 的完整字段请以 Cerebras 官方 API 参考文档Chat Completions为准。同步调用最简单的结构化提取import instructor from pydantic import BaseModel client instructor.from_provider(cerebras/gpt-oss-120b) class User(BaseModel): name: str age: int # Create structured output resp client.create( messages[ { role: user, content: Extract the name and age of the person in this sentence: John Smith is 29 years old., } ], response_modelUser, ) print(resp) # User(nameJohn Smith, age29)response_modelUser即声明了输出 SchemaInstructor 会把它转换为模型可理解的格式JSON Schema 或工具定义并把返回内容解析、校验成User实例之后便可以直接以属性方式访问resp.name、resp.age。异步调用通过async_clientTrue获得异步客户端随后在 async 函数中await client.create(...)import instructor from pydantic import BaseModel import asyncio client instructor.from_provider( cerebras/gpt-oss-120b, async_clientTrue, ) class User(BaseModel): name: str age: int async def extract_user(): resp await client.create( messages[ { role: user, content: Extract the name and age of the person in this sentence: John Smith is 29 years old., } ], response_modelUser, ) return resp # Run async function resp asyncio.run(extract_user()) print(resp) # User(nameJohn Smith, age29)底层_build_cerebras在async_clientTrue时会构造AsyncCerebras并交由from_cerebras返回AsyncInstructor同步路径则返回Instructor两者由from_cerebras的 overload 签名与实例分派保证类型一致instructor/v2/providers/cerebras/client.py。嵌套模型一次请求提取多层结构response_model支持嵌套 Pydantic 模型Cerebras 侧会以单次调用返回完整嵌套结构from pydantic import BaseModel import instructor client instructor.from_provider(cerebras/gpt-oss-120b) class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: list[Address] # Create structured output with nested objects 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 # } # ] # }嵌套 列表组合list[Address]适合地址簿、订单、简历等一对多数据的单次抽取。流式支持Instructor 提供两种流式方式适用场景不同Iterables流式返回同类型对象的列表适合一次抽取多个实体如多个用户Partial Streaming流式返回单个对象并在响应到达时立即开始处理字段逐步填充。重要前提目前 Cerebras 的 partial streaming 是通过解析原始文本补全raw text completion实现的基于函数调用的流式尚未实现。因此使用 partial streaming 时必须设置modeinstructor.Mode.MD_JSON。import instructor from pydantic import BaseModel client instructor.from_provider( cerebras/gpt-oss-120b, modeinstructor.Mode.MD_JSON, ) class Person(BaseModel): name: str age: int resp client.create_partial( messages[ { role: user, content: Ivan is 27 and lives in Singapore, } ], response_modelPerson, streamTrue, ) for person in resp: print(person) # nameNone ageNone # nameIvan ageNone # nameIvan age27可以看到流式迭代过程中字段逐渐从None被填充为最终值——这适合对延迟敏感、需要边接收边渲染的场景。Iterable 示例批量提取同构对象import instructor from pydantic import BaseModel client instructor.from_provider( cerebras/gpt-oss-120b, modeinstructor.Mode.MD_JSON, ) class Person(BaseModel): name: str age: int resp client.create_iterable( messages[ { role: user, content: Extract all users from this sentence : Chris is 27 and lives in San Francisco, John is 30 and lives in New York while their college roommate Jessica is 26 and lives in London, } ], response_modelPerson, streamTrue, ) for person in resp: print(person) # Person(nameChris, age27) # Person(nameJohn, age30) # Person(nameJessica, age26)create_iterable返回一个个独立的Person实例适合新闻实体抽取、批量分类等场景。Instructor Hooks校验失败回调Instructor 提供钩子机制用于定制行为。例如监听parse:error事件在解析/校验失败时得到回调import instructor def validation_hook(error: Exception) - None: print(fValidation failed: {error}) client instructor.from_provider(cerebras/gpt-oss-120b) client.on(parse:error, validation_hook)当模型输出无法被解析成目标 Pydantic 模型时validation_hook会被触发便于接入告警、日志或自定义兜底逻辑。模式Mode详解与推荐Instructor 为 Cerebras 提供了多种模式以适配 Cerebras 支持的响应方式instructor.Mode.MD_JSON将原始补全解析为合法 JSON 对象instructor.Mode.TOOLS使用 Cerebras 的工具调用tool calling能力返回结构化输出。一般推荐使用Mode.TOOLS它最灵活、最具前瞻性能支持的 Schema 表达范围最大使用上也更省心。源码层面印证了这一点from_cerebras的默认模式即为Mode.TOOLSinstructor/v2/providers/cerebras/client.pyCerebras 使用 OpenAI 兼容 API其 handler 复用instructor.v2.providers.openai.handlersprovider 规格表中 Cerebras 支持TOOLS、JSON_SCHEMA、MD_JSON、PARALLEL_TOOLS四种模式不支持RESPONSES_TOOLSinstructor/v2/core/provider_specs.py历史遗留的Mode.CEREBRAS_TOOLS、Mode.CEREBRAS_JSON会被自动归一化为Mode.TOOLS、Mode.MD_JSON见 instructor/v2/core/mode.py 与 provider_specs 的legacy_modes映射旧代码无需改动即可继续工作。源码架构Cerebras provider 是如何实现的兼容门面instructor/providers/cerebras/目录是面向旧 import 路径的兼容层client.py直接转导出 v2 的from_cerebrasinstructor/providers/cerebras/client.py同时instructor/__init__.py也把from_cerebras注册为可选导出v2 客户端工厂from_cerebras依次完成 SDK 存在性检查、模式归一化与注册校验、客户端类型校验必须是Cerebras或AsyncCerebras实例、取出client.chat.completions.create并patch_v2最后按客户端类型返回Instructor或AsyncInstructor统一自动客户端instructor.from_provider(cerebras/...)会走到auto_client._build_cerebras自动构造带api_key的 Cerebras 客户端并调用from_cerebrasSDK 缺失时抛出带安装提示的ConfigurationErrorinstructor/v2/auto_client.pyprovider 注册表Cerebras 的别名、SDK 模块、默认 provider 字符串cerebras/gpt-oss-120b、支持/不支持的模式等均登记在 instructor/v2/core/provider_specs.py内置模型候选instructor/models.py 中内置了cerebras/llama-4-scout-17b-16e-instruct、cerebras/llama3.1-8b、cerebras/llama-3.3-70b等模型供自动客户端选用具体可用模型以你的 Cerebras 账号配额为准测试佐证仓库通过tests/coverage/test_provider_clients_coverage.py断言 Cerebras 走/v1/chat/completions端点、tests/coverage/test_auto_client_tail_coverage.py验证_build_cerebras的导入与构造路径以及tests/docs/test_current_provider_guides.py校验本文档与实现的一致性共同保障集成正确性。注意事项与最佳实践API Key通过CEREBRAS_API_KEY环境变量提供或在from_provider时显式传入SDK 未安装时按提示pip install cerebras-cloud-sdk即可。参数互斥max_completion_tokens与max_tokens不要同时发送。流式模式约束partial streaming 与create_iterable当前需配合modeinstructor.Mode.MD_JSON基于函数调用的流式尚未实现使用前请确认这一点。模式选择无特殊需求优先Mode.TOOLS其 Schema 表达能力最强且是默认模式已有代码中的CEREBRAS_TOOLS/CEREBRAS_JSON旧模式会自动归一化无需迁移。模型选择文档示例使用cerebras/gpt-oss-120b也可按需改为cerebras/llama-3.3-70b等型号只要模型支持对应的请求参数即可。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用 Instructor 与 Cerebras 硬件加速模型构建类型安全的结构化输出
使用 Instructor 与 Cerebras 硬件加速模型构建类型安全的结构化输出【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorCerebras 面向高性能计算环境提供硬件加速 AI 模型而 Instructor 负责把模型的原始输出转换为经过 Pydantic 校验的类型安全响应。本文以 docs/integrations/cerebras.md 为骨架结合仓库源码完整讲解从安装、请求参数、同步/异步调用到流式与 Hooks 的 Cerebras 集成实战读完即可在 Cerebras 上落地可靠的结构化数据提取。Cerebras 与 Instructor 的组合价值Cerebras 提供硬件加速的推理服务模型走 OpenAI 兼容的 Chat Completions 接口Instructor 在此基础上补齐了结构化这一环——通过 Pydantic 模型定义输出 Schema由客户端负责把模型响应解析、校验并重试最终返回BaseModel实例而非字符串。两者的分工让开发者可以只关注我要什么结构而把 JSON 解析、字段校验、错误重试等脏活交给 Instructor。从源码看Cerebras 在 Instructor 中属于注册在案的官方 providerinstructor/v2/core/provider_specs.py中为其登记了别名cerebras、SDK 模块cerebras.cloud.sdk以及支持的运行模式详见后文模式详解因此既可以通过instructor.from_provider(cerebras/...)一行式创建客户端也可以手动构造 Cerebras SDK 客户端后再交给from_cerebras。快速开始安装安装带 Cerebras 支持的 Instructorpip install instructor[cerebras_cloud_sdk]该 extra 会拉取cerebras-cloud-sdk。如果 SDK 缺失from_cerebras工厂会直接抛出ClientError提示先执行pip install cerebras-cloud-sdk见 instructor/v2/providers/cerebras/client.py。调用时需要 Cerebras API Key。使用from_provider创建客户端时工厂会构造Cerebras(api_keyapi_key)或AsyncCerebras(api_keyapi_key)见 instructor/v2/auto_client.pyAPI Key 默认来自CEREBRAS_API_KEY环境变量tests/llm/shared_config.py中即为该 provider 登记了此变量名。Cerebras 请求参数详解client.create(...)中的额外关键字参数会被 Instructor 原样转发给 Cerebras SDK因此无需退回泛化的 OpenAI 客户端即可使用 Cerebras 专属请求参数。官方文档给出如下示例import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int client instructor.from_provider(cerebras/gpt-oss-120b) resp client.create( messages[{role: user, content: Return a short user record.}], response_modelUser, max_completion_tokens256, reasoning_effortnone, seed42, )需要特别留意的参数约束max_completion_tokens是规范的输出长度上限兼容别名max_tokens会被单独转发因此同一个请求中不要同时发送这两个字段否则可能产生歧义。temperature、top_p、stop、response_format、parallel_tool_calls、log probabilitieslogprobs以及各类 penalties 等 Cerebras 参数在所选模型支持的前提下都可以按同样方式传入。从源码机制上看from_cerebras工厂取出的是client.chat.completions.create再经由patch_v2包装后作为 Instructor 的create使用instructor/v2/providers/cerebras/client.py因此请求参数的自然透传是这一设计带来的直接结果。关于当前请求 Schema 的完整字段请以 Cerebras 官方 API 参考文档Chat Completions为准。同步调用最简单的结构化提取import instructor from pydantic import BaseModel client instructor.from_provider(cerebras/gpt-oss-120b) class User(BaseModel): name: str age: int # Create structured output resp client.create( messages[ { role: user, content: Extract the name and age of the person in this sentence: John Smith is 29 years old., } ], response_modelUser, ) print(resp) # User(nameJohn Smith, age29)response_modelUser即声明了输出 SchemaInstructor 会把它转换为模型可理解的格式JSON Schema 或工具定义并把返回内容解析、校验成User实例之后便可以直接以属性方式访问resp.name、resp.age。异步调用通过async_clientTrue获得异步客户端随后在 async 函数中await client.create(...)import instructor from pydantic import BaseModel import asyncio client instructor.from_provider( cerebras/gpt-oss-120b, async_clientTrue, ) class User(BaseModel): name: str age: int async def extract_user(): resp await client.create( messages[ { role: user, content: Extract the name and age of the person in this sentence: John Smith is 29 years old., } ], response_modelUser, ) return resp # Run async function resp asyncio.run(extract_user()) print(resp) # User(nameJohn Smith, age29)底层_build_cerebras在async_clientTrue时会构造AsyncCerebras并交由from_cerebras返回AsyncInstructor同步路径则返回Instructor两者由from_cerebras的 overload 签名与实例分派保证类型一致instructor/v2/providers/cerebras/client.py。嵌套模型一次请求提取多层结构response_model支持嵌套 Pydantic 模型Cerebras 侧会以单次调用返回完整嵌套结构from pydantic import BaseModel import instructor client instructor.from_provider(cerebras/gpt-oss-120b) class Address(BaseModel): street: str city: str country: str class User(BaseModel): name: str age: int addresses: list[Address] # Create structured output with nested objects 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 # } # ] # }嵌套 列表组合list[Address]适合地址簿、订单、简历等一对多数据的单次抽取。流式支持Instructor 提供两种流式方式适用场景不同Iterables流式返回同类型对象的列表适合一次抽取多个实体如多个用户Partial Streaming流式返回单个对象并在响应到达时立即开始处理字段逐步填充。重要前提目前 Cerebras 的 partial streaming 是通过解析原始文本补全raw text completion实现的基于函数调用的流式尚未实现。因此使用 partial streaming 时必须设置modeinstructor.Mode.MD_JSON。import instructor from pydantic import BaseModel client instructor.from_provider( cerebras/gpt-oss-120b, modeinstructor.Mode.MD_JSON, ) class Person(BaseModel): name: str age: int resp client.create_partial( messages[ { role: user, content: Ivan is 27 and lives in Singapore, } ], response_modelPerson, streamTrue, ) for person in resp: print(person) # nameNone ageNone # nameIvan ageNone # nameIvan age27可以看到流式迭代过程中字段逐渐从None被填充为最终值——这适合对延迟敏感、需要边接收边渲染的场景。Iterable 示例批量提取同构对象import instructor from pydantic import BaseModel client instructor.from_provider( cerebras/gpt-oss-120b, modeinstructor.Mode.MD_JSON, ) class Person(BaseModel): name: str age: int resp client.create_iterable( messages[ { role: user, content: Extract all users from this sentence : Chris is 27 and lives in San Francisco, John is 30 and lives in New York while their college roommate Jessica is 26 and lives in London, } ], response_modelPerson, streamTrue, ) for person in resp: print(person) # Person(nameChris, age27) # Person(nameJohn, age30) # Person(nameJessica, age26)create_iterable返回一个个独立的Person实例适合新闻实体抽取、批量分类等场景。Instructor Hooks校验失败回调Instructor 提供钩子机制用于定制行为。例如监听parse:error事件在解析/校验失败时得到回调import instructor def validation_hook(error: Exception) - None: print(fValidation failed: {error}) client instructor.from_provider(cerebras/gpt-oss-120b) client.on(parse:error, validation_hook)当模型输出无法被解析成目标 Pydantic 模型时validation_hook会被触发便于接入告警、日志或自定义兜底逻辑。模式Mode详解与推荐Instructor 为 Cerebras 提供了多种模式以适配 Cerebras 支持的响应方式instructor.Mode.MD_JSON将原始补全解析为合法 JSON 对象instructor.Mode.TOOLS使用 Cerebras 的工具调用tool calling能力返回结构化输出。一般推荐使用Mode.TOOLS它最灵活、最具前瞻性能支持的 Schema 表达范围最大使用上也更省心。源码层面印证了这一点from_cerebras的默认模式即为Mode.TOOLSinstructor/v2/providers/cerebras/client.pyCerebras 使用 OpenAI 兼容 API其 handler 复用instructor.v2.providers.openai.handlersprovider 规格表中 Cerebras 支持TOOLS、JSON_SCHEMA、MD_JSON、PARALLEL_TOOLS四种模式不支持RESPONSES_TOOLSinstructor/v2/core/provider_specs.py历史遗留的Mode.CEREBRAS_TOOLS、Mode.CEREBRAS_JSON会被自动归一化为Mode.TOOLS、Mode.MD_JSON见 instructor/v2/core/mode.py 与 provider_specs 的legacy_modes映射旧代码无需改动即可继续工作。源码架构Cerebras provider 是如何实现的兼容门面instructor/providers/cerebras/目录是面向旧 import 路径的兼容层client.py直接转导出 v2 的from_cerebrasinstructor/providers/cerebras/client.py同时instructor/__init__.py也把from_cerebras注册为可选导出v2 客户端工厂from_cerebras依次完成 SDK 存在性检查、模式归一化与注册校验、客户端类型校验必须是Cerebras或AsyncCerebras实例、取出client.chat.completions.create并patch_v2最后按客户端类型返回Instructor或AsyncInstructor统一自动客户端instructor.from_provider(cerebras/...)会走到auto_client._build_cerebras自动构造带api_key的 Cerebras 客户端并调用from_cerebrasSDK 缺失时抛出带安装提示的ConfigurationErrorinstructor/v2/auto_client.pyprovider 注册表Cerebras 的别名、SDK 模块、默认 provider 字符串cerebras/gpt-oss-120b、支持/不支持的模式等均登记在 instructor/v2/core/provider_specs.py内置模型候选instructor/models.py 中内置了cerebras/llama-4-scout-17b-16e-instruct、cerebras/llama3.1-8b、cerebras/llama-3.3-70b等模型供自动客户端选用具体可用模型以你的 Cerebras 账号配额为准测试佐证仓库通过tests/coverage/test_provider_clients_coverage.py断言 Cerebras 走/v1/chat/completions端点、tests/coverage/test_auto_client_tail_coverage.py验证_build_cerebras的导入与构造路径以及tests/docs/test_current_provider_guides.py校验本文档与实现的一致性共同保障集成正确性。注意事项与最佳实践API Key通过CEREBRAS_API_KEY环境变量提供或在from_provider时显式传入SDK 未安装时按提示pip install cerebras-cloud-sdk即可。参数互斥max_completion_tokens与max_tokens不要同时发送。流式模式约束partial streaming 与create_iterable当前需配合modeinstructor.Mode.MD_JSON基于函数调用的流式尚未实现使用前请确认这一点。模式选择无特殊需求优先Mode.TOOLS其 Schema 表达能力最强且是默认模式已有代码中的CEREBRAS_TOOLS/CEREBRAS_JSON旧模式会自动归一化无需迁移。模型选择文档示例使用cerebras/gpt-oss-120b也可按需改为cerebras/llama-3.3-70b等型号只要模型支持对应的请求参数即可。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
