Odoslanie obrázka prostredníctvom URL
Na tejto strane
Najjednoduchšia metóda
Odoslanie obrázka prostredníctvom URL je najpriamejší spôsob využitia Vision API: poskytneš adresu verejne dostupného obrázka a Mistral si ho stiahne na analýzu. Tvoja požiadavka zostáva ľahká – niekoľko stoviek bajtov – pretože obsahuje iba odkaz.
Uprednostni túto metódu, keď sú tvoje obrázky už hostené na CDN, v cloudovom úložisku alebo na webovej stránke, alebo keď pracuješ s verejnými webovými obrázkami. Tím, ktorý už ukladá vizuály produktov na CDN, môže začať s ich analýzou bez zmeny svojej infraštruktúry.
Formát správy
Multimodálna správa s URL obrázka má nasledujúcu štruktúru:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Tvoja otázka týkajúca sa obrázka"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Pole image_url akceptuje akúkoľvek adresu HTTP alebo HTTPS smerujúcu na platný súbor obrázka vo formáte JPEG, PNG, GIF alebo WebP.
Kompletný príklad v Pythone
Tu je kompletný skript pripravený na spustenie, ktorý analyzuje verejný obrázok z Wikimedia za predpokladu, že máš API kľúč nastavený v prostredí:
from mistralai.client import Mistral
import os
# Inicializácia klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Verejný obrázok na analýzu
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Volanie Vision API
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Presne popíš, čo vidíš na tomto obrázku."
},
{
"type": "image_url",
"image_url": url_image
}
]
}
]
)
print(response.choices[0].message.content)
Všimni si, že kľúč odovzdávame cez os.environ namiesto jeho priameho zakódovania v skripte. Toto je jediný prijateľný prístup, keď skript opustí tvoj lokálny počítač.
Pridanie systémovej inštrukcie
Vyššie uvedená odpoveď bude správna, ale všeobecná – „čierny mravec na rozmazanom pozadí“. Systémová správa zmení povahu analýzy tým, že modelu pridelí rolu ešte predtým, než si obrázok prezrie:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "system",
"content": "Si expert na entomológiu. Analyzuj obrázky hmyzu s vedeckou presnosťou, identifikuj druh, čeľaď a viditeľné morfologické charakteristiky."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Identifikuj tento hmyz."},
{"type": "image_url", "image_url": url_image}
]
}
]
)
S týmto nastavením poskytne ten istý obrázok taxonomickú identifikáciu a morfologický opis. Systémová inštrukcia usmerňuje spôsob, akým model obrázok analyzuje – čo je výkonný nástroj na získanie špecializovaných odpovedí za cenu len niekoľkých desiatok tokenov.
Požiadavky na URL
API musí byť schopné stiahnuť obrázok bez akéhokoľvek kontextu tvojej relácie. To vedie k štyrom požiadavkám: URL musí byť verejne dostupná (žiadne stránky za autentifikáciou); musí smerovať priamo na súbor, nie na HTML stránku obsahujúcu obrázok; formát musí byť podporovaný (JPEG, PNG, GIF, kde sa číta iba prvý snímok, alebo WebP); a veľkosť musí zostať primeraná, pod 20 MB.
Najčastejším zdrojom nejasností sú zdieľané odkazy. Odkaz na Google Drive alebo Dropbox „zdieľaný so všetkými“ vráti HTML stránku, nie súbor obrázka: volanie zlyhá alebo model opíše webové rozhranie. Najlepšou praxou je overiť Content-Type pred odoslaním:
import requests
def verify_image_url(url):
"""Overí, či URL smeruje na dostupný obrázok."""
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"Obrázok dostupný: {content_type}, {size / 1024:.0f} KB")
return True
else:
print(f"Problém: status={response.status_code}, type={content_type}")
return False
except requests.RequestException as e:
print(f"Chyba pripojenia: {e}")
return False
verify_image_url("https://example.com/photo.jpg")
Požiadavka HEAD stačí: získa hlavičky bez sťahovania súboru.
Obrázky z cloudového úložiska
Táto požiadavka na verejnú dostupnosť sa zdá byť nezlučiteľná s dôvernými dokumentmi. Riešením sú predpodpísané URL (pre-signed URLs): ak sú tvoje obrázky v bucketi S3, Google Cloud Storage alebo Azure Blob, vygeneruješ dočasnú adresu, ktorá udeľuje prístup k jednému objektu na vami určený čas.
import boto3
s3 = boto3.client("s3")
# Vygenerovanie predpodpísanej URL platnej 1 hodinu
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Použitie tejto URL s Vision API
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Extrahuj celkovú sumu z tejto faktúry."},
{"type": "image_url", "image_url": presigned_url}
]
}
]
)
Tvoj bucket zostáva súkromný, URL po uplynutí určeného času expiruje a zachovávaš ľahkosť požiadavky. Nastav ExpiresIn čo najkratšie: na volanie API stačí niekoľko minút.
Ošetrenie chýb
Volanie, ktoré závisí od vzdialeného sťahovania, môže zlyhať z dôvodov, ktoré nemôžeš ovplyvniť – obrázok bol vymazaný, URL expirovala alebo hostiteľský server je nedostupný. V produkčnom prostredí nikdy nedovoľ, aby sa surová výnimka dostala až k používateľovi:
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": "Popíš tento obrázok."},
{"type": "image_url", "image_url": "https://example.com/image.jpg"}
]
}
]
)
print(response.choices[0].message.content)
except Exception as e:
print(f"Chyba: {e}")
Otestuj svoje ošetrenie chýb pomocou zámerne neplatnej URL pred nasadením: toto je najčastejší scenár a zároveň ten, ktorý sa testuje najmenej často.
Kľúčové poznatky
- Odoslanie prostredníctvom URL je najjednoduchšia metóda – stačí ti verejná URL
- Pole
contentv správe je pole obsahujúce prvkytextaimage_url - URL musí smerovať priamo na dostupný súbor obrázka
- Predpodpísané URL ti umožňujú bezpečne používať súkromné obrázky
- Vždy pridaj systémovú inštrukciu, aby si usmernil analýzu modelu