进阶 python.useinstructor.com 2026-11-15 16:34:59 · 11 阅读
第14章 设计哲学
哲学¶ 优秀的工具让困难的事情变得简单,同时不让简单的事情变得复杂。这就是 Instructor。从开发者熟悉的东西开始¶ 大多数 AI 框架会发明自己的抽象层,但我们不会。
import instructor
from pydantic import BaseModel
# 你已知的部分(Pydantic)
class User(BaseModel):
name: str
age: int
# Instructor 新增的部分
client = instructor.from_provider("openai/gpt-4.1-mini")
_user = client.create(
response_model=User,
messages=[{"role": "user", "content": "Jane is 33"}],
) # 就这么简单
如果你懂 Pydantic,你就懂 Instructor。没有新概念,没有新语法,也没有 200 页的手册。你的逃生舱口永远都在¶ 最糟糕的框架就像蟑螂旅馆——进容易,出难。Instructor 不同:
import instructor
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
# 使用 Instructor
client = instructor.from_provider("openai/gpt-4.1-mini")
_result = client.create(
response_model=User,
messages=[{"role": "user", "content": "Jane is 33"}],
)
# 想回到原始 API?只需移除 response_model:
client = instructor.from_provider("openai/gpt-4.1-mini")
_result = client.create(messages=[{"role": "user", "content": "Say hello"}])
# 或者直接使用该提供商:
from openai import OpenAI
_raw_client = OpenAI() # 回到原生状态
我们是补丁,不是包装。你的代码,你掌控。展示,而非隐藏¶ 糟糕的框架隐藏复杂度,好的工具帮助你理解它。
import instructor
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
# 查看 Instructor 实际发送的内容
instructor.logfire.configure() # 全面可观测性
client = instructor.from_provider("openai/gpt-4.1-mini")
result = client.create(
response_model=User,
messages=[{"role": "user", "content": "Jane is 33"}],
)
# 访问原始响应
_raw_response = result._raw_response # 查看 LLM 实际返回了什么
当出错时(而且肯定会出错),你可以看清究竟发生了什么。组合优于配置¶ 没有 YAML 文件。没有装饰器。没有魔法。只有函数。
import instructor
from pydantic import BaseModel
client = instructor.from_provider("openai/gpt-4.1-mini")
class User(BaseModel):
name: str
age: int
class Company(BaseModel):
name: str
industry: str
class Analysis(BaseModel):
user: User
company: Company
# 用简单函数构建复杂系统
def extract_user(text: str) -> User:
return client.create(
response_model=User, messages=[{"role": "user", "content": text}]
)
def extract_company(text: str) -> Company:
return client.create(
response_model=Company, messages=[{"role": "user", "content": text}]
)
def analyze_email(email: str) -> Analysis:
user = extract_user(email)
company = extract_company(email)
return Analysis(user=user, company=company)
# 按你的应用需求进行组合
_analysis = analyze_email("Please introduce Jane from Acme.")
从简单开始,自然成长¶ 最好的代码是随需求一同成长的代码:
import instructor
from instructor import Partial
from pydantic import BaseModel, field_validator
client = instructor.from_provider("openai/gpt-4.1-mini")
class User(BaseModel):
name: str
age: int
# 第 1 天:先跑通
_user = client.create(
response_model=User,
messages=[{"role": "user", "content": "Jane is 33"}],
)
# 第 7 天:添加验证
class User(BaseModel):
name: str
age: int
@field_validator("age")
def check_age(cls, value: int) -> int:
if value < 0 or value > 150:
raise ValueError("Invalid age")
return value
# 第 14 天:为生产环境添加重试
_user = client.create(
response_model=User,
messages=[{"role": "user", "content": "Jane is 33"}],
max_retries=3,
)
# 第 30 天:添加流式传输以改善用户体验
def update_ui(_partial: Partial[User]) -> None:
pass
for partial in client.create(
response_model=Partial[User],
messages=[{"role": "user", "content": "Jane is 33"}],
stream=True,
):
update_ui(partial)
每次添加只需一行代码。无需重构。无需迁移指南。我们刻意不做什么¶ 不做提示词工程¶ 我们不替写 prompt。你比我们要更了解你的领域。
# 我们不这样做:
# @instructor.prompt("Extract the user information carefully")
# def extract_user(text: str):
# ...
# 你自己写 prompt:
text = "Jane is 33"
_messages = [
{"role": "system", "content": "You are a precise data extractor"},
{"role": "user", "content": f"Extract user from: {text}"},
]
不引入新抽象¶ 我们不发明诸如“Agents”、“Chains”或“Tools”这样的概念。那些属于你的领域概念。
import instructor
from pydantic import BaseModel
# 我们不这样做:
# class UserExtractionAgent(instructor.Agent):
# tools = [instructor.WebSearch(), instructor.Calculator()]
class User(BaseModel):
name: str
age: int
def search_web(query: str) -> str:
return f"Results for {query}"
client = instructor.from_provider("openai/gpt-4.1-mini")
# 你构建你觉得合理的部分:
def extract_user_with_search(query: str) -> User:
# 你的逻辑,你的方式
search_results = search_web(query)
return client.create(
response_model=User, messages=[{"role": "user", "content": search_results}]
)
_user = extract_user_with_search("Find Jane")
无框架锁定¶ 你的代码应该在有或没有我们的情况下都能工作:
import instructor
from pydantic import BaseModel
# 这只是个 Pydantic 模型
class User(BaseModel):
name: str
age: int
# 这只是个函数
def process_user(user: User) -> dict:
return {"name": user.name.upper(), "adult": user.age >= 18}
client = instructor.from_provider("openai/gpt-4.1-mini")
# Instructor 只是将它们连接到 LLM
user = client.create(
response_model=User,
messages=[{"role": "user", "content": "Jane is 33"}],
)
_result = process_user(user) # 有或没有 Instructor 都能工作
结果¶ 遵循这些原则,我们得到:
- 极小的 API 表面:几分钟学会,而非几天
- 零供应商锁定:随时切换提供商或移除 Instructor
- 可调试:当东西坏掉时,你知道为什么
- 可组合:用简单部件构建复杂系统
- Pythonic:如果在 Python 里感觉自然,在 Instructor 里也感觉自然
实践¶ 使用 Instructor 构建实际应用看起来是这样的:
from enum import Enum
from typing import List
import instructor
from pydantic import BaseModel
# 你的领域模型(而非我们的)
class Priority(str, Enum):
HIGH = "high"
MEDIUM = "medium"
LOW = "low"
class Ticket(BaseModel):
title: str
description: str
priority: Priority
estimated_hours: float
# 你的业务逻辑(而非我们的)
def prioritize_tickets(tickets: List[Ticket]) -> List[Ticket]:
return sorted(tickets, key=lambda t: (t.priority.value, -t.estimated_hours))
# 连接 LLM(一行代码)
client = instructor.from_provider("openai/gpt-4.1-mini")
# 提取结构化数据(简单的函数调用)
tickets = client.create(
response_model=List[Ticket],
messages=[{"role": "user", "content": "Parse these support tickets: ..."}],
)
# 使用你的业务逻辑
_prioritized = prioritize_tickets(tickets)
没有框架。没有抽象。只有 Python。一句话概括其哲学¶ 让结构化 LLM 输出像定义 Pydantic 模型一样简单。其他一切都由此衍生。