Ugrás a tartalomra
Sursa Developers

POST/v1/chat

Az asszisztens válaszának adatfolyama (SSE)

chat

Ha az API több példánya fut egy terheléselosztó mögött (az api.<domain> cím, 1.62.0), a válasz és eseményeinek puffere annak a példánynak a memóriájában él, amely a választ előállítja. Az adatfolyam Last-Event-ID fejléccel való folytatása csak azon a példányon működik.

Ha egy ugyanazzal a request_id értékkel és beszélgetéssel megismételt kérés a válasz befejeződése után egy másik példányhoz érkezik, a mentett választ kapja meg (token és done, az események számozása 1-től), a kérdés újbóli feltevése nélkül. Ha a megismételt kérés akkor érkezik egy másik példányhoz, amikor a válasz még készül, leállítja azt az előállítást, és a választ újból összeállítja; második kérdés ekkor sem jön létre. Ha új előállítás nélkül szeretnéd folytatni az adatfolyamot, tartsd meg a kapcsolatot ugyanazzal a példánnyal, vagy a done esemény után ismételd meg a kérést.

Hitelesítés

Küldj egy API-kulcsot az Authorization fejlécben: Authorization: Bearer <kulcs>.

Fejlécparaméterek

  • X-View-Asstring

    Csak admin szerepkörű API-kulcsokhoz. A kérést a <profile>[:viewer|verifier|editor] adatprofil nevében hajtja végre, például employee:viewer. A telepítési kulcs nem használhatja ezt a fejlécet (403).

Cookie-paraméterek

  • kb_view_asstring

    A „View as” mód sütije egy munkamenethez. A POST /auth/view-as beállítja, a DELETE /auth/view-as törli.

Kéréstörzs

application/json

Objektum: ChatRequest

  • messagesarray of ChatMessagekötelező

    items ≥ 1

  • collectionstring

    Alapértelmezett: "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • streamboolean

    Alapértelmezett: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Ne a válaszok gyorsítótárából vegye a választ (a gyorsítótárazott válasz alatti „Get a fresh answer” gomb, friss válasz kérése). A friss válasz felváltja a gyorsítótárban lévő bejegyzést.

    Alapértelmezett: false

  • languagestring | null

    A válasz nyelve: ISO 639-1 kód (de, en, ru, …), hogy a válasz ezen a nyelven készüljön. auto értékkel vagy a mező nélkül a rendszer a kérdésből állapítja meg a nyelvet. A felület a más nyelvű javaslat nyelvét kifejezetten átadja (Starter.language).

  • scopeChatScope | null

    A kérdés tartománya: több gyűjtemény, egy forrás, címkék és egy időszak. A tartomány gyűjteményei felváltják a collection értéket. A forrás a választ a gyűjteményére (és a saját kártyáira) szűkíti. A címkék hozzáadódnak a tags értékhez. Az időszak a pénzügyi válaszokat erre az időszakra korlátozza. Csak azt választhatod ki, amit a felhasználó lát (gyűjtemények: collections.no_access/collections.not_found; forrás: sources.not_found). conversation_id megadásával a tartomány a beszélgetésben mentődik. A mező nélkül a beszélgetés tartománya érvényes; a null vagy az üres tartomány törli.

  • request_idstring

    A kérdés idempotenciakulcsa. Egy kérdés adatfolyamának minden újrapróbálkozásában ugyanazt a kulcsot küldd (kapcsolatbontás utáni újrapróbálkozás; itt a Last-Event-ID nem folytatja az adatfolyamot, csak naplózásra kerül). Egy már mentett válasz kulcsával érkező újrapróbálkozás nem hoz létre második kérdést: a rendszer a mentett eredményt újra elküldi egyetlen done eseményként (és egy token eseményként a szöveggel), akkor is, ha a kérdés- vagy a kreditkorlát elfogyott. Ha a megszakadt kapcsolatú kliens előző válasza még készül, annak elkészítése leáll, és a válasz újra elkészül.

    length ≤ 64

  • version_ofinteger (int64)

    Új verziót hoz létre a beszélgetésben ennek a kérdésnek a köréből (question_id a beszélgetési előzményekből): szerkesztett kérdés (új szöveg a messages mezőben), újragenerált válasz (ugyanaz a szöveg, általában bypass_cache értékkel) vagy ugyanaz a kérdés más quality értékkel (például precise egy fast válasz után). Az előző kérdés–válasz pár megmarad. Az utána következő körök az ő ágában maradnak, és amíg az új verzió van kiválasztva, nem látszanak a beszélgetési előzményekben (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). A válaszhoz figyelembe vett előzmények a kiválasztott ág körei eddig a körig. Egy verzió quality értéke nem módosítja a beszélgetés beállításait. A conversation_id megadása kötelező; más beszélgetés kérdésére a válasz 404 questions.not_found.

  • qualitystring

    Az eredmény mögötti keresés sebessége és pontossága közötti egyensúly: a fast gyorsabb, a precise pontosabb. Alapértelmezett érték: precise.

    Megengedett értékek: fastprecise

Válaszok

200`stream=true` esetén: `text/event-stream`. Minden esemény az `id: <number>` (az esemény sorszáma az adatfolyamban, 1-től kezdve) és a `data: <JSON>` sorból áll, amelyeket egy üres sor követ. Az `event:` és a `retry:` mező nincs használatban; az esemény típusa a `type` mezőben áll (`ChatEvent`).

stream=true esetén: text/event-stream. Minden esemény az id: <number> (az esemény sorszáma az adatfolyamban, 1-től kezdve) és a data: <JSON> sorból áll, amelyeket egy üres sor követ. Az event: és a retry: mező nincs használatban; az esemény típusa a type mezőben áll (ChatEvent).

A request_id értékkel feltett kérdésre a válasz a kapcsolattól függetlenül készül el. A kapcsolat megszakadása nem állítja le a választ: elkészül, és bekerül a beszélgetésbe (legfeljebb 10 percig). Ugyanannak a kérésnek a megismétlése (ugyanaz a request_id és beszélgetés) a folyamatban lévő válaszhoz kapcsolódik, a Last-Event-ID fejléccel pedig az ezt a sorszámot követő eseményeket kapja meg, így az adatfolyam ugyanazokkal az eseménysorszámokkal folytatódik. Ha az adatfolyam nem folytatható ettől a sorszámtól, a megismételt kérés az elejétől kapja meg az adatfolyamot: ekkor az első esemény sorszáma nem nagyobb a Last-Event-ID értékénél, és a kliens elölről kezdi a választ. Ha a válasz már befejeződött, és az eseménypufferét felszabadították (3 perc után), a mentett eredményt küldi el újra (token és done, 1-től számozva), a kérdés újbóli feltevése nélkül; egyébként a választ újból előállítja. Egy ilyen válasz leállításához hívd meg a POST /v1/chat/cancel végpontot. request_id nélkül a kliens kapcsolatbontása megszakítja a választ.

Az első esemény után, amíg a válasz készül, a kiszolgáló 15 másodpercenként egy : ping megjegyzést küld; hagyd figyelmen kívül. Az események sorrendje: stage események (haladás), meta, sources, data, majd a válasz szövege token eseményekben, végül done. A válasz szövege előtt a sources és a data ismétlődhet, és tool események is megjelenhetnek; a szöveg egyetlen token eseményben vagy részletekben is érkezhet. Gyorsítótárazott válasz: meta (cached mezővel), sources, data, token, done. Az adatfolyam megkezdése utáni hiba error eseményként érkezik, és az adatfolyam done nélkül zárul le; az adatfolyam HTTP-állapota mindig 200. A done után egy followups esemény is érkezhet javasolt további kérdésekkel. A nem kezelt eseménytípusokat hagyd figyelmen kívül.

stream=false esetén: application/json, AnswerResponse törzzsel (és conversation_id mezővel).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

text/event-stream

Objektum: ChatEvent

Az alábbiak egyike

application/json

Objektum: AnswerResponse

  • answerstringkötelező
  • question_idintegerkötelező
  • querystring
  • collectionstringkötelező
  • sourcesarray of Sourcekötelező
  • table_queriesarray of TableQuerykötelező
  • datasetsarray of Datasetkötelező
  • chartsarray of ChartSpeckötelező
  • warningsarray of AnswerWarningkötelező
  • timingsTimingskötelező
  • provenancearray of NumberProvenance
  • emptystring

    Megengedett értékek: no_hitsrestrictedguardrailno_data_for_period

  • basisAnswerBasis
  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • guardrailGuardrailVerdict
  • verified_onlyboolean
  • cachedboolean
  • cache_hitAnswerCacheHit
  • out_of_scopeAnswerOutOfScope
  • attachmentsarray of Attachment
  • export_errorstring
  • toolsstring | null

    Miért használt eszközöket ez a válasz: request (kifejezett kérésre); compare, compute, action (a kérdés alapján); needs_calc (táblázatokon végzett számítás szükséges); summary (egy gyűjtemény vagy dokumentumok áttekintése); mcp (a szervezet külső MCP-szervereket kapcsolt be).

    Megengedett értékek: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntitykötelező
  • followupsarray of Followupkötelező
  • conversation_idstring

    Csak a POST /v1/chat hívásnál, beszélgetéssel.

  • answer_idstring

    A válaszobjektum azonosítója.

400A kérés érvénytelen: egy paraméter értéke vagy az objektum állapota nem teszi lehetővé a műveletet (a `detail` egy üzenet).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

401Nem érkeztek hitelesítő adatok (sem munkamenet-süti, sem API-kulcs), vagy a kulcs nem található.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

403A művelet nem engedélyezett: a szerepkör nem elegendő, nincs hozzáférés a gyűjteményhez vagy a kártyához, a kérés „View as” módban fut, vagy a szervezetet felfüggesztették vagy törölték (a `detail` egy objektum, `code: org_suspended | org_deleted` mezővel).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

404Az objektum nem létezik, vagy nem érhető el számodra. Az API nem erősíti meg, hogy egy korlátozott hozzáférésű objektum létezik.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

422Érvényesítési hiba: a törzs vagy a paraméterek nem felelnek meg a sémának (a `detail` az érvényesítési hibák listája), vagy egy paraméter értéke kívül esik a megengedett tartományon (a `detail` egy üzenet).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

429Túl sok kérés (`api.rate_limited`), elfogyott a szervezet percre, napra vagy hónapra szóló kvótája (`api.quota_exceeded`; az `error.details` a `quota`, a `limit` és a `reset_at` mezőt tartalmazza), a szervezet elérte a korlátját, vagy a válaszszolgáltatás foglalt (`answers.engine_busy`). Várj a `Retry-After` fejlécben megadott ideig.

Válaszfejlécek

  • Retry-After

    Ennyi másodpercet várj, mielőtt újrapróbálod a kérést.

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

Hibakódok

Azok a kódok, amelyeket ez a végpont hiba esetén az error.code mezőben visszaadhat, a minden kérésre érvényes általános kódokon kívül.

Biztonságos újrapróbálkozás

Minden POST és PATCH kéréssel küldj Idempotency-Key fejlécet (például egy UUID-t). Ha 24 órán belül ugyanazzal a kulccsal megismétled a kérést, a mentett választ kapod vissza, és a kérés nem fut le újra.

Gyakorisági korlátok

A válaszokban ott van a RateLimit és a RateLimit-Policy fejléc, valamint a korábbi X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléc. A 429-es válasz Retry-After fejléce másodpercben adja meg a várakozást: várj, majd próbáld újra.

← answers · API-referencia