Pošlji sliko prek URL-ja
Na tej strani
Najpreprostejša metoda
Pošiljanje slike prek URL-ja je najbolj neposreden način uporabe API-ja Vision: posreduješ naslov javno dostopne slike in jo Mistral prenese za analizo. Tvoj zahtevek ostane lahek – nekaj sto bajtov –, saj vsebuje le povezavo.
To metodo uporabi prednostno, ko so tvoje slike že gostovane na CDN-ju, v oblaku ali na spletnem mestu, ali ko delaš z javnimi spletnimi slikami. Ekipa, ki že hrani vizuale izdelkov na CDN-ju, lahko začne z njihovo analizo brez sprememb infrastrukture.
Oblika sporočila
Večmodalno sporočilo z URL-jem slike sledi tej strukturi:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Polje image_url sprejme kateri koli naslov HTTP ali HTTPS, ki kaže na veljavno slikovno datoteko v formatih JPEG, PNG, GIF ali WebP.
Celoten primer v Pythonu
Tukaj je celoten skript, pripravljen za zagon, ki analizira javno sliko iz Wikimedie, ob predpostavki, da je tvoj ključ API nastavljen v okolju:
from mistralai.client import Mistral
import os
# Inicializacija odjemalca
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Javna slika za analizo
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Klic API-ja Vision
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)
Upoštevaj, da ključ posredujemo prek os.environ in ne trdo kodiramo. To je edini sprejemljiv pristop, ko skript zapusti tvoje lokalno okolje.
Dodajanje sistemskega poziva
Odgovor zgoraj bo pravilen, a splošen – „črna mravlja na zamegljenem ozadju”. Sistemsko sporočilo spremeni naravo analize tako, da modelu dodeli vlogo, preden si ogleda sliko:
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}
]
}
]
)
S tem okvirjem ista slika prinese taksonomsko identifikacijo in morfološki opis. Sistemski poziv usmerja način, kako model analizira sliko – to je močno orodje za pridobivanje specializiranih odgovorov ob strošku le nekaj deset žetonov.
Zahteve za URL
API mora biti sposoben prenesti sliko brez kakršnega koli konteksta tvoje seje. To vodi do štirih zahtev: URL mora biti javno dostopen (brez strani za avtentikacijo); mora kazati neposredno na datoteko, ne na HTML-stran, ki vsebuje sliko; format mora biti podprt (JPEG, PNG, GIF, kjer se prebere le prvi okvir, ali WebP); in velikost mora ostati razumna, pod 20 MB.
Najpogostejša zmeda nastane pri povezavah za souporabo. Povezava Google Drive ali Dropbox, „deljena z vsemi”, vrne HTML-stran, ne slikovne datoteke: klic ne uspe ali pa model opiše spletni vmesnik. Najboljša praksa je preverjanje Content-Type pred pošiljanjem:
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")
Zahtevek HEAD je zadosten: pridobi glave brez prenosa datoteke.
Slike iz oblaka
Ta zahteva po javni dostopnosti se zdi nezdružljiva z zaupnimi dokumenti. Rešitev so vnaprej podpisani URL-ji: če so tvoje slike v vedru S3, Google Cloud Storage ali Azure Blob, ustvariš začasni naslov, ki omogoča dostop do enega samega objekta za določen čas.
import boto3
s3 = boto3.client("s3")
# Generiranje vnaprej podpisanega URL-ja, veljavnega 1 uro
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Uporaba tega URL-ja z API-jem Vision
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}
]
}
]
)
Tvoje vedro ostane zasebno, URL poteče po določenem času, ohraniš pa lahkotnost zahtevka. Nastavi ExpiresIn čim krajše: nekaj minut je več kot dovolj za klic API-ja.
Obravnava napak
Klic, ki je odvisen od oddaljenega prenosa, lahko ne uspe zaradi razlogov, na katere nimaš vpliva – slika je izbrisana, URL je potekel ali gostiteljski strežnik ni na voljo. V proizvodnem okolju nikoli ne dopusti, da se surova izjema prenese do uporabnika:
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}")
Preizkusi obravnavo napak z namerno neveljavnim URL-jem pred uvedbo: to je najpogostejši scenarij in tisti, ki ga najredkeje testirajo.
Ključne ugotovitve
- Pošiljanje prek URL-ja je najpreprostejša metoda – potrebuješ le javni URL
- Polje
contentv sporočilu je polje, ki vsebuje elementetextinimage_url - URL mora kazati neposredno na dostopno slikovno datoteko
- Vnaprej podpisani URL-ji omogočajo varno uporabo zasebnih slik
- Vedno dodaj sistemski poziv za usmerjanje analize modela