{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Instructor

使用 Pydantic 验证从 LLM 响应中提取结构化数据，自动重试失败的提取，以类型安全方式解析复杂 JSON，并使用 Instructor 流式传输部分结果——经过实战检验的结构化输出库

Skill 元数据


来源	可选 — 通过 `hermes skills install official/mlops/instructor` 安装
路径	`optional-skills/mlops/instructor`
版本	`1.0.0`
作者	Orchestra Research
许可证	MIT
依赖项	`instructor`, `pydantic`, `openai`, `anthropic`
平台	linux, macos, windows
标签	`Prompt Engineering`, `Instructor`, `Structured Output`, `Pydantic`, `Data Extraction`, `JSON Parsing`, `Type Safety`, `Validation`, `Streaming`, `OpenAI`, `Anthropic`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。

Instructor：结构化 LLM 输出

何时使用此 Skill

在以下情况下使用 Instructor：

从 LLM 响应中可靠地提取结构化数据

根据 Pydantic schema 自动验证输出

通过自动错误处理重试失败的提取

以类型安全和验证方式解析复杂 JSON

流式传输部分结果以进行实时处理

以一致的 API 支持多个 LLM 提供商

GitHub Stars：15,000+｜实战检验：100,000+ 开发者

安装

快速开始

基础示例：提取用户数据

使用 OpenAI

核心概念

1. 响应模型（Pydantic）

响应模型定义 LLM 输出的结构和验证规则。

基础模型

优势：

使用 Python 类型提示保证类型安全

自动验证（word_count > 0）

通过 Field 描述实现自文档化

IDE 自动补全支持

嵌套模型

可选字段

使用枚举约束值

2. 验证

Pydantic 自动验证 LLM 输出。若验证失败，Instructor 会自动重试。

内置验证器

自定义验证器

模型级验证

3. 自动重试

当验证失败时，Instructor 会自动重试，并将错误反馈提供给 LLM。

工作原理：

LLM 生成输出

Pydantic 进行验证

若无效：将错误信息发回给 LLM

LLM 根据错误反馈重新尝试

重复直至达到 max_retries 次数

4. 流式传输

流式传输部分结果以进行实时处理。

流式传输部分对象

流式传输可迭代对象

提供商配置

Anthropic Claude

OpenAI

本地模型（Ollama）

常用模式

模式 1：从文本中提取数据

模式 2：分类

模式 3：多实体提取

模式 4：结构化分析

模式 5：批量处理

高级特性

联合类型

动态模型

自定义模式

上下文管理

错误处理

处理验证错误

自定义错误信息

最佳实践

1. 清晰的字段描述

2. 使用适当的验证

3. 在 prompt（提示词）中提供示例

4. 对固定类别使用枚举

5. 优雅处理缺失数据

与其他方案的对比

特性	Instructor	手动 JSON	LangChain	DSPy
类型安全	✅ 是	❌ 否	⚠️ 部分	✅ 是
自动验证	✅ 是	❌ 否	❌ 否	⚠️ 有限
自动重试	✅ 是	❌ 否	❌ 否	✅ 是
流式传输	✅ 是	❌ 否	✅ 是	❌ 否
多提供商	✅ 是	⚠️ 手动	✅ 是	✅ 是
学习曲线	低	低	中	高

何时选择 Instructor：

需要结构化、经过验证的输出

需要类型安全和 IDE 支持

需要自动重试

构建数据提取系统

何时选择其他方案：

DSPy：需要 prompt 优化

LangChain：构建复杂链路

手动：简单的一次性提取

资源

文档：https://python.useinstructor.com

GitHub：https://github.com/jxnl/instructor（15k+ stars）

Cookbook：https://python.useinstructor.com/examples

Discord：提供社区支持

另请参阅

references/validation.md — 高级验证模式

references/providers.md — 提供商专项配置

references/examples.md — 真实使用案例

"Instructor"

Instructor#

Skill 元数据#

参考：完整 SKILL.md#

Instructor：结构化 LLM 输出#

何时使用此 Skill#

安装#

快速开始#

基础示例：提取用户数据#

使用 OpenAI#

核心概念#

1. 响应模型（Pydantic）#

基础模型#

嵌套模型#

可选字段#

使用枚举约束值#

2. 验证#

内置验证器#

自定义验证器#

模型级验证#

3. 自动重试#

4. 流式传输#

流式传输部分对象#

流式传输可迭代对象#

提供商配置#

Anthropic Claude#

OpenAI#

本地模型（Ollama）#

常用模式#

模式 1：从文本中提取数据#

模式 2：分类#

模式 3：多实体提取#

模式 4：结构化分析#

模式 5：批量处理#

高级特性#

联合类型#

动态模型#

自定义模式#

上下文管理#

错误处理#

处理验证错误#

自定义错误信息#

最佳实践#

1. 清晰的字段描述#

2. 使用适当的验证#

3. 在 prompt（提示词）中提供示例#

4. 对固定类别使用枚举#

5. 优雅处理缺失数据#

与其他方案的对比#

资源#

另请参阅#

Instructor

Skill 元数据

参考：完整 SKILL.md

Instructor：结构化 LLM 输出

何时使用此 Skill

安装

快速开始

基础示例：提取用户数据

使用 OpenAI

核心概念

1. 响应模型（Pydantic）

基础模型

嵌套模型

可选字段

使用枚举约束值

2. 验证

内置验证器

自定义验证器

模型级验证

3. 自动重试

4. 流式传输

流式传输部分对象

流式传输可迭代对象

提供商配置

Anthropic Claude

OpenAI

本地模型（Ollama）

常用模式

模式 1：从文本中提取数据

模式 2：分类

模式 3：多实体提取

模式 4：结构化分析

模式 5：批量处理

高级特性

联合类型

动态模型

自定义模式

上下文管理

错误处理

处理验证错误

自定义错误信息

最佳实践

1. 清晰的字段描述

2. 使用适当的验证

3. 在 prompt（提示词）中提供示例

4. 对固定类别使用枚举

5. 优雅处理缺失数据

与其他方案的对比

资源

另请参阅