Koodaa ja lähetä kuvia Base64-muodossa
Tällä sivulla
Miksi käyttää Base64:ta?
Edellisessä oppitunnissa opit lähettämään kuvia URL-osoitteen kautta. Useimmilla yrityskontekstissa käsiteltävillä kuvilla ei kuitenkaan ole URL-osoitetta: sähköpostilla juuri saapunut lasku, automatisoidun testin tuottama kuvakaappaus tai tuotantolinjalla operaattorin ottama valokuva. Näiden tiedostojen julkaiseminen internetissä reachable-palvelimella pelkkää analysointia varten olisi absurdiä ja usein kiellettyä.
Tässä tulee avuksi Base64-koodaus. Se muuntaa kuvan binääridatan merkkijonoksi, jonka voit sisällyttää suoraan API-pyyntöösi ilman ulkoista URL-osoitetta tai välihostingia.
Milloin käyttää URL:ää ja milloin Base64:ta
| Kriterio | URL | Base64 |
|---|---|---|
| Jo hostatut kuvat | Ihanteellinen | Tarpeeton |
| Paikalliset kuvat | Ei sovellu | Ihanteellinen |
| Dynaamisesti luodut kuvat | Ei sovellu | Ihanteellinen |
| Verkon viive | Riippuu palvelimesta | Ei ole (upotettu) |
| Pyynnön koko | Kevyt | Raskaampi (~33 %) |
| Turvallisuus/yksityisyys | Julkinen URL | Data pyynnön sisällä |
Sääntö on yksinkertainen: jos kuva on saatavilla vakaan URL-osoitteen kautta, käytä URL-osoitetta. Muussa tapauksessa käytä Base64:ta.
Kuvan koodaaminen Base64-muotoon
Ulkoisia riippuvuuksia ei tarvita; Python tarjoaa base64-moduulin vakio kirjastossaan:
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")
Tiedostoa avattaessa käytettävä "rb"-tila ei ole valinnainen: kuvan lukeminen teksti-tilassa aiheuttaa dekoodausvirheen. Oleta merkkijonojen olevan pitkiä – koodaus kasvattaa kokoa noin 33 % alkuperäiseen tiedostoon verrattuna, joten 1 Mt:n kuvasta tulee noin 1,33 Mt tekstiä.
Data URI -muoto
Pelkkä merkkijono ei riitä: API:n on tiedettävä kuvan formaatti. Sinun on siis esitettävä se data URI:na, joka lisää datan eteen sen MIME-tyypin:
data:image/{format};base64,{base64_data}
Neljä käytettävissä olevaa etuliitettä vastaavat tuettuja formaatteja:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
PNG-kuvan ilmoittaminen muodossa image/jpeg aiheuttaa käsittelyvirheen; siksi seuraavassa esimerkissä on tunnistusfunktio.
Täydellinen esimerkki
Tässä on koko ketju paikallisen tiedoston lukemisesta mallin vastaukseen:
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)
Tärkein oivallus: kentän nimi on aina image_url, vaikka se sisältäisi data URI:n. Viestin rakenne ei muutu lainkaan oppitunnista 4; vain arvo eroaa.
Kuvien koodaaminen muista lähteistä
Levyllä oleva tiedosto on vain yksi monista tapauksista. Jos kuvasi on jo muistissa, esimerkiksi Pillow-objektina kaappauksen tai käsittelyvaiheen jälkeen, sen kirjoittaminen levylle vain lukeaksesi sen heti uudelleen olisi tarpeeton kiertotie – muistipuskuri toimii hyvin:
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)
Sama logiikka pätee HTTP:n kautta haettuun kuvaan, jota et halua tallentaa, esimerkiksi koska se tulee lyhytikäisestä linkistä:
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")
Optimoi koko ennen koodausta
Nykyään älypuhelimen ottama valokuva painaa 4–8 Mt, mikä koodattuna on lähes 10 Mt. API skaalaa sen joka tapauksessa, kuten näit oppitunnilla 2: maksaisit siirrosta turhaan. Siksi skaalaa kuva aina ennen koodausta.
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")
Lopullisen koon näyttäminen ei ole vain koristeellista: pidä se testauksessasi, sillä se kertoo välittömästi, lähettääkö putkesi jokaisella kutsulla 80 kt vai 8 Mt.
Huomioitavat rajat
Base64:ään liittyy kolme rajoitusta. Koodattu kuva lisääntyy HTTP-pyynnön rungossa, joten yli 10 Mt:n koossa riskinä on aikakatkaisu. Koodaus lataa myös koko kuvan muistiin: eräajossa käsittele kuvat yksi kerrallaan sen sijaan, että rakentaisit listan tuhannesta koodatusta merkkijonosta. Lopuksi, toisin kuin URL-osoitteet, Base64-kuvat lähetetään kokonaisina jokaisessa pyynnössä – saman laskun analysointi kahdesti tarkoittaa sen lähettämistä kahdesti.
Keskeiset asiat
- Base64 on ihanteellinen paikallisille tai dynaamisesti luoduille kuville
- Data URI -muoto yhdistää MIME-tyypin ja datan:
data:image/png;base64,... - Skaalaa ja pakkaa kuvasi ennen koodausta viiveen optimoimiseksi
- Base64 kasvattaa kokoa noin 33 % – pidä kuvasi alle 10 Mt:n kokoisina
- Käytä URL:ää, kun kuva on jo hostattu, ja Base64:ta kaikissa muissa tapauksissa