Визия: Анализиране на изображения с Grok
На тази страница
Разбиране на изображения чрез Chat Completions
Моделите Grok (започвайки от grok-4.5) включват възможности за визия, които Ви позволяват да анализирате, описвате и разсъждавате върху изображения. Използвате тази функция чрез масивния формат на полето content, комбинирайки обекти text и image_url.
Вариантите за употреба са многобройни: извличане на текст от сканирани документи (OCR), анализ на диаграми, описание на потребителски интерфейси, визуално сравнение или тълкуване на технически схеми.
Изпращане на изображение чрез URL
Най-простият начин е да предоставите публичния URL адрес на изображението:
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Describe what you see in this image."},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo-architecture.jpg",
"detail": "high"
}
}
]
}
]
)
print(response.choices[0].message.content)
Сървърите на xAI изтеглят изображението по време на заявката. То трябва да бъде публично достъпно.
Изпращане на изображение в Base64
За локални или частни изображения използвайте кодиране base64:
import base64
def encode_image(image_path: str) -> str:
with open(image_path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
image_data = encode_image("capture-ecran.png")
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What text is visible in this screenshot?"},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{image_data}"
}
}
]
}
]
)
Форматът на URL адреса е data:image/{format};base64,{data}, където {format} е jpeg, jpg или png.
Нива на детайлност: auto, low и high
Параметърът detail контролира разделителната способност, при която моделът анализира изображението:
detail: “low”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/icone.png",
"detail": "low"
}
}
Изображението се мащабира надолу до ниска разделителна способност преди анализа. Това е най-бързият режим и консумира най-малко токени. Използвайте го за прости изображения: икони, лога, основни диаграми.
detail: “high”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Изображението се анализира във висока разделителна способност. Моделът може да чете малък текст, да идентифицира фини детайли и да анализира конкретни области. Това е препоръчителният режим за документи, екранни снимки и подробни фотографии.
detail: “auto”
Моделът автоматично избира нивото на детайлност въз основа на размера и сложността на изображението. Това е стойността по подразбиране, ако пропуснете параметъра.
Анализиране на множество изображения
Можете да изпратите няколко изображения в едно съобщение за задачи за сравнение или кръстосан анализ:
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two versions of the design. What are the differences?"},
{"type": "image_url", "image_url": {"url": "https://example.com/v1.png", "detail": "high"}},
{"type": "image_url", "image_url": {"url": "https://example.com/v2.png", "detail": "high"}}
]
}
]
)
Няма ограничение за броя изображения на заявка, но всяко изображение консумира допълнителни токени.
Технически ограничения
Имайте предвид следните ограничения при използване на визия:
- Максимален размер: 20 MiB на изображение
- Поддържани формати: Само JPG, JPEG и PNG
- Съвместими модели: grok-4 и по-нови (по-старите модели не поддържат визия)
- Токени: Изображенията консумират токени, които се добавят към текстовата цена на заявката
Ключови изводи
- Визията използва масивния формат на полето
contentс обектиimage_url - Изображенията могат да се изпращат чрез публичен URL адрес или да се кодират в base64
- Три нива на детайлност:
auto(по подразбиране),low(бързо/икономично) иhigh(подробно) - Максимален размер от 20 MiB на изображение, само формати JPG и PNG
- Няколко изображения могат да се изпратят в едно съобщение за сравнения