Siirry sisältöön
Sursa Developers

POST/v1/chat

Vastaanota avustajan vastaus virtana (SSE)

chat

Kun kuormantasaajan takana on useita API-instansseja (api.<domain>-osoite, 1.62.0), vastaus ja sen tapahtumien puskuri ovat sen instanssin muistissa, joka muodostaa vastauksen. Virran jatkaminen Last-Event-ID-otsakkeella toimii vain tässä instanssissa.

Toistettu pyyntö samalla request_id-tunnuksella ja samassa keskustelussa, joka saapuu toiseen instanssiin vastauksen valmistuttua, saa tallennetun vastauksen (token ja done, tapahtumat numeroitu 1:stä alkaen) ilman, että kysymys esitetään uudelleen. Toistettu pyyntö, joka saapuu toiseen instanssiin vastauksen ollessa vielä muodostumassa, pysäyttää muodostamisen ja muodostaa vastauksen alusta; myöskään toista kysymystä ei luoda. Jotta voit jatkaa virtaa ilman uutta muodostamista, pidä yhteys samaan instanssiin tai toista pyyntö done-tapahtuman jälkeen.

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Otsakeparametrit

  • X-View-Asstring

    Vain API-avaimille, joilla on admin-rooli. Suorittaa pyynnön dataprofiilin <profile>[:viewer|verifier|editor] puolesta, esimerkiksi employee:viewer. Asennusavain ei voi käyttää tätä otsaketta (403).

Evästeparametrit

  • kb_view_asstring

    Istunnon ”View as” -tilan eväste. POST /auth/view-as asettaa sen ja DELETE /auth/view-as poistaa sen.

Pyynnön runko

application/json

Objekti: ChatRequest

  • messagesarray of ChatMessagepakollinen

    items ≥ 1

  • collectionstring

    Oletus: "default"

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

    items ≤ 50

  • streamboolean

    Oletus: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Älä ota vastausta vastausvälimuistista (välimuistissa olevan vastauksen alla oleva ”Get a fresh answer” -painike). Uusi vastaus korvaa välimuistissa olevan merkinnän.

    Oletus: false

  • languagestring | null

    Vastauksen kieli: ISO 639-1 -koodi (de, en, ru, …), jolla vastataan kyseisellä kielellä. Arvolla auto tai ilman kenttää kieli tunnistetaan kysymyksestä. Käyttöliittymä välittää toisenkielisen ehdotuksen kielen erikseen (Starter.language).

  • scopeChatScope | null

    Kysymyksen rajaus: useita kokoelmia, lähde, tunnisteet ja jakso. Rajauksen kokoelmat korvaavat collection-kentän. Lähde rajaa vastauksen lähteen kokoelmaan (ja sen omiin kortteihin). Tunnisteet lisätään tags-kenttään. Jakso rajaa taloutta koskevat vastaukset kyseiseen jaksoon. Valita voi vain sitä, minkä käyttäjä näkee (kokoelmat: collections.no_access/collections.not_found; lähde: sources.not_found). Kun mukana on conversation_id, rajaus tallennetaan keskusteluun. Ilman kenttää käytetään keskustelun rajausta; null tai tyhjä rajaus tyhjentää sen.

  • request_idstring

    Kysymyksen idempotenssiavain. Lähetä sama avain jokaisessa saman kysymyksen virran uusintayrityksessä (uusintayritys yhteyden katkettua; tässä Last-Event-ID ei jatka virtaa, vaan se vain kirjataan lokiin). Uusintayritys jo tallennetun vastauksen avaimella ei luo toista kysymystä: tallennettu tulos lähetetään uudelleen yhtenä done-tapahtumana (ja tekstin sisältävänä token-tapahtumana), vaikka kysymys- tai krediittiraja olisi käytetty loppuun. Jos edellistä vastausta muodostetaan vielä katkenneelle asiakkaalle, sen muodostaminen pysähtyy ja vastaus muodostetaan uudelleen.

    length ≤ 64

  • version_ofinteger (int64)

    Luo keskusteluun uuden version tämän kysymyksen vuorosta (question_id syötteestä): muokattu kysymys (uusi teksti messages-kentässä), uudelleen muodostettu vastaus (sama teksti, yleensä bypass_cache-kentän kanssa) tai sama kysymys toisella quality-arvolla (esimerkiksi precise fast-vastauksen jälkeen). Edellinen kysymyksen ja vastauksen pari säilyy. Sen jälkeiset vuorot jäävät sen haaraan ja piilotetaan syötteestä, kun uusi versio on valittuna (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Vastauksessa käytetty historia on valittu haara tähän vuoroon asti. Version quality ei muuta keskustelun asetuksia. Edellyttää conversation_id-kenttää; toisen keskustelun kysymys palauttaa 404 questions.not_found.

  • qualitystring

    Tuloksen taustalla olevan haun nopeuden ja tarkkuuden tasapaino: fast on nopeampi, precise tarkempi. Oletus: precise.

    Sallitut arvot: fastprecise

Vastaukset

200Kun `stream=true`: `text/event-stream`. Jokainen tapahtuma koostuu riveistä `id: <number>` (tapahtuman järjestysnumero virrassa, alkaen 1:stä) ja `data: <JSON>`, joita seuraa tyhjä rivi. Kenttiä `event:` ja `retry:` ei käytetä; tapahtuman tyyppi on `type`-kentässä (`ChatEvent`).

Kun stream=true: text/event-stream. Jokainen tapahtuma koostuu riveistä id: <number> (tapahtuman järjestysnumero virrassa, alkaen 1:stä) ja data: <JSON>, joita seuraa tyhjä rivi. Kenttiä event: ja retry: ei käytetä; tapahtuman tyyppi on type-kentässä (ChatEvent).

Kysymykseen, jolla on request_id, vastataan yhteydestä riippumatta. Yhteyden katkeaminen ei pysäytä vastausta: se viedään loppuun ja tallennetaan keskusteluun (enintään 10 minuutin ajan). Saman pyynnön toistaminen (sama request_id ja sama keskustelu) liittyy käynnissä olevaan vastaukseen, ja Last-Event-ID-otsakkeen kanssa se saa kyseisen numeron jälkeiset tapahtumat, joten virta jatkuu samoilla tapahtumanumeroilla. Jos virta ei voi jatkua kyseisestä numerosta, toistettu pyyntö saa virran alusta: ensimmäisen tapahtuman numero on silloin enintään Last-Event-ID, ja asiakasohjelma aloittaa vastauksen alusta. Jos vastaus on jo valmis ja sen tapahtumapuskuri on vapautettu (3 minuutin kuluttua), tallennettu tulos lähetetään uudelleen (token ja done, numeroitu 1:stä alkaen) ilman, että kysymys esitetään uudelleen; muuten vastaus muodostetaan alusta. Tällaisen vastauksen voi pysäyttää kutsulla POST /v1/chat/cancel. Ilman request_id-tunnusta asiakasohjelman yhteyden katkeaminen peruu vastauksen.

Ensimmäisen tapahtuman jälkeen, kun vastaus on käynnissä, palvelin lähettää : ping -kommentin 15 sekunnin välein; ohita se. Tapahtumien järjestys: stage-tapahtumat (edistyminen), meta, sources, data, sitten vastauksen teksti token-tapahtumissa ja lopuksi done. Ennen vastauksen tekstiä sources ja data voivat toistua ja tool-tapahtumia voi esiintyä; teksti voi saapua yhtenä token-tapahtumana tai osina. Välimuistista tuleva vastaus: meta (jossa cached), sources, data, token, done. Virran alkamisen jälkeinen virhe saapuu error-tapahtumana, ja virta sulkeutuu ilman done-tapahtumaa; virran HTTP-tila on aina 200. done-tapahtuman jälkeen voi saapua followups-tapahtuma, jossa on ehdotettuja seuraavia kysymyksiä. Ohita tapahtumatyypit, joita et käsittele.

Kun stream=false: application/json, jonka runko on AnswerResponse (ja lisäksi conversation_id).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

text/event-stream

Objekti: ChatEvent

Jokin seuraavista

application/json

Objekti: AnswerResponse

  • answerstringpakollinen
  • question_idintegerpakollinen
  • querystring
  • collectionstringpakollinen
  • sourcesarray of Sourcepakollinen
  • table_queriesarray of TableQuerypakollinen
  • datasetsarray of Datasetpakollinen
  • chartsarray of ChartSpecpakollinen
  • warningsarray of AnswerWarningpakollinen
  • timingsTimingspakollinen
  • provenancearray of NumberProvenance
  • emptystring

    Sallitut arvot: 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

    Miksi tähän vastaukseen käytettiin työkaluja: request (pyydettiin erikseen); compare, compute, action (kysymyksen perusteella); needs_calc (tarvitaan laskentaa taulukoista); summary (yleiskatsaus kokoelmaan tai asiakirjoihin); mcp (organisaatio on yhdistänyt ulkoisia MCP-palvelimia).

    Sallitut arvot: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntitypakollinen
  • followupsarray of Followuppakollinen
  • conversation_idstring

    Vain POST /v1/chat-toiminnossa keskustelun kanssa.

  • answer_idstring

    Vastausobjektin tunnus.

400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

404Objektia ei ole tai se ei ole saatavillasi. API ei paljasta, onko rajoitettu objekti olemassa.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

  • Retry-After

    Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← answers · API-viite