Дефиниране на схеми с Pydantic
На тази страница
Pydantic: Основата на персонализираните структурирани изходи в Python
Pydantic е най-популярната библиотека за валидиране на данни в Python. Тя Ви позволява да дефинирате модели на данни със строги типове, което е точно това, което API на Mistral използва за персонализирани структурирани изходи (Custom Structured Outputs). Ако работите с Python, Pydantic се превръща във Вашия основен инструмент за описване на изходни схеми: това, което напишете в класа, е точно това, към което моделът ще бъде ограничен да произведе.
Ето и добрата новина относно инсталацията: Pydantic е включен като зависимост на Mistral SDK. Ако вече имате инсталиран mistralai, не е необходимо да правите нищо допълнително.
pip install mistralai
# Pydantic v2 is included automatically
Бърза проверка на версията избягва изненади, тъй като синтаксисът на валидаторите се промени между основните версии:
import pydantic
print(pydantic.__version__) # 2.x required
Дефиниране на прост модел
Моделът на Pydantic е клас, който наследява BaseModel, като всеки атрибут е поле с изричен тип.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Този модел казва на Mistral: „Вашият изход трябва да бъде JSON обект с точно тези 4 полета, всички от тип низ (string).“ Не са необходими допълнителни инструкции в подкана (prompt), за да се получи тази структура.
Типове, които ще използвате
Pydantic поддържа всички стандартни типове на Python и Mistral ги разбира всички. Следващият модел ги събира в реалистичен случай – анализиране на билет за поддръжка – и показва как се комбинират: основни типове за прости полета, Optional за изпълнител, който все още не е определен, Enum за приоритет, който може да приеме само четири стойности, и списъци за тагове и свързани ID-та.
from pydantic import BaseModel
from typing import Optional
from enum import Enum
class Priority(str, Enum):
low = "low"
medium = "medium"
high = "high"
critical = "critical"
class TicketAnalysis(BaseModel):
# Basic types
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Optional types
assignee: Optional[str] = None
# Enums (constrained values)
priority: Priority
# Lists
tags: list[str]
related_ids: list[int]
Ето съответната шпаргалка:
| Тип | Значение |
|---|---|
str | текстов низ |
int | цяло число |
float | десетично число |
bool | булев тип (вярно/грешно) |
list[T] | списък от елементи от тип T |
Optional[T] | поле, което може да е null |
Enum | стойност от краен набор |
Изброените типове (Enums) заслужават специално споменаване: те са единственият начин да гарантирате, че приоритетът никога няма да бъде "very urgent" или "P1" в зависимост от настроението на модела.
Вложени модели
Данните в реалния свят рядко са плоски. Един контакт принадлежи към компания, която има адрес. Pydantic Ви позволява да влагате модели толкова дълбоко, колкото е необходимо, а Mistral следва йерархията.
from pydantic import BaseModel
from typing import Optional
class Address(BaseModel):
street: str
city: str
postal_code: str
country: str
class Company(BaseModel):
name: str
industry: str
address: Address # Nested model
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Two-level nesting
Генерираният JSON възпроизвежда точно тази дървовидна структура:
{
"first_name": "Marie",
"last_name": "Dupont",
"email": "[email protected]",
"role": "Sales Director",
"company": {
"name": "TechVision SAS",
"industry": "Technology",
"address": {
"street": "42 rue de la Paix",
"city": "Paris",
"postal_code": "75002",
"country": "France"
}
}
}
Същият механизъм извлича множество елементи наведнъж: модел обгръща списък от друг модел и Вие получавате пълен каталог с едно единствено извикване.
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
category: str
in_stock: bool
class Catalog(BaseModel):
products: list[Product]
total_count: int
Насочване на модела с описания
Името на полето не разказва цялата история. score може да означава оценка до 10, процент или стойност между 0 и 1 – моделът трябва да познае. Описанията премахват тази двусмислица: те се включват в JSON схемата, изпратена до Mistral, и действат като инструкции за всяко поле поотделно.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Overall sentiment: 'positive', 'negative', or 'neutral'"
)
score: float = Field(
description="Confidence score between 0.0 and 1.0"
)
keywords: list[str] = Field(
description="The 3-5 main keywords from the text"
)
summary: str = Field(
description="Summary in one sentence maximum"
)
Колкото по-точни са тези описания, толкова по-високо е качеството на изхода. Това е частта с най-голям ефект от цялата настройка: няколко добре подбрани думи често заместват цял абзац от подканата.
Field също така задава стойности по подразбиране. В следващия пример езикът по подразбиране е "fr", ако моделът не открие информацията, броят на думите остава None, ако не може да бъде определен, а таговете започват като празен списък благодарение на default_factory.
from pydantic import BaseModel, Field
from typing import Optional
class ArticleMetadata(BaseModel):
title: str
author: str
language: str = Field(default="fr", description="ISO 639-1 language code")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Полетата със стойности по подразбиране ще бъдат попълнени от модела, ако той открие информацията, или ще запазят стойността по подразбиране в противен случай.
Валидирането идва безплатно
И накрая, но не на последно място: валидирането е автоматично. Ако стойност не съвпада с декларирания тип, Pydantic незабавно генерира ValidationError, посочвайки точно кое поле е проблемното, без Вие да пишете нито ред код за проверка.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Type error
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 validation error for SentimentAnalysis
# score
# Input should be a valid number [type=float_parsing, ...]
Целият ръчен код за проверка, написан в предишния урок, изчезва тук, заменен от декларацията на модела.
Ключови изводи
- Pydantic
BaseModelе основата на всички персонализирани схеми в Python - Използвайте изрични типове:
str,int,float,bool,list[T],Optional[T] - Вложените модели позволяват сложни JSON структури
Field(description=...)подобрява качеството на изхода, като насочва модела- Валидирането е автоматично – грешките в типовете се откриват незабавно