Preskočiť na obsah
Sursa Developers

POST/v1/chat

Streamovať odpoveď asistenta (SSE)

chat

Pri viacerých kópiách API za vyrovnávačom záťaže (load balancer; adresa api.<domain>, 1.62.0) existujú odpoveď a medzipamäť jej udalostí v pamäti kópie, ktorá odpoveď generuje. Obnovenie streamu s Last-Event-ID funguje len na tejto kópii.

Opakovaná požiadavka s tým istým request_id a konverzáciou, ktorá sa po dokončení odpovede dostane na inú kópiu, dostane uloženú odpoveď (token a done, udalosti číslované od 1) bez opätovného položenia otázky. Opakovaná požiadavka, ktorá sa dostane na inú kópiu, kým sa odpoveď ešte generuje, toto generovanie zastaví a zostaví odpoveď nanovo; ani vtedy sa nevytvorí druhá otázka. Ak chcete obnoviť stream bez nového generovania, udržiavajte spojenie s tou istou kópiou alebo zopakujte požiadavku po udalosti done.

Autentifikácia

Odošlite kľúč API v hlavičke Authorization: Authorization: Bearer <kľúč>.

Parametre hlavičky

  • X-View-Asstring

    Len pre kľúče API s rolou admin. Vykoná požiadavku v mene dátového profilu <profile>[:viewer|verifier|editor], napríklad employee:viewer. Inštalačný kľúč túto hlavičku použiť nemôže (403).

Parametre cookie

  • kb_view_asstring

    Súbor cookie režimu „View as“ pre reláciu. POST /auth/view-as ho nastaví a DELETE /auth/view-as ho odstráni.

Telo požiadavky

application/json

Objekt: ChatRequest

  • messagesarray of ChatMessagepovinné

    items ≥ 1

  • collectionstring

    Predvolené: "default"

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

    items ≤ 50

  • streamboolean

    Predvolené: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Nepreberať odpoveď z vyrovnávacej pamäte odpovedí (tlačidlo „Get a fresh answer“ pod odpoveďou z vyrovnávacej pamäte). Nová odpoveď nahradí záznam vo vyrovnávacej pamäti.

    Predvolené: false

  • languagestring | null

    Jazyk odpovede: kód ISO 639-1 (de, en, ru, …), ak má odpoveď byť v tomto jazyku. Pri auto alebo bez poľa sa jazyk určí z otázky. Rozhranie odovzdáva jazyk odporúčania v inom jazyku výslovne (Starter.language).

  • scopeChatScope | null

    Rozsah otázky: niekoľko kolekcií, zdroj, štítky a obdobie. Kolekcie rozsahu nahrádzajú collection. Zdroj zúži odpoveď na svoju kolekciu (a svoje vlastné karty). Štítky sa pridajú k tags. Obdobie obmedzí finančné odpovede na toto obdobie. Vybrať možno len to, čo používateľ vidí (kolekcie: collections.no_access/collections.not_found; zdroj: sources.not_found). S conversation_id sa rozsah uloží v konverzácii. Bez poľa platí rozsah konverzácie; null alebo prázdny rozsah ho vymaže.

  • request_idstring

    Kľúč idempotencie otázky. Rovnaký kľúč posielajte pri každom opakovaní streamu pre jednu otázku (opakovanie po odpojení; tu Last-Event-ID stream neobnoví a len sa zaznamená do logu). Opakovanie s kľúčom odpovede, ktorá je už uložená, nevytvorí druhú otázku: uložený výsledok sa znova pošle ako jedna udalosť done (a token s textom), aj keď je limit otázok alebo kreditov vyčerpaný. Ak sa predchádzajúca odpoveď pre odpojeného klienta ešte generuje, toto generovanie sa zastaví a odpoveď sa vygeneruje nanovo.

    length ≤ 64

  • version_ofinteger (int64)

    Vytvorí novú verziu kola tejto otázky v konverzácii (question_id z priebehu konverzácie): upravenú otázku (nový text v messages), znova vygenerovanú odpoveď (rovnaký text, zvyčajne s bypass_cache) alebo tú istú otázku s inou hodnotou quality (napríklad precise po odpovedi fast). Predchádzajúca dvojica otázky a odpovede sa zachová. Kolá za ňou zostanú v jej vetve a kým je vybraná nová verzia, sú skryté v priebehu konverzácie (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Históriou pre odpoveď je vybraná vetva až po toto kolo. quality verzie nemení nastavenia konverzácie. Vyžaduje conversation_id; otázka z inej konverzácie vráti 404 questions.not_found.

  • qualitystring

    Pomer medzi rýchlosťou a presnosťou vyhľadávania, z ktorého výsledok vychádza: fast je rýchlejší, precise je presnejší. Predvolené: precise.

    Povolené hodnoty: fastprecise

Odpovede

200So `stream=true`: `text/event-stream`. Každá udalosť sa skladá z riadkov `id: <number>` (poradové číslo udalosti v streame, od 1) a `data: <JSON>`, po ktorých nasleduje prázdny riadok. Polia `event:` a `retry:` sa nepoužívajú; typ udalosti je v poli `type` (`ChatEvent`).

So stream=true: text/event-stream. Každá udalosť sa skladá z riadkov id: <number> (poradové číslo udalosti v streame, od 1) a data: <JSON>, po ktorých nasleduje prázdny riadok. Polia event: a retry: sa nepoužívajú; typ udalosti je v poli type (ChatEvent).

Na otázku s request_id sa odpovedá nezávisle od spojenia. Odpojenie odpoveď nezastaví: dokončí sa a uloží do konverzácie (nanajvýš do 10 minút). Opakovanie tej istej požiadavky (rovnaké request_id a konverzácia) sa pripojí k rozpracovanej odpovedi a s hlavičkou Last-Event-ID dostane udalosti po tomto čísle, takže stream pokračuje s rovnakými číslami udalostí. Ak stream od tohto čísla pokračovať nemôže, opakovaná požiadavka dostane stream od začiatku: prvá udalosť má potom číslo nie väčšie ako Last-Event-ID a klient začne odpoveď odznova. Ak sa odpoveď už dokončila a medzipamäť jej udalostí bola uvoľnená (po 3 minútach), uložený výsledok sa pošle znova (token a done, číslované od 1) bez opätovného položenia otázky; inak sa odpoveď vygeneruje nanovo. Ak chcete takúto odpoveď zastaviť, zavolajte POST /v1/chat/cancel. Bez request_id odpojenie klienta odpoveď zruší.

Po prvej udalosti, kým odpoveď prebieha, server posiela každých 15 sekúnd komentár : ping; preskočte ho. Poradie udalostí: udalosti stage (priebeh), meta, sources, data, potom text odpovede v udalostiach token a nakoniec done. Pred textom odpovede sa sources a data môžu opakovať a môžu sa objaviť udalosti tool; text môže prísť ako jeden token alebo po častiach. Odpoveď z vyrovnávacej pamäte: meta (s cached), sources, data, token, done. Chyba po začatí streamu príde ako udalosť error a stream sa uzavrie bez done; stavový kód HTTP streamu je vždy 200. Po done môže prísť udalosť followups s odporúčanými ďalšími otázkami. Typy udalostí, ktoré nespracúvate, ignorujte.

So stream=false: application/json s telom AnswerResponse (a navyše conversation_id).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

text/event-stream

Objekt: ChatEvent

Jedna z možností

application/json

Objekt: AnswerResponse

  • answerstringpovinné
  • question_idintegerpovinné
  • querystring
  • collectionstringpovinné
  • sourcesarray of Sourcepovinné
  • table_queriesarray of TableQuerypovinné
  • datasetsarray of Datasetpovinné
  • chartsarray of ChartSpecpovinné
  • warningsarray of AnswerWarningpovinné
  • timingsTimingspovinné
  • provenancearray of NumberProvenance
  • emptystring

    Povolené hodnoty: 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

    Prečo sa pri tejto odpovedi použili nástroje: request (výslovne vyžiadané); compare, compute, action (podľa otázky); needs_calc (je potrebný výpočet nad tabuľkami); summary (prehľad kolekcie alebo dokumentov); mcp (organizácia pripojila externé servery MCP).

    Povolené hodnoty: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntitypovinné
  • followupsarray of Followuppovinné
  • conversation_idstring

    Len pri POST /v1/chat s konverzáciou.

  • answer_idstring

    ID objektu odpovede.

400Požiadavka je neplatná: hodnota parametra alebo stav objektu akciu nedovoľuje (`detail` je správa).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

401Neboli odoslané žiadne prihlasovacie údaje (ani cookie relácie, ani kľúč API) alebo sa kľúč nenašiel.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

403Akcia nie je povolená: rola nestačí, chýba prístup ku kolekcii alebo karte, požiadavka beží v režime „View as“ alebo je organizácia pozastavená či odstránená (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

404Objekt neexistuje alebo vám nie je dostupný. API nepotvrdzuje, že objekt s obmedzeným prístupom existuje.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

422Chyba validácie: telo alebo parametre nezodpovedajú schéme (`detail` je zoznam chýb validácie) alebo je hodnota parametra mimo rozsahu (`detail` je správa).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

429Príliš veľa požiadaviek (`api.rate_limited`), vyčerpaná kvóta organizácie na minútu, deň alebo mesiac (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), dosiahnutý limit organizácie alebo zaneprázdnená služba odpovedí (`answers.engine_busy`). Počkajte čas uvedený v hlavičke `Retry-After`.

Hlavičky odpovede

  • Retry-After

    Počet sekúnd, ktoré treba počkať pred opakovaním požiadavky.

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, ktoré táto operácia môže vrátiť v error.code, okrem všeobecných kódov každej požiadavky.

Bezpečné opakovanie

S každou požiadavkou POST a PATCH odošlite hlavičku Idempotency-Key (napríklad UUID). Opakovaná požiadavka s rovnakým kľúčom do 24 hodín vráti uloženú odpoveď namiesto toho, aby sa požiadavka vykonala znova.

Limity frekvencie

Odpovede obsahujú hlavičky RateLimit a RateLimit-Policy a staršie X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpoveď 429 má hlavičku Retry-After v sekundách: počkajte a požiadavku zopakujte.

← answers · Referencia API