第9章 Instructor 入门指南:快速上手
使用 Instructor 快速上手
本指南将带你了解如何使用 Instructor 从语言模型中提取结构化数据。读完后,你能够掌握以下技能:
- 安装并配置 Instructor - 提取基础结构化数据 - 处理数据验证与错误 - 使用流式响应 - 接入不同的 LLM 提供商
安装
首先,安装 Instructor:
``` pip install instructor ```
若要使用特定提供商,请安装对应的附加包:
Instructor 核心安装仅包含必需的依赖项。各提供商的 SDK 属于可选依赖,需显式安装。
``` # OpenAI(默认包含) pip install instructor
# Anthropic pip install "instructor[anthropic]"
# 其他提供商 pip install "instructor[google-genai]" # Google/Gemini pip install "instructor[vertexai]" # Vertex AI pip install "instructor[cohere]" # Cohere pip install "instructor[litellm]" # LiteLLM(支持多家提供商) pip install "instructor[mistral]" # Mistral pip install "instructor[xai]" # xAI ```
配置环境
请通过环境变量设置 API 密钥:
``` # OpenAI export OPENAI_API_KEY=your_openai_api_key
# Anthropic export ANTHROPIC_API_KEY=your_anthropic_api_key
# 其他提供商,设置相应的 API 密钥 ```
第一个结构化输出示例
我们从 OpenAI 的一个简单例子入手:
```python import instructor from pydantic import BaseModel
# 定义输出结构 class UserInfo(BaseModel): name: str age: int
# 使用 from_provider 创建 instructor 客户端 client = instructor.from_provider("openai/gpt-5-nano")
# 提取结构化数据 user_info = client.create( response_model=UserInfo, messages=[ {"role": "user", "content": "John Doe is 30 years old."} ], )
print(f"Name: {user_info.name}, Age: {user_info.age}") # 输出: Name: John Doe, Age: 30 ```
这个例子展示了核心工作流:
1. 使用 Pydantic 模型定义输出结构 2. 使用 from_provider 创建 Instructor 客户端 3. 通过 response_model 参数请求结构化输出
数据验证与错误处理
Instructor 利用 Pydantic 的验证机制确保数据符合要求:
```python from pydantic import BaseModel, Field, field_validator
class User(BaseModel): name: str age: int = Field(gt=0, lt=120) # 年龄必须在 0 到 120 之间
@field_validator('name') def name_must_have_space(cls, v): if ' ' not in v: raise ValueError('姓名必须包含名和姓') return v
# 若验证失败,LLM 会自动重试 user = client.create( response_model=User, messages=[ {"role": "user", "content": "Extract: Tom is 25 years old."} ], ) ```
处理复杂模型
Instructor 与嵌套的 Pydantic 模型无缝协作:
```python from pydantic import BaseModel from typing import List
class Address(BaseModel): street: str city: str state: str zip_code: str
class Person(BaseModel): name: str age: int addresses: List[Address]
person = client.create( response_model=Person, messages=[ {"role": "user", "content": """ Extract: John Smith is 35 years old. He has homes at 123 Main St, Springfield, IL 62704 and 456 Oak Ave, Chicago, IL 60601. """} ], ) ```
流式响应
对于较大的响应或为了提升用户体验,可使用流式处理:
```python from instructor import Partial
# 在生成过程中流式返回响应 stream = client.create_partial( response_model=Person, messages=[ {"role": "user", "content": "Extract a detailed person profile for John Smith, 35, who lives in Chicago and Springfield."} ], )
for partial in stream: # 逐步展示响应构建过程 print(partial) ```
使用不同提供商
Instructor 支持多家 LLM 提供商。以下是使用 Anthropic 的方式:
```python import instructor from pydantic import BaseModel
class UserInfo(BaseModel): name: str age: int
# 使用 from_provider 创建 instructor 客户端 client = instructor.from_provider("anthropic/claude-3-opus-20240229")
user_info = client.create( response_model=UserInfo, messages=[ {"role": "user", "content": "John Doe is 30 years old."} ], )
print(f"Name: {user_info.name}, Age: {user_info.age}") ```
常见问题
start-here.md 与 getting-started.md 有什么区别?
- Start Here:介绍 Instructor 是什么以及为何使用(概念性概述) - Getting Started:本指南——展示如何安装和使用 Instructor(实操步骤)
应该从哪家提供商入手?
OpenAI 因可靠性和广泛的社区支持,是初学者的热门选择。熟悉之后,可探索 Anthropic Claude、Google Gemini 或开源模型。
我需要了解 Pydantic 吗?
基础了解有帮助,但你可以从简单模型开始。Instructor 支持任何 Pydantic BaseModel,随着需求增长再学习高级特性。
能否在异步代码中使用 Instructor?
可以!创建客户端时设置 async_client=True:
```python client = instructor.from_provider("openai/gpt-4o", async_client=True) ```
然后使用 await client.create()。
验证失败怎么办?
Instructor 会自动携带验证反馈重试。你可以通过 max_retries 参数配置重试行为,详见“重试机制”。
查看全部 FAQ →
下一步
掌握基础之后,建议继续:
- 学习如何使用 from_provider 针对不同 LLM 提供商配置客户端 - 探索高级验证技巧以确保数据质量 - 查看 Cookbook 示例,了解实际应用 - 了解如何使用 hooks 进行监控与调试
仍在用旧式写法?
如果你正在使用 instructor.patch() 或 provider 专属函数如 from_openai(),请参考迁移指南以现代化你的代码。
刚接触 Instructor?
从 Start Here 开始,获取概念性概述。如需某一主题的深入信息,请访问 Concepts 章节。如有疑问或需要帮助,欢迎加入我们的 Discord 社区,或查看 GitHub 仓库。