Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Näkökyky: Kuvien analysointi Grokilla

Oppitunti 7 / 12 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kuvien ymmärtäminen Chat Completions -rajapinnalla
  2. Kuvan lähetys URL-osoitteen kautta
  3. Kuvan lähetys Base64-muodossa
  4. Tarkkuustasot: auto, low ja high
  5. Useiden kuvien analysointi
  6. Tekniset rajoitukset
  7. Keskeiset asiat

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 taulukkomuotoa image_url-objektien kanssa
  • Kuvat voidaan lähettää julkisen URL-osoitteen kautta tai koodata base64-muotoon
  • Kolme tarkkuustasoa: auto (oletus), low (nopea/taloudellinen) ja high (yksityiskohtainen)
  • Enimmäiskoko 20 MiB kuvaa kohden, vain JPG- ja PNG-muodot
  • Useita kuvia voidaan lähettää yhdessä viestissä vertailuja varten