Näkökyky: Kuvien analysointi Grokilla
Tällä sivulla
Kuvien ymmärtäminen Chat Completions -rajapinnalla
Grok-mallit (alkaen versiosta grok-4.5) sisältävät näkökykyominaisuuksia, joiden avulla voit analysoida, kuvailla ja päätellä tietoja kuvista. Käytät tätä ominaisuutta content-kentän taulukkomuodon kautta yhdistämällä text- ja image_url-objekteja.
Käyttökohteita on lukuisia: tekstin erottaminen skannatuista asiakirjoista (OCR), kaavioiden analysointi, käyttöliittymien kuvaaminen, visuaalinen vertailu tai teknisten kaavioiden tulkinta.
Kuvan lähetys URL-osoitteen kautta
Yksinkertaisin tapa on antaa kuvan julkinen URL-osoite:
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-palvelimet lataavat kuvan pyynnön yhteydessä. Kuvan on oltava julkisesti saatavilla.
Kuvan lähetys Base64-muodossa
Paikallisille tai yksityisille kuville käytä base64-koodausta:
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-muoto on data:image/{format};base64,{data}, jossa {format} on jpeg, jpg tai png.
Tarkkuustasot: auto, low ja high
detail-parametri ohjaa resoluutiota, jolla malli analysoi kuvan:
detail: “low”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/icone.png",
"detail": "low"
}
}
Kuva skaalataan pienempään resoluutioon ennen analyysiä. Tämä on nopein tila ja kuluttaa vähiten tokeneja. Käytä sitä yksinkertaisiin kuviin: kuvakkeet, logot, peruskaaviot.
detail: “high”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Kuva analysoidaan korkealla resoluutiolla. Malli pystyy lukemaan pientä tekstiä, tunnistamaan hienovaraisia yksityiskohtia ja analysoimaan tiettyjä alueita. Tämä on suositeltu tila asiakirjoille, kuvakaappauksille ja yksityiskohtaisille valokuville.
detail: “auto”
Malli valitsee tarkkuustason automaattisesti kuvan koon ja monimutkaisuuden perusteella. Tämä on oletusarvo, jos jätät parametrin pois.
Useiden kuvien analysointi
Voit lähettää useita kuvia yhdessä viestissä vertailua tai ristiinanalyysiä varten:
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"}}
]
}
]
)
Kuvien määrälle pyyntöä kohden ei ole rajoitusta, mutta jokainen kuva kuluttaa lisää tokeneja.
Tekniset rajoitukset
Pidä nämä rajat mielessäsi käyttäessäsi näkökykyominaisuuksia:
- Enimmäiskoko: 20 MiB kuvaa kohden
- Tuetut muodot: Vain JPG, JPEG ja PNG
- Yhteensopivat mallit: grok-4 ja uudemmat (vanhemmat mallit eivät tue näkökykyä)
- Tokenit: Kuvat kuluttavat tokeneja, jotka lisäävät pyynnön tekstikustannuksia
Keskeiset asiat
- Näkökyky käyttää
content-kentän taulukkomuotoaimage_url-objektien kanssa - Kuvat voidaan lähettää julkisen URL-osoitteen kautta tai koodata base64-muotoon
- Kolme tarkkuustasoa:
auto(oletus),low(nopea/taloudellinen) jahigh(yksityiskohtainen) - Enimmäiskoko 20 MiB kuvaa kohden, vain JPG- ja PNG-muodot
- Useita kuvia voidaan lähettää yhdessä viestissä vertailuja varten