Kép küldése URL-címen keresztül
Ezen az oldalon
A legegyszerűbb módszer
A kép URL-címen keresztüli küldése a Vision API használatának legközvetlenebb módja: megadod egy nyilvánosan elérhető kép címét, és a Mistral letölti azt elemzésre. A kérésed így könnyű marad – néhány száz bájt –, mivel csak egy hivatkozást tartalmaz.
Akkor részesítsd előnyben ezt a módszert, ha a képeid már CDN-en, felhőtárhelyen vagy weboldalon vannak elhelyezve, illetve ha nyilvános webes képekkel dolgozol. Egy csapat, amely például már CDN-en tárolja a termékvizuálokat, infrastruktúrája módosítása nélkül kezdheti meg azok elemzését.
Üzenetformátum
Egy kép URL-címét tartalmazó multimodális üzenet a következő szerkezetet követi:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Az image_url mező bármilyen HTTP vagy HTTPS URL-címet elfogad, amely érvényes képfájlra mutat JPEG, PNG, GIF vagy WebP formátumban.
Teljes Python-példa
Íme egy teljes, futtatható szkript, amely egy nyilvános képet elemez a Wikimédiáról, feltételezve, hogy az API-kulcsod a környezetváltozókban van beállítva:
from mistralai.client import Mistral
import os
# A kliens inicializálása
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# A nyilvános kép, amit elemezni szeretnénk
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# A Vision API meghívása
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe precisely what you see in this image."
},
{
"type": "image_url",
"image_url": url_image
}
]
}
]
)
print(response.choices[0].message.content)
Vedd észre, hogy a kulcsot az os.environ segítségével adjuk át, nem pedig közvetlenül a kódba írva. Ez az egyetlen elfogadható megközelítés, ha a szkript kikerül a helyi gépedről.
Rendszerüzenet (system prompt) hozzáadása
A fenti válasz helyes lesz, de általános: „egy fekete hangya elmosódott háttér előtt“. Egy rendszerüzenet megváltoztatja az elemzés jellegét azáltal, hogy szerepet assigns a modellnek, még mielőtt az látná a képet:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "system",
"content": "You are an entomology expert. Analyze insect images with scientific precision, identifying the species, family, and visible morphological characteristics."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Identify this insect."},
{"type": "image_url", "image_url": url_image}
]
}
]
)
Ezzel a keretezéssel ugyanaz a kép taxonómiai azonosítást és morfológiai leírást eredményez. A rendszerüzenet irányítja, hogyan elemzi a modell a képet – ez egy hatalmas eszköz specializált válaszok získálására, mindössze néhány tucat token költségén.
URL-követelmények
Az API-nak képesnek kell lennie a kép letöltésére a munkameneted kontextusa nélkül. Ez négy követelményt von maga után: az URL-nek nyilvánosan elérhetőnek kell lennie (nincs hitelesítés mögött rejtett oldal); közvetlenül a fájlra kell mutatnia, nem pedig egy olyan HTML-oldalra, amely tartalmazza a képet; a formátumnak támogatottnak kell lennie (JPEG, PNG, GIF – ahol csak az első képkockát olvassa be –, vagy WebP); a méretnek pedig ésszerűnek kell maradnia, 20 MB alatt.
A leggyakoribb félreértés a megosztási hivatkozásokkal kapcsolatos. Egy Google Drive vagy Dropbox link, amelyet „mindenkivel megosztottak“, egy HTML-oldalt ad vissza, nem pedig egy képfájlt: a hívás sikertelen, vagy a modell egy webes felületet ír le. A legjobb gyakorlat a Content-Type ellenőrzése küldés előtt:
import requests
def verify_image_url(url):
"""Verify that a URL points to an accessible image."""
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"Image accessible: {content_type}, {size / 1024:.0f} KB")
return True
else:
print(f"Issue: status={response.status_code}, type={content_type}")
return False
except requests.RequestException as e:
print(f"Connection error: {e}")
return False
verify_image_url("https://example.com/photo.jpg")
Egy HEAD kérés elegendő: ez lekéri a fejléceket a fájl letöltése nélkül.
Képek felhőtárhelyről
Ez a nyilvános hozzáférhetőségi követelmény összeférhetetlennek tűnik a bizalmas dokumentumokkal. A megoldás az előjelezett URL-címekben (pre-signed URLs) rejlik: ha a képeid egy S3 vödörben, Google Cloud Storage-ban vagy Azure Blob-ban vannak, generálhatsz egy ideiglenes címet, amely meghatározott időtartamra hozzáférést biztosít egyetlen objektumhoz.
import boto3
s3 = boto3.client("s3")
# Előjelezett URL generálása, amely 1 óráig érvényes
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Az URL használata a Vision API-val
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Extract the total amount from this invoice."},
{"type": "image_url", "image_url": presigned_url}
]
}
]
)
A vödröd privát marad, az URL a megadott idő után elévül, és a kérés könnyűsége megmarad. Állítsd az ExpiresIn értéket a lehető legrövidebbre: néhány perc több mint elég egy API-híváshoz.
Hibakezelés
Egy távoli letöltéstől függő hívás olyan okok miatt is sikertelen lehet, amelyek rajtad kívül állnak: a képet törölték, az URL elévült, vagy a hoszting szerver nem elérhető. Éles környezetben soha ne engedd, hogy a nyers kivétel (exception) elérjen a felhasználóig:
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": "Describe this image."},
{"type": "image_url", "image_url": "https://example.com/image.jpg"}
]
}
]
)
print(response.choices[0].message.content)
except Exception as e:
print(f"Error: {e}")
Teszteld a hibakezelésedet szándékosan érvénytelen URL-lel, mielőtt telepítenéd: ez a leggyakoribb forgatókönyv, és egyben az, amelyet a legritkábban tesztelnek.
Főbb megállapítások
- Az URL-en keresztüli küldés a legegyszerűbb módszer – csak egy nyilvános URL-re van szükséged
- Az üzenet
contentmezője egy tömb, amelytextésimage_urlelemeket tartalmaz - Az URL-nek közvetlenül egy elérhető képfájlra kell mutatnia
- Az előjelezett URL-ek lehetővé teszik privát képek biztonságos használatát
- Mindig adj hozzá rendszerüzenetet a modell elemzésének irányításához