Lähetä kuva URL-osoitteen kautta
Tällä sivulla
Yksinkertaisin menetelmä
Kuvan lähettäminen URL-osoitteen kautta on suoraviivaisin tapa hyödyntää Vision APIa: annat julkisesti saatavilla olevan kuvan osoitteen, ja Mistral lataa sen analysoitavaksi. Pyyntösi pysyy kevyenä – vain muutaman sadan tavun kokoisena – koska se sisältää ainoastaan linkin.
Suosi tätä menetelmää, kun kuvasi ovat jo CDN:ssä, pilvitallennustilassa tai verkkosivustolla, tai kun työskentelet julkisten verkkokuvien kanssa. Tiimi, joka säilyttää tuotekuvansa jo CDN:ssä, voi aloittaa niiden analysoinnin muuttamatta infrastruktuuriaan.
Viestin muoto
Monimodaalinen viesti, jossa on kuvan URL-osoite, noudattaa tätä rakennetta:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Kenttä image_url hyväksyy minkä tahansa HTTP- tai HTTPS-URL-osoitteen, joka viittaa kelvolliseen kuvatiedostoon JPEG-, PNG-, GIF- tai WebP-muodossa.
Täydellinen Python-esimerkki
Tässä on täydellinen, ajokelpoinen skripti, joka analysoi julkisen kuvan Wikimediasta olettaen, että API-avaimesi on asetettu ympäristömuuttujaan:
from mistralai.client import Mistral
import os
# Alustetaan asiakasohjelma
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Analysoitava julkinen kuva
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Kutsutaan Vision APIa
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)
Huomaa, että välitämme avaimen os.environ-muuttujan kautta emmekä kovakoodaa sitä. Tämä on ainoa hyväksyttävä tapa, kun skripti poistuu paikalliselta koneeltasi.
Järjestelmäkehotteen lisääminen
Yllä oleva vastaus on oikea, mutta yleinen – “musta muurahainen sumealla taustalla”. Järjestelmäviesti muuttaa analyysin luonnetta määrittämällä mallille roolin ennen kuin se näkee kuvan:
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}
]
}
]
)
Tällä kehyksellä sama kuva tuottaa taksonomisen tunnistuksen ja morfologisen kuvauksen. Järjestelmäkehote ohjaa sitä, miten malli analysoi kuvaa – tehokas vipu erikoistuneiden vastausten saamiseksi vain muutaman kymmenen tokenin kustannuksella.
URL-vaatimukset
APIn on pystyttävä lataamaan kuva ilman istuntosi kontekstia. Tästä seuraa neljä vaatimusta: URL-osoitteen on oltava julkisesti saatavilla (ei sivuja tunnistautumisen takana); sen on viitattava suoraan tiedostoon, ei HTML-sivuun, joka sisältää kuvan; muodon on oltava tuettu (JPEG, PNG, GIF, jossa luetaan vain ensimmäinen kehys, tai WebP); ja koon on pysyttävä kohtuullisena, alle 20 Mt.
Yleisin sekaannus liittyy jakolinkkeihin. Google Driven tai Dropboxin “kaikille jaettu” linkki palauttaa HTML-sivun, ei kuvatiedostoa: kutsu epäonnistuu, tai malli kuvailee verkkoliittymää. Paras käytäntö on tarkistaa Content-Type ennen lähettämistä:
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")
HEAD-pyyntö riittää: se noutaa otsikkotiedot lataamatta tiedostoa.
Kuvat pilvitallennustilasta
Tämä julkisen saatavuuden vaatimus vaikuttaa ristiriitaiselta luottamuksellisten asiakirjojen kanssa. Ratkaisu löytyy etukäteisallekirjoitetuista URL-osoitteista: jos kuvasi ovat S3-ämpärissä, Google Cloud Storagessa tai Azure Blobissa, voit luoda väliaikaisen osoitteen, joka myöntää pääsyn yksittäiseen objektiin määrittämäksesi ajaksi.
import boto3
s3 = boto3.client("s3")
# Luodaan etukäteisallekirjoitettu URL, joka on voimassa 1 tunnin
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Käytetään tätä URL-osoitetta Vision APIn kanssa
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}
]
}
]
)
Ämpärisi pysyy yksityisenä, URL-osoite vanhenee määritetyn viiveen jälkeen, ja pyynnön keveys säilyy. Aseta ExpiresIn mahdollisimman lyhyeksi: muutama minuutti riittää hyvin API-kutsuun.
Virheenkäsittely
Etälatauksesta riippuva kutsu voi epäonnistua syistä, jotka eivät ole hallinnassasi – kuva on poistettu, URL-osoite on vanhentunut tai isäntäpalvelin ei ole saatavilla. Tuotantoympäristössä älä koskaan anna raakapoikkeuksen nousta käyttäjälle asti:
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}")
Testaa virheenkäsittelysi tarkoituksellisesti virheellisellä URL-osoitteella ennen käyttöönottoa: tämä on yleisin skenaario ja se, jota testataan harvimmin.
Keskeiset asiat
- Lähettäminen URL-osoitteen kautta on yksinkertaisin menetelmä – tarvitset vain julkisen URL-osoitteen
- Viestin
content-kenttä on taulukko, joka sisältäätext- jaimage_url-elementtejä - URL-osoitteen on viitattava suoraan saatavilla olevaan kuvatiedostoon
- Etukäteisallekirjoitetut URL-osoitteet mahdollistavat yksityisten kuvien turvallisen käytön
- Lisää aina järjestelmäkehote ohjaamaan mallin analyysiä