Кодиране и изпращане на изображения в Base64
На тази страница
Защо да използвате Base64?
В предишния урок научихте как да изпращате изображения чрез URL адрес. Обаче повечето изображения, обработвани в бизнес контекст, нямат такъв: фактура, току-що получена по имейл, екранна снимка, генерирана от автоматизиран тест, или снимка, направена от оператор на производствена линия. Публикуването на тези файлове на сървър, достъпен от интернет, само за да бъдат анализирани, би било абсурдно и често забранено.
Тук идва на помощ кодирането 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 от стъпка на заснемане или обработка, записването му на диска само за да бъде прочетено отново веднага след това би било излишно отклонение – буфер в паметта работи отлично:
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")
Оптимизиране на размера преди кодиране
Снимка от смартфон днес тежи между 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 рискувате изчакване на времето (timeout). Кодирането също зарежда цялото изображение в паметта: за пакетна обработка обработвайте изображенията едно по едно, вместо да създавате списък от хиляда кодирани низа. Накрая, за разлика от URL адресите, изображенията в Base64 се предават изцяло при всяка заявка – анализирането на една и съща фактура два пъти означава изпращането ѝ два пъти.
Ключови изводи
- Base64 е идеален за локални или динамично генерирани изображения
- Форматът data URI комбинира MIME типа и данните:
data:image/png;base64,... - Преоразмерявайте и компресирайте изображенията си преди кодиране, за да оптимизирате латентността
- Base64 увеличава размера с около 33% – дръжте изображенията си под 10 MB
- Използвайте URL, когато изображението е вече хоствано, и Base64 във всички останали случаи