Основы Pydantic AI 2.0: приложения с искусственным интеллектом и контролем типов

Pydantic AI 2.0 представляет собой фреймворк для разработки приложений с искусственным интеллектом, обеспечивающий контроль типов и валидацию данных. Он позволяет получать структурированные результаты от больших языковых моделей (LLM) и без проблем интегрируется с моделями Pydantic.

Что такое Pydantic AI?

Pydantic AI — это библиотека Python, построенная на основе Pydantic и специально разработанная для работы с LLM. Она предоставляет:

Type-safe вывод AI: ответы от моделей автоматически конвертируются в модели Pydantic
Валидация: входные и выходные данные проверяются по схемам
Поддержка нескольких провайдеров: OpenAI, Anthropic, Groq, локальные модели (Ollama, vLLM)
Потоковая передача: реал-тайм потоковая передача структурированных данных
Tool-calling: встроенная поддержка вызова функций

Зачем использовать Pydantic AI?

Типичный пользователь

Pydantic AI идеально подходит для:

Python-разработчиков, которые уже используют Pydantic и ценят контроль типов
Backend-разработчиков, желающих интегрировать структурированный вывод моделей в свои API
Data Engineers, нуждающихся в извлечении и валидации данных с помощью AI
Разработчиков приложений с AI, требующих надежного валидированного вывода

Кто выигрывает от использования Pydantic AI?

Конечные пользователи: получают согласованные валидированные данные вместо неструктурированного текста
Разработчики: экономят время на валидации и обработке ошибок
Системы: интеграция проще, так как выходные данные уже имеют правильные типы
QA-команды: требуется меньше тестов, поскольку валидация происходит автоматически

Рассчитываем перед интеграцией проекта

Перед добавлением Pydantic AI в проект задайте себе следующие вопросы:

1. Нужны ли тебе структурированные выходные данные?

✅ Да: Pydantic AI идеален, если требуются ответы от AI в конкретных форматах (JSON, объекты, enum)
❌ Нет: Если нужен только свободный текст, Pydantic AI может быть излишним

2. Уже ли ты используешь Python и Pydantic?

✅ Да: Pydantic AI органично интегрируется в существующую экосистему
❌ Нет: Если Python не используется, Pydantic AI не подойдет (специфичен для Python)

3. Насколько важен контроль типов для проекта?

✅ Критически важен: Pydantic AI обеспечивает валидацию на этапе компиляции и во время выполнения
⚠️ Среднее значение: Pydantic AI помогает, но альтернативы вроде LangChain могут быть достаточными
❌ Не важен: Если строгая типизация не требуется, подойдут более простые решения

4. Планируешь ли ты поддержку нескольких провайдеров?

✅ Да: Pydantic AI делает простым переход между OpenAI, Anthropic, Groq и локальными моделями
❌ Нет: Если используется только один провайдер, это не критерий выбора

5. Какова сложность твоей интеграции AI?

✅ Простая или средняя: Pydantic AI идеален для структурированного вывода и tool-calling
⚠️ Очень сложная: Для многоагентных систем LangChain или LangGraph могут быть лучше

Матрица принятия решения

Требование	Pydantic AI	LangChain	Прямой API
Структурированный вывод	✅ Оптимально	⚠️ Возможно	❌ Ручной
Контроль типов	✅ Встроенный	⚠️ Ограниченный	❌ Отсутствует
Простота	✅ Высокая	⚠️ Средняя	⚠️ Средняя
Многоагентность	⚠️ Ограниченная	✅ Сильная	❌ Нет
Независимость провайдера	✅ Да	✅ Да	❌ Нет
Кривая обучения	🟢 Низкая	🟡 Средняя	🟡 Средняя

Когда НЕ использовать Pydantic AI

Ты не используешь Python
Нужен только свободный текст без структуры
Требуется сложная оркестрация многоагентных систем (используй LangGraph)
Хочется минимизировать зависимости
Проект очень маленький и простой (прямого API достаточно)

Когда использовать Pydantic AI

Ты уже используешь Python и Pydantic
Нужны надежные валидированные выходные данные от AI
Контроль типов для тебя важен
Хочешь менять LLM-провайдеров
Разрабатываешь API с интеграцией AI
Нужен tool-calling с валидированными параметрами

Практический пример: компания с API на FastAPI и Langdock

Предположим, в компании используется FastAPI с Langdock для создания GDPR-совместимой среды. Чат работает, чатботы работают. Почему стоит рассмотреть Pydantic AI?

Ответ: вероятно, нет необходимости в текущей ситуации.

Если чатбот просто возвращает свободный текст без структурированных данных, Pydantic AI не понадобится. Langdock и FastAPI уже обеспечивают GDPR-совместимость и функциональность чата.

Когда Pydantic AI все же может потребоваться:

Представим небольшое расширение сценария:

# Сейчас: только свободный текст
response = "Привет! Я могу помочь."

# С Pydantic AI: структурированный вывод
from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    kategorie: str  # например "технический", "биллинг", "hr"
    prioritaet: str  # например "высокая", "средняя", "низкая"
    beschreibung: str
    assigned_to: str | None = None

# AI анализирует запрос и возвращает структурированные данные
ticket = agent.run_sync(
    "Мой компьютер не запускается, нужна срочная помощь!",
    result_type=SupportTicket
)
# SupportTicket(kategorie='технический', prioritaet='высокая', beschreibung='Мой компьютер не запускается...', assigned_to=None)

Конкретный пример для компании:

Без Pydantic AI: чатбот возвращает текст → нужно парсить текст, чтобы определить категории
С Pydantic AI: чатбот сразу возвращает объект SupportTicket → можно напрямую сохранить в базу данных без парсинга

Итоговый вывод для этого сценария:

Если нужны только чаты: Pydantic AI не требуется
Если нужно извлекать структурированные данные из чатов (тикеты, формы, отчеты): Pydantic AI очень полезен

Ключевая идея:

Чатботу не нужен Pydantic AI. AI-агенту обычно нужен. Типичные случаи использования: ассистенты для кода, агенты исследования, автоматизация, рабочие процессы с несколькими инструментами или приложения, требующие типизированного валидированного вывода.

Установка

pip install pydantic-ai

Для конкретных провайдеров:

pip install pydantic-ai[openai]  # OpenAI
pip install pydantic-ai[anthropic]  # Anthropic
pip install pydantic-ai[openai,anthropic]  # Оба

Основы: структурированный вывод

Простой пример

from pydantic import BaseModel
from pydantic_ai import Agent

class UserResponse(BaseModel):
    name: str
    age: int
    email: str

agent = Agent('openai:gpt-4o')

result = agent.run_sync(
    'Создай профиль пользователя для разработчика',
    result_type=UserResponse
)

print(result.data)
# UserResponse(name='Max Mustermann', age=28, email='max@example.com')

С системным промптом

from pydantic_ai import Agent, SystemPrompt

agent = Agent(
    'openai:gpt-4o',
    system_prompt=SystemPrompt('Ты полезный ассистент для разработчиков.')
)

result = agent.run_sync(
    'Создай профиль для Python-разработчика',
    result_type=UserResponse
)

Сложные модели

Вложенные структуры

from typing import List
from pydantic import BaseModel

class Skill(BaseModel):
    name: str
    years_experience: int
    level: str  # beginner, intermediate, advanced

class DeveloperProfile(BaseModel):
    name: str
    role: str
    skills: List[Skill]
    github_url: str | None = None
    available_for_hire: bool

agent = Agent('openai:gpt-4o')

result = agent.run_sync(
    'Erstelle ein detailliertes Profil für einen Senior Python-Entwickler',
    result_type=DeveloperProfile
)

Валидация с помощью Enum

from enum import Enum
from pydantic import BaseModel

class SkillLevel(str, Enum):
    BEGINNER = 'beginner'
    INTERMEDIATE = 'intermediate'
    ADVANCED = 'advanced'
    EXPERT = 'expert'

class Skill(BaseModel):
    name: str
    level: SkillLevel

Поддержка нескольких провайдеров

OpenAI

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')
result = agent.run_sync('Hallo Welt!')

Anthropic

agent = Agent('anthropic:claude-3-5-sonnet-20241022')
result = agent.run_sync('Hallo Welt!')

Локальные модели с Ollama

agent = Agent('ollama:llama3.2')
result = agent.run_sync('Hallo Welt!')

Groq

agent = Agent('groq:llama-3.1-70b-versatile')
result = agent.run_sync('Hallo Welt!')

Вызов инструментов

Простой инструмент

from pydantic_ai import Agent, Tool

def get_weather(location: str) -> str:
    """Holt das Wetter für einen Ort."""
    # In der Realität: API-Aufruf
    return f'In {location} sind es 22°C.'

agent = Agent('openai:gpt-4o', tools=[Tool(get_weather)])

result = agent.run_sync('Wie ist das Wetter in Berlin?')

С использованием моделей Pydantic

from pydantic import BaseModel

class WeatherQuery(BaseModel):
    location: str
    unit: str = 'celsius'

def get_weather(query: WeatherQuery) -> str:
    return f'In {query.location} sind es 22°{query.unit}.'

agent = Agent('openai:gpt-4o', tools=[Tool(get_weather)])

Потоковая передача данных

Потоковая передача текста

agent = Agent('openai:gpt-4o')

async for chunk in agent.run_stream('Erzähle mir eine Geschichte'):
    print(chunk.content, end='')

Структурированная потоковая передача

async for chunk in agent.run_stream(
    'Erstelle ein Benutzerprofil',
    result_type=UserResponse
):
    if chunk.content:
        print(chunk.content, end='')

Обработка ошибок

Ошибки валидации

from pydantic import ValidationError

try:
    result = agent.run_sync(
        'Erstelle ein Profil',
        result_type=UserResponse
    )
except ValidationError as e:
    print(f'Validierungsfehler: {e}')

Логика повторных попыток

from pydantic_ai import Agent, RetryPolicy

agent = Agent(
    'openai:gpt-4o',
    retry_policy=RetryPolicy(max_retries=3)
)

Best Practices

1. Определяйте четкие модели

# ✅ Хорошо
class UserProfile(BaseModel):
    name: str
    email: str
    age: int

# ❌ Плохо
class Response(BaseModel):
    data: dict  # Keine Type-Safety

2. Используйте системные подсказки

agent = Agent(
    'openai:gpt-4o',
    system_prompt=SystemPrompt(
        'Du bist ein technischer Dokumentations-Assistent. '
        'Antworte präzise und strukturiert.'
    )
)

3. Используйте валидацию

from pydantic import field_validator

class UserProfile(BaseModel):
    email: str
    
    @field_validator('email')
    def validate_email(cls, v):
        if '@' not in v:
            raise ValueError('Ungültige E-Mail')
        return v

4. Оптимизация затрат

# Более компактные модели для простых задач
agent_simple = Agent('openai:gpt-4o-mini')

# Более мощные модели для сложных задач
agent_complex = Agent('openai:gpt-4o')

Интеграция с существующими проектами

Интеграция с FastAPI

from fastapi import FastAPI
from pydantic_ai import Agent

app = FastAPI()
agent = Agent('openai:gpt-4o')

@app.post('/generate')
async def generate(prompt: str):
    result = await agent.run(prompt)
    return {'response': result.content}

Async/Await

import asyncio

async def main():
    agent = Agent('openai:gpt-4o')
    result = await agent.run('Hallo Welt!')
    print(result.content)

asyncio.run(main())

Типичные ошибки

1. Отсутствующие API-ключи

import os
from pydantic_ai import Agent

# API-Key setzen
os.environ['OPENAI_API_KEY'] = 'sk-...'

agent = Agent('openai:gpt-4o')

2. Некорректные названия моделей

# ✅ Правильно
agent = Agent('openai:gpt-4o')

# ❌ Неправильно
agent = Agent('openai:gpt-5')  # Modell existiert nicht

3. Отсутствующие аннотации типов

# ✅ С аннотациями типов
def get_weather(location: str) -> str:
    return f'Wetter in {location}'

# ❌ Без аннотаций типов
def get_weather(location):
    return f'Wetter in {location}'

Pydantic AI и альтернативы

Функция	Pydantic AI	LangChain	LlamaIndex
Type-Safety	✅ Встроенная	⚠️ Ограниченная	⚠️ Ограниченная
Интеграция Pydantic	✅ Полная	⚠️ Частичная	⚠️ Частичная
Поддержка нескольких провайдеров	✅ Простая	✅ Да	✅ Да
Потоковая передача	✅ Да	✅ Да	✅ Да
Вызов инструментов	✅ Встроенный	✅ Да	✅ Да
Кривая обучения	🟢 Низкая	🟡 Средняя	🟡 Средняя

Täglicher Artikel