Instructor

什么是 Instructor？

Instructor 是一个面向开发者的库，用于将 LLM 响应转换为结构化、类型化的数据。开发者使用 Pydantic 模型定义预期输出，然后将该模型传递给客户端请求。Instructor 会将模型转换为提供方可使用的模式，验证响应，在验证失败时重试，并返回类型化的 Pydantic 对象。

它专为以模式为先的数据提取而设计，而非智能体编排。Python 工作流支持嵌套模型、列表、枚举、可选字段、字段约束、自定义验证器、异步客户端、部分响应、流式处理、钩子以及访问原始补全结果。通过文档所述的集成方式，它可以与托管模型、路由服务和本地开源模型结合使用。

Instructor 能做什么？

Pydantic 响应模型

定义 LLM 响应中预期的字段、类型、约束和嵌套结构。

验证与重试

Instructor 会根据响应模型验证生成的数据，并可重试失败的请求；重试行为可通过 max_retries 和 Tenacity 进行配置。

多提供方接口

from_provider 为受支持的提供方提供通用的客户端初始化模式，同时各提供方特有的模式和功能仍分别记录在文档中。

流式处理与部分结果

create_partial 可在生成响应时逐步返回仅填充部分字段的模型，并且该库支持流式列表和可迭代响应。

提供方输出模式

根据提供方的支持情况，Instructor 可以使用工具调用、JSON 生成、JSON Schema、嵌入 Markdown 的 JSON 或并行工具调用。

同步与异步用法

Python 客户端支持普通调用，也支持通过 async_client=True 使用异步客户端。

使用场景

“从非结构化文本中提取字段”

将句子、文档片段或用户消息转换为类型化对象，例如包含姓名、年龄和职业字段的人员记录。

“解析嵌套的支持案例”

表示包含客户详情和经过验证的工单列表的客户支持案例，其中包括优先级、预计工时和字段级规则。

“处理长篇或增量输出”

在大型结构化响应生成期间使用模型的部分结果，而不必等待完整对象生成。

“构建 API 提取端点”

在 FastAPI 路由中使用 Instructor 客户端，使提交的文本以声明的 Pydantic 响应类型返回。

“切换模型或托管环境”

在云端提供方、路由层或通过 Ollama 提供服务的本地模型之间迁移时，继续使用响应模型工作流。

常见问题

如何安装 Instructor？

使用 `pip install instructor` 安装基础软件包。Anthropic 和 Google/Gemini 等集成提供特定于提供方的额外组件。

Instructor 如何将 LLM 响应转换为结构化数据？

将 Pydantic 类作为 `response_model` 提供。Instructor 会将该模型转换为兼容提供方的模式，格式化请求，验证响应，在验证失败时重试，并返回类型化对象。

可以使用开源模型或本地模型吗？

可以。文档介绍了通过 Ollama 和 llama-cpp-python 集成本地开源模型的方式，也介绍了其他提供方和路由集成。具体功能因提供方而异。

可以查看原始模型响应吗？

可以。`create_with_completion` 会同时返回解析后的 Pydantic 结果和原始补全结果。

Instructor 支持异步工作流吗？

支持。使用 `async_client=True` 初始化提供方，然后等待客户端的 `create` 调用。文档还提供了使用异步端点的 FastAPI 示例。