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

第10章 为什么要用 Instructor?

为什么要用 Instructor?

你用 LLM 构建了一个应用,但有 15% 的概率它会返回乱码。解析 JSON 简直是场噩梦,不同提供商的 API 也五花八门。肯定有更简单的办法。

非结构化输出的痛点

诚实地说,和 LLM 打交道的现实是这样的:

# 你期望的代码: user_info = extract_user("John is 25 years old") print(user_info.name) # "John" print(user_info.age) # 25

# 实际得到的结果: response = llm.complete("Extract: John is 25 years old") # "我很乐意帮忙!根据文本,用户名是 John,年龄是 25。还有什么需要提取的吗?"

# 接下来你得手动: # 1. 想办法解析这段文本 # 2. 处理 JSON 语法错误 # 3. 验证数据是否符合预期 # 4. 在失败时重试(它总会失败) # 5. 为每个 LLM 提供商写不同的逻辑

Instructor 的区别

用 Instructor 完成同样的任务只需几行代码:

import instructor from pydantic import BaseModel

class User(BaseModel): name: str age: int

client = instructor.from_provider("openai/gpt-5.4-mini") user = client.create( response_model=User, messages=[{"role": "user", "content": "John is 25 years old"}], )

print(user.name) # "John" print(user.age) # 25

就这样。无需解析,无需重试,无需针对特定提供商的代码。

Instructor 解决的现实问题

1. “它 90% 的时间都能正常工作”

不用 Instructor 时,LLM 大多数时候返回完美的 JSON。但那 10% 的成功率可能会让你周末泡汤。

# 没有 Instructor:容易随机崩溃的脆弱代码 try: data = json.loads(llm_response) user = User(data) # KeyError: 'name' except: # 接下来怎么办?重试?解析文本?放弃? pass

# 使用 Instructor:自动重试并附带验证错误 user = client.create( response_model=User, messages=[{"role": "user", "content": "..."}], max_retries=3, # 重试时包含验证错误信息 ) # 始终返回有效的 User 对象,或抛出清晰的异常

2. “每个提供商都不一样”

每个 LLM 提供商都有自己的 API,你的代码会变成一堆 if-else 的混乱组合。

# 没有 Instructor:针对提供商的意大利面代码 if provider == "openai": response = openai.chat.completions.create( tools=[{"type": "function", "function": {...}}] ) data = json.loads(response.choices[0].message.tool_calls[0].function.arguments) elif provider == "anthropic": response = anthropic.messages.create( tools=[{"name": "extract", "input_schema": {...}}] ) data = response.content[0].input elif provider == "google": # ... 又是不同的 API

# 使用 Instructor:所有提供商统一 API client = instructor.from_provider("openai/gpt-5.4-mini") # 或者 client = instructor.from_provider("anthropic/claude-3") # 或者 client = instructor.from_provider("google/gemini-pro")

# 所有提供商使用相同代码 user = client.create( response_model=User, messages=[{"role": "user", "content": "..."}], )

3. “复杂数据结构不可能实现”

嵌套对象、列表、枚举——LLM 在处理复杂 schema 时往往力不从心。

# 没有 Instructor:祝你好运 schema = { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string"}, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street": {"type": "string"}, "city": {"type": "string"} } } } } } } } }

# 使用 Instructor:直接用 Python from typing import List

class Address(BaseModel): street: str city: str

class User(BaseModel): name: str addresses: List[Address]

class UserList(BaseModel): users: List[User]

# 完美运行 result = client.create( response_model=UserList, messages=[{"role": "user", "content": "..."}], )

不用 Instructor 的代价

让我们算算实际账:

浪费时间: - 实现 JSON 解析和验证:2-3 小时 - 调试边缘案例:4-6 小时 - 每添加一个新提供商:2-3 小时 - API 变更带来的持续维护成本

生产环境 Bug: - 格式错误的 JSON 导致应用崩溃 - 缺失字段引发静默失败 - 类型不匹配损坏数据库 - 客户抱怨可靠性差

开发者挫败感: - “测试时明明好的!” - “为什么这次 JSON 不一样?” - “返回的是字符串而不是数字怎么办?”

开发者们怎么说

基于我们的 GitHub issues 和 Discord 社区反馈:

- “LLM 代码量减少了 80%” —— 常见反馈 - “终于有了可以信任的 LLM 输出” —— 来自生产用户 - “光是有重试机制就值得” —— 节省了处理边缘案例的时间 - “每个提供商体验完全一致” —— 不再受提供商锁定

现在开始,日后感谢自己

没有 Instructor 的每一天,就意味着更多: - 调试格式错误的 JSON - 编写特定提供商的代码 - 手动处理验证 - 向 PM 解释为什么 LLM 集成不稳定

安装 Instructor: pip install instructor

30 秒上手: import instructor from pydantic import BaseModel

client = instructor.from_provider("openai/gpt-5.4-mini")

class User(BaseModel): name: str age: int

user = client.create( response_model=User, messages=[{"role": "user", "content": "John is 25 years old"}], )

print(user) # User(name='John', age=25)

何时不用 Instructor

说清楚一点,如果你有这些情况,可能不需要 Instructor: - 只需要原始文本响应(聊天机器人、创意写作) - 正在写一次性脚本且无需错误处理 - 喜欢在凌晨 3 点调试 JSON 解析错误

对于其他正在构建生产级 LLM 应用的开发者来说,Instructor 是显而易见的选择。

立即开始 →

评论 (0)