Kodēt un nosūtīt attēlus Base64 formātā
Šajā lapā
Kāpēc izmantot Base64?
Iepriekšējā nodarbībā tu uzzināji, kā nosūtīt attēlus, izmantojot URL. Tomēr lielākajai daļai attēlu, ko apstrādā uzņēmumu vidē, nav URL: rēķins, kas tikko saņemts pa e-pastu, ekrānuzņēmums, ko ģenerējis automatizēts tests, vai foto, ko ražošanas līnijā uzņēmis operators. Šo failu publicēšana serverī, kas pieejams internetā, tikai lai tos analizētu, būtu absurda un bieži vien aizliegta.
Šeit nāk talkā Base64 kodējums. Tas pārveido attēla bināros datus teksta virknē, ko iekļauj tieši savā API pieprasījumā, neizmantojot ārēju URL vai starpposma mitināšanu.
Kad izmantot URL, bet kad Base64
| Kritērijs | URL | Base64 |
|---|---|---|
| Jau mitināti attēli | Ideāli | Nav nepieciešams |
| Lokālie attēli | Nav piemērots | Ideāli |
| Dinamiski ģenerēti attēli | Nav piemērots | Ideāli |
| Tīkla latentums | Atkarīgs no servera | Nav (iegults) |
| Pieprasījuma lielums | Vieglšvara | Smagāks (~33 %) |
| Drošība/konfidencialitāte | Publisks URL | Dati pieprasījuma ietvaros |
Noteikums ir vienkāršs: ja attēls ir pieejams, izmantojot stabilu URL, izmanto URL. Pretējā gadījumā izmanto Base64.
Attēla kodēšana Base64 formātā
Nav nepieciešamas nekādas papildu atkarības; Python standarta bibliotēkā ir iekļauts 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")
Režīms "rb", atverot failu, nav izvēles iespēja: attēla nolasīšana teksta režīmā izraisīs dekodēšanas kļūdu. Rēķinies ar garām virknēm — kodēšana palielina lielumu par aptuveni 33 % salīdzinājumā ar sākotnējo failu, tāpēc 1 MB liels attēls radīs aptuveni 1,33 MB teksta.
Datu URI formāts
Ar neapstrādātu virkni nepietiek: API ir jāzina attēla formāts. Tāpēc tas ir jāprezentē kā datu URI, kuram priekšā pievienots tā MIME tips:
data:image/{format};base64,{base64_data}
Četri izmantojamie prefiksi atbilst atbalstītajiem formātiem:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
PNG attēla paziņošana kā image/jpeg izraisīs apstrādes kļūdu; tieši tāpēc tālāk redzamajā piemērā ir iekļauta noteikšanas funkcija.
Pilns piemērs
Lūk, pilns process, sākot no lokālā faila nolasīšanas līdz modeļa atbildei:
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)
Galvenā atziņa: lauks vienmēr tiek saukts par image_url, pat ja tas satur datu URI. Ziņojuma struktūra neatšķiras ne par mata tiesu no 4. nodarbības; mainās tikai vērtība.
Attēlu kodēšana no citiem avotiem
Fails diskā ir tikai viens no daudziem gadījumiem. Ja tavs attēls jau eksistē atmiņā, piemēram, kā Pillow objekts pēc uzņemšanas vai apstrādes posma, tā saglabāšana diskā, lai to tūlīt atkal nolasītu, būtu lieks solis — pietiek ar atmiņas buferi:
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)
Tāda pati loģika attiecas uz attēlu, kas iegūts, izmantojot HTTP un ko nevēlies saglabāt, piemēram, tāpēc, ka tas nāk no īslaicīgas saites:
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")
Optimizē lielumu pirms kodēšanas
Mūsdienu viedtālruņa foto sver no 4 līdz 8 MB, kas pēc kodēšanas kļūst par gandrīz 10 MB. API tāpat mainīs tā izmēru, kā redzēji 2. nodarbībā: tu maksātu par pārsūtīšanu veltīgi. Tāpēc vienmēr maini izmēru pirms kodēšanas.
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")
Galīgā lieluma parādīšana nav tikai dekoratīvs elements: saglabā to testēšanas laikā, jo tas uzreiz pateiks, vai tava pipeline katrā izsaukumā nosūta 80 KB vai 8 MB.
Ierobežojumi, kas jāzina
Base64 izmantošana saistīta ar trim ierobežojumiem. Kodētais attēls tiek pievienots HTTP pieprasījuma ķermenim, tāpēc, pārsniedzot 10 MB, pastāv noilguma risks. Kodēšana arī ielādē visu attēlu atmiņā: partijas apstrādei apstrādā attēlus pa vienam, nevis veido tūkstoš kodētu virkņu sarakstu. Visbeidzot, atšķirībā no URL, Base64 attēli tiek pārsūtīti pilnībā ar katru pieprasījumu — viena un tā paša rēķina analizēšana divreiz nozīmē tā nosūtīšanu divreiz.
Galvenās atziņas
- Base64 ir ideāli piemērots lokāliem vai dinamiski ģenerētiem attēliem
- Datu URI formāts apvieno MIME tipu un datus:
data:image/png;base64,... - Pirms kodēšanas maini attēlu izmēru un saspied tos, lai optimizētu latentumu
- Base64 palielina lielumu par aptuveni 33 % — uzturi attēlus zem 10 MB robežas
- Izmanto URL, ja attēls jau ir mitināts, un Base64 visos pārējos gadījumos