Pydantic AI vs LangGraph:微调模型该选哪个智能体框架

更新于 2026-05-10——反映 5 月初 Pydantic AI v1.90.x / v1.93.x 发布(显式 tool_choice、专用 OutputToolCallEvent / OutputToolResultEvent 流式事件、OpenAI Conversations API 状态)。下方决策矩阵不变;新原语主要进一步收紧了 Pydantic AI 已经领先的类型安全与可观测性故事。

到 2026 年,Python 智能体框架格局已经收敛。任何把智能体送上生产的团队都已经抛弃了"循环里调 OpenAI"的手写做法。带四十个可组合抽象的 LangChain 早期 Frankenstein 栈也已不见踪影。两个框架仍占据严肃工作的中心:LangGraph,基于图的状态机框架,如今在 Uber、JPMorgan、BlackRock 与 Replit 上运行生产智能体;以及 Pydantic AI,类型安全的 FastAPI 风格框架,2026 年 4 月发布的 1.0 让它成为新项目的当然默认。

两者都与模型无关。两者都能与通过 Ollama、vLLM 或 Ertas Cloud 提供服务的微调开源权重模型干净地协作。两者都把工具调用视作一等原语。在两者之间选择不是"哪个更好"的问题——这是一个关于你的智能体应当如何组织的设计哲学抉择。本篇诚实地走完取舍,然后展示在任一框架下叠加微调模型如何带来戏剧性的收益。

Pydantic AI:类型优先的智能体

Pydantic AI 由 Pydantic 与 Logfire 团队构建。设计精神直接借自 FastAPI:类型即契约,验证不可妥协,框架在你声明形态后应当退到背景。Agent 由结果类型参数化。工具是装饰过的函数,Pydantic AI 解析其签名构建工具 schema。输出根据结果类型自动验证。如果模型发出不符合的内容,你会得到 ValidationError,而不是悄悄的 bug。

运行时是轻量的。没有图引擎、没有检查点层、没有执行调度器。智能体作为普通 Python 运行:调用 agent.run 或 agent.run_sync,框架处理 LLM 循环、工具分派与验证。整个库以 MIT 许可发布,依赖树小到你几乎注意不到它在你的 pyproject.toml 里。

这让 Pydantic AI 天然契合最常见的生产场景:接收输入、调用几个工具、返回结构化输出的智能体。提取智能体、分类器、路由器、轻量级助手。如果你的工作流主要是线性的而你关心输出 schema,Pydantic AI 让你比目前任何可用方案更快达到经过测试的生产智能体。2026 年 4 月的 1.0 发布让 API 趋稳,可以放心地在其上构建商业产品。

LangGraph:有状态、可持久、图编排

LangGraph 走相反的设计路径。智能体是由边连接的节点的有向图。每个节点是函数(LLM 调用、工具执行、条件检查)。边描述状态如何在节点间流动,包括根据中间状态分支的条件边。图引擎运行整个程序,在每一步持久化状态。

这种设计有三件事是 Pydantic AI 不去做的。

持久化检查点。每次状态转换都会被持久化。如果智能体在执行中途崩溃——进程被杀、服务器重启、网络分区——你可以从最近一个检查点恢复,而不是从头来过。对于运行数小时或数天的智能体,这就是可行与不可行的差别。

并行分支。因为图引擎调度节点,你可以扇出到多个并行分支并稍后汇合。一个并行调用五个不同 API 并聚合结果的研究智能体是一个图定义,而不是手写的异步协调层。

人机协同中断。一个图可以在指定节点暂停,把状态呈现给人类审核者,在决策返回后恢复。对于审批工作流、升级以及任何在受监管行业运营的智能体,这是必须的。LangGraph 的 interrupt 原语把"人工审批"从事后修补变成像其他节点一样的图节点。

这些能力的代价是复杂性。LangGraph 要求你把智能体当作状态机思考。图定义比 Pydantic AI 基于装饰器的智能体更冗长。运行时更重——它带着图引擎、检查点层,并且(在生产中)通常带着用于持久化的 Postgres 或 Redis 后端。对于线性提取智能体这是杀鸡用牛刀。对于多阶段审批工作流则正是你需要的。

LangGraph 是 JPMorgan、BlackRock 与 Uber 为接触金钱、客户支持以及合规相关运营的生产智能体所选择的方案。图模型为它们提供了合规团队所需的审计跟踪:每次状态转换都被记录,每次工具调用都可重现,每个决策都可重放。Pydantic AI 的轻量运行时无法轻易提供这种程度的可追溯性。

两个框架的重叠之处

尽管哲学不同,两个框架在若干实际点上落到同一位置。

两者都把兼容 OpenAI 的 API 作为一等传输。两者都能与暴露该接口的任何模型服务器协作——Ollama、vLLM、llama.cpp 的 llama-server、LM Studio、Ertas Cloud、OpenAI API 本身、通过 OpenAI 兼容代理的 Anthropic,或任何自定义服务栈。这意味着你在 Ertas Studio 中部署的微调模型,在两个框架下都能不改一行代码地工作。

两者都有一流的工具调用支持。你声明函数,框架提取其 schema,LLM 拿到结构化的工具使用格式。两者都在执行前验证工具参数;两者都在下一轮把工具结果回传给 LLM。

两者在生产中都有重要的可观测性故事。Pydantic AI 与 Logfire(同一团队)紧密集成并发出 OpenTelemetry 追踪。LangGraph 与 LangSmith 集成进行图执行追踪并支持 OpenTelemetry 导出器。任一者都能为你提供生产环境中每次工具调用的延迟、token 使用量与错误追踪。

所以在两者之间选择不是关于基本能力,而是关于工作流形态与运维需求。

决策矩阵

注意这一规律。Pydantic AI 在工作流主要线性、输出结构重要、你想快速行动时获胜。LangGraph 在工作流名副其实是状态机、持久性与审计跟踪不可妥协、团队有工程精力仔细设计图时获胜。

微调视角:为何两个框架都需要它

下面是 2026 年关于智能体框架的不舒服真相:它们假定模型能够可靠地产出结构化输出。Pydantic AI 假定如此,因为验证器在每次输出上触发。LangGraph 假定如此,因为每个节点的输出会成为下一个节点的输入。当模型表现不佳时,两个框架都退回到重试——而重试要花延迟、要花 token,会侵蚀用户信任。

面对像 Claude 或 GPT-5 Pro 这样的前沿 API,这一假设勉强够用。面对从 Hugging Face 货架上拿下的通用开源权重模型——Qwen3-7B、Llama 3.3 8B、Mistral Small——则不够。schema 违规很常见。错误的工具名称出现。参数类型漂移。框架的验证层从"护栏"变成"反复出现的异常源",你的团队开始把每个智能体调用包在重试装饰器里以掩盖真正的问题。

微调从根源解决这个问题。在你智能体使用的精确工具 schema、代码期望的精确输出格式以及来自你领域的几百次代表性对话上训练模型。模型变成可靠的结构化输出生产者。Pydantic AI 的验证器回到护栏的角色。LangGraph 的节点之间无需包裹逻辑即可流动。

经济模型同向倾斜。多步骤智能体一次前沿 API 调用每次运行 0.01 至 0.05 美元。每天 10,000 次运行就是每天 100 至 500 美元、每年 36,000 至 180,000 美元。一个在单 GPU 实例上提供服务的微调 7B 或 8B 模型成本低数个数量级,而一个微调 4B 模型可在用户设备上免费运行。对于在 500 到 5,000 用户之间感受到智能体成本悬崖咬噬的移动应用开发者——API 账单消耗利润快于营收增长的那一刻——微调不是优化,而是唯一前进的路径。

两个框架的集成是相同的:在 Ertas Studio 中训练模型、导出为 GGUF、通过 Ollama 或 vLLM 提供服务,然后把智能体的 base_url 指向兼容 OpenAI 的端点。从框架视角看,你的微调模型只是另一个兼容 OpenAI 的模型。从用户视角看,智能体的可靠性大幅提升,账单大幅缩水。

同一个智能体,两个框架

为了让对比具体化,这里是同一个分诊智能体——一个把支持工单映射到正确团队的理赔路由分类器——分别在两个框架下面向通过 Ollama 提供服务的 Ertas 微调 Qwen3-4B 实现。

Pydantic AI 版本:

from typing import Literal
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel(
    "ertas-claims-router-4b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
)

class TriageDecision(BaseModel):
    team: Literal["billing", "technical", "fraud", "general"]
    priority: Literal["low", "normal", "high", "urgent"]
    reasoning: str

agent = Agent(
    model,
    result_type=TriageDecision,
    system_prompt="Route incoming support tickets to the right team and priority.",
)

@agent.tool
async def lookup_account(ctx, account_id: str) -> dict:
    """Look up account history to inform routing."""
    return await crm.get_account(account_id)

result = agent.run_sync(
    "My card was charged twice for the same order this morning."
)
print(result.data)
# TriageDecision(team='billing', priority='high', reasoning='Duplicate charge')

LangGraph 版本:

from typing import TypedDict, Literal
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

llm = ChatOpenAI(
    model="ertas-claims-router-4b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
).bind_tools([lookup_account_tool])

class TriageState(TypedDict):
    ticket: str
    account_data: dict | None
    team: str | None
    priority: str | None

def fetch_account(state):
    if account_id := extract_account_id(state["ticket"]):
        return {"account_data": crm.get_account(account_id)}
    return {"account_data": None}

def classify(state):
    msg = llm.invoke([HumanMessage(content=build_prompt(state))])
    parsed = parse_triage_decision(msg.content)
    return {"team": parsed["team"], "priority": parsed["priority"]}

graph = StateGraph(TriageState)
graph.add_node("fetch", fetch_account)
graph.add_node("classify", classify)
graph.set_entry_point("fetch")
graph.add_edge("fetch", "classify")
graph.add_edge("classify", END)

app = graph.compile()
result = app.invoke({"ticket": "My card was charged twice this morning."})

两种实现都能工作。两者都使用相同的微调模型。两者都大约三十行代码。Pydantic AI 版本更短并按构造为你提供带类型的输出;LangGraph 版本更冗长但每次状态转换都可检查点化,通过添加 interrupt 节点该图可以为人工审核暂停,而整体可自然地扩展到——比如说——还要通知团队、开 Jira 工单、并等待人工确认优先级后再做最终路由的工作流。

对于纯分类器,Pydantic AI 是显然的选择。对于作为更长工作流第一节点、其后涉及审批与升级的分类器,LangGraph 开始挣得它的复杂性。

推荐

对于 2026 年的大多数团队,正确答案是从 Pydantic AI 开始。认知负担更低,运行时更轻,API 更愉悦,类型安全在第一次抓住生产前的格式异常输出时就为自己买了单。九成智能体用例是线性或接近线性的,Pydantic AI 干净地处理它们。

当图编排成为瓶颈时再升级到 LangGraph——当你发现自己在手动构建检查点层,当你需要真正的人机协同中断,当合规要求每次状态转换的审计跟踪,当工作流自然地分支与汇合而手写控制流无法干净地表达时。这对一些团队是真实的时刻,但对大多数团队从未到来。

只要看到第二或第三张 API 账单,就在任一框架下叠加微调。微调 4B 至 8B 模型与真正的智能体框架的组合,正是 2026 年让生产智能体既可靠又经济的方式。没有微调,你的框架大部分精力都花在为模型不可靠铺路。有了微调,框架就可以做它被设计来做的工作。

Ertas Studio 处理微调一侧。挑选基础模型——移动与边缘选 Qwen3-4B,服务端智能体选 Qwen3-7B 或 Llama 3.3 8B——在 Data Craft 中精选几百个样本,训练、评估、导出为 GGUF。Ertas Deployment CLI 在需要时处理移动端发货路径。OpenAI 兼容服务意味着无论你选择哪个框架,集成都是一行配置。

按工作流形态选择框架。按领域选择模型。微调让模型原生说出你的工具语言。这就是 2026 年的生产配方。

延伸阅读

• Pydantic AI 设备端:微调 Qwen3-4B 打造类型安全的移动智能体——面向移动应用的 Pydantic AI 加设备端微调模型完整流水线
• FunctionGemma 与专用工具调用模型的崛起——270M 工具调用专家何时打败微调 7B 智能体
• 面向工具调用的微调:如何构建可靠的 AI 智能体——可靠驱动智能体框架的模型训练完整指南