Kódovanie a odosielanie obrázkov v Base64
Na tejto strane
Prečo používať Base64?
V predchádzajúcej lekcii si sa naučil, ako odosielať obrázky prostredníctvom URL. Väčšina obrázkov spracovávaných v business kontexte však nemá URL: faktúra, ktorá práve prišla e-mailom, screenshot vygenerovaný automatizovaným testom alebo fotografia odfotená operátorom na výrobnej linke. Zverejňovanie týchto súborov na serveri prístupnom z internetu len preto, aby sa analyzovali, by bolo absurdné a často zakázané.
Tu prichádza na rad kódovanie Base64. Transformuje binárne dáta obrázka na textový reťazec, ktorý zahrnieš priamo do svojej požiadavky API, bez potreby externej URL alebo intermediárneho hostingu.
Kedy použiť URL a kedy Base64
| Kritérium | URL | Base64 |
|---|---|---|
| Už hostované obrázky | Ideálne | Zbytočné |
| Lokálne obrázky | Nevhodné | Ideálne |
| Dynamicky generované obrázky | Nevhodné | Ideálne |
| Latencia siete | Závisí od servera | Žiadna (vložené) |
| Veľkosť požiadavky | Ľahká | Ťažšia (~33 %) |
| Bezpečnosť/súkromie | Verejná URL | Dáta vo vnútri požiadavky |
Pravidlo je jednoduché: ak je obrázok dostupný cez stabilnú URL, použi URL. Inak použi Base64.
Kódovanie obrázka do Base64
Nie sú potrebné žiadne závislosti; Python poskytuje modul base64 vo svojej štandardnej knižnici:
import base64
def encode_image(file_path):
"""Encode an image file to a Base64 string."""
with open(file_path, "rb") as f:
return base64.standard_b64encode(f.read()).decode("utf-8")
# Encode a local image
image_b64 = encode_image("captures/screenshot.png")
print(f"Base64 string length: {len(image_b64)} characters")
Režim "rb" pri otváraní súboru nie je voliteľný: čítanie obrázka v textovom režime vyvolá chybu dekódovania. Priprav sa na dlhé reťazce – kódovanie zväčší veľkosť približne o 33 % oproti pôvodnému súboru, takže obrázok s veľkosťou 1 MB vytvorí približne 1,33 MB textu.
Formát Data URI
Surový reťazec nestačí: API potrebuje vedieť formát obrázka. Musíš ho preto predložiť ako data URI, ktoré prefixuje dáta ich MIME typom:
data:image/{format};base64,{base64_data}
Štyri použiteľné prefixy zodpovedajú podporovaným formátom:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Nahlásenie PNG ako image/jpeg spôsobí chybu spracovania; preto funkcia na detekciu v nasledujúcom príklade.
Kompletný príklad
Tu je celý reťazec, od čítania lokálneho súboru až po odpoveď modelu:
import base64
import os
from mistralai.client import Mistral
def encode_image(chemin):
"""Encode a local image to Base64."""
with open(chemin, "rb") as f:
return base64.standard_b64encode(f.read()).decode("utf-8")
# Determine MIME type
def obtenir_mime(chemin):
"""Return MIME type based on extension."""
extensions = {
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".png": "image/png",
".gif": "image/gif",
".webp": "image/webp"
}
ext = os.path.splitext(chemin)[1].lower()
return extensions.get(ext, "image/jpeg")
# Prepare the image
chemin_image = "documents/facture-2024.png"
image_b64 = encode_image(chemin_image)
mime_type = obtenir_mime(chemin_image)
data_uri = f"data:{mime_type};base64,{image_b64}"
# Call the API
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Extract all information from this invoice."},
{"type": "image_url", "image_url": data_uri}
]
}
]
)
print(response.choices[0].message.content)
Kľúčové poznatky: pole sa vždy nazýva image_url, aj keď obsahuje data URI. Štruktúra správy sa oproti lekcii 4 nemení ani o chlp; líši sa len hodnota.
Kódovanie obrázkov z iných zdrojov
Súbor na disku je len jedným z mnohých prípadov. Ak už máš obrázok v pamäti, ako objekt Pillow zo snímky alebo kroku spracovania, jeho zapisovanie na disk len preto, aby si ho hneď znovu čítal, by bolo zbytočnou oklikou – funguje aj vyrovnávacia pamäť v pamäti:
import base64
from io import BytesIO
from PIL import Image
def pil_to_base64(pil_image):
"""Convert a Pillow image to a Base64 data URI."""
buffer = BytesIO()
pil_image.save(buffer, format="PNG")
b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
return f"data:image/png;base64,{b64}"
# Example with a Pillow image
img = Image.open("capture.png")
data_uri = pil_to_base64(img)
Rovnaká logika platí pre obrázok získaný cez HTTP, ktorý nechceš ukladať, napríklad preto, že pochádza z krátko žijúceho odkazu:
import base64
import requests
def url_to_base64(url):
"""Download an image and convert it to a data URI."""
response = requests.get(url, timeout=10)
response.raise_for_status()
content_type = response.headers.get("Content-Type", "image/jpeg")
b64 = base64.standard_b64encode(response.content).decode("utf-8")
return f"data:{content_type};base64,{b64}"
data_uri = url_to_base64("https://example.com/photo.jpg")
Optimalizácia veľkosti pred kódovaním
Fotografia zo smartfónu dnes váži 4 až 8 MB, čo sa po zakódovaní zmení na takmer 10 MB. API ju aj tak zmenší, ako si videl v lekcii 2: platil by si za prenos zbytočne. Vždy ju preto najprv zmenši.
from PIL import Image
from io import BytesIO
import base64
def preparer_et_encoder(chemin, taille_max=1024, qualite=85):
"""Resize, compress, and encode an image."""
img = Image.open(chemin)
# Resize if necessary
if max(img.size) > taille_max:
img.thumbnail((taille_max, taille_max))
# Convert to JPEG to reduce size
buffer = BytesIO()
img.convert("RGB").save(buffer, format="JPEG", quality=qualite)
b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
taille_ko = len(buffer.getvalue()) / 1024
print(f"Encoded image: {taille_ko:.0f} KB")
return f"data:image/jpeg;base64,{b64}"
data_uri = preparer_et_encoder("photo_haute_resolution.png")
Zobrazenie konečnej veľkosti nie je len dekoratívne: udržuj si ju počas testov, pretože ti okamžite povie, či tvoje pipeline odosiela pri každom volaní 80 KB alebo 8 MB.
Obmedzenia, ktoré treba poznať
S Base64 sú spojené tri obmedzenia. Zakódovaný obrázok sa pridáva do tela HTTP požiadavky, takže pri prekročení 10 MB riskuješ časové limity (timeout). Kódovanie tiež načíta celý obrázok do pamäte: pri dávkovom spracovaní spracúvaj obrázky jeden po druhom, namiesto zostavovania zoznamu tisíc zakódovaných reťazcov. Nakoniec, na rozdiel od URL, sa obrázky Base64 odosielajú v plnom rozsahu s každou požiadavkou – analýza tej istej faktúry dvakrát znamená jej dvojité odoslanie.
Kľúčové poznatky
- Base64 je ideálny pre lokálne alebo dynamicky generované obrázky
- Formát data URI kombinuje MIME typ a dáta:
data:image/png;base64,... - Pred kódovaním zmenši a komprimuj obrázky na optimalizáciu latencie
- Base64 zväčšuje veľkosť približne o 33 % – udržuj obrázky pod 10 MB
- Použi URL, keď je obrázok už hostovaný, Base64 vo všetkých ostatných prípadoch