Limites e Otimização da Vision API
Nesta página
Conheça os limites para os contornar
As dez lições anteriores abordaram o que a Vision API faz bem. Esta cobre as suas dificuldades. Isto não é um exercício de humildade: a diferença entre um protótipo de demonstração impressionante e uma aplicação que se mantém em produção resume-se exatamente a isto. Aqui, aprenderá sobre restrições técnicas, armadilhas comuns — sendo as alucinações visuais a principal delas — e estratégias para otimizar custos e latência.
Limites técnicos
Já abordámos anteriormente as restrições de formato, mas vamos reuni-las. Cada imagem tem um limite de aproximadamente 20 MB e será redimensionada internamente de qualquer forma, tipicamente para 768x768 ou equivalente: uma imagem 4K não melhorará os resultados. Os formatos aceites são JPEG, PNG, GIF (apenas o primeiro quadro) e WebP. A Vision API não suporta PDF diretamente — precisa de chamar a Document AI para isso, conforme discutido na Lição 8.
A restrição mais estrutural permanece o consumo de tokens. Cada imagem consome um número significativo de tokens, e esta função traduz essa estimativa em dólares em vez de unidades abstratas:
# Estimate the cost of a vision call
def estimate_cost(num_images=1, text_tokens=100, response_tokens=500,
tokens_per_image=1000, input_price=0.10, output_price=0.30):
"""Estimates the cost in dollars for a vision call (Small 3.2)."""
input_tokens = (num_images * tokens_per_image) + text_tokens
output_tokens = response_tokens
input_cost = (input_tokens / 1_000_000) * input_price
output_cost = (output_tokens / 1_000_000) * output_price
total_cost = input_cost + output_cost
print(f"Input tokens: {input_tokens} (${input_cost:.4f})")
print(f"Output tokens: {output_tokens} (${output_cost:.4f})")
print(f"Total cost: ${total_cost:.4f}")
return total_cost
# 1 image with Small 3.2
estimate_cost(num_images=1)
# 5 images with Large 3
estimate_cost(num_images=5, input_price=2.00, output_price=6.00)
Compare as duas chamadas no final do script: a segunda custa dezenas de vezes mais do que a primeira. Multiplique isso pelo seu volume diário antes de tomar uma decisão. Além disso, existe o limite da janela de contexto, que o total de imagens + prompt + resposta não deve exceder — um teto que múltiplas imagens atingem muito mais rapidamente do que um texto longo.
Alucinações visuais
O modelo pode “inventar” detalhes ausentes da imagem. Esta é a questão mais crítica em produção porque é silenciosa: a resposta é bem formada, plausível e errada.
Quatro padrões recorrem. Texto inventado, onde o modelo lê uma palavra que não existe na imagem. Números aproximados, onde valores lidos de um gráfico podem desviar 5–15% da realidade. Detalhes adicionados, onde o modelo preenche o que não vê claramente com informação plausível — um número SIRET desfocado torna-se um SIRET perfeitamente formatado mas falso. Finalmente, confusão de elementos, onde dois objetos próximos são fundidos num só.
Existem três contramedidas; combine-as com base na criticidade. Primeiro, force o modelo a qualificar a sua própria certeza. Segundo, peça-lhe para reler a imagem após a transcrição. Terceiro, coloque dois modelos contra a mesma pergunta e mantenha apenas aquilo em que concordam.
# 1. Ask for a confidence level
prompt_confiance = """Analyze this image. For each piece of extracted information, indicate your confidence level:
- [CERTAIN]: clearly visible
- [PROBABLE]: partially visible or inferred
- [INCERTAIN]: barely legible, estimated
If an element is illegible, mark it [ILLISIBLE] rather than guessing."""
# 2. Ask for cross-verification
prompt_verification = """Read the text in this document. After transcribing, reread the image and verify every number and proper noun. Correct any detected errors."""
# 3. Double reading with two models
def double_verification(image_uri, question):
"""Sends the same image to two models and compares results."""
resultats = {}
for modele in ["mistral-small-latest", "mistral-large-latest"]:
response = client.chat.complete(
model=modele,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": question},
{"type": "image_url", "image_url": image_uri}
]
}]
)
resultats[modele] = response.choices[0].message.content
return resultats
A dupla leitura duplica o custo: reserve-a para valores, identificadores e qualquer coisa que desencadeie uma ação irreversível.
Otimizar custos
A otimização mais económica foi abordada na Lição 5, e é a mais simples: reduza o tamanho da imagem antes de enviar. Uma foto de 6 MB redimensionada para 1024 pixels não perde nada para fins de análise e aligeira toda a cadeia.
from PIL import Image
from io import BytesIO
import base64
def optimiser_image(chemin, taille_max=1024, qualite=80):
"""Resizes and compresses an image for the Vision API."""
img = Image.open(chemin)
taille_originale = img.size
# Resize
if max(img.size) > taille_max:
img.thumbnail((taille_max, taille_max))
# Compress as JPEG
buffer = BytesIO()
img.convert("RGB").save(buffer, format="JPEG", quality=qualite)
taille_fichier = buffer.tell()
b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
print(f"Original: {taille_originale} | Optimized: {img.size} | Size: {taille_fichier/1024:.0f} KB")
return f"data:image/jpeg;base64,{b64}"
Em seguida vem o encaminhamento por complexidade: nem todas as tarefas merecem o modelo mais caro. Uma função de três linhas é suficiente para decidir, desde que tenha classificado as suas tarefas a montante.
def choose_model(task):
"""Selects the optimal model based on the task."""
simple_tasks = ["classification", "ocr_simple", "description", "triage"]
complex_tasks = ["extraction_json", "comparaison", "analyse_graphique", "raisonnement"]
if task in simple_tasks:
return "mistral-small-latest" # ~$0.10/M tokens
else:
return "mistral-large-latest" # ~$2.00/M tokens
A terceira alavanca é a mais frequentemente esquecida: não pague duas vezes pela mesma análise. Em produção, a mesma imagem retorna mais vezes do que imagina — reexecução de um processo, envios duplicados ou nova tentativa após um incidente. Uma cache em disco indexada no hash do ficheiro e no prompt elimina estas chamadas redundantes.
import hashlib
import json
from pathlib import Path
CACHE_DIR = Path("cache_vision/")
CACHE_DIR.mkdir(exist_ok=True)
def analyser_avec_cache(image_path, prompt, modele="mistral-small-latest"):
"""Analyzes an image with disk caching."""
# Generate a cache key
with open(image_path, "rb") as f:
image_hash = hashlib.md5(f.read()).hexdigest()
cache_key = hashlib.md5(f"{image_hash}{prompt}{modele}".encode()).hexdigest()
cache_file = CACHE_DIR / f"{cache_key}.json"
# Check cache
if cache_file.exists():
return json.loads(cache_file.read_text())
# API call
response = client.chat.complete(
model=modele,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": prompt},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
resultat = response.choices[0].message.content
# Save to cache
cache_file.write_text(json.dumps(resultat, ensure_ascii=False))
return resultat
A chave inclui o prompt e o modelo, não apenas a imagem: alterar a pergunta na mesma foto deve, de facto, desencadear uma nova chamada.
Otimizar a latência
Para uma aplicação interativa, quatro definições afetam o tempo de resposta percecionado. Redimensione as imagens no lado do cliente para um máximo de 1024 pixels, o que encurta o tempo de upload. Escolha o Small ou o Ministral, pois a sua geração é significativamente mais rápida. Passe as imagens por URL quando já estiverem alojadas para evitar enviar um corpo de pedido Base64 grande. Finalmente, ative o streaming, que não reduz o tempo total, mas exibe a resposta à medida que é construída:
# Streaming for a progressive response
stream = client.chat.stream(
model="mistral-small-latest",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image."},
{"type": "image_url", "image_url": image_url}
]
}]
)
for chunk in stream:
if chunk.data.choices[0].delta.content:
print(chunk.data.choices[0].delta.content, end="", flush=True)
É chat.stream a substituir chat.complete; o resto da mensagem é exatamente o mesmo.
Lista de verificação para produção
Antes de implementar uma aplicação Vision em produção, verifique cada um destes pontos:
- Redimensionamento automático de imagens (máx. 1024 px)
- Validação de formato e tamanho antes do envio
- Gestão de erros da API (nova tentativa, tempo limite, fallback)
- Cache de resultados para imagens idênticas
- Encaminhamento inteligente (Small para simples, Large para complexo)
- Monitorização de custos e latência
- Testes com imagens de baixa qualidade (desfocadas, baixa resolução, rodadas)
- Estratégia anti-alucinação (níveis de confiança, dupla verificação)
O penúltimo ponto é o mais frequentemente ignorado e o que causa mais danos: construa um conjunto de dados de imagens deliberadamente más e execute-o antes de cada implementação.
Pontos-chave
- As imagens são redimensionadas internamente — não é necessário enviar resoluções muito altas
- As alucinações visuais são o risco principal — peça níveis de confiança
- O redimensionamento no lado do cliente é a otimização mais económica
- O encaminhamento por complexidade (Small vs. Large) reduz custos em 90% em tarefas simples
- A cache em disco evita chamadas API redundantes nas mesmas imagens