Sisu vorming: lihtne string ja objektide massiiv
Sellel lehel
Kaks sisu välja vormingut
IGA sõnumi content väli aktsepteerib xAI Chat Completions API-s kahte erinevat vormingut. Valik sõltub sellest, mida mudelile saadad: kas palja teksti või multimeediumsisu (tekst + pildid).
Stringi vorming: kõige levinum juhtum
Puhtalt tekstisõnumite puhul on content väli lihtne string:
{
"role": "user",
"content": "Selgita, kuidas transformer töötab."
}
See on vorming, mida kasutad valdaval enamikul juhtudel. See on lihtne, loetav ja piisav igasuguseks tekstisuhtluseks Grokiga.
system sõnumi puhul kasutatakse peaaegu alati stringi vormingut:
{
"role": "system",
"content": "Oled tarkvara arhitektuuri ekspert. Vasta inglise keeles, tuues näiteid Pythoni koodist."
}
Massiivi vorming: multimeediumsisu
Kui pead saatma koos tekstiga ka pilte, muutub content väli tüübitud objektide massiiviks. Igal objektil on väli type, mis näitab selle olemust.
{
"role": "user",
"content": [
{
"type": "text",
"text": "Mida see pilt kujutab?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Saadaval olevad objektitüübid
Sisu massiiv aktsepteerib kahte tüüpi objekte:
text: tekstiplokk omadusegatextimage_url: viide pildile omadusegaimage_url
Saad ühes sõnumis kombineerida nii palju objekte, kui vaja. Näiteks, kui soovid, et mudel võrdleks kahte pilti:
{
"role": "user",
"content": [
{"type": "text", "text": "Võrdle neid kahte arhitektuuri skeemi."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
Piltide detaili parameeter
Iga image_url objekt aktsepteerib valikulist parameetrit detail, mis kontrollib analüüsi lahutusvõimet:
auto: mudel valib detailitase automaatselt (vaikimisi väärtus)low: kiire ja ökonoomne analüüs, piisab lihtsate piltide jaoks (ikoonid, lihtsad skeemid)high: üksikasjalik analüüs, soovitatav keerukate piltide jaoks (dokumendid, fotod, liidesed)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Detailitaseme valik mõjutab otseselt tarbitavate tokenite arvu ja seega ka päringu hinda.
Millal millist vormingut kasutada?
Reegel on lihtne:
- Ainult tekst → stringi vorming (lihtsam, loetavam)
- Tekst + pildid → massiivi vorming (kohustuslik multimeediumi jaoks)
- Ainult pildid → massiivi vorming, mis sisaldab ainult
image_urlobjekte
Massiivi vorming, mis sisaldab ühteainsat text objekti, on funktsionaalselt samaväärne stringi vorminguga, kuid on põhjendamatult sõnaohker:
// Samaväärne, kuid põhjendamatult keeruline
{"content": [{"type": "text", "text": "Tere"}]}
// Eelista seda vormi
{"content": "Tere"}
Piltide tehnilised piirangud
Enne piltide xAI API-le saatmist pea meeles järgmisi piiranguid:
- Maksimaalne suurus: 20 MiB pildi kohta
- Aktsepteeritud vormingud: ainult JPG, JPEG, PNG (ei GIF, WebP ega SVG)
- Arv: piirangut piltide arvule päringu kohta ei ole
- Ühilduvad mudelid: ainult grok-4.5 ja uuemad
Pilte saab edastada avaliku URL-i kaudu või kodeerituna base64-formaadis otse URL-i sees (vorming data:image/jpeg;base64,...).
Peamised punktid
- Väli
contentaktsepteerib lihtsat stringi (tekst) või objektide massiivi (multimeedium) - Massiivi vorming kasutab objekte väljaga
type:"text"või"image_url" - Parameeter
detail(auto,low,high) kontrollib piltide analüüsi lahutusvõimet - Piltide suurus on piiratud 20 MiB-ga (JPG/PNG) ja need nõuavad mudelit grok-4.5 või uuemat
- Kasuta ainult teksti saatmisel stringi vormingut – see on loetavam ja lihtsam