Kodowanie i wysyłanie obrazów w formacie Base64
Na tej stronie
Dlaczego używać Base64?
W poprzedniej lekcji nauczyłeś się wysyłać obrazy za pomocą adresu URL. Jednak większość obrazów przetwarzanych w kontekście biznesowym nie posiada takiego adresu: faktura, która właśnie dotarła mailem, zrzut ekranu wygenerowany przez test automatyczny czy zdjęcie wykonane przez operatora na linii produkcyjnej. Publikowanie tych plików na serwerze dostępnym w internecie tylko po to, by je przeanalizować, byłoby absurdalne i często zabronione.
Tutaj z pomocą przychodzi kodowanie Base64. Przekształca ono dane binarne obrazu w ciąg tekstowy, który dołączasz bezpośrednio do żądania API, bez potrzeby używania zewnętrznego adresu URL ani pośredniego hostingu.
Kiedy użyć URL, a kiedy Base64?
| Kryterium | URL | Base64 |
|---|---|---|
| Obrazy już hostowane | Idealne | Niepotrzebne |
| Obrazy lokalne | Nieodpowiednie | Idealne |
| Obrazy generowane dynamicznie | Nieodpowiednie | Idealne |
| Opóźnienie sieciowe | Zależne od serwera | Brak (osadzone) |
| Rozmiar żądania | Lekkie | Cięższe (~33%) |
| Bezpieczeństwo/prywatność | Publiczny URL | Dane wewnątrz żądania |
Zasada jest prosta: jeśli obraz jest dostępny pod stabilnym adresem URL, użyj URL. W przeciwnym razie użyj Base64.
Kodowanie obrazu do Base64
Nie są wymagane żadne zewnętrzne zależności; Python udostępnia moduł base64 w swojej bibliotece standardowej:
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")
Tryb "rb" podczas otwierania pliku nie jest opcjonalny: odczyt obrazu w trybie tekstowym spowoduje błąd dekodowania. Przygotuj się na długie ciągi – kodowanie zwiększa rozmiar o około 33% w porównaniu do oryginalnego pliku, więc obraz o wielkości 1 MB wygeneruje około 1,33 MB tekstu.
Format Data URI
Sam surowy ciąg znaków nie wystarczy: API musi znać format obrazu. Musisz więc przedstawić go jako data URI, co oznacza dodanie prefiksu z typem MIME przed danymi:
data:image/{format};base64,{base64_data}
Cztery użyteczne prefiksy odpowiadają obsługiwanym formatom:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Zgłoszenie pliku PNG jako image/jpeg spowoduje błąd przetwarzania; stąd funkcja wykrywania w poniższym przykładzie.
Pełny przykład
Oto pełny łańcuch operacji, od odczytu pliku lokalnego po odpowiedź modelu:
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)
Kluczowa uwaga: pole zawsze nazywa się image_url, nawet gdy zawiera data URI. Struktura wiadomości nie zmienia się ani o jotę w stosunku do Lekcji 4; różni się tylko wartość.
Kodowanie obrazów z innych źródeł
Plik na dysku to tylko jeden z wielu przypadków. Jeśli Twój obraz istnieje już w pamięci, jako obiekt Pillow pochodzący z przechwycenia lub etapu przetwarzania, zapisywanie go na dysku tylko po to, by natychmiast go odczytać, byłoby niepotrzebną objazdową drogą – bufor w pamięci sprawdzi się doskonale:
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 sama logika dotyczy obrazu pobranego przez HTTP, którego nie chcesz zapisywać, na przykład dlatego, że pochodzi z linku o krótkim czasie ważności:
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")
Optymalizacja rozmiaru przed kodowaniem
Zdjęcie ze smartfona waży dziś od 4 do 8 MB, co po zakodowaniu daje nearly 10 MB. API i tak zmieni jego rozmiar, jak widziałeś w Lekcji 2: płaciłbyś za transfer bez potrzeby. Dlatego zawsze zmieniaj rozmiar przed kodowaniem.
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")
Wyświetlanie końcowego rozmiaru nie jest tylko ozdobnikiem: zachowaj to podczas testów, ponieważ natychmiast powie Ci, czy Twój pipeline wysyła przy każdym wywołaniu 80 KB, czy 8 MB.
Ograniczenia, które musisz znać
Z Base64 wiążą się trzy ograniczenia. Zakodowany obraz powiększa treść żądania HTTP, więc powyżej 10 MB ryzykujesz przekroczenie limitu czasu (timeout). Kodowanie ładuje również cały obraz do pamięci: przy przetwarzaniu wsadowym obsługuj obrazy pojedynczo, zamiast budować listę tysiąca zakodowanych ciągów. Wreszcie, w przeciwieństwie do adresów URL, obrazy Base64 są przesyłane w całości z każdym żądaniem – analiza tej samej faktury dwukrotnie oznacza wysłanie jej dwa razy.
Kluczowe wnioski
- Base64 jest idealny dla obrazów lokalnych lub generowanych dynamicznie
- Format data URI łączy typ MIME z danymi:
data:image/png;base64,... - Zmień rozmiar i skompresuj obrazy przed kodowaniem, aby zoptymalizować opóźnienia
- Base64 zwiększa rozmiar o około 33% – utrzymuj obrazy poniżej 10 MB
- Używaj URL, gdy obraz jest już hostowany, a Base64 we wszystkich innych przypadkach