Wysyłanie obrazu przez URL
Na tej stronie
Najprostsza metoda
Wysyłanie obrazu przez URL to najbardziej bezpośredni sposób korzystania z Vision API: podajesz adres publicznie dostępnego obrazu, a Mistral pobiera go do analizy. Twoje żądanie pozostaje lekkie – liczy zaledwie kilkaset bajtów – ponieważ zawiera tylko link.
Wybierz tę metodę, gdy Twoje obrazy są już hostowane na CDN, w chmurze lub na stronie internetowej, albo gdy pracujesz z publicznie dostępnymi grafikami w sieci. Zespół, który przechowuje wizualizacje produktów na CDN, może zacząć je analizować bez konieczności zmiany swojej infrastruktury.
Format wiadomości
Wiadomość multimodalna zawierająca URL obrazu ma następującą strukturę:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Twoje pytanie dotyczące obrazu"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Pole image_url akceptuje dowolny adres HTTP lub HTTPS wskazujący na prawidłowy plik obrazu w formacie JPEG, PNG, GIF lub WebP.
Kompletny przykład w Pythonie
Oto kompletny skrypt gotowy do uruchomienia, który analizuje publiczny obraz z Wikimedia, przy założeniu, że Twój klucz API jest ustawiony w zmiennych środowiskowych:
from mistralai.client import Mistral
import os
# Inicjalizacja klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Publiczny obraz do analizy
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Wywołanie Vision API
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Opisz dokładnie, co widzisz na tym obrazie."
},
{
"type": "image_url",
"image_url": url_image
}
]
}
]
)
print(response.choices[0].message.content)
Zwróć uwagę, że przekazujemy klucz przez os.environ, zamiast hardkodować go w kodzie. To jedyna akceptowalna metoda, gdy skrypt opuszcza Twój komputer lokalny.
Dodawanie monitu systemowego
Odpowiedź z powyższego przykładu będzie poprawna, ale ogólna – „czarna mrówka na rozmytym tle“. Wiadomość systemowa zmienia charakter analizy, przypisując modelowi konkretną rolę, zanim zobaczy on obraz:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "system",
"content": "Jesteś ekspertem od entomologii. Analizuj obrazy owadów z naukową precyzją, identyfikując gatunek, rodzinę oraz widoczne cechy morfologiczne."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Zidentyfikuj tego owada."},
{"type": "image_url", "image_url": url_image}
]
}
]
)
Dzięki takiemu ukierunkowaniu ten sam obraz pozwoli uzyskać identyfikację taksonomiczną i opis morfologiczny. Monit systemowy steruje sposobem, w jaki model analizuje obraz – to potężne narzędzie do uzyskiwania wyspecjalizowanych odpowiedzi kosztem zaledwie kilkudziesięciu tokenów.
Wymagania dotyczące URL
API musi mieć możliwość pobrania obrazu bez żadnego kontekstu Twojej sesji. Wynika z tego cztery wymagania: URL musi być publicznie dostępny (brak stron za logowaniem); musi wskazywać bezpośrednio na plik, a nie na stronę HTML zawierającą obraz; format musi być obsługiwany (JPEG, PNG, GIF – gdzie odczytywana jest tylko pierwsza klatka – lub WebP); a rozmiar musi być rozsądny, poniżej 20 MB.
Najczęstszym nieporozumieniem są linki udostępniania. Link do Google Drive lub Dropboxa „udostępniony wszystkim“ zwraca stronę HTML, a nie plik obrazu: wywołanie kończy się niepowodzeniem lub model opisuje interfejs sieciowy. Najlepszą praktyką jest weryfikacja nagłówka Content-Type przed wysłaniem żądania:
import requests
def verify_image_url(url):
"""Sprawdź, czy URL wskazuje na dostępny obraz."""
try:
response = requests.head(url, timeout=5, allow_redirects=True)
content_type = response.headers.get("Content-Type", "")
if response.status_code == 200 and "image" in content_type:
size = int(response.headers.get("Content-Length", 0))
print(f"Obraz dostępny: {content_type}, {size / 1024:.0f} KB")
return True
else:
print(f"Problem: status={response.status_code}, type={content_type}")
return False
except requests.RequestException as e:
print(f"Błąd połączenia: {e}")
return False
verify_image_url("https://example.com/photo.jpg")
Żądanie HEAD jest wystarczające: pobiera nagłówki bez konieczności ściągania całego pliku.
Obrazy z chmury
Wymóg publicznej dostępności wydaje się niezgodny z poufnymi dokumentami. Rozwiązaniem są URL-e z podpisem czasowym (pre-signed URLs): jeśli Twoje obrazy znajdują się w zasobniku S3, Google Cloud Storage lub Azure Blob, generujesz tymczasowy adres, który przyznaje dostęp do pojedynczego obiektu na określony przez Ciebie czas.
import boto3
s3 = boto3.client("s3")
# Generowanie URL-a z podpisem ważnego przez 1 godzinę
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Użycie tego URL-a z Vision API
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Wyciągnij całkowitą kwotę z tej faktury."},
{"type": "image_url", "image_url": presigned_url}
]
}
]
)
Twój zasobnik pozostaje prywatny, URL wygasa po określonym czasie, a Ty zachowujesz lekkość żądania. Ustaw ExpiresIn na jak najkrótszy możliwy czas: kilka minut w zupełności wystarczy na wykonanie wywołania API.
Obsługa błędów
Wywołanie zależne od zdalnego pobierania może się nie powieść z przyczyn niezależnych od Ciebie – obraz został usunięty, URL wygasł lub serwer hostingowy jest niedostępny. W środowisku produkcyjnym nigdy nie pozwalaj, aby surowy wyjątek dotarł do użytkownika:
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Opisz ten obraz."},
{"type": "image_url", "image_url": "https://example.com/image.jpg"}
]
}
]
)
print(response.choices[0].message.content)
except Exception as e:
print(f"Błąd: {e}")
Przetestuj swoją obsługę błędów, używając celowo nieprawidłowego URL-a przed wdrożeniem: to najczęstszy scenariusz i ten, który najrzadziej jest testowany.
Kluczowe wnioski
- Wysyłanie przez URL to najprostsza metoda – wystarczy publiczny adres
- Pole
contentwiadomości to tablica zawierająca elementytextiimage_url - URL musi wskazywać bezpośrednio na dostępny plik obrazu
- URL-e z podpisem czasowym pozwalają bezpiecznie używać prywatnych obrazów
- Zawsze dodawaj monit systemowy, aby ukierunkować analizę modelu