Apribojimai: formatai, dydis ir ribos
Šiame puslapyje
Pagrindinės taisyklės
Prieš integruodamas „Grok“ vaizdų analizę į savo programas, privalai žinoti techninius apribojimus, kuriuos nustato xAI API. Jei šių ribų nepaisysi, susidursi su tyliomis klaidomis arba atmestais užklausomis, kurias gamybinėje aplinkoje gali būti labai sunku išderinti.
Priimtini vaizdų formatai
xAI API priima du vaizdų failų formatus (tris plėtinius: .jpg, .jpeg, .png):
- JPG (arba JPEG) – dažniausiai naudojamas formatas nuotraukoms
- PNG – tinkamas ekrano kopijoms, diagramoms ir vaizdams su tekstu
Visi kiti formatai atmetami. Jei dirbi su WebP, GIF, BMP, TIFF, SVG arba HEIC vaizdais, prieš siųsdamas privalai juos konvertuoti:
from PIL import Image
def convert_to_jpeg(source_path, output_path):
img = Image.open(source_path)
# Convert to RGB (required for JPEG)
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")
img.save(output_path, "JPEG", quality=90)
Dažna klaida: RGBA vaizdai
PNG failai su permatomumu (alfa kanalu) priimami tokie, kokie yra. Tačiau jei konvertuoji juos į JPEG, pirmiausia privalai pašalinti alfa kanalą, nes JPEG formatas permatomumo nepalaiko.
Maksimalus dydis: 20 MiB
Kiekvienas vaizdas negali viršyti 20 MiB (20 971 520 baitų). Viršijus šią ribą, API atmeta užklausą.
Šis limitas taikomas:
- Atsisiųstam failui, jei naudojamas URL
- Dekoduotiems duomenims, jei naudojamas Base64 (ne pačiai koduotai eilutei, kuri yra ~33 % ilgesnė)
Patikrink dydį prieš siųsdamas
import os
def check_size(image_path, max_mib=20):
size = os.path.getsize(image_path)
size_mib = size / (1024 * 1024)
if size_mib > max_mib:
raise ValueError(
f"Image too large: {size_mib:.1f} MiB "
f"(max {max_mib} MiB)"
)
return size_mib
Suspausk, jei reikia
Vaizdams, kurių dydis artimas limitui, gali sumažinti JPEG kokybę:
def compress_image(path, quality=80, max_size_mib=20):
img = Image.open(path)
buffer = io.BytesIO()
img.save(buffer, "JPEG", quality=quality)
while buffer.tell() > max_size_mib * 1024 * 1024 and quality > 20:
quality -= 10
buffer = io.BytesIO()
img.save(buffer, "JPEG", quality=quality)
buffer.seek(0)
return buffer
Vaizdų skaičius vienoje užklausoje: neribotas
Skirtingai nei kitos vaizdų analizės API, kurios riboja vaizdų skaičių vienoje užklausoje, xAI API nenustato jokių limitų. Vienoje užklausoje gali siųsti tiek vaizdų, kiek reikia.
Tačiau atmink:
- Kiekvienas vaizdas suvartoja nuo 256 iki 1792 tokenų
- Bendras modelio kontekstas turi maksimalų dydį
- Daugiau vaizdų = didesnė delsos trukmė ir kaina
Praktinė rekomendacija
Nors limitas teoriškai neribotas, laikykis protingumo:
# Best practice: process in batches
def analyze_batch(images, batch_size=10):
results = []
for i in range(0, len(images), batch_size):
batch = images[i:i + batch_size]
input_data = []
for img in batch:
input_data.append({
"type": "input_image",
"image_url": img,
"detail": "low"
})
input_data.append({
"type": "input_text",
"text": "Briefly describe each image."
})
response = client.responses.create(
model="grok-4.5",
input=input_data
)
results.append(response)
return results
Suderinami modeliai
Vaizdų supratimas galimas naudojant „grok-4.5“ ir naujesnius modelius. Senesni modeliai šios funkcijos nepalaiko.
Visada patikrink kode naudojamą modelį:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Klaidų valdymas
Numatyk su apribojimais susijusias klaidas ir patikrink vaizdus prieš siųsdamas:
def validate_image(path):
errors = []
# Check format
extension = path.lower().rsplit(".", 1)[-1]
if extension not in ("jpg", "jpeg", "png"):
errors.append(f"Unsupported format: {extension}")
# Check size
size_mib = os.path.getsize(path) / (1024 * 1024)
if size_mib > 20:
errors.append(f"Too large: {size_mib:.1f} MiB (max 20)")
# Check that it is a real image
try:
img = Image.open(path)
img.verify()
except Exception:
errors.append("Corrupted file or not a valid image")
return errors
Svarbiausi punktai
- Priimami tik JPG/JPEG ir PNG formatai – kitus konvertuok
- Maksimalus dydis: 20 MiB vienam vaizdui – prireikus suspausk
- Vaizdų skaičius vienoje užklausoje yra neribotas, tačiau kiekvienas vaizdas suvartoja tokenų
- Vaizdų analizę palaiko tik „grok-4.5“ ir naujesni modeliai
- Prieš siųsdamas visada patikrink vaizdus, kad išvengtum tylių klaidų