84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
---
|
||
title: "Pydantic 三件套：从校验库到 AI 基础设施"
|
||
created: 2026-06-10
|
||
updated: 2026-06-10
|
||
type: article
|
||
tags: [pydantic, agent, observability, open-telemetry, validation]
|
||
sources: [raw/articles/pydantic-three-piece-suite-2026.md]
|
||
---
|
||
|
||
# Pydantic 三件套：从校验库到 AI 基础设施
|
||
|
||
> 微信公众号 | 2026年
|
||
> Pydantic 不只是 BaseModel——Rust 验证引擎 + OTel 可观测平台 + 类型安全 Agent 框架
|
||
|
||
## TL;DR
|
||
|
||
- [[pydantic]] 生态三层：[[pydantic-core|Rust 引擎]] + [[logfire|Logfire 可观测]] + [[pydantic-ai|Pydantic AI Agent 框架]]
|
||
- **strict + forbid + frozen 三配置零成本立即生效**
|
||
- Logfire 四行代码接入，debug 从半天降到分钟级
|
||
- Pydantic AI 让类型系统约束 Agent 行为，而非仅事后校验
|
||
|
||
## 核心问题
|
||
|
||
LLM 时代的校验需求已经变了。人填的表单错误模式稳定，LLM 输出的 JSON 错误模式**漂移**——同样的 prompt 跑 100 次，第 1 次可能字段名少了条下划线，第 47 次可能多了个字段，第 89 次可能把 str 塞了 None。
|
||
|
||
传统的 BaseModel 只能告诉你「第 47 次错了」，但你需要的是 [[drift-detection|漂移检测]]——哪个字段一直在漂？哪个模型输出最不稳定？token 成本是不是偷偷在涨？
|
||
|
||
## 三件套全景
|
||
|
||
| 层 | 解决的问题 | 不用的话 |
|
||
|---|-----------|---------|
|
||
| [[pydantic-core|pydantic-core (Rust)]] | 校验速度 / 脱离 GIL | 多线程校验串行 |
|
||
| [[logfire|Logfire (OTel)]] | 可观测 / 成本监控 / 漂移检测 | 只知"第 47 次错" |
|
||
| [[pydantic-ai|Pydantic AI]] | Agent 行为约束 / 类型安全 tool 调用 | 手写 JSON Schema + 事后校验 |
|
||
|
||
三层独立，共享同一套类型定义。可任意叠加。
|
||
|
||
## 第一件：pydantic-core
|
||
|
||
Rust 写的物理引擎，通过 PyO3 绑定。`model_validate(data)` 的实际路径：Python → CoreSchema JSON → Rust 层逐字段校验 → 返回。**步骤 2-4 全部在 Rust 侧完成，不走 GIL**。配合 `asyncio.gather()` 并发调 20 个 LLM API 时，每个回复的 JSON 解析可在不同线程并行跑 Rust 校验。
|
||
|
||
**[[typeadapter|TypeAdapter]]**：同一份数据，不同严格度——API 入口用 strict，Agent 内部传递用宽松，不用写两套模型。
|
||
|
||
**三个零成本配置**：
|
||
```python
|
||
model_config = {
|
||
"strict": True, # 空字符串不会变 0，类型不匹配直接炸
|
||
"extra": "forbid", # LLM 多塞字段立刻报错
|
||
"frozen": True, # 模块间传递不可篡改
|
||
}
|
||
```
|
||
|
||
## 第二件：Logfire
|
||
|
||
基于 [[open-telemetry|OpenTelemetry]] 标准的可观测平台。核心价值：
|
||
- **4 行代码**拿到完整 Agent span 树（根 → model request → tool 调用 → follow-up）
|
||
- **OTel 标准**：数据不锁定厂商，可自托管或导出到 Grafana/Jaeger
|
||
- **SQL 查询 trace**：不是点按钮过滤，是写 SQL 查 [[drift-detection|漂移趋势]]
|
||
|
||
真实案例：Sophos 安全团队发现 Agent 调用某个 tool 的频率从每 50 次推理 1 次涨到每 8 次 1 次——传统日志只看调用成功与否，Logfire 的 SQL 查询揭示了频率异常。
|
||
|
||
## 第三件：Pydantic AI
|
||
|
||
把 Pydantic 的类型系统直接嵌入 Agent 运行时——类型从"报错器"变成"编译器"，在运行时之前就约束了 Agent 的行为空间。
|
||
|
||
- `@agent.tool` 自动从函数签名推断 tool schema（不需手写 JSON Schema）
|
||
- `result.data` 类型安全，IDE 补全可用
|
||
- 多步 Agent 支持（多次推理 + 多次 tool 调用）
|
||
- `instrument=True` 自动接 Logfire trace
|
||
|
||
与 Instructor 的定位差异：单次 LLM 结构化输出 → Instructor；多步推理 + 多 tool 调用的 Agent → Pydantic AI。
|
||
|
||
## 渐进路线图
|
||
|
||
1. **今天 (5min)**：所有 BaseModel 加 `strict=True, extra='forbid', validate_default=True`
|
||
2. **这周**：有 Agent 就加 Logfire，4 行代码
|
||
3. **下次新 Agent 项目**：tool > 3 就试 Pydantic AI
|
||
|
||
## 参考
|
||
|
||
- [[agent-observability|Agent 可观测性]]
|
||
- [[type-safety-in-agents|Agent 类型安全]]
|
||
- [原始存档](raw/articles/pydantic-three-piece-suite-2026.md)
|