Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Formáid ábhair: teaghrán simplí agus eagar d'oiriúna

Ceacht 3 as 12 Nuashonraithe 30 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Dhá fhormáid don réimse ábhair
  2. Formáid teaghráin: an cás is coitianta
  3. Formáid eagra: ábhar ilmhóideach
  4. Cathin a úsáidfidh tú gach formáid?
  5. Srianta teicniúla d’íomhánna
  6. Príomhphointí

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í text
  • image_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_url amhá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 content le 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í