Пређите на садржај
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 прекид везе клијента отказује одговор.

После првог догађаја, док је одговор у току, сервер на сваких 15 секунди шаље коментар : ping; прескочите га. Редослед догађаја: догађаји 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, поред општих кодова сваког захтева.

Безбедни поновни покушаји

Уз сваки POST и PATCH захтев пошаљите заглавље Idempotency-Key (на пример UUID). Поновни покушај са истим кључем у року од 24 сата враћа сачувани одговор уместо да поново изврши захтев.

Ограничења учесталости

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

← answers · API референца