Kódování a odesílání obrázků v Base64
Na této stránce
Proč používat Base64?
V předchozí lekci jsi se naučil, jak odesílat obrázky prostřednictvím URL. Většina obrázků zpracovávaných v podnikovém prostředí však nemá žádnou URL adresu: faktura, která právě přišla e-mailem, snímek obrazovky vygenerovaný automatizovaným testem nebo fotografie pořízená operátorem na výrobní lince. Zveřejňování těchto souborů na serveru přístupném z internetu pouze za účelem jejich analýzy by bylo absurdní a často zakázané.
Zde přichází na řadu kódování Base64. Transformuje binární data obrázku na textový řetězec, který můžeš přímo zahrnout do žádosti API, aniž bys potřeboval externí URL nebo průběžné hostování.
Kdy použít URL a kdy Base64
| Kritérium | URL | Base64 |
|---|---|---|
| Již hostované obrázky | Ideální | Zbytečné |
| Lokální obrázky | Nevhodné | Ideální |
| Dynamicky generované obrázky | Nevhodné | Ideální |
| Latence sítě | Závisí na serveru | Žádná (vložené) |
| Velikost požadavku | Lehké | Těžší (~33 %) |
| Bezpečnost/soukromí | Veřejná URL | Data uvnitř požadavku |
Pravidlo je jednoduché: pokud je obrázek přístupný prostřednictvím stabilní URL, použij URL. V opačném případě použij Base64.
Kódování obrázku do Base64
Nejsou vyžadovány žádné závislosti; Python poskytuje modul base64 ve své standardní knihovně:
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" při otevírání souboru není volitelný: čtení obrázku v textovém režimu vyvolá chybu dekódování. Připrav se na dlouhé řetězce – kódování zvětšuje velikost přibližně o 33 % oproti původnímu souboru, takže obrázek o velikosti 1 MB vytvoří přibližně 1,33 MB textu.
Formát Data URI
Samotný řetězec nestačí: API musí znát formát obrázku. Musíš jej tedy prezentovat jako data URI, které prefixuje data jeho MIME typem:
data:image/{format};base64,{base64_data}
Čtyři použitelné prefixy odpovídají podporovaným formátům:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Oznámení PNG jako image/jpeg způsobí chybu zpracování; proto slouží detekční funkce v následujícím příkladu.
Kompletní příklad
Zde je celý řetězec od čtení lokálního souboru až po odpověď 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)
Klíčové poznatky: pole se vždy nazývá image_url, i když obsahuje data URI. Struktura zprávy se ani v nejmenším nemění oproti lekci 4; liší se pouze hodnota.
Kódování obrázků z jiných zdrojů
Soubor na disku je jen jedním z mnoha případů. Pokud již máš obrázek v paměti, například jako objekt Pillow ze snímku nebo kroku zpracování, bylo by zbytečné jej zapisovat na disk a hned znovu číst – funguje i vyrovnávací 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)
Stejná logika platí pro obrázek získaný přes HTTP, který nechceš ukládat, například protože pochází z odkazu s krátkou životností:
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")
Optimalizace velikosti před kódováním
Fotografie ze smartphonu dnes váží 4 až 8 MB, což se po zakódování zvýší na téměř 10 MB. API ji stejně změní velikost, jak jsi viděl v lekci 2: platil bys za přenos zbytečně. Vždy tedy změň velikost před kódováním.
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")
Zobrazení konečné velikosti není jen dekorativní: ponech si jej během testů, protože ti okamžitě řekne, zda tvé pipeline při každém volání odesílá 80 KB, nebo 8 MB.
Limity, které musíš znát
S Base64 jsou spojena tři omezení. Zakódovaný obrázek se přidává do těla požadavku HTTP, takže při překročení 10 MB riskuješ časové limity (timeout). Kódování také načte celý obrázek do paměti: pro dávkové zpracování zpracovávej obrázky jeden po druhém, místo abys vytvářel seznam tisíců zakódovaných řetězců. Nakonec, na rozdíl od URL, jsou obrázky Base64 při každém požadavku přenášeny v plném rozsahu – analýza stejné faktury dvakrát znamená její dvojí odeslání.
Klíčové poznatky
- Base64 je ideální pro lokální nebo dynamicky generované obrázky
- Formát data URI kombinuje MIME typ a data:
data:image/png;base64,... - Před kódováním změň velikost a komprimuj obrázky pro optimalizaci latence
- Base64 zvětšuje velikost přibližně o 33 % – udržuj své obrázky pod 10 MB
- Použij URL, když je obrázek již hostován, Base64 ve všech ostatních případech