进阶 python.useinstructor.com 2026-11-15 16:34:59 · 11 阅读

第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 仓库。

评论 (0)