Képek kódolása és küldése Base64-ben
Ezen az oldalon
Miért használd a Base64-et?
Az előző leckében megtanultad, hogyan küldj képeket URL-en keresztül. Azonban az üzleti környezetben feldolgozott képek többsége nem rendelkezik URL-lel: egy éppen e-mailben megérkezett számla, egy automatizált teszt által generált képernyőfotó vagy egy gyártósori operátor által készített fénykép. Ezeket a fájlokat csak azért feltölteni egy interneten elérhető szerverre, hogy elemezni tudjuk őket, abszurd lenne, és gyakran tiltott is.
Itt jön képbe a Base64 kódolás. Ez az eljárás a kép bináris adatait egy szöveges lánccá alakítja át, amelyet közvetlenül belefoglalhatsz az API-kérésedbe, anélkül, hogy külső URL-re vagy közbenső tárhelyre lenne szükséged.
Mikor használj URL-t és mikor Base64-et?
| Szempont | URL | Base64 |
|---|---|---|
| Már hosztolt képek | Ideális | Felesleges |
| Helyi képek | Nem megfelelő | Ideális |
| Dinamikusan generált képek | Nem megfelelő | Ideális |
| Hálózati késleltetés | A szervertől függ | Nincs (beágyazva) |
| Kérés mérete | Könnyű | Nehezebb (~33%) |
| Biztonság/adatvédelem | Nyilvános URL | Adat a kérésen belül |
A szabály egyszerű: ha a kép egy stabil URL-en keresztül elérhető, használd az URL-t. Egyéb esetben használd a Base64-et.
Kép kódolása Base64-be
Nincsenek szükség további függőségekre; a Python a base64 modult tartalmazza a szabványos könyvtárában:
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")
A fájl megnyitásakor a "rb" mód nem opcionális: ha szöveges módban olvasod be a képet, dekódolási hiba lép fel. Számíts hosszú karakterláncokra: a kódolás körülbelül 33%-kal növeli a méretet az eredeti fájlhoz képest, tehát egy 1 MB-os képből durván 1,33 MB szöveg keletkezik.
Data URI formátum
A nyers karakterlánc önmagában nem elég: az API-nak tudnia kell a kép formátumát. Ezért data URI formátumban kell megadnod, amely a MIME-típussal előtagolja az adatokat:
data:image/{format};base64,{base64_data}
A négy használható előtag a támogatott formátumoknak felel meg:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Ha egy PNG-t image/jpeg-ként adsz meg, az feldolgozási hibát okoz; ezért szükséges a következő példában látható típusfelismerő függvény.
Teljes példa
Íme a teljes folyamat a helyi fájl beolvasásától a modell válaszáig:
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)
Fontos tanulság: a mező neve mindig image_url, még akkor is, ha data URI-t tartalmaz. Az üzenet szerkezete egyáltalán nem változik a 4. leckéhez képest; csak az érték más.
Képek kódolása más forrásokból
A lemezen lévő fájl csak egy a sok lehetőség közül. Ha a képed már a memóriában van, például egy rögzítés vagy feldolgozási lépésből származó Pillow objektumként, felesleges körút lenne lemezre írni, csak hogy azonnal visszaolvasd – egy memóriapuffer is tökéletesen megfelel:
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)
Ugyanez a logika vonatkozik egy HTTP-n keresztül lekért képre is, amelyet nem szeretnél elmenteni, például mert rövid életű linkről származik:
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")
Méret optimalizálása kódolás előtt
Egy mai okostelefonnal készült fotó mérete 4–8 MB, ami kódolás után közel 10 MB-ra nő. Az API amúgy is átméretezi a képet, ahogy azt a 2. leckében láttad: feleslegesen fizetnél az adatátvitelért. Ezért mindig méretezd át a képet kódolás előtt.
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")
A végső méret kiírása nem csak díszítés: tartsd meg ezt a tesztjeid során, mert azonnal jelzi, ha a pipeline-od hívásonként 80 KB vagy 8 MB adatot küld.
Ismerendő korlátok
Három korlátozással kell számolnod a Base64 használatakor. A kódolt kép hozzáadódik a HTTP-kérés törzséhez, így 10 MB felett időtúllépést kockáztatsz. A kódolás a teljes képet betölti a memóriába: kötegelt feldolgozás esetén a képeket egyesével kezeld, ne pedig ezer kódolt karakterlánc listáját építsd fel. Végül, az URL-ekkel ellentétben a Base64 képeket minden kéréssel teljes egészében újraküldöd – ugyanannak a számlának a kétszeri elemzése azt jelenti, hogy kétszer küldöd el azt.
Főbb megállapítások
- A Base64 ideális helyi vagy dinamikusan generált képekhez
- A data URI formátum egyesíti a MIME-típust és az adatokat:
data:image/png;base64,... - Méretezd át és tömörítsd a képeidet kódolás előtt a késleltetés optimalizálása érdekében
- A Base64 körülbelül 33%-kal növeli a méretet – tartsd a képeket 10 MB alatt
- Használj URL-t, ha a kép már hosztolt, minden más esetben pedig Base64-et