Kodiranje i slanje slika u Base64 formatu
Na ovoj stranici
Zašto koristiti Base64?
U prethodnoj lekciji naučio/la si kako slati slike putem URL-a. Međutim, većina slika koje se obrađuju u poslovnom kontekstu nema URL: račun koji je upravo stigao e-poštom, snimka zaslona generirana automatiziranim testom ili fotografija koju je operater napravio na proizvodnoj liniji. Objavljivanje tih datoteka na poslužitelju dostupnom putem interneta samo radi njihove analize bilo bi apsurdno i često zabranjeno.
Tu na scenu stupa kodiranje Base64. Ono pretvara binarne podatke slike u tekstualni niz koji uključuješ izravno u svoj API zahtjev, bez potrebe za vanjskim URL-om ili međupohranom.
Kada koristiti URL, a kada Base64
| Kriterij | URL | Base64 |
|---|---|---|
| Već hostane slike | Idealno | Nepotrebno |
| Lokalne slike | Nije prikladno | Idealno |
| Dinamički generirane slike | Nije prikladno | Idealno |
| Kašnjenje mreže | Ovisi o poslužitelju | Nema (ugrađeno) |
| Veličina zahtjeva | Lagano | Teže (~33%) |
| Sigurnost/privatnost | Javni URL | Podaci unutar zahtjeva |
Pravilo je jednostavno: ako je slika dostupna putem stabilnog URL-a, koristi URL. U suprotnom, koristi Base64.
Kodiranje slike u Base64
Nisu potrebne nikakve dodatne ovisnosti; Python pruža modul base64 u svojoj standardnoj 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 otvaranju datoteke nije opcionalan: čitanje slike u tekstualnom načinu izazvat će pogrešku dekodiranja. Očekuj duge nizove – kodiranje povećava veličinu za oko 33% u usporedbi s izvornom datotekom, pa slika od 1 MB proizvodi otprilike 1,33 MB teksta.
Format Data URI
Sirovi niz nije dovoljan: API mora znati format slike. Stoga je moraš predstaviti kao data URI, koji podatke prefiksira njihovom MIME vrstom:
data:image/{format};base64,{base64_data}
Četiri upotrebljiva prefiksa odgovaraju podržanim formatima:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Najavljivanje PNG-a kao image/jpeg uzrokuje pogrešku obrade; stoga funkcija za detekciju u sljedećem primjeru.
Potpuni primjer
Evo cjelokupnog lanca, od čitanja 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 poruka: polje se uvijek zove image_url, čak i kada sadrži data URI. Struktura poruke se nimalo ne mijenja u odnosu na Lekciju 4; razlikuje se samo vrijednost.
Kodiranje slika iz drugih izvora
Datoteka na disku samo je jedan od mnogih slučajeva. Ako tvoja slika već postoji u memoriji, kao Pillow objekt iz koraka snimanja ili obrade, zapisivanje na disk samo da bi se odmah ponovno pročitala bio bi nepotreban zaobilazni put – međuspremnik u memoriji sasvim dobro funkcionira:
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)
Ista logika vrijedi za sliku dohvaćenu putem HTTP-a koju ne želiš pohraniti, na primjer jer dolazi s privremene poveznice:
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")
Optimiziraj veličinu prije kodiranja
Današnja fotografija sa pametnog telefona teži od 4 do 8 MB, što nakon kodiranja postaje gotovo 10 MB. API će je ionako promijeniti veličinu, kao što si vidio/la u Lekciji 2: plaćao/la bi prijenos uzalud. Zato uvijek promijeni veličinu prije kodiranja.
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")
Prikazivanje konačne veličine nije samo dekorativno: zadrži ga tijekom testiranja jer će ti odmah reći šalje li tvoj pipeline 80 KB ili 8 MB pri svakom pozivu.
Ograničenja koja trebaš znati
S Base64 dolaze tri ograničenja. Kodirana slika dodaje se tijelu HTTP zahtjeva, pa preko 10 MB riskiraš istek vremena čekanja (timeout). Kodiranje također učitava cijelu sliku u memoriju: za serijsku obradu obrađuj slike jednu po jednu umjesto izgradnje popisa tisuću kodiranih nizova. Konačno, za razliku od URL-ova, Base64 slike se prenose u cijelosti sa svakim zahtjevom – analiza istog računa dva puta znači slanje dva puta.
Ključne točke
- Base64 je idealan za lokalne ili dinamički generirane slike
- Format data URI kombinira MIME vrstu i podatke:
data:image/png;base64,... - Promijeni veličinu i komprimiraj slike prije kodiranja radi optimizacije kašnjenja
- Base64 povećava veličinu za oko 33% – drži slike ispod 10 MB
- Koristi URL kada je slika već hostana, a Base64 u svim ostalim slučajevima