Κωδικοποίηση και αποστολή εικόνων σε Base64
Σε αυτήν τη σελίδα
Γιατί να χρησιμοποιήσετε Base64;
Στο προηγούμενο μάθημα, μάθατε πώς να στέλνετε εικόνες μέσω URL. Ωστόσο, οι περισσότερες εικόνες που επεξεργάζονται σε επιχειρηματικό πλαίσιο δεν διαθέτουν URL: ένα τιμολόγιο που μόλις λάβατε μέσω email, ένα στιγμιότυπο οθόνης που παρήχθη από αυτοματοποιημένο έλεγχο, ή μια φωτογραφία που τράβηξε χειριστής σε γραμμή παραγωγής. Η δημοσίευση αυτών των αρχείων σε διακομιστή προσβάσιμο από το διαδίκτυο απλώς και μόνο για να αναλυθούν θα ήταν παράλογη και συχνά απαγορευμένη.
Εδώ εισέρχεται η κωδικοποίηση Base64. Μετατρέπει τα δυαδικά δεδομένα μιας εικόνας σε συμβολοσειρά κειμένου την οποία ενσωματώνετε απευθείας στο αίτημά σας προς το API, χωρίς να χρειάζεστε εξωτερικό URL ή ενδιάμεση φιλοξενία.
Πότε να χρησιμοποιήσετε URL έναντι Base64
| Κριτήριο | URL | Base64 |
|---|---|---|
| Ήδη φιλοξενούμενες εικόνες | Ιδανικό | Περιττό |
| Τοπικές εικόνες | Μη κατάλληλο | Ιδανικό |
| Δυναμικά παραγόμενες εικόνες | Μη κατάλληλο | Ιδανικό |
| Καθυστέρηση δικτύου | Εξαρτάται από τον διακομιστή | Καμία (ενσωματωμένο) |
| Μέγεθος αιτήματος | Ελαφρύ | Βαρύ (~33%) |
| Ασφάλεια/Ιδιωτικότητα | Δημόσιο URL | Δεδομένα μέσα στο αίτημα |
Ο κανόνας είναι απλός: αν η εικόνα είναι προσβάσιμη μέσω σταθερού URL, χρησιμοποιήστε το URL. Διαφορετικά, χρησιμοποιήστε Base64.
Κωδικοποίηση εικόνας σε Base64
Δεν απαιτούνται εξωτερικές βιβλιοθήκες· η Python παρέχει το άρθρωμα 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")
Η λειτουργία "rb" κατά το άνοιγμα του αρχείου δεν είναι προαιρετική: η ανάγνωση μιας εικόνας σε λειτουργία κειμένου θα προκαλέσει σφάλμα αποκωδικοποίησης. Προσδοκήστε μεγάλες συμβολοσειρές—η κωδικοποίηση αυξάνει το μέγεθος κατά περίπου 33% σε σχέση με το αρχικό αρχείο, οπότε μια εικόνα 1 MB παράγει περίπου 1,33 MB κειμένου.
Μορφή Data URI
Η ακατέργαστη συμβολοσειρά δεν αρκεί: το API πρέπει να γνωρίζει τη μορφή της εικόνας. Επομένως, πρέπει να την παρουσιάσετε ως data URI, το οποίο προσθέτει ως πρόθεμα τον τύπο MIME των δεδομένων:
data:image/{format};base64,{base64_data}
Τα τέσσερα διαθέσιμα προθέματα αντιστοιχούν στις υποστηριζόμενες μορφές:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Η δήλωση μιας PNG ως image/jpeg προκαλεί σφάλμα επεξεργασίας· εξ ου και η συνάρτηση ανίχνευσης στο παρακάτω παράδειγμα.
Πλήρες παράδειγμα
Ακολουθεί η πλήρης αλυσίδα, από την ανάγνωση του τοπικού αρχείου έως την απάντηση του μοντέλου:
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)
Βασικό συμπέρασμα: το πεδίο ονομάζεται πάντα image_url, ακόμη και όταν περιέχει ένα data URI. Η δομή του μηνύματος δεν αλλάζει ούτε στο ελάχιστο σε σχέση με το Μάθημα 4· διαφέρει μόνο η τιμή.
Κωδικοποίηση εικόνων από άλλες πηγές
Ένα αρχείο στον δίσκο είναι απλώς μία από τις πολλές περιπτώσεις. Αν η εικόνα σας υπάρχει ήδη στη μνήμη, ως αντικείμενο Pillow από μια λήψη ή βήμα επεξεργασίας, η εγγραφή της στον δίσκο μόνο για να διαβαστεί αμέσως μετά θα ήταν περιττή παράκαμψη—ένας buffer μνήμης λειτουργεί μια χαρά:
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)
Η ίδια λογική ισχύει για μια εικόνα που ανακτάται μέσω HTTP και δεν θέλετε να αποθηκεύσετε, για παράδειγμα επειδή προέρχεται από σύνδεσμο βραχείας διάρκειας:
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")
Βελτιστοποίηση μεγέθους πριν την κωδικοποίηση
Μια φωτογραφία smartphone σήμερα ζυγίζει 4 έως 8 MB, γεγονός που γίνεται σχεδόν 10 MB μόλις κωδικοποιηθεί. Το API θα αλλάξει ούτως ή άλλως το μέγεθός της, όπως είδατε στο Μάθημα 2: θα πληρώνατε για τη μεταφορά χωρίς λόγο. Επομένως, αλλάζετε πάντα το μέγεθος πριν την κωδικοποίηση.
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")
Η εμφάνιση του τελικού μεγέθους δεν είναι απλώς διακοσμητική: κρατήστε την κατά τις δοκιμές σας, καθώς θα σας δείξει αμέσως αν ο αγωγός σας στέλνει 80 KB ή 8 MB σε κάθε κλήση.
Όρια που πρέπει να γνωρίζετε
Τρεις περιορισμοί συνοδεύουν το Base64. Η κωδικοποιημένη εικόνα προστίθεται στο σώμα του αιτήματος HTTP, οπότε πέρα από τα 10 MB διακινδυνεύετε χρονικά όρια αναμονής (timeouts). Η κωδικοποίηση φορτώνει επίσης ολόκληρη την εικόνα στη μνήμη: για επεξεργασία παρτίδων, χειριστείτε τις εικόνες μία προς μία αντί να δημιουργήσετε μια λίστα χιλιάδων κωδικοποιημένων συμβολοσειρών. Τέλος, σε αντίθεση με τα URL, οι εικόνες Base64 μεταδίδονται πλήρως με κάθε αίτημα—η ανάλυση του ίδιου τιμολογίου δύο φορές σημαίνει ότι το στέλνετε δύο φορές.
Βασικά σημεία
- Το Base64 είναι ιδανικό για τοπικές ή δυναμικά παραγόμενες εικόνες
- Η μορφή data URI συνδυάζει τον τύπο MIME και τα δεδομένα:
data:image/png;base64,... - Αλλάξτε το μέγεθος και συμπιέστε τις εικόνες σας πριν την κωδικοποίηση για βελτιστοποίηση της καθυστέρησης
- Το Base64 αυξάνει το μέγεθος κατά περίπου 33%—κρατήστε τις εικόνες σας κάτω από 10 MB
- Χρησιμοποιήστε URL όταν η εικόνα είναι ήδη φιλοξενούμενη, Base64 σε όλες τις άλλες περιπτώσεις