Ekstrakcja danych strukturalnych z obrazów
Na tej stronie
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