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_asstringCookie της λειτουργίας «View as» για μια συνεδρία. Το
POST /auth/view-asτο ορίζει και τοDELETE /auth/view-asτο καταργεί.
Σώμα αιτήματος
application/json
items ≥ 1
collectionstringΠροεπιλογή: "default"
tagsarray of string | nullexportstring | nullcard_idsarray of string | nullitems ≤ 50
streambooleanΠροεπιλογή: false
conversation_idstring | nulllength ≤ 64
originstring | nulltoolsboolean | nullbypass_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
application/json
answerstringυποχρεωτικόquestion_idintegerυποχρεωτικόquerystringcollectionstringυποχρεωτικόprovenancearray of NumberProvenanceemptystringΕπιτρεπόμενες τιμές:
no_hitsrestrictedguardrailno_data_for_periodbasisAnswerBasisverificationAnswerVerificationalt_periodsarray of AnswerAltPerioditems ≤ 6
drilldownarray of AnswerDrilldownitems ≤ 20
restrictedRestrictedInfoguardrailGuardrailVerdictverified_onlybooleancachedbooleancache_hitAnswerCacheHitout_of_scopeAnswerOutOfScopeattachmentsarray of Attachmentexport_errorstringtoolsstring | nullΓιατί χρησιμοποιήθηκαν εργαλεία για αυτή την απάντηση:
request(ζητήθηκε ρητά)·compare,compute,action(με βάση την ερώτηση)·needs_calc(χρειάζεται υπολογισμός σε πίνακες)·summary(επισκόπηση μιας συλλογής ή εγγράφων)·mcp(ο οργανισμός έχει συνδέσει εξωτερικούς διακομιστές MCP).Επιτρεπόμενες τιμές:
requestcomparecomputeactionneeds_calcsummarymcpnulltool_callsarray of ToolCallInfocalculationsarray of Calculationpending_actionsarray of PendingActionconversation_idstringΜόνο για
POST /v1/chatμε συνομιλία.answer_idstringID του αντικειμένου της απάντησης.
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
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Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
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
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
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
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.code, εκτός από τους γενικούς κωδικούς κάθε αιτήματος.
- 400answers.empty_question
- 409answers.external_ai_disabled
- 400answers.last_message_not_user
- 404answers.no_collections
- 422answers.scope_invalid
- 401auth.not_authenticated
- 403auth.system_scope
- 403collections.no_access
- 404collections.not_found
- 404conversations.not_found
- 422conversations.title_empty
- 429limits.concurrent_answers
- 429limits.questions
- 403org.deleted
- 403org.suspended
- 404sources.not_found
- 403view_as.read_only
Ασφαλείς επαναλήψεις
Στείλτε μια κεφαλίδα Idempotency-Key (για παράδειγμα ένα UUID) με κάθε POST και PATCH. Μια επανάληψη με το ίδιο κλειδί εντός 24 ωρών επιστρέφει την αποθηκευμένη απόκριση αντί να εκτελέσει ξανά το αίτημα.
Όρια ρυθμού
Οι αποκρίσεις περιέχουν τις κεφαλίδες RateLimit και RateLimit-Policy, καθώς και τις παλαιότερες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Μια απόκριση 429 έχει την κεφαλίδα Retry-After σε δευτερόλεπτα: περιμένετε και επαναλάβετε το αίτημα.