Przejdź do głównej treści
Polski— Wybierz język
Menu

Ekstrakcja danych strukturalnych z obrazów

Lekcja 9 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Zamiana obrazów na dane gotowe do działania
  2. Tryb JSON w API
  3. Ekstrakcja tabeli z obrazu
  4. Formularze i dokumenty administracyjne
  5. Ekstrakcja danych z etykiet produktów
  6. Potok ekstrakcji z walidacją
  7. Konwersja do CSV lub DataFrame
  8. Kluczowe wnioski

Zamiana obrazów na dane gotowe do działania

Poprzednia lekcja skupiała się na transkrypcji tekstu; ta idzie o krok dalej, generując dane strukturalne. Ekstrakcja danych strukturalnych oznacza przekształcenie zawartości wizualnej obrazu – tabeli, formularza, wizytówki lub etykiety – w format JSON, CSV lub dowolny inny, którym Twój kod może manipulować bezpośrednio, bez konieczności ręcznej weryfikacji.

Stawka jest wyższa. Przybliżona transkrypcja może wciąż pomóc człowiekowi, ale brak nawet jednego klucza w odpowiedzi JSON spowoduje awarię programu, który ją przetwarza. W tej lekcji omówimy dwa gwarantowane mechanizmy, które musisz wdrożyć: tryb JSON API zapewniający poprawność składniową oraz walidację schematu zgodną z wymaganiami biznesowymi.

Tryb JSON w API

Mistral oferuje parametr response_format, który wymusza na modelu zwracanie poprawnego kodu JSON. Bez niego stracisz czas na czyszczenie odpowiedzi owiniętych w bloki Markdown lub poprzedzonych uprzejmymi zdaniami wstępnymi.

from mistralai.client import Mistral
import os
import json

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

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "Always return a valid JSON object with the data extracted from the image."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extract the following data from this business card as JSON: name, title, company, email, phone, address."
                },
                {"type": "image_url", "image_url": data_uri_carte}
            ]
        }
    ]
)

# Wynik można bezpośrednio sparsować
donnees = json.loads(response.choices[0].message.content)
print(json.dumps(donnees, indent=2, ensure_ascii=False))

Wywołanie json.loads przebiega bez specjalnych zabezpieczeń: response_format={"type": "json_object"} gwarantuje składniowo poprawne wyjście JSON. Nie gwarantuje jednak, jakie klucze będą obecne. Dlatego musisz opisać oczekiwany format bezpośrednio w prompcie, jak pokazano w poniższych przykładach.

Ekstrakcja tabeli z obrazu

Zdjęcia tabel lub zrzuty ekranu to częsty przypadek użycia i właśnie tutaj jawny schemat przynosi największe korzyści. Bez jasnych instrukcji model wymyśli własną strukturę, która może różnić się przy każdym wywołaniu.

prompt_tableau = """Extract the content of this table as JSON.
Expected format:
{
  "columns": ["Column1", "Column2", ...],
  "rows": [
    {"Column1": "value", "Column2": "value"},
    ...
  ]
}
Read all visible rows. If a cell is empty, use null."""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_tableau},
                {"type": "image_url", "image_url": encoder_image("captures/tableau-excel.png")}
            ]
        }
    ]
)

donnees = json.loads(response.choices[0].message.content)
print(f"Columns: {donnees['columns']}")
print(f"Number of rows: {len(donnees['rows'])}")

Instrukcja dotycząca pustych komórek jest kluczowa. Bez niej model może przesunąć wartości, aby wypełnić luki, zniekształcając tym samym tabelę. Wyświetlenie liczby wierszy zapewnia natychmiastową kontrolę poprawności: jeśli obraz pokazuje dwanaście wierszy, a skrypt zgłasza osiem, ekstrakcja jest niekompletna.

Formularze i dokumenty administracyjne

Wypełnione formularze wprowadzają dwa wyzwania: odręczne pismo i pola wyboru (checkboxy), które nie mają wartości tekstowej. Twój schemat musi zatem zawierać dedykowane pola dla tych elementów.

prompt_formulaire = """Analyze this filled form and extract all fields and their values.
Expected JSON format:
{
  "form_type": "...",
  "fields": {
    "field_name": "entered_value",
    ...
  },
  "checked_boxes": ["field1", "field2"],
  "signature_present": true/false
}
If a field is empty or illegible, use null."""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "You are a precise form extractor. Return structured JSON."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_formulaire},
                {"type": "image_url", "image_url": encoder_image("formulaires/cerfa-12345.jpg")}
            ]
        }
    ]
)

Ekstrakcja danych z etykiet produktów

Etykiety żywności mają standardową strukturę: tabela wartości odżywczych na 100 g, lista składników i alergeny. Możesz zdefiniować schemat aż do nazwy jednostki, unikając późniejszych domysłów, czy „12“ odnosiło się do gramów, czy kilokalorii.

prompt_etiquette = """Extract the nutritional information from this label.
JSON format:
{
  "product_name": "...",
  "net_weight": "...",
  "nutrition_per_100g": {
    "energy_kcal": ...,
    "fat_g": ...,
    "saturated_fat_g": ...,
    "carbohydrates_g": ...,
    "sugars_g": ...,
    "protein_g": ...,
    "salt_g": ...
  },
  "ingredients": "...",
  "allergens": ["..."]
}"""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_etiquette},
                {"type": "image_url", "image_url": encoder_image("produits/etiquette.jpg")}
            ]
        }
    ]
)

produit = json.loads(response.choices[0].message.content)

Potok ekstrakcji z walidacją

W środowisku produkcyjnym gwarancje składniowe nie wystarczają. Model może zwrócić perfekcyjnie poprawny JSON, w którym brakuje pola email lub gdzie phone zawiera liczbę całkowitą zamiast ciągu znaków. Pydantic zamienia takie przypadki w jawne wyjątki na etapie ekstrakcji, a nie trzy kroki dalej w Twoim potoku przetwarzania.

from pydantic import BaseModel, Field
from typing import Optional
import json

class BusinessCard(BaseModel):
    last_name: str
    first_name: str
    title: Optional[str] = None
    company: Optional[str] = None
    email: Optional[str] = None
    phone: Optional[str] = None
    address: Optional[str] = None
    website: Optional[str] = None

def extract_business_card(image_path):
    """Extract and validate business card data."""
    response = client.chat.complete(
        model="mistral-large-latest",
        response_format={"type": "json_object"},
        messages=[
            {
                "role": "system",
                "content": "Extract data from this business card. Fields: last_name, first_name, title, company, email, phone, address, website. Return JSON."
            },
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Extract information from this business card."},
                    {"type": "image_url", "image_url": encoder_image(image_path)}
                ]
            }
        ]
    )

    # Parsowanie i walidacja za pomocą Pydantic
    raw_data = json.loads(response.choices[0].message.content)
    card = BusinessCard(**raw_data)
    return card

# Użycie
card = extract_business_card("cartes/contact-dupont.jpg")
print(f"Contact: {card.first_name} {card.last_name} - {card.email}")

Zwróć uwagę na różnicę między last_name: str a title: Optional[str] = None. Wizytówka bez nazwiska to nieudana ekstrakcja; wizytówka bez stanowiska to sytuacja normalna. To Ty wyznaczasz tę granicę, a Pydantic jej przestrzega.

Konwersja do CSV lub DataFrame

Ostatnim krokiem jest zasilenie Twojego potoku przetwarzania danych. Wygenerowany powyżej JSON konwertuje się bezpośrednio:

import pandas as pd

# Z wyekstrahowanej tabeli
donnees = json.loads(response.choices[0].message.content)

# Utworzenie DataFrame pandas
df = pd.DataFrame(donnees["rows"])
print(df.to_string())

# Eksport do CSV
df.to_csv("export/tableau_extrait.csv", index=False, encoding="utf-8")

Argument encoding="utf-8" podczas eksportu jest obowiązkowy, gdy Twoje dane zawierają znaki akcentowane lub symbole walut.

Kluczowe wnioski

  • Parametr response_format={"type": "json_object"} gwarantuje poprawne wyjście JSON
  • Zawsze podawaj oczekiwany schemat JSON w prompcie, aby kierować ekstrakcją
  • Używaj Pydantic do walidacji wyekstrahowanych danych w środowisku produkcyjnym
  • Tabele, formularze, etykiety i wizytówki to idealne cele ekstrakcji
  • Połącz ekstrakcję z pandas, aby bezpośrednio zintegrować dane z Twoimi przepływami pracy