Přejít na obsah
Sursa Developers

POST/v1/chat

Streamovat odpověď asistenta (SSE)

chat

Při několika kopiích API za nástrojem pro vyrovnávání zátěže (adresa api.<domain>, 1.62.0) se odpověď a vyrovnávací paměť jejích událostí nacházejí v paměti té kopie, která odpověď generuje. Obnovení streamu pomocí Last-Event-ID funguje jen na této kopii.

Opakovaný požadavek se stejným request_id a konverzací, který po dokončení odpovědi dorazí na jinou kopii, dostane uloženou odpověď (token a done, události číslované od 1), aniž by se otázka pokládala znovu. Opakovaný požadavek, který dorazí na jinou kopii, zatímco se odpověď ještě generuje, toto generování zastaví a sestaví odpověď znovu; ani v tom případě nevznikne druhá otázka. Chcete-li stream obnovit bez nového generování, udržujte spojení se stejnou kopií, nebo požadavek zopakujte po události done.

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry hlavičky

  • X-View-Asstring

    Jen pro klíče API s rolí admin. Provede požadavek jako datový profil <profile>[:viewer|verifier|editor], například employee:viewer. Instalační klíč tuto hlavičku použít nemůže (403).

Parametry cookie

  • kb_view_asstring

    Cookie režimu „View as“ pro relaci. POST /auth/view-as ji nastaví a DELETE /auth/view-as ji smaže.

Tělo požadavku

application/json

Objekt: ChatRequest

  • messagesarray of ChatMessagepovinné

    items ≥ 1

  • collectionstring

    Výchozí: "default"

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

    items ≤ 50

  • streamboolean

    Výchozí: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Nebrat odpověď z mezipaměti odpovědí (tlačítko „Get a fresh answer“ pod odpovědí z mezipaměti). Nová odpověď nahradí záznam v mezipaměti.

    Výchozí: false

  • languagestring | null

    Jazyk odpovědi: kód ISO 639-1 (de, en, ru, …), aby odpověď byla v tomto jazyce. S auto nebo bez tohoto pole se jazyk určí podle otázky. Rozhraní předává jazyk návrhu v jiném jazyce výslovně (Starter.language).

  • scopeChatScope | null

    Rozsah otázky: několik kolekcí, zdroj, štítky a období. Kolekce z rozsahu nahrazují collection. Zdroj zúží odpověď na svou kolekci (a své vlastní karty). Štítky se přidají k tags. Období omezí finanční odpovědi na toto období. Vybrat lze jen to, co uživatel vidí (kolekce: collections.no_access/collections.not_found; zdroj: sources.not_found). S conversation_id se rozsah uloží do konverzace. Bez tohoto pole platí rozsah konverzace; null nebo prázdný rozsah ho vymaže.

  • request_idstring

    Klíč idempotence otázky. Stejný klíč posílejte při každém opakování streamu pro jednu otázku (opakování po odpojení; Last-Event-ID zde stream nenavazuje a jen se zaprotokoluje). Opakování s klíčem odpovědi, která už je uložená, nevytvoří druhou otázku: uložený výsledek se odešle znovu jako jedna událost done (a token s textem), i když je vyčerpaný limit otázek nebo kreditů. Pokud se předchozí odpověď pro odpojeného klienta ještě generuje, generování se zastaví a odpověď se vygeneruje znovu.

    length ≤ 64

  • version_ofinteger (int64)

    Vytvoří novou verzi kola této otázky v konverzaci (question_id z průběhu konverzace): upravenou otázku (nový text v messages), znovu vygenerovanou odpověď (stejný text, obvykle s bypass_cache) nebo stejnou otázku s jinou hodnotou quality (například precise po odpovědi fast). Předchozí dvojice otázky a odpovědi se zachová. Kola po ní zůstávají v její větvi a jsou skrytá v průběhu konverzace, dokud je vybraná nová verze (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Historie použitá pro odpověď je vybraná větev až po toto kolo. quality verze nemění nastavení konverzace. Vyžaduje conversation_id; otázka z jiné konverzace vrací 404 questions.not_found.

  • qualitystring

    Poměr mezi rychlostí a přesností vyhledávání, ze kterého výsledek vychází: fast je rychlejší, precise přesnější. Výchozí: precise.

    Povolené hodnoty: fastprecise

Odpovědi

200Se `stream=true`: `text/event-stream`. Každá událost se skládá z řádků `id: <number>` (pořadové číslo události ve streamu, od 1) a `data: <JSON>`, za nimiž následuje prázdný řádek. Pole `event:` a `retry:` se nepoužívají; typ události je v poli `type` (`ChatEvent`).

Se stream=true: text/event-stream. Každá událost se skládá z řádků id: <number> (pořadové číslo události ve streamu, od 1) a data: <JSON>, za nimiž následuje prázdný řádek. Pole event: a retry: se nepoužívají; typ události je v poli type (ChatEvent).

Na otázku s request_id se odpovídá nezávisle na spojení. Odpojení odpověď nezastaví: dokončí se a uloží do konverzace (nejdéle po dobu 10 minut). Opakování stejného požadavku (stejné request_id a konverzace) se připojí k probíhající odpovědi a s hlavičkou Last-Event-ID dostane události po tomto čísle, takže stream pokračuje se stejnými čísly událostí. Pokud stream nemůže od tohoto čísla pokračovat, opakovaný požadavek dostane stream od začátku: první událost pak má číslo nejvýše rovné Last-Event-ID a klient začne odpověď skládat od začátku. Pokud odpověď už skončila a vyrovnávací paměť jejích událostí byla uvolněna (po 3 minutách), uložený výsledek se odešle znovu (token a done, číslované od 1), aniž by se otázka pokládala znovu; jinak se odpověď vygeneruje znovu. Chcete-li takovou odpověď zastavit, zavolejte POST /v1/chat/cancel. Bez request_id odpojení klienta odpověď zruší.

Po první události, dokud odpověď probíhá, server každých 15 sekund odešle komentář : ping; přeskočte ho. Pořadí událostí: události stage (průběh), meta, sources, data, pak text odpovědi v událostech token, pak done. Před textem odpovědi se sources a data mohou opakovat a mohou se objevit události tool; text může přijít jako jeden token nebo po částech. Odpověď z mezipaměti: meta (s cached), sources, data, token, done. Chyba po zahájení streamu přijde jako událost error a stream se uzavře bez done; stavový kód HTTP streamu je vždy 200. Po done může přijít událost followups s navrhovanými dalšími otázkami. Typy událostí, které nezpracováváte, ignorujte.

Se stream=false: application/json s tělem AnswerResponse (a navíc conversation_id).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího 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

    Proč byly pro tuto odpověď použity nástroje: request (výslovně vyžádáno); compare, compute, action (podle otázky); needs_calc (je potřeba výpočet nad tabulkami); summary (přehled kolekce nebo dokumentů); mcp (organizace připojila 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

    Jen pro POST /v1/chat s konverzací.

  • answer_idstring

    ID objektu odpovědi.

400Požadavek je neplatný: hodnota parametru nebo stav objektu akci neumožňuje (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

404Objekt neexistuje nebo vám není dostupný. API nepotvrzuje, že objekt s omezeným přístupem existuje.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← answers · Reference API