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

Fíordheimhniú agus comharthaí sealadacha

Ceacht 2 as 16 Nuashonraithe 30 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Dhá bhealach le fíordheimhniú a dhéanamh
  2. Ailtireacht mholta le comharthaí sealadacha
  3. Dea-chleachtais slándála
  4. Príomhphointí

Dhá bhealach le fíordheimhniú a dhéanamh

Tá dhá bhealach ar fáil sa Voice Agent API chun do nasc WebSocket a fhíordheimhniú. Braitheann an ceann a roghnaíonn tú ar an áit a ritheann do chód: ar an bhfreastalaí nó ar an gcliant.

Eochair API dhíreach (taobh an fhreastalaí)

Is é an modh is simplí ná d’eochair API a chur sa cheanntásc údaraithe nuair a osclaíonn tú an WebSocket. Oibríonn sé seo d’fheidhmchláir fhreastalaí, áit a bhfanann an eochair faoi chosaint:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-your-api-key"
  }
});

Ná húsáid an modh seo riamh i gcód a ritheann sa bhrabhsálaí: nochtfaí an eochair API sa chód foinseach nó sna huirlisí forbróra.

Comharthaí sealadacha (taobh an chliaint)

Do fheidhmchláir front-end (brabhsálaí, soghluaiste), soláthraíonn xAI comharthaí sealadacha. Gineann do chúlchóras comhartha gearrshaolach, a chuireann tú ar fáil don chliant ansin chun an nasc WebSocket a oscailt.

Cruthaíonn tú comhartha le hiarratas POST:

curl -X POST "https://api.x.ai/v1/realtime/client_secrets" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_after": {"seconds": 300}}'

Socraíonn an réimse expires_after.seconds cá fhad a bheidh an comhartha bailí, i soicind. Úsáideann sampla na doiciméadachta oifigiúla 300 soicind (5 nóiméad): tá comhartha sealadach ceaptha chun seisiún gutha a chlúdach, ní chun maireachtáil go ceann i bhfad. Dírich ar an saolré is giorra a oireann do do sheisiúin.

Ailtireacht mholta le comharthaí sealadacha

Seo an sruth iomlán d’fheidhmchlár gréasáin:

// 1. Taobh an fhreastalaí (Node.js/Express): gin an comhartha
app.post("/api/realtime-token", async (req, res) => {
  const response = await fetch(
    "https://api.x.ai/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
        "Content-Type": application/json"
      },
      body: JSON.stringify({ expires_after: { seconds: 600 } })
    }
  );
  // Fill corp freagartha xAI mar atá sé;
  // tá an comhartha sealadach ann
  res.json(await response.json());
});

// 2. Taobh an chliaint (brabhsálaí): úsáid an comhartha
// Ní ghlacann tógálaí WebSocket an bhrabhsálaí le ceanntásca:
// cuirtear an comhartha i bhFO-PRÓTACAL, réamhaithe le "xai-client-secret."
async function startVoiceSession(ephemeralToken) {
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime",
    [`xai-client-secret.${ephemeralToken}`]
  );

  ws.onopen = () => {
    console.log("Voice session started");
  };
}

Comharthaí a athnuachan

Ní luaitear sa doiciméadacht an ndúnann comhartha atá ag dul in éag nasc atá oscailte cheana féin. Cibé scéal é, ní mór plean a bheith ag d’fheidhmchlár don uair a thiteann an nasc: bí ar an airdeall don imeacht dúnta, iarr comhartha nua ó do chúlchóras, agus athnasc ansin:

ws.onclose = async () => {
  // Cailltear an nasc nó dúnadh é: iarr comhartha nua
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Dea-chleachtais slándála

Coinníonn roinnt rialacha riachtanacha do naisc slán:

  • Ná nocht riamh do phríomheochair API ar an gcliant
  • Coinnigh an saolré (expires_after.seconds) chomh gearr agus is féidir: má mhaireann do sheisiún meánach cúig nóiméad, tá 300 go 600 soicind go leor
  • Fíordheimhnigh iarratais comhartha ar an bhfreastalaí (fíordheimhniú úsáideora, teorannú ráta)
  • Déan logáil ar chruthú comhartha ionas gur féidir leat úsáid mhínormálta a bhrath
  • Rothlaigh do phríomheochair API má amhras tú go bhfuil sí curtha i mbaol

Príomhphointí

  • Níl eochair API dhíreach oiriúnach ach d’fheidhmchláir fhreastalaí
  • Tá comharthaí sealadacha riachtanach d’fheidhmchláir taobh an chliaint (brabhsálaí, soghluaiste)
  • Socraigh saolré an chomhartha le expires_after.seconds agus coinnigh gearr é (300 soicind sa sampla oifigiúil)
  • Is é an sruth molta: gineann do chúlchóras an comhartha, agus cuireann do thosaigh ar fáil é mar an fho-phrótacal xai-client-secret. chun an WebSocket a oscailt
  • Pleanáil i gcónaí d’athnuachan uathoibríoch comharthaí