Ir al contenido principal
Español— Elegir un idioma
Menú

Extraer datos estructurados de imágenes

Lección 9 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Convierte imágenes en datos accionables
  2. El modo JSON de la API
  3. Extraer una tabla de una imagen
  4. Formularios y documentos administrativos
  5. Extraer datos de etiquetas de productos
  6. Canalización de extracción con validación
  7. Convertir a CSV o DataFrame
  8. Puntos clave

Convierte imágenes en datos accionables

La lección anterior se centró en la transcripción de texto; esta va un paso más allá generando datos estructurados. Extraer datos estructurados significa transformar el contenido visual de una imagen —una tabla, un formulario, una tarjeta de visita o una etiqueta— en JSON, CSV o cualquier otro formato que tu código pueda manipular directamente, sin necesidad de revisión manual.

Las consecuencias de un error son mayores. Una transcripción aproximada podría seguir siendo útil para un lector humano, pero la ausencia de una única clave en una respuesta JSON hará fallar el programa que la consume. Esta lección cubre las dos garantías que debes implementar: el modo JSON de la API para la validez sintáctica y la validación de esquemas para el cumplimiento de las reglas de negocio.

El modo JSON de la API

Mistral ofrece el parámetro response_format que obliga al modelo a devolver JSON válido. Sin él, perderás tiempo limpiando respuestas envueltas en bloques Markdown o precedidas por frases introductorias de cortesía.

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": "Devuelve siempre un objeto JSON válido con los datos extraídos de la imagen."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extrae los siguientes datos de esta tarjeta de visita como JSON: nombre, cargo, empresa, correo electrónico, teléfono, dirección."
                },
                {"type": "image_url", "image_url": data_uri_carte}
            ]
        }
    ]
)

# El resultado es directamente analizable
donnees = json.loads(response.choices[0].message.content)
print(json.dumps(donnees, indent=2, ensure_ascii=False))

La llamada a json.loads se ejecuta sin precauciones especiales: response_format={"type": "json_object"} garantiza una salida JSON sintácticamente válida. Sin embargo, no garantiza qué claves estarán presentes. Por eso debes describir el formato esperado en el propio prompt, como se muestra en los ejemplos siguientes.

Extraer una tabla de una imagen

Las fotografías de tablas o las capturas de pantalla son un caso de uso habitual, y es aquí donde un esquema explícito resulta más rentable. Sin instrucciones claras, el modelo inventará su propia estructura, que puede variar en cada llamada.

prompt_tableau = """Extrae el contenido de esta tabla como JSON.
Formato esperado:
{
  "columns": ["Columna1", "Columna2", ...],
  "rows": [
    {"Columna1": "valor", "Columna2": "valor"},
    ...
  ]
}
Lee todas las filas visibles. Si una celda está vacía, usa 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"Columnas: {donnees['columns']}")
print(f"Número de filas: {len(donnees['rows'])}")

La instrucción sobre las celdas vacías es crítica. Sin ella, el modelo podría desplazar valores para rellenar huecos, distorsionando la tabla. Mostrar el recuento de filas proporciona una comprobación de cordura inmediata: si la imagen muestra doce filas pero el script informa de ocho, la extracción está incompleta.

Formularios y documentos administrativos

Los formularios rellenados presentan dos desafíos: la escritura a mano y las casillas de verificación, que no tienen valor de texto. Por lo tanto, tu esquema debe incluir campos dedicados para estos casos.

prompt_formulaire = """Analiza este formulario rellenado y extrae todos los campos y sus valores.
Formato JSON esperado:
{
  "form_type": "...",
  "fields": {
    "field_name": "entered_value",
    ...
  },
  "checked_boxes": ["field1", "field2"],
  "signature_present": true/false
}
Si un campo está vacío o es ilegible, usa null."""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "Eres un extractor de formularios preciso. Devuelve JSON estructurado."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_formulaire},
                {"type": "image_url", "image_url": encoder_image("formulaires/cerfa-12345.jpg")}
            ]
        }
    ]
)

Extraer datos de etiquetas de productos

Las etiquetas alimentarias siguen una estructura estándar: una tabla de información nutricional por 100 g, una lista de ingredientes y alérgenos. Puedes definir el esquema hasta el nombre de la unidad, evitando así suposiciones posteriores sobre si «12» se refería a gramos o kilocalorías.

prompt_etiquette = """Extrae la información nutricional de esta etiqueta.
Formato JSON:
{
  "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)

Canalización de extracción con validación

En producción, las garantías sintácticas no son suficientes. El modelo podría devolver un JSON perfectamente válido donde falte email, o donde phone contenga un entero en lugar de una cadena. Pydantic convierte estos casos en excepciones explícitas en la etapa de extracción, en lugar de tres pasos más adelante en tu canalización.

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):
    """Extrae y valida los datos de una tarjeta de visita."""
    response = client.chat.complete(
        model="mistral-large-latest",
        response_format={"type": "json_object"},
        messages=[
            {
                "role": "system",
                "content": "Extrae los datos de esta tarjeta de visita. Campos: last_name, first_name, title, company, email, phone, address, website. Devuelve JSON."
            },
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Extrae la información de esta tarjeta de visita."},
                    {"type": "image_url", "image_url": encoder_image(image_path)}
                ]
            }
        ]
    )

    # Analizar y validar con Pydantic
    raw_data = json.loads(response.choices[0].message.content)
    card = BusinessCard(**raw_data)
    return card

# Uso
card = extract_business_card("cartes/contact-dupont.jpg")
print(f"Contacto: {card.first_name} {card.last_name} - {card.email}")

Observa la distinción entre last_name: str y title: Optional[str] = None. Una tarjeta sin nombre es una extracción fallida; una tarjeta sin cargo es un caso normal. Tú trazas esa línea y Pydantic la hace cumplir.

Convertir a CSV o DataFrame

El paso final es alimentar tu canalización de procesamiento de datos. El JSON producido anteriormente se convierte directamente:

import pandas as pd

# Desde una tabla extraída
donnees = json.loads(response.choices[0].message.content)

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

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

El argumento encoding="utf-8" durante la exportación es obligatorio siempre que tus datos contengan caracteres acentuados o símbolos de moneda.

Puntos clave

  • El parámetro response_format={"type": "json_object"} garantiza una salida JSON válida
  • Proporciona siempre un esquema JSON esperado en tu prompt para guiar la extracción
  • Usa Pydantic para validar los datos extraídos en producción
  • Las tablas, formularios, etiquetas y tarjetas de visita son objetivos ideales
  • Combina la extracción con pandas para una integración directa en tus flujos de trabajo de datos