Analisar Gráficos com a Vision API
Nesta página
Ler Gráficos como um Analista
Os gráficos — de barras, de linhas, circulares, de área — estão presentes em toda a parte nos relatórios empresariais, nos painéis de controlo e nas publicações científicas. Colocam um problema específico: a informação está encerrada numa imagem, muitas vezes sem os dados de origem anexados. Um relatório anual em PDF pode conter trinta curvas, e ninguém possui já o ficheiro Excel original.
A Vision API da Mistral consegue ler estes gráficos, interpretar tendências e extrair dados numéricos. Esta lição mostra-lhe como escrever prompts que produzem resultados acionáveis em vez de comentários vagos, e como estruturar o output.
Princípios da Análise de Gráficos
Deixado à sua sorte, o modelo produz uma frase genérica como «este gráfico mostra a evolução das vendas». Um prompt eficaz impõe, em vez disso, um processo ordenado: identificar o tipo de gráfico (barras, linhas, circular, dispersão), ler os eixos e as legendas com as suas unidades e escalas, extrair valores aproximando a posição visual e, só depois, interpretar as tendências — subida, descida, sazonalidade, anomalias. A ordem importa: uma interpretação formada antes da leitura dos eixos é uma interpretação inventada.
Analisar um Gráfico de Barras
A mensagem de sistema é o local natural para codificar este método de uma vez por todas, independentemente da imagem a analisar:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": """You are an expert data analyst. When analyzing a chart:
1. Identify the chart type and its title
2. Describe the axes (labels, units, scale)
3. List the main values you can read
4. Identify trends, highs/lows, and anomalies
5. Write a 2-3 sentence conclusion"""
},
{
"role": "user",
"content": [
{"type": "text", "text": "Analyze this bar chart of quarterly revenue."},
{"type": "image_url", "image_url": "https://exemple.com/ca-trimestriel.png"}
]
}
]
)
print(response.choices[0].message.content)
O prompt de sistema estrutura a resposta do modelo em passos lógicos, melhorando tanto a precisão como a legibilidade. Obtém um relatório coerente de um gráfico para o outro, o que é essencial se estas respostas precisarem de ser processadas automaticamente mais tarde.
Extrair Dados Numéricos
Para obter dados utilizáveis em vez de uma descrição, a instrução deve ser explicitamente restritiva. O modelo tem uma tendência natural para comentar; deve proibi-lo:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "You are a data extractor. Analyze the chart and return the data as a markdown table. Do not comment, do not describe—only extract the data."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Extract the data from this bar chart into a table."},
{"type": "image_url", "image_url": "https://exemple.com/ventes-mensuelles.png"}
]
}
]
)
O modelo devolverá algo como:
| Month | Sales (k€) |
|----------|------------|
| January | 120 |
| February | 135 |
| March | 148 |
Este formato analisa-se em poucas linhas de código e importa-se diretamente para uma folha de cálculo ou DataFrame.
Analisar um Gráfico de Linhas (Tendências)
Os gráficos de linhas são particularmente adequados para a análise de tendências, e a pergunta pode então tornar-se num questionário completo colocado na mensagem do utilizador:
prompt_tendance = """Analyze this line chart and answer:
1. What is the general trend (rising, falling, stable)?
2. Are there any inflection points? If so, on what dates?
3. Do you observe seasonality?
4. What is the approximate value at the start and end of the period?
5. What projection do you make for the next quarter?"""
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": prompt_tendance},
{"type": "image_url", "image_url": "https://exemple.com/evolution-prix.png"}
]
}
]
)
A quinta pergunta é de natureza diferente das primeiras quatro: pede uma extrapolação, não uma leitura. Trate a sua resposta como uma hipótese a validar, nunca como um facto.
Analisar um Gráfico Circular (Distribuição)
Para os gráficos circulares, a questão foca-se nas proporções e na concentração em vez da evolução:
prompt_camembert = """Analyze this pie chart:
- List each segment with its approximate percentage
- Identify the dominant segment
- Indicate whether the distribution is concentrated or dispersed
Return the data in a markdown table."""
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": prompt_camembert},
{"type": "image_url", "image_url": "https://exemple.com/repartition-marche.png"}
]
}
]
)
Verifique sempre se a soma das percentagens devolvidas se aproxima de 100: um total de 87% sinaliza uma leitura incompleta, um segmento esquecido ou um oculto pela legenda.
Pipeline de Análise de Relatórios
Estas chamadas isoladas tornam-se úteis à escala de um relatório inteiro. O seguinte script varre uma pasta de gráficos exportados, solicita um output JSON padronizado de cada vez e regista tudo num único ficheiro:
import base64
from pathlib import Path
from mistralai.client import Mistral
import json
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def encoder_image(chemin):
with open(chemin, "rb") as f:
b64 = base64.standard_b64encode(f.read()).decode("utf-8")
return f"data:image/png;base64,{b64}"
def analyser_graphique(chemin_image, question=None):
"""Analyze a chart and return structured data."""
if question is None:
question = "Analyze this chart. Return a JSON with: type (bar/line/pie/other), title, data (array of {label, value}), trend, and summary."
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Return only valid JSON, no markdown code blocks."
},
{
"role": "user",
"content": [
{"type": "text", "text": question},
{"type": "image_url", "image_url": encoder_image(chemin_image)}
]
}
]
)
return response.choices[0].message.content
# Analyze all charts in a folder
dossier = Path("rapport/graphiques/")
resultats = {}
for fichier in sorted(dossier.glob("*.png")):
print(f"Analyse de {fichier.name}...")
resultats[fichier.name] = analyser_graphique(fichier)
# Save results
with open("rapport/analyse_graphiques.json", "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
A instrução «no markdown code blocks» evita o aborrecimento clássico do JSON envolto em três crases, o que quebra a análise.
Limites da Análise de Gráficos
Quatro situações desafiam o modelo, e deve conhecê-las antes de construir um processo à sua volta. Primeiro, os valores precisos: são estimados a partir da posição visual das barras ou pontos, com uma margem de erro de 5 a 10%. Segundo, gráficos sobrecarregados, onde múltiplas séries, legendas e texto pequeno turvam a legibilidade. Terceiro, baixa resolução, que torna as etiquetas desfocadas ou pixelizadas e ilegíveis — lembre-se do redimensionamento interno descrito na Lição 2. Por fim, gráficos 3D, onde a perspetiva distorce mecanicamente a leitura da altura.
A conclusão prática é clara: para uma extração precisa, prefira exportar os dados de origem como CSV quando disponível. A Vision API é ideal para análise rápida e síntese, não para substituir uma folha de cálculo. Brilha quando os dados de origem desapareceram; é uma má escolha quando os dados estão ao seu alcance.
Pontos-chave
- Utilize o Mistral Large 3 para análise de gráficos — a precisão é crítica
- Estruture o seu prompt em etapas: tipo, eixos, valores, tendências, conclusão
- Solicite explicitamente um formato de output (tabela markdown, JSON) para dados utilizáveis
- O modelo estima valores com uma margem de 5–10% — não o utilize para cifras exatas
- Combine a Vision API com uma exportação CSV para obter o melhor dos dois mundos