Pydantic AI: English for Building Type-Safe AI Agents (англійською)
Вивчіть англійську лексику для Pydantic AI: агенти, інструменти, структурований вивід, шаблони, що не залежать від моделі, асинхронні агенти і моделі Pydantic для розробки безпечних типів штучного інтелекту.
Pydantic AI приносить безпеку типів і перевірку даних, які інженери Python вже довіряють Pydantic у світі розробки агентів штучного інтелекту. Виражаючи вхідні дані агента, вихідні дані і інтерфейси інструментів як моделі Pydantic, команди можуть ловити помилки в часі розробки, а не в часі виконання в виробництві.
Якщо ви знайомі з Pydantic для перевірки API, але ще не вміли використовувати його у агентах штучного інтелекту, цей підручник допоможе вам ознайомитися з словником. Ці терміни постійно з’ являються в документації, переглядах запитів на завантаження і обговореннях архітектури.
Ключовий словник
Agent
У Pydantic AI, ** агент ** є об’єктом Python, який обгортає виклик моделі мови (або послідовність викликів) і накладає типовий контракт на вхідні і вихідні дані. Агент знає, яку модель використовувати, які інструменти доступні, що таке системна команда і який тип виводу має бути.
“Ми маємо агента сортування, який приймає сирий квиток підтримки як вхід і повертає структуровану модель TriageResult — агент гарантує, що вивід завжди вводиться і перевіряється.”
Tool
** tool ** це функція Python, зареєстрована з агентом, який модель мови може викликати під час процесу обґрунтування. Інструменти описуються моделі через їхні підписи функцій і докштрихів; Pydantic AI автоматично генерує схему JSON для параметрів кожного інструменту з анотацій типів.
“Ми зареєстрували інструмент get_customer_account на агенті — його анотації типів автоматично генерують схему JSON, тому модель завжди точно знає, які аргументи передати.”
Структурований вивід
** Структурований вивід ** означає, що агент обмежено повертати певну модель Pydantic, а не рядок вільної форми. Фреймворк перевіряє відповідь моделі на визначену схему і піднімає типову помилку, якщо вивід не відповідає. Це основна цінність пропозиції Pydantic AI над сирими LLM викликами.
“Перехід на структурований вивід вилучив цілу категорію помилок аналізу — якщо модель створює неправильно сформований JSON, ми отримуємо помилку перевірки на рівні агента, а не аварію десь далі по течії.”
Модель-агностик
** Модель- агностичний ** описує код, який не пов’ язаний з конкретним постачальником LLM. ШІ Pydantic розроблено таким чином, щоб не залежати від моделі: ви можете перемикатися між моделями OpenAI, Anthropic, Gemini або локальною моделлю Ollama змінюючи один параметр налаштування, без переписування логіки агента.
“Наші агенти повністю агностичні до моделей — ми перемикаємось між Claude і GPT-4 в наших тестах, а рівень бізнес-логіки зовсім не змінюється.”
Асинхронний агент
Async агент є агентом, реалізованим за допомогою шаблону Python async / await, що дозволяє декільком агентам виконуватись одночасно без блокування. Pydantic AI підтримує як синхронне, так і асинхронне виконання агентів; асинхронні агенти є кращими для виробничих серверів, що обробляють одночасні запити.
- “Ми перейшли на асинхронні агенти, коли перейшли до виробничого режиму — синхронні виклики агентів блокували петлю подій і спричиняли перевищення часу очікування під час завантаження.” *
Підантична модель (як тип виводу)
**Pydantic модель ** використовується як тип виводу є клас Python успадкований від BaseModel, який визначає структуру, типи і правила перевірки для повернення агента значення. Кожне поле має анотацію типу; додатковими полями є типові поля; нетипові перевірки можуть застосовувати бізнес- правила.
“Вихідний тип агента є PolicyDecision моделлю з трьома полями: approved як булева, reason як рядок, і confidence як число з плаваючою комою між 0 і 1 — Pydantic перевіряє всі три на кожній відповіді.”
Ін’єкція залежності
** Введення залежностей ** у Pydantic AI є механізмом для передачі зовнішніх ресурсів — з’ єднань з базами даних, клієнтів API, налаштувань — до інструментів агента і системної команди під час виконання, без їхнього твердого кодування у визначенні агента. Залежності визначаються як типовий клас даних і вводяться через параметр агента deps_type.
“Ми вставляємо з’ єднання бази даних як залежність, щоб інструменти могли запитувати дані клієнта без потреби в глобальному стані — це також робить агент простим для тестування з імітацією бази даних.”
Перевірка результатів
** Перевірка результату ** — це функція, зареєстрована у агенті, яка виконує додаткове перевірку структурованого виводу після успішного завершення перевірки схеми Pydantic. Він може перевірити перевірену модель і підняти помилку, якщо бізнес-правила були порушені - наприклад, перевірити, що рекомендована дія знаходиться в списку дозволених, або що довірчий бал відповідає мінімальному порогу.
“Pydantic перевіряє схему, але наш перевіряючий результат перевіряє бізнес-правила — він відкидає будь-яке рішення політики, де approved є істинним, але confidence нижче 0.7.”
Корисні фрази
- “Тип виводу агента забезпечує виконання контракту на рівні структури — якщо модель не повертає коректний структурований вивід, агент автоматично повторює спробу.”
- “Ми вводимо всі зовнішні залежності за допомогою шаблону deps, тому інструменти залишаються чистими функціями без побічних ефектів під час тестування.”
- “Зміна моделей є зміною в одній лінії - модель-агностичний дизайн Pydantic AI означає, що наша логіка агента повністю відокремлена від провайдера.”
- “Відстежувач результатів виявив крайній випадок, який Pydantic сам би не помітив — схема була коректною, але бізнес-логіка була порушена.”
- “Ми запускаємо всіх агентів асинхронно — без асинхронності, кожен виклик LLM буде блокуватися, а час відповіді нашого API буде неприйнятним.”
Поширені помилки
Плутанина Pydantic AI з Pydantic
Інженери, які не знають про фреймворк, іноді вважають, що Pydantic AI це просто Pydantic з деякими додатковими можливостями. Це різні проекти з різними цілями. Pydantic є бібліотекою перевірки даних загального призначення. Pydantic AI є платформою агента, побудованою на основі Pydantic, спеціально для оркестрування викликів LLM з типованими вхідними і вихідними даними. Ви можете сказати * “ми використовуємо Pydantic AI для наших агентів і Pydantic для наших моделей запитів API” * щоб зробити відмінність ясною.
Оминання анотацій типів на функціях інструментів
Частою помилкою є визначення функцій інструментів без повного анотування типів. Pydantic AI генерує JSON схему, яку LLM використовує для виклику інструменту безпосередньо з анотації типів — відсутні або надто широкі типи (наприклад, Any або dict ) виробляють погані схеми, які призводять до того, що модель передає неправильні аргументи. Завжди анотируйте параметри інструментів за певними типами і використовуйте рядки документації для опису дії кожного з параметрів.
Розгляд структурованого виводу як необов’ язкового
Інженери, які мігрують з сирих LLM викликів, іноді використовують структурований вивід тільки для «важливих» відповідей і повертають прості рядки в інших місцях. Це створює невідповідність — деякі шляхи коду перевіряються, інші не перевіряються — і підриває безпеку типів, яку надає Pydantic AI. Рекомендується визначати структурований тип виводу для кожного агента, навіть для простих, і резервувати простий рядковий вивід лише для випадків використання у розмові або у вільній формі, коли структурування не є дійсним.
Підхід Pydantic AI до розробки агентів полягає в тому, щоб зробити неявні контракти явними. Словник в цьому посібнику — структурований вивід, введення залежностей, перевірки результатів, дизайн, що не залежить від моделі — все це відображає філософію, що поведінка агента ШІ повинна бути настільки ж жорсткою і передбачуваною, як і будь-який інший програмний інтерфейс. Якщо ви зможете висловити цю філософію точною англійською, ви побачите, що обговорення архітектури стануть продуктивнішими, а ваші коментарі щодо запитів на звантаження стануть простішими у написанні.
Пов’язані статті
- AI Agents Vocabulary: Agent Loop, ReAct, Tool Calling, and Agentic Systems Explained (англійською)
- Англійська для інженерів-агентів штучного інтелекту
- AI and Machine Learning Vocabulary: LLM, RAG, Embeddings Explained (англійською)
Розрізняють: мовні та немовні мовні мовлення
Основна сила Pydantic AI - будівництво * безпечних типів * агентів штучного інтелекту - сильно залежить від точного спілкування. Для розробників, чия перша мова не є англійською, це може бути особливо складним. Це не просто про знання окремих слів; це про розуміння нюансів фразування і очікувань професійного технічного дискурсу. Розглянемо звичайний сценарій: коментар перегляду коду. Уявіть, що ви надіслали PR для інтеграції асинхронного агента у вашу систему. Рецензент може залишити коментар на зразок: « У виводі агента відсутня інформація про явний тип — чи не могли б ви додати Pydantic- моделі, щоб забезпечити більш сувору перевірку? » Хоча * значення * є ясним, формулювання може здатися приголомшливим. Ключовим у цьому випадку є розбиття елементів. « Відсутня інформація про явний тип » не просто говорить про те, що щось не так; це підсвічує певну вимогу: * перевірка *. « Примусити до більш суворих перевірок » говорить про бажання більшої надійності і зменшує потенційні помилки у подальшому. Навчання ідентифікувати ці основні наміри - * чому * за запитом - має вирішальне значення, особливо при зустрічі незнайомих технічних термінів.
Крім того, розмови Slack часто включають швидкий обмін повідомленнями, де цінується короткість, але ясність залишається найважливішою. Розробник може швидко описати нову функціональність агента за допомогою « Реалізовано асинхронний агент для підсумування ». Хоча ця фраза технічно правильна, у ній бракує контексту. Більш лаконічним варіантом буде: « Реалізовано асинхронний агент, розроблений для створення коротких резюме вхідного тексту, використовуючи моделі Pydantic для забезпечення того, щоб вивід відповідав заздалегідь визначеній схемі — зокрема, забезпечення того, щоб резюме відповідало максимальному обмеженню символів і включало ключові об’ єкти. » Додаткові подробиці демонструють розуміння * цілі * агента (резюме), архітектурного підходу (асинхронний) і механізму перевірки (моделі Pydantic). Цей рівень специфічності очікується в професійних умовах; це не про звучання багатослівності, а про демонстрацію ретельності і прихильності до міцних практик розробки.
Нарешті, при написанні описів PR, прагніть до ясності щодо * моделі-агностичних шаблонів *. Ця концепція — проектування агентів, які можуть працювати з різними моделями ШІ без модифікації — часто вимагає ретельної документації. Замість простого зауваження «Інтегрований новий агент», описати архітектуру: «Ця PR вводить асинхронний агент, побудований за допомогою моделі-агностичного шаблону, використовуючи Pydantic моделі для стандартизації вхідних і вихідних форматів в різних LLM інтеграціях. Це дозволяє майбутнє розширення без необхідності значних змін коду при переключенні між різними моделями штучного інтелекту»
Ось приклад того, як ви можете використовувати pydantic у вашому робочому потоці:
from pydantic import BaseModel, Field
class SummaryRequest(BaseModel):
text: str = Field(..., min_length=10, max_length=200) # Text input with length constraints
keywords: list[str] = Field([], min_items=0, max_items=5) # Keywords to prioritize
# Example usage (simplified for illustration)
request = SummaryRequest(text="This is a sample text.", keywords=["important", "key"])
print(request.model_dump())Цей простий приклад показує, як можна використовувати моделі Pydantic для визначення структури запитів і відповідей, забезпечуючи безпеку типів і правила перевірки. Сфокусування на цих конкретних аспектах - намір, архітектура і перевірка - значно поліпшить ваші комунікаційні навички в контексті розвитку Pydantic AI.