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

Пайплайн за производство

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

Актуализация от 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.

От доказателство на концепцията до производство

Научихте как да използвате OCR, анотации и въпроси и отговори за Document AI. Остава една скъпа пропаст: разстоянието между скрипт, който работи на вашия лаптоп, и услуга, на която колегите Ви разчитат всяка сутрин. Този финален урок събира предишните строителни блокове в надежден пайплайн, завършен с възстановяване от грешки, мониторинг и контрол на разходите.

Шестте компонента на един завършен пайплайн

  1. Опашка за входящи данни (Ingestion Queue): Получава и приоритизира документите.
  2. Предварителна обработка: Валидира, конвертира формати и подобрява изображенията.
  3. OCR + Анотации: Извлича текст и структурирани данни.
  4. Последваща обработка: Валидира, почиства и обогатява данните.
  5. Съхранение: Бази данни, векторни хранилища и архивиране.
  6. Интерфейс за заявки: QnA API, табла за управление и интеграции.

Кодът в този урок обхваща ядрото на веригата – стъпки 3 и 4 – защото там се концентрират оперативните трудности.

Клас, който капсулира обработката

Класът PipelineDocumentAI задава конфигурацията веднъж завинаги – схемата за анотации, формата на таблиците и броя на повторните опити – след което я прилага към всеки документ. Три механизма заслужават вниманието Ви. Първо, повторният опит с експоненциално забавяне (time.sleep(2 ** tentative)) разпределя опитите на една, после две, после четири секунди. Това дава време на преходното претоварване на API да се разреши, вместо да го влошава. Второ, регистрирането (logging) проследява всеки успех с броя страници и продължителността, както и всеки неуспех с номера на опита; без тези редове ще откриете инцидентите едва когато счетоводството Ви се обади. Накрая, речникът stats захранва доклада в края на партидата.

Обърнете внимание, че методът винаги връща ResultatTraitement, дори след изчерпване на повторните опити: извикващият никога не трябва да обработва изключение, а просто чете полето erreur.

import os
import time
import base64
import logging
from pathlib import Path
from dataclasses import dataclass, field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
from typing import Optional

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("document_ai_pipeline")

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


@dataclass
class ResultatTraitement:
    fichier: str
    pages: int = 0
    texte: str = ""
    annotations: Optional[dict] = None
    duree_secondes: float = 0.0
    erreur: Optional[str] = None


class PipelineDocumentAI:
    def __init__(
        self,
        schema_annotation=None,
        table_format: str = "markdown",
        max_retries: int = 3,
    ):
        self.schema_annotation = schema_annotation
        self.table_format = table_format
        self.max_retries = max_retries
        self.stats = {"total": 0, "succes": 0, "erreurs": 0}

    def traiter_document(self, chemin: str) -> ResultatTraitement:
        """Processes a document with retry and monitoring."""
        debut = time.time()
        self.stats["total"] += 1

        for tentative in range(self.max_retries):
            try:
                # Read and encode
                with open(chemin, "rb") as f:
                    doc_b64 = base64.b64encode(f.read()).decode("utf-8")

                # Call parameters
                params = {
                    "model": "mistral-ocr-latest",
                    "document": {
                        "type": "document_url",
                        "document_url": f"data:application/pdf;base64,{doc_b64}"
                    },
                    "table_format": self.table_format,
                }

                if self.schema_annotation:
                    params["document_annotation_format"] = (
                        response_format_from_pydantic_model(
                            self.schema_annotation
                        )
                    )

                # OCR Call
                response = client.ocr.process(**params)

                # Extract text
                texte = "\n\n".join(
                    p.markdown for p in response.pages
                )

                # Extract annotations
                annotations = None
                if self.schema_annotation:
                    if response.document_annotation:
                        annotations = response.document_annotation

                duree = time.time() - debut
                self.stats["succes"] += 1

                logger.info(
                    f"OK: {chemin} ({len(response.pages)} pages, "
                    f"{duree:.1f}s)"
                )

                return ResultatTraitement(
                    fichier=chemin,
                    pages=len(response.pages),
                    texte=texte,
                    annotations=annotations,
                    duree_secondes=duree,
                )

            except Exception as e:
                logger.warning(
                    f"Tentative {tentative + 1}/{self.max_retries} "
                    f"échouée pour {chemin}: {e}"
                )
                if tentative < self.max_retries - 1:
                    time.sleep(2 ** tentative)  # Exponential backoff

        # All attempts failed
        self.stats["erreurs"] += 1
        return ResultatTraitement(
            fichier=chemin,
            duree_secondes=time.time() - debut,
            erreur="Échec après toutes les tentatives",
        )

    def traiter_dossier(self, dossier: str) -> list[ResultatTraitement]:
        """Processes all PDFs in a folder."""
        chemin = Path(dossier)
        fichiers = sorted(chemin.glob("*.pdf"))
        resultats = []

        for fichier in fichiers:
            resultat = self.traiter_document(str(fichier))
            resultats.append(resultat)

        return resultats

    def rapport(self) -> str:
        """Generates a processing report."""
        return (
            f"Documents traités : {self.stats['total']}\n"
            f"Succès : {self.stats['succes']}\n"
            f"Erreurs : {self.stats['erreurs']}\n"
            f"Taux de succès : "
            f"{self.stats['succes']/max(self.stats['total'],1)*100:.1f}%"
        )

На практика един и същи клас покрива и двете нужди: инстанциран без схема, той просто извлича текст; инстанциран с Pydantic модел, той също така произвежда структурирани данни.

# Simple pipeline (OCR only)
pipeline = PipelineDocumentAI(table_format="markdown")
resultats = pipeline.traiter_dossier("./factures/")
print(pipeline.rapport())

# Pipeline with annotations
from pydantic import BaseModel, Field

class ExtractionFacture(BaseModel):
    fournisseur: str = Field(..., description="Nom du fournisseur")
    montant_ttc: float = Field(..., description="Montant TTC")
    date: str = Field(..., description="Date (YYYY-MM-DD)")

pipeline_annote = PipelineDocumentAI(
    schema_annotation=ExtractionFacture,
    table_format="markdown"
)
resultats = pipeline_annote.traiter_dossier("./factures/")

Предвиждане на сметката

Контролът на разходите е от съществено значение в производството и започва с разбирането на това, за което Ви се таксува.

ЕлементОснова за таксуване
OCRНа обработена страница
АнотацииВключени в OCR повикването (без допълнително заплащане)
QnAВходни/изходни токени въз основа на чат модела
Вграждания (Embeddings)Входни токени

Фактът, че анотациите не носят допълнителни разходи, променя дизайна: извличайте метаданните по време на OCR прохода, вместо да стартирате отделно LLM повикване впоследствие. Функцията за оценка по-долу Ви позволява да оцените проекта преди стартирането му; нейните тарифи са приблизителни фигури, които да коригирате, като публикуваната справочна таблица на Mistral остава авторитетният източник.

def estimer_cout(
    nombre_pages: int,
    avec_qna: bool = False,
    modele_qna: str = "mistral-small-latest"
) -> dict:
    """Estimates processing cost."""

    # Approximate rates (check current rates)
    cout_ocr_par_page = 0.001  # Adjust based on tier
    cout_qna_par_1k_tokens = {
        "mistral-small-latest": 0.001,
        "mistral-large-latest": 0.008,
    }

    cout_ocr = nombre_pages * cout_ocr_par_page
    cout_qna = 0.0

    if avec_qna:
        # Estimate: ~500 tokens per page on average
        tokens_estimes = nombre_pages * 500
        cout_qna = (
            tokens_estimes / 1000
            * cout_qna_par_1k_tokens.get(modele_qna, 0.001)
        )

    return {
        "cout_ocr": round(cout_ocr, 4),
        "cout_qna": round(cout_qna, 4),
        "cout_total": round(cout_ocr + cout_qna, 4),
    }

Мониторинг на здравето на услугата

Един пайплайн се влошава бавно и тихо: нов доставчик изпраща сканирания с лошо качество, процентът на грешки скача от 2% на 15% и никой не забелязва до месечното приключване. Четири метрики са достатъчни за откриване на отклонение – обработен обем, средна продължителност, процент на грешките и оценена цена – при условие че ги излъчвате систематично и ги изпращате към Вашия обичаен инструмент, било то Datadog, Prometheus или друг.

import json
from datetime import datetime

def log_metrique(nom: str, valeur: float, tags: dict = None) -> None:
    """Records a monitoring metric."""
    metrique = {
        "timestamp": datetime.utcnow().isoformat(),
        "nom": nom,
        "valeur": valeur,
        "tags": tags or {}
    }
    # In production: send to Datadog, Prometheus, etc.
    logger.info(f"METRIQUE: {json.dumps(metrique)}")

# Example metrics to track
log_metrique("ocr.pages_traitees", 150, {"batch": "factures_mars"})
log_metrique("ocr.duree_moyenne_secondes", 2.3)
log_metrique("ocr.taux_erreur", 0.02)
log_metrique("ocr.cout_estime_usd", 0.15)

Къде да продължите оттук

Сега разполагате с основите за изграждане на цялостна система Document AI и се отварят няколко разширения в зависимост от Вашите ограничения. Много големите обеми оправдават локално разполагане (on-premise) на OCR модела на специализиран GPU; документите, силно специфични за Вашия бизнес, могат да мотивират фина настройка (fine-tuning), тема, която да обсъдите директно с Mistral. От гледна точка на интеграцията, предизвикателството е свързването на пайплайна с Вашите съществуващи системи – ERP, CRM – и изграждането на табло за управление, така че екипите Ви да могат сами да правят заявки към документите, без да минават през Вас. Финалната стъпка е премахването на ръчното задействане: пайплайнът работи автоматично, когато пристигнат нови документи.

Обобщение на курса

Тези шестнадесет урока Ви преведоха през целия цикъл. Започнахте с основите – какво е Document AI, моделът OCR 4 и случаите на употреба – преди да преминете към усъвършенстван OCR с API, извличане на таблици, горни/долни колонтитули и оптимизация. След това анотациите Ви дадоха структурирано извличане, пакетна обработка и контрол на съответствието, последвани от Document QnA, което отвори възможността за заявки на естествен език, от изолирани документи до корпуси, индексирани в RAG. Сега разполагате с необходимите строителни блокове, за да оборудвате управлението на документи във Вашата организация с Mistral Document AI.

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

  • Един производствен пайплайн включва повторни опити, регистриране, мониторинг и управление на разходите.
  • Експоненциалното забавяне предпазва от преходни грешки на API.
  • Оценявайте разходите си преди мащабиране (OCR на страница, QnA на токен).
  • Непрекъснатият мониторинг позволява откриването на влошаване на производителността.
  • Document AI обхваща целия жизнен цикъл на документа, от приемането до експлоатацията.

Проверете знанията си

OCR, анотации, QnA: валидирайте цялата верига за документи.

1. Какво произвежда OCR API на Mistral от един документ?

Отговор: Структурираното съдържание на документа – текст, таблици, оформление – готово за програмна употреба: OCR 4 чете документа като източник на данни, а не като изображение.

2. Каква е целта на API за анотации?

Отговор: Да извлича структурирани метаданни според Вашата схема (полета на фактури, клаузи в договори) – индивидуално или пакетно за големи обеми.

3. Какво позволява Document QnA?

Отговор: Задаването на въпроси на естествен език относно един или повече документи и получаването на отговори въз основа на тяхното съдържание – разговорният слой върху извличането.

4. Как оптимизирате точността на OCR?

Отговор: Чрез качеството на входа (резолюция, острота, ориентация) и обработката на трудните зони – горни и долни колонтитули, номерация на страници, които курсът Ви учи да управлявате изрично.

5. Защо да комбинирате OCR и RAG?

Отговор: OCR трансформира сканираните документи в индексируем текст, докато RAG ги прави достъпни за заявки в мащаб: заедно те позволяват семантично търсене в цели архиви.

Извличане, анотиране, въпроси и отговори, индексиране: горният производствен пайплайн свързва всичките четири заедно – Вашата документация се превръща в база данни.