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
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 (
deenru…) เพื่อให้ตอบเป็นภาษานั้น เมื่อเป็น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_foundqualitystringความสมดุลระหว่างความเร็วและความแม่นยำของการค้นหาที่อยู่เบื้องหลังผลลัพธ์:
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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
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(ขออย่างชัดเจน)comparecomputeและ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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>X-RateLimit-Limitขีดจำกัดของรายการที่เข้มงวดที่สุดใน
RateLimit-Policy(รายการที่เหลือคำขอน้อยที่สุด)X-RateLimit-Remainingจำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด
X-RateLimit-Resetจำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต
application/json
401ไม่ได้ส่งข้อมูลรับรอง (ไม่มีทั้งคุกกี้เซสชันและคีย์ API) หรือไม่พบคีย์
เฮดเดอร์การตอบกลับ
RateLimit-Policyขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF
draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค"<name>";q=<quota>;w=<window in seconds>โดยkeyคืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือuserและเมื่อไม่มีข้อมูลรับรองคือip) ส่วนminutedayและmonthคือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTCRateLimitส่วนที่เหลือของแต่ละขีดจำกัดใน
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 ชั่วโมง Sursa จะส่งคืนการตอบกลับที่บันทึกไว้แทนการดำเนินการคำขอซ้ำ
ขีดจำกัดอัตราการเรียก
การตอบกลับมีเฮดเดอร์ RateLimit และ RateLimit-Policy รวมถึงเฮดเดอร์แบบเดิม X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset การตอบกลับ 429 มี Retry-After เป็นวินาที ให้รอตามนั้นแล้วลองใหม่