第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 是显而易见的选择。
立即开始 →