进阶 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 模型一样简单。其他一切都由此衍生。

评论 (0)