Премини към основното съдържание
Български— Изберете език
Меню

Разширени случаи на употреба

Урок 10 от 12 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Отвъд простите примери
  2. Извличане на фактура
  3. Анализиране на отзиви по аспекти
  4. Класифициране на текст в множество категории
  5. Факторизиране на извикването
  6. Ключови изводи

Отвъд простите примери

Вече сте усвоили Pydantic, Zod и client.chat.parse(). Следващите три случая надхвърлят простите схеми с четири полета и преминават към сценарии, които ще срещнете в корпоративна среда: счетоводни документи, детайлен анализ на клиентски отзиви и текстове, принадлежащи едновременно към няколко категории. Всеки от тях илюстрира различна техника за моделиране.

Извличане на фактура

Обработката на документи е естествената територия за вложени схеми. Фактурата не е плосък обект: тя съдържа заглавка, крайна част с общи суми и променлив брой редове със собствена структура. Затова моделираме LineItem отделно и след това го реферираме в списък. Валутата използва изброим тип (enum), което предотвратява връщането на "euros" или "€" от модела в зависимост от формулировката в документа.

from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum

class Currency(str, Enum):
    eur = "EUR"
    usd = "USD"
    gbp = "GBP"

class LineItem(BaseModel):
    description: str = Field(description="Line item description")
    quantity: float = Field(description="Quantity")
    unit_price: float = Field(description="Unit price excluding tax")
    vat_rate: float = Field(description="VAT rate as a percentage (e.g., 20.0)")
    total_ht: float = Field(description="Line total excluding tax")

class InvoiceData(BaseModel):
    invoice_number: str = Field(description="Invoice number")
    date: str = Field(description="Invoice date in YYYY-MM-DD format")
    due_date: Optional[str] = Field(default=None, description="Due date")
    vendor_name: str = Field(description="Vendor name")
    vendor_address: Optional[str] = Field(default=None)
    client_name: str = Field(description="Client name")
    line_items: list[LineItem] = Field(description="Invoice line items")
    subtotal_ht: float = Field(description="Subtotal excluding tax")
    total_vat: float = Field(description="Total VAT amount")
    total_ttc: float = Field(description="Total including tax")
    currency: Currency = Field(description="Currency")
    payment_method: Optional[str] = Field(default=None)

# Extraction
response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": """You are an accounting expert. Extract data from the invoice.
Be precise with amounts. Calculate totals if necessary.
Dates must be in YYYY-MM-DD format."""
        },
        {"role": "user", "content": invoice_text}
    ],
    response_format=InvoiceData,
    temperature=0
)

invoice = response.choices[0].message.parsed
print(f"Invoice {invoice.invoice_number} — {invoice.vendor_name}")
print(f"Total incl. tax: {invoice.total_ttc} {invoice.currency.value}")
for item in invoice.line_items:
    print(f"  - {item.description}: {item.quantity} x {item.unit_price}€ = {item.total_ht}€ excl. tax")

Форматът на датата, наложен в системния промпт, не е второстепенна подробност: без него един френски документ може да генерира 12/03/2026, докато американски ще върне 03/12/2026, създавайки две неразличими низа за вашата база данни. TypeScript версията следва същата архитектура, като форматът е документиран чрез .describe().

import { z } from "zod";

const LineItemSchema = z.object({
  description: z.string(),
  quantity: z.number(),
  unitPrice: z.number().describe("Unit price excluding tax"),
  vatRate: z.number().describe("VAT rate in %"),
  totalHt: z.number(),
});

const InvoiceSchema = z.object({
  invoiceNumber: z.string(),
  date: z.string().describe("Format YYYY-MM-DD"),
  dueDate: z.string().nullable(),
  vendorName: z.string(),
  clientName: z.string(),
  lineItems: z.array(LineItemSchema),
  subtotalHt: z.number(),
  totalVat: z.number(),
  totalTtc: z.number(),
  currency: z.enum(["EUR", "USD", "GBP"]),
});

const response = await client.chat.parse({
  model: "mistral-large-latest",
  messages: [
    { role: "system", content: "Extract invoice data precisely." },
    { role: "user", content: invoiceText },
  ],
  responseFormat: InvoiceSchema,
  temperature: 0,
});

const invoice = response.choices[0].message.parsed!;
console.log(`Invoice ${invoice.invoiceNumber} — Total: ${invoice.totalTtc} ${invoice.currency}`);

Анализиране на отзиви по аспекти

Един реален клиентски отзив рядко е изцяло положителен или отрицателен. Хотелският отзив по-долу хвали стаята и закуската, осъжда паркинга и Wi-Fi, и предлага нюансиран поглед към персонала: една единствена глобална оценка би загубила цялата тази информация. Решението е да се моделира многократно използваем AspectSentiment и да се поиска списък от такива. Полето evidence е най-интересната част от схемата – изисквайки цитат от текста, Вие принуждавате модела да обоснове преценката си и си осигурявате средства за нейната проверка.

from pydantic import BaseModel, Field

class AspectSentiment(BaseModel):
    aspect: str = Field(description="The aspect analyzed (quality, price, service, delivery, etc.)")
    sentiment: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="Score between -1.0 (very negative) and 1.0 (very positive)")
    evidence: str = Field(description="Quote or excerpt from the text justifying the sentiment")

class ReviewAnalysis(BaseModel):
    overall_sentiment: str = Field(description="Overall sentiment: positive, negative, mixed, or neutral")
    overall_score: float = Field(description="Overall score between -1.0 and 1.0")
    aspects: list[AspectSentiment] = Field(description="Aspect-by-aspect analysis")
    recommendation: bool = Field(description="Does the author recommend the product/service?")
    key_strengths: list[str] = Field(description="Identified strengths")
    key_weaknesses: list[str] = Field(description="Identified weaknesses")

review_text = """
The hotel is magnificent; the room was spacious and clean. The breakfast is excellent
with a wide selection. However, the parking is outrageously expensive (€35/night) and the Wi-Fi was
unstable throughout the stay. The reception staff was very welcoming,
but room service took over an hour to deliver our order.
"""

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": "Analyze this customer review by detailing each mentioned aspect."
        },
        {"role": "user", "content": review_text}
    ],
    response_format=ReviewAnalysis,
    temperature=0
)

review = response.choices[0].message.parsed
print(f"Overall sentiment: {review.overall_sentiment} ({review.overall_score:+.1f})")
for aspect in review.aspects:
    print(f"  [{aspect.score:+.1f}] {aspect.aspect}: {aspect.sentiment}")

Класифициране на текст в множество категории

За разлика от простата класификация, при която се присвоява един единствен етикет, мулти-етикетната класификация признава, че един текст може да принадлежи към няколко категории. Инцидентът, описан по-долу, засяга едновременно сигурността, финансите, измамите и защитата на данните: налагането на един единствен етикет би обеднило логиката за насочване.

Два елемента от схемата заслужават внимание. reasoning изисква обосновка за всеки етикет, което подобрява качеството на оценките. requires_human_review превръща несигурността на модела в оперативен сигнал: вместо да откривате постфактум, че дадена класификация е съмнителна, Вие автоматично я ескалирате към човек, когато доверието падне под 0.7.

from pydantic import BaseModel, Field

class LabelScore(BaseModel):
    label: str = Field(description="Category name")
    confidence: float = Field(description="Confidence score between 0.0 and 1.0")
    reasoning: str = Field(description="One-sentence justification")

class MultiLabelClassification(BaseModel):
    primary_label: str = Field(description="Primary category")
    all_labels: list[LabelScore] = Field(
        description="All applicable categories with their confidence scores"
    )
    requires_human_review: bool = Field(
        description="True if classification is uncertain (confidence < 0.7)"
    )

text = """
Our mobile payment application has a security vulnerability allowing
access to banking data. Several customers have reported unauthorized
transactions. The technical team is currently investigating.
"""

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": """Classify this text among the following categories (multiple possible):
security, finance, technical, legal, customer_support, compliance, fraud, data_privacy.
Assign a confidence score to each applicable category."""
        },
        {"role": "user", "content": text}
    ],
    response_format=MultiLabelClassification,
    temperature=0
)

result = response.choices[0].message.parsed
print(f"Primary category: {result.primary_label}")
print(f"Human review required: {'Yes' if result.requires_human_review else 'No'}")
for label in result.all_labels:
    print(f"  [{label.confidence:.0%}] {label.label} — {label.reasoning}")

Факторизиране на извикването

Тези три примера споделят една и съща механика: системен промпт, текст, схема и temperature=0. Вместо да копирате извикването за всеки нов случай, извлечете го в обща функция. TypeVar, ограничен до BaseModel, запазва типовете: върнатият обект има типа на схемата, подадена като аргумент, и Вашата IDE го знае.

from typing import TypeVar, Type
from pydantic import BaseModel

T = TypeVar("T", bound=BaseModel)

def extract(client, text: str, schema: Type[T], system_prompt: str = "") -> T:
    """Reusable structured extraction."""
    messages = []
    if system_prompt:
        messages.append({"role": "system", "content": system_prompt})
    messages.append({"role": "user", "content": text})

    response = client.chat.parse(
        model="mistral-large-latest",
        messages=messages,
        response_format=schema,
        temperature=0
    )
    return response.choices[0].message.parsed

# Usage
invoice = extract(client, invoice_text, InvoiceData, "Extract invoice data.")
review = extract(client, customer_review, ReviewAnalysis, "Analyze this customer review.")
classification = extract(client, ticket, MultiLabelClassification, "Classify this text.")

Три много различни случая на употреба, всеки от които изисква само един ред код за извикване: това е конкретната полза от доброто моделиране на схеми.

Ключови изводи

  • Вложените схеми (list[LineItem], list[AspectSentiment]) позволяват сложен анализ
  • Изброимите типове (Currency, категории) ограничават възможните стойности
  • Полето evidence / reasoning принуждава модела да обоснове избора си
  • Обща обвиваща функция намалява дублирането на код
  • temperature=0 е задължително за тези производствени случаи на употреба