Mine sisu juurde
Sursa Developers

POST/v1/chat

Assistendi vastuse voogedastus (SSE)

chat

Kui koormusjaoturi taga on mitu API eksemplari (aadress api.<domain>, 1.62.0), elavad vastus ja selle sündmuste puhver selle eksemplari mälus, mis vastuse koostab. Voo jätkamine päisega Last-Event-ID töötab ainult selles eksemplaris.

Korduspäring sama request_id ja vestlusega, mis jõuab pärast vastuse valmimist teise eksemplari, saab salvestatud vastuse (token ja done, sündmused nummerdatud alates 1-st) ilma küsimust uuesti esitamata. Korduspäring, mis jõuab teise eksemplari ajal, kui vastust alles koostatakse, peatab selle koostamise ja koostab vastuse uuesti; ka sel juhul teist küsimust ei looda. Voo jätkamiseks ilma uue koostamiseta hoidke ühendust sama eksemplariga või korrake päringut pärast sündmust done.

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Päiseparameetrid

  • X-View-Asstring

    Ainult rolliga admin API-võtmetele. Teeb päringu andmeprofiili <profile>[:viewer|verifier|editor] nimel, näiteks employee:viewer. Paigaldusvõti seda päist kasutada ei saa (403).

Küpsiseparameetrid

  • kb_view_asstring

    Seansi režiimi „View as“ küpsis. POST /auth/view-as määrab selle ja DELETE /auth/view-as kustutab selle.

Päringu keha

application/json

Objekt: ChatRequest

  • messagesarray of ChatMessagekohustuslik

    items ≥ 1

  • collectionstring

    Vaikimisi: "default"

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

    items ≤ 50

  • streamboolean

    Vaikimisi: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Vastust ei võeta vastuste vahemälust (vahemälust võetud vastuse all olev nupp „Get a fresh answer“, värske vastus). Värske vastus asendab vahemälu kirje.

    Vaikimisi: false

  • languagestring | null

    Vastuse keel: ISO 639-1 kood (de, en, ru, …), et vastata selles keeles. Väärtusega auto või ilma väljata tuvastatakse keel küsimuse järgi. Liides edastab teises keeles soovituse keele selgesõnaliselt (Starter.language).

  • scopeChatScope | null

    Küsimuse piiritlus: mitu kogu, allikas, sildid ja periood. Piiritluse kogud asendavad välja collection. Allikas kitsendab vastuse oma koguga (ja oma kaartidega). Sildid lisatakse väljale tags. Periood piirab finantsvastused selle perioodiga. Valida saab ainult seda, mida kasutaja näeb (kogud: collections.no_access/collections.not_found; allikas: sources.not_found). Väljaga conversation_id salvestatakse piiritlus vestlusesse. Ilma väljata kehtib vestluse piiritlus; null või tühi piiritlus tühjendab selle.

  • request_idstring

    Küsimuse idempotentsusvõti. Saatke sama võti ühe küsimuse voo igas korduskatses (korduskatse pärast ühenduse katkemist; siin ei jätka Last-Event-ID voogu ja see ainult logitakse). Korduskatse juba salvestatud vastuse võtmega ei loo teist küsimust: salvestatud tulemus saadetakse uuesti ühe sündmusena done (ja tekstiga token), isegi kui küsimuste või krediidi limiit on ammendatud. Kui eelmist vastust katkenud ühendusega kliendile alles koostatakse, see koostamine peatub ja vastus koostatakse uuesti.

    length ≤ 64

  • version_ofinteger (int64)

    Loob selle küsimuse voorust vestluses uue versiooni (question_id vestluse ajaloost): muudetud küsimus (uus tekst väljas messages), uuesti koostatud vastus (sama tekst, tavaliselt koos bypass_cache) või sama küsimus teise väärtusega quality (näiteks precise pärast vastust režiimis fast). Eelmine küsimuse ja vastuse paar säilib. Sellele järgnevad voorud jäävad selle harusse ja on vestluse ajaloost peidetud, kuni uus versioon on valitud (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Vastuse jaoks kasutatav ajalugu on valitud haru kuni selle voorini. Versiooni quality ei muuda vestluse seadeid. Nõuab välja conversation_id; teise vestluse küsimus tagastab vastuse 404 questions.not_found.

  • qualitystring

    Tulemuse aluseks oleva otsingu kiiruse ja täpsuse tasakaal: fast on kiirem, precise täpsem. Vaikimisi: precise.

    Lubatud väärtused: fastprecise

Vastused

200Kui `stream=true`: `text/event-stream`. Iga sündmus koosneb ridadest `id: <number>` (sündmuse järjekorranumber voos, alates 1-st) ja `data: <JSON>`, millele järgneb tühi rida. Välju `event:` ja `retry:` ei kasutata; sündmuse tüüp on väljal `type` (`ChatEvent`).

Kui stream=true: text/event-stream. Iga sündmus koosneb ridadest id: <number> (sündmuse järjekorranumber voos, alates 1-st) ja data: <JSON>, millele järgneb tühi rida. Välju event: ja retry: ei kasutata; sündmuse tüüp on väljal type (ChatEvent).

Küsimusele, millel on request_id, vastatakse ühendusest sõltumatult. Ühenduse katkemine vastust ei peata: see lõpetatakse ja salvestatakse vestlusesse (kuni 10 minuti jooksul). Sama päringu kordamine (sama request_id ja vestlus) liitub pooleli oleva vastusega ning päisega Last-Event-ID saab see sellele numbrile järgnevad sündmused, nii et voog jätkub samade sündmusenumbritega. Kui voog ei saa sellelt numbrilt jätkuda, saab korduspäring voo algusest: esimese sündmuse number ei ole siis suurem kui Last-Event-ID ja klient alustab vastust otsast peale. Kui vastus on juba valmis ja selle sündmuste puhver on vabastatud (3 minuti pärast), saadetakse salvestatud tulemus uuesti (token ja done, nummerdatud alates 1-st) ilma küsimust uuesti esitamata; muidu koostatakse vastus uuesti. Sellise vastuse peatamiseks kutsuge POST /v1/chat/cancel. Ilma väljata request_id tühistab kliendi ühenduse katkemine vastuse.

Pärast esimest sündmust, kuni vastus on pooleli, saadab server iga 15 sekundi järel kommentaari : ping; jätke see vahele. Sündmuste järjekord: sündmused stage (edenemine), meta, sources, data, seejärel vastuse tekst sündmustes token, seejärel done. Enne vastuse teksti võivad sources ja data korduda ning ilmuda võivad sündmused tool; tekst võib saabuda ühe sündmusena token või osadena. Vahemälust tulev vastus: meta (koos väljaga cached), sources, data, token, done. Viga pärast voo algust saabub sündmusena error ja voog suletakse ilma sündmuseta done; voo HTTP-olek on alati 200. Pärast sündmust done võib saabuda sündmus followups soovitatud järgmiste küsimustega. Eirake sündmusetüüpe, mida te ei töötle.

Kui stream=false: application/json kehaga AnswerResponse (lisaks conversation_id).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

text/event-stream

Objekt: ChatEvent

Üks järgmistest

application/json

Objekt: AnswerResponse

  • answerstringkohustuslik
  • question_idintegerkohustuslik
  • querystring
  • collectionstringkohustuslik
  • sourcesarray of Sourcekohustuslik
  • table_queriesarray of TableQuerykohustuslik
  • datasetsarray of Datasetkohustuslik
  • chartsarray of ChartSpeckohustuslik
  • warningsarray of AnswerWarningkohustuslik
  • timingsTimingskohustuslik
  • provenancearray of NumberProvenance
  • emptystring

    Lubatud väärtused: 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

    Miks selle vastuse jaoks tööriistu kasutati: request (selgesõnaliselt taotletud); compare, compute, action (küsimuse põhjal); needs_calc (vaja on arvutust tabelite põhjal); summary (kogu või dokumentide ülevaade); mcp (organisatsioon on ühendanud välised MCP-serverid).

    Lubatud väärtused: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntitykohustuslik
  • followupsarray of Followupkohustuslik
  • conversation_idstring

    Ainult toimingul POST /v1/chat koos vestlusega.

  • answer_idstring

    Vastuse objekti ID.

400Päring on vigane: parameetri väärtus või objekti olek ei võimalda toimingut (`detail` on teade).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

404Objekti ei ole olemas või see ei ole teile kättesaadav. API ei kinnita piiratud juurdepääsuga objekti olemasolu.

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

422Valideerimisviga: keha või parameetrid ei vasta skeemile (`detail` on valideerimisvigade loend) või parameetri väärtus on lubatud vahemikust väljas (`detail` on teade).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

  • Retry-After

    Sekundite arv, mida oodata enne päringu kordamist.

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Turvalised korduskatsed

Saatke iga POST- ja PATCH-päringuga päis Idempotency-Key (näiteks UUID). Sama võtmega korduskatse 24 tunni jooksul tagastab salvestatud vastuse ega käivita päringut uuesti.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← answers · API teatmik