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

Извличане на структурирани метаданни

Урок 10 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Извлечете точно това, от което имате нужда
  2. Структура вместо изравняване
  3. Повтарящи се данни
  4. Квадратчета за отметка и формуляри
  5. Изпълнение от край до край
  6. Ключови изводи

Актуализация от 2 ноември 2026 г. — OCR. OCR 4.0 (mistral-ocr-4-0) беше прекратен на 30 септември 2026 г. Използвайте OCR 4.1 (mistral-ocr-4-1), който е общодостъпен от 31 август на същата цена, или псевдонима mistral-ocr-latest, който сочи към него от 16 юли. OCR 4.1 добавя оценки за надеждност на ниво блок. Допълнение от 3 ноември 2026 г.: Локален PDF файл се предава в base64 като {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; типът document_base64 от по-старите примери не съществува нито в документацията, нито в SDK mistralai и тези примери биха се провалили. Източници: OCR Processor · Document QnA. Коригирано на 3 ноември 2026 г.: Предишният код четеше page.document_annotation страница по страница; в SDK mistralai версия 3.7.0 анотацията на документа е едно поле в отговора (response.document_annotation), а анотацията на изображението се чете от image.image_annotation.

Извлечете точно това, от което имате нужда

Анотирането на документи не се ограничава само до извличане на суров текст. То произвежда структурирани, типизирани и валидирани данни, готови за незабавна употреба във вашите системи: ред, вмъкнат в база данни; поле, сравнено с референтна стойност; или сума, проверена преди плащане. Предизвикателството се измества изцяло към проектирането на схемата, което е фокусът на този урок.

Структура вместо изравняване

Схемата за извличане трябва да отразява реалността на документа. Една фактура идва от юридическо лице с име на компания, номер SIRET (френски бизнес идентификатор) и адрес. Вместо да подравнявате осем полета като emetteur_rue, emetteur_ville, emetteur_siret, дефинирайте модел Address, след което модел LegalEntity, който го съдържа. Използвайте повторно тези градивни елементи както за издателя, така и за получателя. Изброението DocumentType играе подобна роля: то предотвратява измислянето на категория от модела и гарантира стойност, която можете да използвате в инструкция if или за насочване. Полетата Optional изрично посочват какво може да липсва, докато стойностите по подразбиране – като default="France" за държавата – избавят модела от необходимостта да guessed очевидното.

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

class DocumentType(str, Enum):
    INVOICE = "facture"
    CONTRACT = "contrat"
    REPORT = "rapport"
    FORM = "formulaire"
    OTHER = "autre"

class Address(BaseModel):
    street: Optional[str] = Field(None, description="Numéro et street")
    postal_code: Optional[str] = Field(None, description="Code postal")
    city: Optional[str] = Field(None, description="Ville")
    country: str = Field(default="France", description="Pays")

class LegalEntity(BaseModel):
    name: str = Field(..., description="Raison sociale")
    siret: Optional[str] = Field(None, description="Numéro SIRET")
    address: Optional[Address] = Field(None, description="Address postale")
    email: Optional[str] = Field(None, description="Address email")

class DocumentExtraction(BaseModel):
    document_type: DocumentType = Field(
        ..., description="Type du document"
    )
    date: Optional[str] = Field(
        None, description="Date principale (YYYY-MM-DD)"
    )
    emetteur: LegalEntity = Field(
        ..., description="Entité qui émet le document"
    )
    destinataire: Optional[LegalEntity] = Field(
        None, description="Entité destinataire"
    )
    resume: str = Field(
        ..., description="Résumé en 2-3 phrases du contenu"
    )
    langue: str = Field(
        ..., description="Langue du document (code ISO 639-1)"
    )

Повтарящи се данни

Много документи съдържат серии: редове за фактуриране, клаузи или статии за разходи. Моделирайте ги като list[...] от специализиран подмодел. Тогава моделът сканира таблицата на документа и произвежда толкова обекти InvoiceLine, колкото редове открие, включително описанието, количеството, единичната цена и общата сума за всеки от тях. Това ви предоставя достатъчно данни, за да преизчислите сами междинната сума и да проверите съгласуваността на документа, преди да го приемете.

from pydantic import BaseModel, Field

class InvoiceLine(BaseModel):
    description: str = Field(..., description="Description du produit/service")
    quantity: float = Field(..., description="Quantité")
    unit_price: float = Field(..., description="Prix unitaire HT")
    amount: float = Field(..., description="Montant total HT de la ligne")

class DetailedInvoice(BaseModel):
    supplier: str = Field(..., description="Nom du supplier")
    number: str = Field(..., description="Numéro de facture")
    date: str = Field(..., description="Date (YYYY-MM-DD)")
    lines: list[InvoiceLine] = Field(
        ..., description="Lignes de la facture"
    )
    subtotal_excl_tax: float = Field(..., description="Sous-total HT")
    vat: float = Field(..., description="Montant TVA")
    total_incl_tax: float = Field(..., description="Total TTC")
    payment_terms: str = Field(
        ..., description="Conditions de paiement mentionnées"
    )

Квадратчета за отметка и формуляри

Сканираните хартиени формуляри са областта, в която моделът блести. Поле от тип bool, сдвоено с етикета на въпроса, е достатъчно: моделът разпознава дали квадратчето е отметнато, извлича съответния въпрос и – което е от решаващо значение за медицинска или административна употреба – заключава, че липсва поле, вместо да измисля стойност, както демонстрира екипът на Mistral. Бележката “null if not provided” в описанието на телефонния номер не е декоративна; тя изрично разрешава празна стойност.

from pydantic import BaseModel, Field

class FormResponse(BaseModel):
    question: str = Field(..., description="Intitulé de la question")
    answer: bool = Field(..., description="True si coché, False sinon")

class MedicalForm(BaseModel):
    patient_name: str = Field(..., description="Nom complet du patient")
    age: Optional[int] = Field(None, description="Âge du patient")
    sex: Optional[str] = Field(None, description="Sexe (M/F)")
    patient_id: Optional[str] = Field(None, description="ID patient")
    phone: Optional[str] = Field(
        None, description="Numéro de téléphone (null si non fourni)"
    )
    responses: list[FormResponse] = Field(
        ..., description="Réponses aux questions du formulaire"
    )

Изпълнение от край до край

Вземете примера с подробната фактура и го свържете с документ, кодиран в base64. Подканата за анотация допълва схемата, като уточнява типа на файла и набляга на вниманието към редовете за фактуриране; валидирането на Pydantic при връщане преобразува JSON низа в обект, който можете безопасно да обхождате.

import os
import json
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    },
    document_annotation_format=response_format_from_pydantic_model(
        DetailedInvoice
    ),
    document_annotation_prompt=(
        "Ce document est une invoice. Extrais toutes les lines "
        "de facturation avec leurs montants."
    )
)

# Extraction and validation
if ocr_response.document_annotation:
    invoice = DetailedInvoice.model_validate_json(
        ocr_response.document_annotation
    )

    print(f"Facture {invoice.numero} - {invoice.fournisseur}")
    print(f"Date : {invoice.date}")
    print(f"\nLignes :")
    for line in invoice.lines:
        print(f"  - {line.description}: {line.quantite} x "
              f"{line.prix_unitaire}€ = {line.montant}€")
    print(f"\nTotal TTC : {invoice.total_incl_tax}€")

Лошите резултати от извличането почти винаги произтичат от схемата, рядко от модела. Прегледайте описанията си едно по едно: те трябва да бъдат точни и недвусмислени, тъй като моделът разчита единствено на тях, за да разбере вашите очаквания. Пишете ги на езика на вашите документи – френският работи перфектно за френски фактури – и запазете изброенията (enums) за полета с ограничени стойности, а подмоделите – за структури, които ще използвате повторно в различни схеми.

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

  • Схемите на Pydantic позволяват извличане на типизирани и валидирани данни
  • Използвайте сложни типове (списъци, изброявания, вложени модели) за прецизни извличания
  • Моделът обработва надеждно незадължителни полета и квадратчета за отметка
  • Описанията на полетата насочват извличането: бъдете точни и изрични
  • Комбинирайте document_annotation_prompt със схемата за максимален контекст