Przejdź do treści
Sursa Developers

POST/v1/chat

Strumieniowanie odpowiedzi asystenta (SSE)

chat

Przy kilku kopiach API za modułem równoważenia obciążenia (adres api.<domain>, 1.62.0) odpowiedź i bufor jej zdarzeń znajdują się w pamięci kopii, która ją generuje. Wznowienie strumienia z Last-Event-ID działa tylko na tej kopii.

Powtórzone żądanie z tym samym request_id i tą samą rozmową, które trafi do innej kopii po zakończeniu odpowiedzi, otrzymuje zapisaną odpowiedź (token i done, zdarzenia numerowane od 1) bez ponownego zadawania pytania. Powtórzone żądanie, które trafi do innej kopii, gdy odpowiedź jest jeszcze generowana, zatrzymuje to generowanie i buduje odpowiedź od nowa; drugie pytanie również nie powstaje. Aby wznowić strumień bez nowego generowania, utrzymuj połączenie z tą samą kopią lub powtórz żądanie po zdarzeniu done.

Uwierzytelnianie

Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.

Parametry nagłówka

  • X-View-Asstring

    Tylko dla kluczy API z rolą admin. Wykonuje żądanie jako profil dostępu <profile>[:viewer|verifier|editor], np. employee:viewer. Klucz instalacji nie może używać tego nagłówka (403).

Parametry cookie

  • kb_view_asstring

    Plik cookie trybu „View as” dla sesji. POST /auth/view-as go ustawia, a DELETE /auth/view-as usuwa.

Treść żądania

application/json

Obiekt: ChatRequest

  • messagesarray of ChatMessagewymagane

    items ≥ 1

  • collectionstring

    Domyślnie: "default"

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

    items ≤ 50

  • streamboolean

    Domyślnie: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Nie pobiera odpowiedzi z pamięci podręcznej odpowiedzi (przycisk „Get a fresh answer” pod odpowiedzią z pamięci podręcznej). Nowa odpowiedź zastępuje wpis w pamięci podręcznej.

    Domyślnie: false

  • languagestring | null

    Język odpowiedzi: kod ISO 639-1 (de, en, ru, …), aby odpowiedź była w tym języku. Przy auto lub bez pola język jest wykrywany na podstawie pytania. Interfejs jawnie przekazuje język podpowiedzi w innym języku (Starter.language).

  • scopeChatScope | null

    Zakres pytania: kilka kolekcji, źródło, tagi i okres. Kolekcje zakresu zastępują collection. Źródło zawęża odpowiedź do swojej kolekcji (i swoich kart). Tagi są dodawane do tags. Okres ogranicza odpowiedzi finansowe do tego okresu. Można wybrać tylko to, co widzi użytkownik (kolekcje: collections.no_access/collections.not_found; źródło: sources.not_found). Z conversation_id zakres jest zapisywany w rozmowie. Bez pola obowiązuje zakres rozmowy; null lub pusty zakres go czyści.

  • request_idstring

    Klucz idempotencji pytania. Wysyłaj ten sam klucz w każdym ponowieniu strumienia dla jednego pytania (ponowienie po rozłączeniu; tutaj Last-Event-ID nie kontynuuje strumienia i jest tylko zapisywany w dzienniku). Ponowienie z kluczem odpowiedzi, która jest już zapisana, nie tworzy drugiego pytania: zapisany wynik zostaje wysłany ponownie jako jedno zdarzenie done (i token z tekstem), nawet jeśli limit pytań lub kredytów jest wyczerpany. Jeśli poprzednia odpowiedź jest nadal generowana dla rozłączonego klienta, to generowanie się zatrzymuje, a odpowiedź jest generowana od nowa.

    length ≤ 64

  • version_ofinteger (int64)

    Tworzy nową wersję tury tego pytania w rozmowie (question_id z przebiegu rozmowy): zmienione pytanie (nowy tekst w messages), ponownie wygenerowaną odpowiedź (ten sam tekst, zwykle z bypass_cache) lub to samo pytanie z innym quality (np. precise po odpowiedzi fast). Poprzednia para pytania i odpowiedzi zostaje zachowana. Tury po niej pozostają w jej gałęzi i są ukryte w przebiegu rozmowy, dopóki wybrana jest nowa wersja (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Historia używana do odpowiedzi to wybrana gałąź aż do tej tury. quality wersji nie zmienia ustawień rozmowy. Wymaga conversation_id; pytanie z innej rozmowy zwraca 404 questions.not_found.

  • qualitystring

    Równowaga między szybkością a dokładnością wyszukiwania stojącego za wynikiem: fast jest szybszy, precise – dokładniejszy. Domyślnie: precise.

    Dozwolone wartości: fastprecise

Odpowiedzi

200Z `stream=true`: `text/event-stream`. Każde zdarzenie składa się z wierszy `id: <number>` (numer kolejny zdarzenia w strumieniu, od 1) i `data: <JSON>`, po których następuje pusty wiersz. Pola `event:` i `retry:` nie są używane; typ zdarzenia jest w polu `type` (`ChatEvent`).

Z stream=true: text/event-stream. Każde zdarzenie składa się z wierszy id: <number> (numer kolejny zdarzenia w strumieniu, od 1) i data: <JSON>, po których następuje pusty wiersz. Pola event: i retry: nie są używane; typ zdarzenia jest w polu type (ChatEvent).

Odpowiedź na pytanie z request_id powstaje niezależnie od połączenia. Rozłączenie nie zatrzymuje odpowiedzi: zostaje ona dokończona i zapisana w rozmowie (do 10 minut). Powtórzenie tego samego żądania (ten sam request_id i ta sama rozmowa) dołącza do trwającej odpowiedzi, a z nagłówkiem Last-Event-ID otrzymuje zdarzenia po tym numerze, więc strumień jest kontynuowany z tymi samymi numerami zdarzeń. Jeśli strumienia nie da się kontynuować od tego numeru, powtórzone żądanie otrzymuje strumień od początku: pierwsze zdarzenie ma wtedy numer nie większy niż Last-Event-ID, a klient zaczyna odpowiedź od nowa. Jeśli odpowiedź już się zakończyła, a bufor jej zdarzeń został zwolniony (po 3 minutach), zapisany wynik jest wysyłany ponownie (token i done, numerowane od 1) bez ponownego zadawania pytania; w przeciwnym razie odpowiedź jest generowana od nowa. Aby zatrzymać taką odpowiedź, wywołaj POST /v1/chat/cancel. Bez request_id rozłączenie klienta anuluje odpowiedź.

Po pierwszym zdarzeniu, dopóki odpowiedź trwa, serwer co 15 sekund wysyła komentarz : ping; pomiń go. Kolejność zdarzeń: zdarzenia stage (postęp), meta, sources, data, następnie tekst odpowiedzi w zdarzeniach token, a potem done. Przed tekstem odpowiedzi sources i data mogą się powtarzać i mogą pojawić się zdarzenia tool; tekst może przyjść jako jeden token lub w częściach. Odpowiedź z pamięci podręcznej: meta (z cached), sources, data, token, done. Błąd po rozpoczęciu strumienia przychodzi jako zdarzenie error, a strumień zamyka się bez done; status HTTP strumienia to zawsze 200. Po done może przyjść zdarzenie followups z propozycjami kolejnych pytań. Ignoruj typy zdarzeń, których nie obsługujesz.

Z stream=false: application/json z treścią AnswerResponse (oraz conversation_id).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

text/event-stream

Obiekt: ChatEvent

Jedno z

application/json

Obiekt: AnswerResponse

  • answerstringwymagane
  • question_idintegerwymagane
  • querystring
  • collectionstringwymagane
  • sourcesarray of Sourcewymagane
  • table_queriesarray of TableQuerywymagane
  • datasetsarray of Datasetwymagane
  • chartsarray of ChartSpecwymagane
  • warningsarray of AnswerWarningwymagane
  • timingsTimingswymagane
  • provenancearray of NumberProvenance
  • emptystring

    Dozwolone wartości: 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

    Dlaczego przy tej odpowiedzi użyto narzędzi: request (wprost o to poproszono); compare, compute, action (na podstawie pytania); needs_calc (potrzebne są obliczenia na tabelach); summary (przegląd kolekcji lub dokumentów); mcp (organizacja podłączyła zewnętrzne serwery MCP).

    Dozwolone wartości: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntitywymagane
  • followupsarray of Followupwymagane
  • conversation_idstring

    Tylko dla POST /v1/chat z rozmową.

  • answer_idstring

    ID obiektu odpowiedzi.

400Żądanie jest nieprawidłowe: wartość parametru lub stan obiektu nie pozwala na to działanie (`detail` zawiera komunikat).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

403Działanie jest niedozwolone: rola jest niewystarczająca, brak dostępu do kolekcji lub karty, żądanie jest wykonywane w trybie „View as” albo organizacja jest zawieszona lub usunięta (`detail` to obiekt z `code: org_suspended | org_deleted`).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

404Obiekt nie istnieje lub nie jest dla Ciebie dostępny. API nie potwierdza istnienia obiektu z ograniczonym dostępem.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

422Błąd walidacji: treść lub parametry nie odpowiadają schematowi (`detail` to lista błędów walidacji) albo wartość parametru jest poza zakresem (`detail` zawiera komunikat).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

429Zbyt wiele żądań (`api.rate_limited`), wyczerpano przydział organizacji na minutę, dzień lub miesiąc (`api.quota_exceeded`; `error.details` zawiera `quota`, `limit` i `reset_at`), osiągnięto limit organizacji albo usługa odpowiedzi jest zajęta (`answers.engine_busy`). Odczekaj czas podany w nagłówku `Retry-After`.

Nagłówki odpowiedzi

  • Retry-After

    Liczba sekund oczekiwania przed ponowieniem żądania.

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

Kody błędów

Kody, które ta operacja może zwrócić w error.code, oprócz ogólnych kodów każdego żądania.

Bezpieczne ponawianie

Wysyłaj nagłówek Idempotency-Key (na przykład UUID) z każdym żądaniem POST i PATCH. Ponowienie z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź, zamiast ponownie wykonywać żądanie.

Limity częstotliwości

Odpowiedzi zawierają nagłówki RateLimit i RateLimit-Policy oraz starsze X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź 429 ma nagłówek Retry-After w sekundach: odczekaj i ponów żądanie.

← answers · Dokumentacja API