Formáid ábhair: teaghrán simplí agus eagar d'oiriúna
Ar an leathanach seo
Dhá fhormáid don réimse ábhair
Glacann an réimse content i ngach teachtaireacht le dhá fhormáid éagsúla in API Comhlánú Comhrá xAI. Braitheann do rogha ar an méid a sheolann tú chuig an tsamhail: gnáth-théacs nó ábhar ilmhóideach (téacs + íomhánna).
Formáid teaghráin: an cás is coitianta
I gcás teachtaireachtaí atá bunaithe ar théacs amháin, is teaghrán simplí é an réimse content:
{
"role": "user",
"content": "Explain how a transformer works."
}
Seo an fhormáid a úsáidfidh tú sa chuid is mó de na cásanna. Tá sí simplí, inléite, agus leordhóthanach do gach idirghníomhaíocht téacs le Grok.
Don teachtaireacht system, úsáidtear an fhormáid teaghráin beagnach i gcónaí:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Formáid eagra: ábhar ilmhóideach
Nuair a theastaíonn uait íomhánna a sheoladh in éineacht le téacs, déanann an réimse content eagar d’oiriúna de réir cineáil. Tá réimse type i ngach oiriún a léiríonn a nádúr.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Cineálacha oiriúna atá ar fáil
Glacann an t-eagar ábhair le dhá chineál oiriúna:
text: bloc téacs leis an airítextimage_url: tagairt d’íomhá leis an airíimage_url
Is féidir leat oiread oiriúna agus is gá a chomhcheangal in aon teachtaireacht amháin. Mar shampla, chun iarraidh ar an tsamhail dhá íomhá a chur i gcomparáid:
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two architecture diagrams."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
An paraiméadar detail d’íomhánna
Glacann gach oiriún image_url le paraiméadar roghnach detail a rialaíonn taifead an anailís:
auto: roghnaíonn an tsamhail an leibhéal mionsonraithe go huathoibríoch (an luach réamhshocraithe)low: anailís tapa agus eacnamaíoch, leordhóthanach d’íomhánna simplí (deilbhíní, léaráidí bunúsacha)high: anailís mhionsonraithe, molta d’íomhánna casta (doiciméid, grianghraif, comhéadain)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Bíonn tionchar díreach ag an rogha leibhéil mionsonraithe ar líon na dtócan a úsáidtear agus, dá bhrí sin, ar chostas na hiarrata.
Cathin a úsáidfidh tú gach formáid?
Tá an riail simplí:
- Téacs amháin → formáid teaghráin (níos simplí, níos inléite)
- Téacs + íomhánna → formáid eagra (riachtanach d’ábhar ilmhóideach)
- Íomhánna amháin → formáid eagra le hoiriúna
image_urlamháin
Tá formáid eagra le hoiriún text amháin feidhmiúil coibhéiseach leis an bhformáid teaghráin, ach tá sí ró-fhocalach gan ghá:
// Coibhéiseach ach ró-chasta gan ghá
{"content": [{"type": "text", "text": "Hello"}]}
// Is fearr an fhoirm seo
{"content": "Hello"}
Srianta teicniúla d’íomhánna
Sula seolann tú íomhánna chuig API xAI, cuimhnigh ar na teorainneacha seo:
- Uasmhéid: 20 MiB in aghaidh na híomhá
- Formáidí glactha: JPG, JPEG, PNG amháin (gan GIF, WebP, ná SVG)
- Líon: gan teorainn ar líon na n-íomhánna in aghaidh na hiarrata
- Samhlacha comhoiriúnacha: grok-4.5 agus leaganacha níos airde amháin
Is féidir íomhánna a sholáthar trí URL poiblí nó iad a chódú i mbonn64 laistigh den URL féin (formáid data:image/jpeg;base64,...).
Príomhphointí
- Glacann an réimse
contentle teaghrán simplí (téacs) nó le eagar d’oiriúna (ilmhóideach) - Úsáideann an fhormáid eagra oiriúna le réimse
type:"text"nó"image_url" - Rialaíonn an paraiméadar
detail(auto,low,high) taifead an anailís d’íomhánna - Tá íomhánna teoranta do 20 MiB i bhformáid JPG/PNG agus éilíonn siad grok-4.5 nó leagan níos airde
- Úsáid an fhormáid teaghráin nuair a sheolann tú téacs amháin – tá sí níos inléite agus níos simplí