Kodiranje in pošiljanje slik v Base64
Na tej strani
Zakaj uporabiti Base64?
V prejšnji lekciji si se naučil, kako pošiljati slike prek URL-ja. Vendar pa večina slik, obdelanih v poslovnem okolju, nima URL-ja: račun, ki je pravkar prispel po e-pošti, posnetek zaslona, ki ga je ustvaril avtomatiziran test, ali fotografija, ki jo je operater posnel na proizvodni liniji. Objavljanje teh datotek na strežniku, dostopnem prek interneta, zgolj zato, da bi jih analizirali, bi bilo absurdno in pogosto prepovedano.
Tu nastopi kodiranje Base64. Pretvori binarne podatke slike v besedilni niz, ki ga vključiš neposredno v zahtevo API-ja, brez potrebe po zunanjem URL-ju ali vmesnem gostovanju.
Kdaj uporabiti URL in kdaj Base64
| Merilo | URL | Base64 |
|---|---|---|
| Slike, ki so že gostovane | Idealno | Nepotrebno |
| Lokalne slike | Ni primerno | Idealno |
| Dinamično ustvarjene slike | Ni primerno | Idealno |
| Omrežna zakasnitev | Odvisno od strežnika | Nična (vgrajeno) |
| Velikost zahteve | Lahka | Težja (~33 %) |
| Varnost/zasebnost | Javni URL | Podatki znotraj zahteve |
Pravilo je preprosto: če je slika dostopna prek stabilnega URL-ja, uporabi URL. V nasprotnem primeru uporabi Base64.
Kodiranje slike v Base64
Ni potrebnih nobenih odvisnosti; Python ponuja modul base64 v svoji standardni knjiž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")
Način "rb" pri odpiranju datoteke ni izbirni: branje slike v besedilnem načinu bo sprožilo napako pri dekodiranju. Pričakuj dolge nize – kodiranje poveča velikost za približno 33 % v primerjavi z izvirno datoteko, zato slika velikosti 1 MB ustvari približno 1,33 MB besedila.
Oblika podatkovnega URI-ja (Data URI)
Surovi niz ni dovolj: API mora vedeti format slike. Zato jo moraš predstaviti kot podatkovni URI, ki podatkom doda predpono z njihovo vrsto MIME:
data:image/{format};base64,{base64_data}
Štiri uporabne predpone ustrezajo podprtim formatom:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Če PNG napoveš kot image/jpeg, pride do napake pri obdelavi; zato funkcija za zaznavanje v naslednjem primeru.
Celoten primer
Tukaj je celoten potek, od branja lokalne datoteke do odgovora modela:
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)
Ključna ugotovitev: polje se vedno imenuje image_url, tudi ko vsebuje podatkovni URI. Struktura sporočila se niti za las ne razlikuje od tiste v lekciji 4; razlikuje se le vrednost.
Kodiranje slik iz drugih virov
Datoteka na disku je le eden od mnogih primerov. Če slika že obstaja v pomnilniku, kot objekt Pillow iz koraka zajema ali obdelave, bi bilo njeno zapisovanje na disk zgolj zato, da bi jo takoj znova prebral, nepotreben ovinek – medpomnilnik v pomnilniku deluje brez težav:
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)
Enaka logika velja za sliko, pridobljeno prek HTTP-ja, ki je ne želiš shraniti, na primer zato, ker izvira iz kratkotrajne povezave:
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")
Optimizacija velikosti pred kodiranjem
Fotografija s pametnega telefona danes tehta od 4 do 8 MB, kar po kodiranju naraste na skoraj 10 MB. API jo bo tako ali tako spremenil v manjšo velikost, kot si videl v lekciji 2: plačeval bi za prenos zaman. Zato slike pred kodiranjem vedno spremeni v manjšo velikost.
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")
Prikaz končne velikosti ni le okrasen: ohrani ga med testi, saj ti bo takoj povedal, ali tvoja cevovodna obdelava pri vsakem klicu pošilja 80 KB ali 8 MB.
Omejitve, ki jih moraš poznati
S Base64 so povezane tri omejitve. Kodirana slika se doda telesu zahteve HTTP, zato pri velikostih nad 10 MB tvegaš časovne omejitve (timeouts). Kodiranje prav tako naloži celotno sliko v pomnilnik: pri serijski obdelavi obravnavaj slike eno za drugo, namesto da bi gradil seznam tisočih kodiranih nizov. Končno, za razliko od URL-jev, se slike Base64 pri vsaki zahtevi prenesejo v celoti – dvakratna analiza istega računa pomeni, da ga pošlješ dvakrat.
Ključne ugotovitve
- Base64 je idealen za lokalne ali dinamično ustvarjene slike
- Oblika podatkovnega URI-ja združuje vrsto MIME in podatke:
data:image/png;base64,... - Pred kodiranjem spremeni velikost in stisni slike za optimizacijo zakasnitve
- Base64 poveča velikost za približno 33 % – slike ohrani pod 10 MB
- Uporabi URL, ko je slika že gostovana, Base64 pa v vseh drugih primerih