Codificarea și trimiterea imaginilor în Base64
Pe această pagină
De ce să utilizați Base64?
În lecția anterioară, ați învățat cum să trimiteți imagini prin URL. Totuși, majoritatea imaginilor procesate în contexte de afaceri nu au un URL: o factură care tocmai a sosit prin e-mail, o captură de ecran generată de un test automatizat sau o fotografie făcută de un operator pe o linie de producție. Publicarea acestor fișiere pe un server accesibil internetului doar pentru a le analiza ar fi absurdă și, adesea, interzisă.
Aici intervine codificarea Base64. Aceasta transformă datele binare ale unei imagini într-un șir de text pe care îl includeți direct în cererea dvs. API, fără a avea nevoie de un URL extern sau de o găzduire intermediară.
Când să utilizați URL vs. Base64
| Criteriu | URL | Base64 |
|---|---|---|
| Imagini deja găzduite | Ideal | Inutil |
| Imagini locale | Nepotrivit | Ideal |
| Imagini generate dinamic | Nepotrivit | Ideal |
| Latența rețelei | Depinde de server | Nulă (încorporat) |
| Dimensiunea cererii | Ușoară | Mai grea (~33%) |
| Securitate/confidențialitate | URL public | Date în interiorul cererii |
Regula este simplă: dacă imaginea este accesibilă printr-un URL stabil, utilizați URL-ul. În caz contrar, utilizați Base64.
Codificarea unei imagini în Base64
Nu sunt necesare dependențe externe; Python oferă modulul base64 în biblioteca sa standard:
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")
Modul "rb" la deschiderea fișierului nu este opțional: citirea unei imagini în mod text va genera o eroare de decodare. Așteptați-vă la șiruri lungi—codificarea mărește dimensiunea cu aproximativ 33% față de fișierul original, astfel încât o imagine de 1 MB produce aproximativ 1,33 MB de text.
Formatul Data URI
Șirul brut nu este suficient: API-ul trebuie să cunoască formatul imaginii. Prin urmare, trebuie să îl prezentați ca un data URI, care prefixează datele cu tipul lor MIME:
data:image/{format};base64,{base64_data}
Cele patru prefixe utilizabile corespund formatelor suportate:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Anunțarea unui PNG ca image/jpeg provoacă o eroare de procesare; de aici și funcția de detectare din exemplul următor.
Exemplu complet
Iată lanțul complet, de la citirea fișierului local până la răspunsul modelului:
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)
Concluzia principală: câmpul se numește întotdeauna image_url, chiar și atunci când conține un data URI. Structura mesajului nu se schimbă cu nimic față de Lecția 4; doar valoarea diferă.
Codificarea imaginilor din alte surse
Un fișier de pe disc este doar un caz printre multe altele. Dacă imaginea există deja în memorie, ca un obiect Pillow provenit dintr-o captură sau o etapă de procesare, scrierea ei pe disc doar pentru a o citi imediat ar fi un ocol inutil—un buffer de memorie funcționează perfect:
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)
Aceași logică se aplică unei imagini recuperate prin HTTP pe care nu doriți să o stocați, de exemplu, pentru că provine dintr-un link cu durată scurtă de viață:
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")
Optimizarea dimensiunii înainte de codificare
O fotografie realizată cu un smartphone cântărește astăzi între 4 și 8 MB, ceea ce devine aproape 10 MB odată codificată. API-ul va redimensiona imaginea oricum, așa cum ați văzut în Lecția 2: ați plăti transferul degeaba. Prin urmare, redimensionați întotdeauna înainte de codificare.
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")
Afișarea dimensiunii finale nu este doar decorativă: păstrați-o în timpul testelor, deoarece vă va indica imediat dacă pipeline-ul dvs. trimite 80 KB sau 8 MB la fiecare apel.
Limite de cunoscut
Trei constrângeri vin odată cu Base64. Imaginea codificată se adaugă la corpul cererii HTTP, astfel încât, dincolo de 10 MB, riscați timeout-uri. Codificarea încarcă, de asemenea, întreaga imagine în memorie: pentru procesarea în lot, gestionați imaginile una câte una, în loc să construiți o listă de o mie de șiruri codificate. În final, spre deosebire de URL-uri, imaginile Base64 sunt retransmise în întregime la fiecare cerere—analizarea aceleiași facturi de două ori înseamnă trimiterea ei de două ori.
Puncte cheie
- Base64 este ideal pentru imagini locale sau generate dinamic
- Formatul data URI combină tipul MIME și datele:
data:image/png;base64,... - Redimensionați și comprimați imaginile înainte de codificare pentru a optimiza latența
- Base64 mărește dimensiunea cu aproximativ 33%—mențineți imaginile sub 10 MB
- Utilizați URL când imaginea este deja găzduită, Base64 în toate celelalte cazuri