Koduoti ir siųsti vaizdus Base64 formatu
Šiame puslapyje
Kodėl naudoti Base64?
Ankstesnėje pamokoje sužinojai, kaip siųsti vaizdus per URL. Tačiau dauguma verslo kontekste apdorojamų vaizdų neturi URL: sąskaita faktūra, ką tik gauta el. paštu, automatinio testavimo sugeneruota ekrano kopija arba gamybos linijoje operatoriaus padaryta nuotrauka. Skelbti šiuos failus internete pasiekiamame serveryje vien tam, kad juos išanalizuotum, būtų absurdiška ir dažnai draudžiama.
Čia į pagalbą ateina Base64 kodavimas. Jis paverčia vaizdo dvejetainius duomenis teksto eilute, kurią gali tiesiogiai įtraukti į savo API užklausą, nereikalaudamas išorinio URL ar tarpinio talpinimo.
Kada naudoti URL, o kada Base64
| Kriterijus | URL | Base64 |
|---|---|---|
| Jau patalpinti vaizdai | Idealu | Nereikalinga |
| Vietiniai vaizdai | Netinka | Idealu |
| Dinamiškai generuojami vaizdai | Netinka | Idealu |
| Tinklo delsos | Priklauso nuo serverio | Nėra (įterpta) |
| Užklausos dydis | Lengvas | Sunkesnis (~33 %) |
| Saugumas / privatumas | Viešas URL | Duomenys užklausos viduje |
Taisyklė paprasta: jei vaizdas pasiekiamas stabiliaus URL, naudok URL. Kitu atveju – Base64.
Vaizdo kodavimas į Base64
Jokių papildomų bibliotekų nereikia; Python standartinėje bibliotekoje yra modulis base64:
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")
Atidarant failą režimas "rb" nėra pasirenkamas: skaitant vaizdą tekstiniu režimu įvyks dekodavimo klaida. Tikėkis ilgų eilučių – kodavimas padidina dydį maždaug 33 %, palyginti su pradiniu failu, todėl 1 MB vaizdas taps maždaug 1,33 MB teksto.
Data URI formatas
„Grynos“ eilutės nepakanka: API turi žinoti vaizdo formatą. Todėl jį reikia pateikti kaip data URI, kuris prieš duomenis prideda MIME tipą:
data:image/{format};base64,{base64_data}
Keturi galimi priešdėliai atitinka palaikomus formatus:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Jei PNG vaizdą pavadinsi image/jpeg, įvyks apdorojimo klaida; todėl toliau pateiktame pavyzdyje naudojama formato nustatymo funkcija.
Pilnas pavyzdys
Štai visa grandinė – nuo vietinio failo nuskaitymo iki modelio atsakymo:
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)
Svarbiausia: laukas visada vadinasi image_url, net jei jame yra data URI. Pranešimo struktūra nė kiek nesiskiria nuo 4-osios pamokos; skiriasi tik reikšmė.
Vaizdų kodavimas iš kitų šaltinių
Failas diske – tik vienas iš daugelio atvejų. Jei vaizdas jau yra atmintyje, pavyzdžiui, kaip Pillow objektas po fiksavimo ar apdorojimo etapo, rašyti jį į diską ir tuoj pat vėl skaityti būtų nereikalingas nukrypimas – puikiai tinka atminties buferis:
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)
Ta pati logika taikoma ir vaizdui, gautam per HTTP, kurio nenori saugoti, pavyzdžiui, jei jis gaunamas iš trumpalaikės nuorodos:
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")
Optimizuok dydį prieš koduodamas
Šiandien išmaniojo telefono nuotrauka sveria 4–8 MB, o užkoduota – beveik 10 MB. API ją vis tiek sumažins, kaip matei 2-oje pamokoje: mokėtum už perdavimą veltui. Todėl prieš koduodamas visada sumažink vaizdo dydį.
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")
Galutinio dydžio rodymas nėra tik dekoracija: palik jį testavimo metu, nes tai iškart parodys, ar tavo sistema su kiekvienu kvietimu siunčia 80 KB, ar 8 MB.
Žinotinos ribos
Base64 turi tris apribojimus. Užkoduotas vaizdas didina HTTP užklausos kūną, todėl viršijus 10 MB gresia laiko limito viršijimas. Kodavimas taip pat įkelia visą vaizdą į atmintį: apdorojant didelius kiekius, tvarkyk vaizdus po vieną, o ne kurdamas tūkstančio užkoduotų eilučių sąrašą. Galiausiai, skirtingai nei URL, Base64 vaizdai siunčiami pilnai su kiekviena užklausa – tą pačią sąskaitą faktūrą analizuojant du kartus, ją teks siųsti du kartus.
Svarbiausi punktai
- Base64 idealiai tinka vietiniams arba dinamiškai generuojamiems vaizdams
- Data URI formatas sujungia MIME tipą ir duomenis:
data:image/png;base64,... - Prieš koduodamas sumažink ir suspausk vaizdus, kad optimizuotum delsas
- Base64 padidina dydį maždaug 33 % – laikyk vaizdus mažesnius nei 10 MB
- Naudok URL, kai vaizdas jau patalpintas, o Base64 – visais kitais atvejais