Μετάβαση στο περιεχόμενο
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).

Παράμετροι cookie

  • kb_view_asstring

    Cookie της λειτουργίας «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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

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

  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • verified_onlyboolean
  • cachedboolean
  • 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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

401Δεν στάλθηκαν διαπιστευτήρια (ούτε cookie συνεδρίας ούτε κλειδί 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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

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

    Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

Κωδικοί σφαλμάτων

Κωδικοί που μπορεί να επιστρέψει αυτό το τελικό σημείο στο 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