Към съдържанието
Sursa Developers

POST/v1/chat

Поток с отговора на асистента (SSE)

chat

При няколко екземпляра на API зад балансьор на натоварването (адресът api.<domain>, 1.62.0) отговорът и буферът на събитията му се намират в паметта на екземпляра, който го генерира. Възобновяването на потока с Last-Event-ID работи само на този екземпляр.

Повторна заявка със същите request_id и разговор, която стигне до друг екземпляр, след като отговорът е завършил, получава записания отговор (token и done, събития с номера от 1), без въпросът да се задава отново. Повторна заявка, която стигне до друг екземпляр, докато отговорът все още се генерира, спира това генериране и изгражда отговора наново; втори въпрос също не се създава. За да възобновите потока без ново генериране, запазете връзката към същия екземпляр или повторете заявката след събитието done.

Удостоверяване

Изпратете API ключ в заглавката Authorization: Authorization: Bearer <ключ>.

Параметри в заглавката

  • X-View-Asstring

    Само за API ключове с ролята admin. Изпълнява заявката от името на профила за достъп <profile>[:viewer|verifier|editor], например employee:viewer. Ключът на инсталацията не може да използва тази заглавка (403).

Параметри в бисквитка

  • kb_view_asstring

    Бисквитка на режима „View as“ за сесия. POST /auth/view-as я задава, а DELETE /auth/view-as я изчиства.

Тяло на заявката

application/json

Обект: ChatRequest

  • messagesarray of ChatMessageзадължително

    items ≥ 1

  • collectionstring

    По подразбиране: "default"

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

    items ≤ 50

  • streamboolean

    По подразбиране: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Не взема отговора от кеша на отговорите (бутонът „Get a fresh answer“ под кеширан отговор). Новият отговор заменя кеширания запис.

    По подразбиране: false

  • languagestring | null

    Език на отговора: код по ISO 639-1 (de, en, ru, …), за да се отговори на този език. При auto или без полето езикът се определя по въпроса. Интерфейсът подава изрично езика на предложение на друг език (Starter.language).

  • scopeChatScope | null

    Обхват на въпроса: няколко колекции, източник, етикети и период. Колекциите от обхвата заменят collection. Източник стеснява отговора до своята колекция (и собствените си карти). Етикетите се добавят към tags. Периодът ограничава финансовите отговори до този период. Можете да изберете само това, което потребителят вижда (колекции: collections.no_access/collections.not_found; източник: sources.not_found). С conversation_id обхватът се записва в разговора. Без полето се прилага обхватът на разговора; null или празен обхват го изчиства.

  • request_idstring

    Ключ за идемпотентност на въпроса. Изпращайте един и същ ключ при всеки повторен опит за потока на един въпрос (повторен опит след прекъсване на връзката; тук Last-Event-ID не продължава потока и само се записва в журнала). Повторен опит с ключа на вече записан отговор не създава втори въпрос: записаният резултат се изпраща отново като едно събитие done (и token с текста), дори ако лимитът на въпросите или на кредитите е изчерпан. Ако предишният отговор още се генерира за клиент с прекъсната връзка, генерирането спира и отговорът се генерира наново.

    length ≤ 64

  • version_ofinteger (int64)

    Създава нова версия на репликата с този въпрос в разговора (question_id от историята на разговора): редактиран въпрос (нов текст в messages), повторно генериран отговор (същият текст, обикновено с bypass_cache) или същият въпрос с друго quality (например precise след отговор fast). Предишната двойка въпрос–отговор се запазва. Репликите след нея остават в нейния клон и са скрити от историята, докато е избрана новата версия (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Предишните реплики, които се вземат предвид за отговора, са избраният клон до тази реплика. quality на една версия не променя настройките на разговора. Изисква conversation_id; въпрос от друг разговор връща 404 questions.not_found.

  • qualitystring

    Баланс между скорост и точност на търсенето, на което се основава резултатът: fast е по-бързо, precise е по-точно. По подразбиране: precise.

    Допустими стойности: fastprecise

Отговори

200При `stream=true`: `text/event-stream`. Всяко събитие се състои от редовете `id: <number>` (поредният номер на събитието в потока, започвайки от 1) и `data: <JSON>`, последвани от празен ред. Полетата `event:` и `retry:` не се използват; типът на събитието е в полето `type` (`ChatEvent`).

При stream=true: text/event-stream. Всяко събитие се състои от редовете id: <number> (поредният номер на събитието в потока, започвайки от 1) и data: <JSON>, последвани от празен ред. Полетата event: и retry: не се използват; типът на събитието е в полето type (ChatEvent).

На въпрос с request_id се отговаря независимо от връзката. Прекъсването на връзката не спира отговора: той се довършва и се записва в разговора (до 10 минути). Повтарянето на същата заявка (същите request_id и разговор) се присъединява към отговора в ход, а със заглавката Last-Event-ID получава събитията след този номер, така че потокът продължава със същите номера на събитията. Ако потокът не може да продължи от този номер, повторната заявка получава потока от началото: тогава първото събитие има номер, не по-голям от Last-Event-ID, и клиентът започва отговора отначало. Ако отговорът вече е завършил и буферът на събитията му е освободен (след 3 минути), записаният резултат се изпраща отново (token и done, с номера от 1), без въпросът да се задава отново; иначе отговорът се генерира наново. За да спрете такъв отговор, извикайте POST /v1/chat/cancel. Без request_id прекъсването на връзката от клиента отменя отговора.

След първото събитие, докато отговорът е в ход, сървърът изпраща коментар : ping на всеки 15 секунди; пропускайте го. Ред на събитията: събития stage (напредък), meta, sources, data, след това текстът на отговора в събития token, след това done. Преди текста на отговора sources и data могат да се повтарят и могат да се появят събития tool; текстът може да пристигне като един token или на части. Отговор от кеша: meta (с cached), sources, data, token, done. Грешка след началото на потока пристига като събитие error и потокът се затваря без done; HTTP статусът на потока винаги е 200. След done може да пристигне събитие followups с предложени следващи въпроси. Пренебрегвайте типовете събития, които не обработвате.

При stream=false: application/json с тяло AnswerResponse (плюс conversation_id).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

text/event-stream

Обект: ChatEvent

Едно от

application/json

Обект: AnswerResponse

  • answerstringзадължително
  • question_idintegerзадължително
  • querystring
  • collectionstringзадължително
  • sourcesarray of Sourceзадължително
  • table_queriesarray of TableQueryзадължително
  • datasetsarray of Datasetзадължително
  • chartsarray of ChartSpecзадължително
  • warningsarray of AnswerWarningзадължително
  • timingsTimingsзадължително
  • provenancearray of NumberProvenance
  • emptystring

    Допустими стойности: 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

    Защо за този отговор са използвани инструменти: request (поискано изрично); compare, compute, action (според въпроса); needs_calc (нужно е изчисление по таблици); summary (преглед на колекция или документи); mcp (организацията е свързала външни MCP сървъри).

    Допустими стойности: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityзадължително
  • followupsarray of Followupзадължително
  • conversation_idstring

    Само за POST /v1/chat с разговор.

  • answer_idstring

    ID на обекта на отговора.

400Заявката е невалидна: стойност на параметър или състоянието на обекта не позволява действието (`detail` е съобщение).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

401Не са изпратени идентификационни данни (нито бисквитка на сесията, нито API ключ) или ключът не е намерен.

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

403Действието не е разрешено: ролята е недостатъчна, няма достъп до колекцията или картата, заявката се изпълнява в режим „View as“ или организацията е спряна или изтрита (`detail` е обект с `code: org_suspended | org_deleted`).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

404Обектът не съществува или не е достъпен за вас. API не потвърждава, че съществува обект с ограничен достъп.

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

422Грешка при валидиране: тялото или параметрите не съответстват на схемата (`detail` е списък с грешки при валидиране) или стойност на параметър е извън допустимия диапазон (`detail` е съобщение).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

429Твърде много заявки (`api.rate_limited`), квотата на организацията за минутата, деня или месеца е изчерпана (`api.quota_exceeded`; `error.details` съдържа `quota`, `limit` и `reset_at`), достигнат е лимит на организацията или услугата за отговори е заета (`answers.engine_busy`). Изчакайте времето от заглавката `Retry-After`.

Заглавки на отговора

  • Retry-After

    Брой секунди, които да изчакате, преди да повторите заявката.

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

Кодове на грешки

Кодове, които тази операция може да върне в error.code, освен общите кодове на всяка заявка.

Безопасни повторни опити

Изпращайте заглавката Idempotency-Key (например UUID) с всяка заявка POST и PATCH. Повторен опит със същия ключ в рамките на 24 часа връща запазения отговор, вместо да изпълни заявката отново.

Лимити на честотата

Отговорите съдържат заглавките RateLimit и RateLimit-Policy, както и по-ранните X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Отговорът 429 съдържа Retry-After в секунди: изчакайте и опитайте отново.

← answers · Справочник на API