Pydantic AI + Ertas

使用 Pydantic AI 构建生产级智能体——这是来自 Pydantic 团队的类型安全 Python 智能体框架，通过兼容 OpenAI 的端点对微调后的本地模型提供一流支持。

Overview

Pydantic AI 是 Pydantic 与 Logfire 团队推出的智能体框架——Pydantic 是几乎被所有现代 Python Web 框架采用、成为 Python 运行时数据完整性事实标准的验证库。Pydantic AI 将同样的类型安全准则延伸到 LLM 智能体：每个工具、每个输入、每个输出都是带类型的 Pydantic 模型，在运行时进行验证，并且具备 Python 开发者已经熟悉的完整 Pydantic 错误报告与 IDE 自动补全。该框架在 2026 年 4 月发布了 v1 版本，并迅速成为优先考虑类型安全和开发者人体工学的团队继 LangGraph 之后的明星替代品。2026 年 5 月初的 v1.90.x 与 v1.93.x 小版本发布在 `Agent` 上新增了显式的 `tool_choice` 设置、用于细粒度流式处理的专用 `OutputToolCallEvent` 与 `OutputToolResultEvent` 事件，以及 OpenAI Conversations API 状态支持——这些改进让生产环境的使用更可控、更可观测。

该框架的设计直接借鉴自 FastAPI：依赖通过类型提示声明，工具是用 `@agent.tool` 装饰的函数，验证自动完成。与通过提示工程和事后解析处理结构化输出的旧式智能体框架不同，Pydantic AI 使用底层模型的原生函数调用能力，将验证失败暴露为可捕获并重试的 Python 异常。这使得智能体的可靠性大幅提升——出错时你得到清晰的栈跟踪，而不是模型幻觉出字段后悄悄在下游失败。

Pydantic AI 与模型无关。该框架通过其提供商抽象支持 OpenAI、Anthropic、Google 以及任何兼容 OpenAI 的端点，这使其天然适配通过 Ollama、vLLM 或 LM Studio 提供服务的自托管本地模型。Pydantic AI 的类型安全与微调本地模型的组合尤其引人注目：框架在边界上强制 schema 合规，微调模型按训练好的格式产出高质量输出，两者结合交付出既可靠又经济的智能体。

How Ertas Integrates

Ertas 训练的模型通过其 OpenAI 提供商配置到本地端点后即可与 Pydantic AI 协同工作。在 Ertas Studio 中微调模型并导出为 GGUF 后，你通过 Ollama、vLLM 或 Ertas Cloud 提供服务，然后让 Pydantic AI 的 `OpenAIModel` 提供商指向你的端点。代码库中的每个智能体——无论是单次 LLM 调用还是协调复杂的多步骤工作流——都会以你的 Ertas 训练模型作为底层引擎。

这种集成尤其强大的原因在于 Pydantic AI 处理结构化输出的方式。框架的 `result_type` 参数接受任何 Pydantic 模型，智能体会根据该 schema 验证 LLM 的输出，若不符则抛出 `ValidationError`。专门针对微调模型——Ertas Studio 的训练流程可纳入 schema 合规示例——这就形成了一个自我强化的循环：模型产出符合 schema 的输出，Pydantic AI 进行验证，任何失败（微调后会变得罕见）都会以可捕获的异常出现，便于重试或记录日志。

对于通过 Ertas Deployment CLI 进行的移动部署，Pydantic AI 的轻量级运行时是绝佳选择。该框架除了 LLM 调用本身之外几乎不增加额外开销——这在通过 llama.cpp 在设备端运行智能体循环时尤为重要。在主机应用一侧（无论主机是 Python 后端还是调用本地推理服务的移动应用），类型安全使契约显式化并减少了通常隐藏错误的集成面。

Getting Started

1
在 Ertas Studio 中微调你的领域模型
在包含 Pydantic AI 智能体所需结构化输出和工具调用的数据上训练。Studio 的 JSONL 格式直接映射到 Pydantic AI 的 `messages` 与 `result_type` 模式。
2
部署到兼容 OpenAI 的端点
导出为 GGUF 并通过 Ollama、vLLM 或 Ertas Cloud 提供服务。Pydantic AI 的 OpenAI 提供商可连接任何暴露标准聊天补全 API 的端点。
3
安装 Pydantic AI 并配置模型提供商
安装 pydantic-ai。创建一个指向你的 Ertas 推理端点并带有模型名称的 `OpenAIModel`（或 `OpenAIProvider`）实例。
4
定义带类型的工具与结果 schema
将工具声明为带类型提示的装饰 Python 函数。将结果 schema 定义为 Pydantic 模型。Pydantic AI 自动处理验证、schema 失败时的重试以及清晰的错误报告。
5
运行智能体并处理验证
使用你的输入调用 `agent.run()` 或 `agent.run_sync()`。Pydantic AI 返回带类型的结果。捕获 `ValidationError` 以实现结构化重试逻辑，或依赖框架内置的重试行为。

python

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

# Point Pydantic AI at your Ertas-trained model served via Ollama
model = OpenAIModel(
    "ertas-support-agent-7b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
)

class TicketTriage(BaseModel):
    category: str
    priority: int  # 1-5
    suggested_team: str
    requires_human: bool

agent = Agent(
    model,
    result_type=TicketTriage,
    system_prompt="You triage customer-support tickets for a SaaS product.",
)

@agent.tool
async def lookup_customer(ctx, customer_id: str) -> dict:
    """Fetch customer record from the CRM."""
    return await crm.get_customer(customer_id)

# The agent returns a validated TicketTriage object — or raises ValidationError
result = agent.run_sync(
    "Customer 12345 says the dashboard hasn't loaded for 30 minutes."
)
print(result.data.priority, result.data.suggested_team)

在 Pydantic AI 中构建一个由 Ertas 训练模型支持的类型安全工单分诊智能体。智能体的输出会自动根据 Pydantic schema 进行验证。