Αποστολή εικόνας μέσω URL
Σε αυτήν τη σελίδα
Η απλούστερη μέθοδος
Η αποστολή μιας εικόνας μέσω URL είναι ο πιο άμεσος τρόπος χρήσης του Vision API: παρέχετε τη διεύθυνση μιας δημόσια προσβάσιμης εικόνας και το Mistral την κατεβάζει για ανάλυση. Το αίτημά σας παραμένει ελαφρύ—μερικές εκατοντάδες bytes—καθώς μεταφέρει μόνο έναν σύνδεσμο.
Προτιμήστε αυτή τη μέθοδο όταν οι εικόνες σας φιλοξενούνται ήδη σε CDN, αποθήκευση cloud ή ιστότοπο, ή όταν εργάζεστε με δημόσιες εικόνες του web. Μια ομάδα που αποθηκεύει ήδη οπτικό υλικό προϊόντων σε CDN μπορεί να ξεκινήσει την ανάλυσή τους χωρίς να αλλάξει την υποδομή της.
Μορφή μηνύματος
Ένα πολυτροπικό μήνυμα με URL εικόνας ακολουθεί την εξής δομή:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Το πεδίο image_url δέχεται οποιοδήποτε HTTP ή HTTPS URL που δείχνει σε ένα έγκυρο αρχείο εικόνας σε μορφή JPEG, PNG, GIF ή WebP.
Πλήρες παράδειγμα σε Python
Ακολουθεί ένα πλήρες σενάριο, έτοιμο προς εκτέλεση, που αναλύει μια δημόσια εικόνα από το Wikimedia, υποθέτοντας ότι το κλειδί API σας έχει οριστεί στο περιβάλλον:
from mistralai.client import Mistral
import os
# Αρχικοποίηση του client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Δημόσια εικόνα προς ανάλυση
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Κλήση του Vision API
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)
Σημειώστε ότι περνάμε το κλειδί μέσω του os.environ αντί να το κωδικοποιήσουμε απευθείας στον κώδικα. Αυτή είναι η μόνη αποδεκτή προσέγγιση μόλις το σενάριο εγκαταλείψει τον τοπικό σας υπολογιστή.
Προσθήκη prompt συστήματος
Η παραπάνω απάντηση θα είναι σωστή αλλά γενική—«ένα μαύρο μυρμήγκι σε θολό φόντο». Ένα μήνυμα συστήματος αλλάζει τη φύση της ανάλυσης αναθέτοντας έναν ρόλο στο μοντέλο πριν αυτό δει την εικόνα:
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}
]
}
]
)
Με αυτή τη διατύπωση, η ίδια εικόνα παράγει μια ταξινομική αναγνώριση και μια μορφολογική περιγραφή. Το prompt συστήματος καθοδηγεί τον τρόπο με τον οποίο το μοντέλο αναλύει την εικόνα—ένας ισχυρός μοχλός για τη λήψη εξειδικευμένων απαντήσεων με κόστος μόλις μερικών δεκάδων tokens.
Απαιτήσεις URL
Το API πρέπει να μπορεί να κατεβάσει την εικόνα χωρίς κανένα πλαίσιο από τη συνεδρία σας. Αυτό οδηγεί σε τέσσερις απαιτήσεις: το URL πρέπει να είναι δημόσια προσβάσιμο (όχι σελίδες πίσω από έλεγχο ταυτότητας)· πρέπει να δείχνει απευθείας στο αρχείο, όχι σε μια σελίδα HTML που περιέχει την εικόνα· η μορφή πρέπει να υποστηρίζεται (JPEG, PNG, GIF όπου διαβάζεται μόνο το πρώτο καρέ, ή WebP)· και το μέγεθος πρέπει να παραμένει λογικό, κάτω από 20 MB.
Η πιο συχνή σύγχυση αφορά τους συνδέσμους κοινής χρήσης. Ένας σύνδεσμος Google Drive ή Dropbox «κοινόχρηστος με όλους» επιστρέφει μια σελίδα HTML, όχι ένα αρχείο εικόνας: η κλήση αποτυγχάνει ή το μοντέλο περιγράφει μια διαδικτυακή διεπαφή. Η βέλτιστη πρακτική είναι να επαληθεύετε το Content-Type πριν την αποστολή:
import requests
def verify_image_url(url):
"""Επαλήθευση ότι ένα URL δείχνει σε μια προσβάσιμη εικόνα."""
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 είναι επαρκές: ανακτά τις κεφαλίδες χωρίς να κατεβάζει το αρχείο.
Εικόνες από αποθήκευση cloud
Αυτή η απαίτηση δημόσιας προσβασιμότητας φαίνεται ασυμβίβαστη με εμπιστευτικά έγγραφα. Η λύση βρίσκεται στα προ-υπογεγραμμένα URLs (pre-signed URLs): αν οι εικόνες σας βρίσκονται σε έναν κάδο S3, στο Google Cloud Storage ή στο Azure Blob, δημιουργείτε μια προσωρινή διεύθυνση που χορηγεί πρόσβαση σε ένα μόνο αντικείμενο για διάρκεια που εσείς ορίζετε.
import boto3
s3 = boto3.client("s3")
# Δημιουργία προ-υπογεγραμμένου URL ισχύος 1 ώρας
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Χρήση αυτού του URL με το Vision API
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}
]
}
]
)
Ο κάδος σας παραμένει ιδιωτικός, το URL λήγει μετά την καθορισμένη καθυστέρηση και διατηρείτε τον ελαφρύ χαρακτήρα του αιτήματος. Ορίστε το ExpiresIn όσο το δυνατόν συντομότερο: λίγα λεπτά είναι περισσότερο από αρκετά για μια κλήση API.
Διαχείριση σφαλμάτων
Μια κλήση που εξαρτάται από μια απομακρυσμένη λήψη μπορεί να αποτύχει για λόγους πέρα από τον έλεγχό σας—η εικόνα διαγράφηκε, το URL έληξε ή ο διακομιστής φιλοξενίας δεν είναι διαθέσιμος. Σε περιβάλλον παραγωγής, μην αφήνετε ποτέ την ακατέργαστη εξαίρεση να φτάσει στον χρήστη:
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}")
Δοκιμάστε τη διαχείριση σφαλμάτων σας με ένα σκόπιμα μη έγκυρο URL πριν την ανάπτυξη: αυτό είναι το πιο συχνό σενάριο και αυτό που ελέγχεται λιγότερο συχνά.
Βασικά σημεία
- Η αποστολή μέσω URL είναι η απλούστερη μέθοδος—χρειάζεστε μόνο ένα δημόσιο URL
- Το πεδίο
contentτου μηνύματος είναι ένας πίνακας που περιέχει στοιχείαtextκαιimage_url - Το URL πρέπει να δείχνει απευθείας σε ένα προσβάσιμο αρχείο εικόνας
- Τα προ-υπογεγραμμένα URLs σας επιτρέπουν να χρησιμοποιείτε ιδιωτικές εικόνες με ασφάλεια
- Προσθέτετε πάντα ένα prompt συστήματος για να καθοδηγήσετε την ανάλυση του μοντέλου