logo
การพัฒนา
ภาพรวมพื้นที่นักพัฒนาพื้นที่ทำงานเอกสาร APIแนวปฏิบัติที่ดีบันทึกการเปลี่ยนแปลง
ค้นหา
ภาษาไทย
เอกสาร API / ความรู้ API / ซิงค์ฐานความรู้ทันที
ซิงค์ฐานความรู้ทันที
อัปเดตล่าสุด：ใน ประมาณ 4 ชั่วโมง

ซิงค์ฐานความรู้ทันที

สามารถทริกเกอร์การซิงค์แบบเพิ่มขึ้น (incremental) ของความรู้ที่มีแหล่งที่มา ในฐานความรู้ได้ทันที ปัจจุบันรองรับเฉพาะแหล่งที่มาจาก Google Drive เท่านั้น

หมายเหตุ:

อินเทอร์เฟซจะคืนค่าทันทีหลังจากทำการตรวจสอบและวางแผนเสร็จ ดังนั้นค่าที่คืนกลับมาคือ "ได้รับเรื่องแล้ว" ไม่ใช่ "อัปเดตแล้ว"

ข้อจำกัดความถี่: แต่ละ Agent / Workflow เรียกได้สูงสุด 1 ครั้งต่อนาที

วิธีการร้องขอ

POST

URL สำหรับร้องขอ

เลือก path ที่สอดคล้องกันตามประเภททรัพยากรที่ API Key สังกัดอยู่ ทั้งสองอินเทอร์เฟซมีพารามิเตอร์การร้องขอ, โครงสร้างการตอบกลับ และกฎการจำกัดอัตราเหมือนกันทุกประการ

  • Agent:

https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync

  • Workflow:

https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync

คำอธิบายการร้องขอ / การตอบกลับด้านล่างใช้ได้กับทั้งสอง path พร้อมกัน โดยตัวอย่างเขียนด้วย path ของ Agent

การยืนยันตัวตนในการร้องขอ

ดูรายละเอียดได้ที่คำอธิบายวิธีการยืนยันตัวตนใน API Overview

การร้องขอ

ตัวอย่างการร้องขอ

  • ซิงค์ฐานความรู้ที่ระบุ:
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "source": "google-drive", "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"] }'
                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive",
    "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'
บล็อกโค้ดนี้ในหน้าต่างลอย
  • ซิงค์ฐานความรู้ทั้งหมดภายใต้ Agent นี้:
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "source": "google-drive" }'
                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive"
}'
บล็อกโค้ดนี้ในหน้าต่างลอย

Header สำหรับร้องขอ

ฟิลด์ ประเภท คำอธิบาย
Authorization Bearer ${API Key} ใช้ Authorization: Bearer ${API Key} ในการยืนยันตัวตน โปรดรับคีย์จากหน้า API Key เพื่อใช้เป็น API Key
Content-Type application/json ประเภทข้อมูล ค่าเป็น application/json

พารามิเตอร์การร้องขอ

ฟิลด์ ประเภท บังคับ คำอธิบาย
source String ใช่ ประเภทแหล่งที่มา ปัจจุบันรองรับเฉพาะ google-drive เท่านั้น หากส่งค่าอื่นจะคืนข้อผิดพลาดพารามิเตอร์
knowledge_base_ids Array<String> ไม่ รายการ ID ของฐานความรู้เป้าหมาย สูงสุด 200 รายการ หากเกินจะคืนข้อผิดพลาดพารามิเตอร์ หากไม่ส่ง, ส่ง null หรือส่งอาร์เรย์ว่าง หมายถึงฐานความรู้ทั้งหมดภายใต้ Agent / Workflow นั้น ID ในรายการที่ไม่มีอยู่หรือไม่ได้เป็นของ Agent / Workflow ปัจจุบันจะไม่ทำให้ทั้งคำขอล้มเหลว แต่จะปรากฏใน skipped

การตอบกลับ

ตัวอย่างการตอบกลับ

{ "code": 0, "message": "OK", "data": { "accepted": true, "source": "google-drive", "matched_knowledge_base_count": 2, "matched_doc_count": 37, "matched_folder_count": 3, "skipped": [ { "reason": "DRIVE_NOT_AUTHORIZED", "message": "The document owner has not authorized Google Drive, or the authorization has expired.", "knowledge_base_id": "6a44c3512ceb43775567391e", "doc_count": 8 }, { "reason": "KNOWLEDGE_BASE_NOT_FOUND", "message": "Knowledge base does not exist or does not belong to this agent.", "knowledge_base_id": "deadbeefdeadbeefdeadbeef" } ], "scheduled_round_running": false } }
                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "accepted": true,
        "source": "google-drive",
        "matched_knowledge_base_count": 2,
        "matched_doc_count": 37,
        "matched_folder_count": 3,
        "skipped": [
            {
                "reason": "DRIVE_NOT_AUTHORIZED",
                "message": "The document owner has not authorized Google Drive, or the authorization has expired.",
                "knowledge_base_id": "6a44c3512ceb43775567391e",
                "doc_count": 8
            },
            {
                "reason": "KNOWLEDGE_BASE_NOT_FOUND",
                "message": "Knowledge base does not exist or does not belong to this agent.",
                "knowledge_base_id": "deadbeefdeadbeefdeadbeef"
            }
        ],
        "scheduled_round_running": false
    }
}
บล็อกโค้ดนี้ในหน้าต่างลอย

การตอบกลับเมื่อสำเร็จ

ฟิลด์ ประเภท คำอธิบาย
code Integer รหัสการตอบกลับ 0 หมายถึงสำเร็จ
message String ข้อความตอบกลับ
data Object ผลการรับเรื่อง
accepted Boolean ได้รับเรื่องแล้วหรือไม่ false หมายถึงครั้งนี้ไม่ได้เริ่มอะไรเลย ดูสาเหตุได้ที่ skipped
source String ประเภทแหล่งที่มาของการซิงค์ครั้งนี้
matched_knowledge_base_count Integer จำนวนฐานความรู้ที่ตรงกันในครั้งนี้
matched_doc_count Integer จำนวนเอกสารความรู้ที่จะตรวจสอบในครั้งนี้ โปรดสังเกตว่าเป็น "จะตรวจสอบ" ไม่ใช่ "อัปเดตแล้ว"
matched_folder_count Integer จำนวนแหล่งที่มาแบบโฟลเดอร์ที่จะตรวจสอบไฟล์ใหม่ในครั้งนี้
skipped Array<Object> รายละเอียดที่ถูกข้าม จัดกลุ่มตาม "ฐานความรู้ + สาเหตุ" ไม่แจกแจงเป็นรายเอกสาร
reason String สาเหตุการข้าม ดูค่าที่เป็นไปได้ในตารางด้านล่าง
message String คำอธิบายสาเหตุ
knowledge_base_id String ID ของฐานความรู้ที่ได้รับผลกระทบ กรณีสาเหตุระดับรวม (เช่น ยอดคงเหลือไม่พอ) จะไม่คืนฟิลด์นี้
doc_count Integer จำนวนเอกสารที่ได้รับผลกระทบ เมื่อข้ามทั้งฐานความรู้จะไม่คืนฟิลด์นี้
scheduled_round_running Boolean รอบการซิงค์ตามกำหนดเวลาของระบบกำลังทำงานอยู่หรือไม่ เป็นเพียงการแจ้งให้ทราบ ไม่มีผลต่อการรับเรื่องครั้งนี้ เมื่อ accepted เป็น false ครั้งนี้จะไม่ได้ทำการตัดสินนี้ และคืนค่า null

ค่าของ skipped[].reason

ค่า ความหมาย คำแนะนำการจัดการ
KNOWLEDGE_BASE_NOT_FOUND ฐานความรู้ไม่มีอยู่ หรือไม่ได้เป็นของ Agent / Workflow ที่ API Key ปัจจุบันผูกไว้ ตรวจสอบ knowledge_base_ids สามารถเรียก "รายการฐานความรู้" เพื่อยืนยันก่อนได้
NO_GOOGLE_DRIVE_SOURCE ฐานความรู้มีอยู่ แต่ไม่มีเอกสารใดที่มาจาก Google Drive เป็นสถานการณ์ปกติ แสดงว่าฐานความรู้นี้ไม่จำเป็นต้องซิงค์
DRIVE_NOT_AUTHORIZED สมาชิกที่เป็นเจ้าของเอกสารไม่มีการอนุญาต Google Drive ที่ใช้ได้ (ไม่เคยอนุญาต หรือการอนุญาตหมดอายุแล้ว) ให้สมาชิกดังกล่าวอนุญาต Google Drive ใหม่อีกครั้ง
DOC_IN_PROGRESS เอกสารกำลังประมวลผลอยู่ ส่วนใหญ่เป็นเพราะรอบตามกำหนดเวลาหรือการซิงค์ครั้งก่อนยังไม่เสร็จ ลองใหม่ภายหลัง หรือรอให้การประมวลผลเสร็จ
DOC_NO_OWNER เอกสารขาดข้อมูลสมาชิกเจ้าของ ไม่สามารถระบุได้ว่าจะใช้การอนุญาต Google Drive ของใคร ต้องติดต่อฝ่ายสนับสนุนเพื่อตรวจสอบเอกสารนี้
INSUFFICIENT_BALANCE ยอดคงเหลือขององค์กรไม่เพียงพอ ในกรณีนี้ accepted เป็น false และจะไม่เริ่มการซิงค์ใด ๆ ลองใหม่หลังจากเติมเงิน
SYNC_IN_PROGRESS การซิงค์ด้วยตนเองครั้งก่อนของ Agent / Workflow นี้ยังทำงานอยู่ ในกรณีนี้ accepted เป็น false รอให้ครั้งก่อนเสร็จแล้วลองใหม่

การตอบกลับเมื่อผิดพลาด

ฟิลด์ ประเภท คำอธิบาย
code Integer รหัสข้อผิดพลาด
message String รายละเอียดข้อผิดพลาด

รหัสข้อผิดพลาดที่พบบ่อย:

HTTP code สถานการณ์
400 40000 source ขาดหายไปหรือไม่รองรับ; knowledge_base_ids เกิน 200 รายการ; จำนวนเอกสารที่ตรงกันในครั้งเดียวเกิน 5000 (ต้องใช้ knowledge_base_ids เพื่อจำกัดขอบเขต)
400 40001 ทริกเกอร์บ่อยเกินไป เกินการจำกัดอัตราของอินเทอร์เฟซ
401 40101 ขาด Header Authorization
401 40127 API Key ไม่ถูกต้อง

ตัวอย่างการตอบกลับเมื่อ source ไม่ถูกต้อง:

{ "code": 40000, "message": "Unsupported source: sharepoint. Supported: google-drive" }
                      
                      {
    "code": 40000,
    "message": "Unsupported source: sharepoint. Supported: google-drive"
}
บล็อกโค้ดนี้ในหน้าต่างลอย

คำอธิบายการใช้งาน

ค่าที่คืนกลับคือ "ได้รับเรื่องแล้ว" ไม่ใช่ "เสร็จสิ้นแล้ว"

อินเทอร์เฟซจะคืนค่าทันทีหลังจากทำการตรวจสอบและวางแผนเสร็จ ส่วนการดึง, แยกวิเคราะห์ และแปลงเป็นเวกเตอร์จริง ๆ จะทำงานแบบอะซิงโครนัสในเบื้องหลัง ดังนั้น matched_doc_count คือ "ครั้งนี้จะตรวจสอบเอกสารกี่ฉบับ" ไม่ใช่ "อัปเดตเอกสารไปกี่ฉบับ" หากต้องการยืนยันผลลัพธ์สุดท้าย โปรด poll อินเทอร์เฟซรายการเอกสาร เพื่อดูสถานะเอกสาร เมื่อสถานะเอกสารเปลี่ยนเป็น AVAILABLE แสดงว่าเอกสารนั้นซิงค์เสร็จแล้ว

ทำเฉพาะแบบเพิ่มขึ้นเท่านั้น จะไม่กินโควตาซ้ำ

สำหรับเอกสารแต่ละฉบับ ระบบจะเปรียบเทียบเวลาแก้ไขล่าสุดบน Google Drive ก่อน:

  • เอกสารต้นทางไม่มีการเปลี่ยนแปลง: ข้าม ไม่ดาวน์โหลดใหม่ ไม่แยกวิเคราะห์ใหม่ และไม่กินโควตา
  • เอกสารต้นทางมีการเปลี่ยนแปลง: ดึงใหม่แล้วแยกวิเคราะห์และแปลงเป็นเวกเตอร์ใหม่
  • โฟลเดอร์ที่ผูกไว้มีไฟล์ใหม่: จะเพิ่มเป็นเอกสารความรู้โดยอัตโนมัติ

ดังนั้นการเรียกอินเทอร์เฟซนี้ซ้ำจึงปลอดภัย เนื้อหาที่ไม่เปลี่ยนแปลงจะไม่ก่อให้เกิดค่าใช้จ่ายเพิ่มเติม

อินเทอร์เฟซนี้ไม่สามารถลองแยกวิเคราะห์เอกสารที่ล้มเหลวใหม่ได้

การตัดสินแบบเพิ่มขึ้นจะดูเฉพาะว่าเอกสารต้นทางบน Google Drive มีการเปลี่ยนแปลงหรือไม่ ไม่ได้ดูว่าเอกสารอยู่ในสถานะใดในปัจจุบัน

ดังนั้น เอกสารที่เคยแยกวิเคราะห์ล้มเหลว (สถานะเป็น FAIL) ตราบใดที่ไฟล์ต้นทางบน Google Drive ไม่ถูกแก้ไข การเรียกอินเทอร์เฟซนี้จะไม่ประมวลผลมันใหม่ — มันจะถูกถือว่า "เอกสารต้นทางไม่มีการเปลี่ยนแปลง" และถูกข้ามไปโดยตรง สถานะคงเดิม และจะไม่ปรากฏใน skipped

หากต้องการลองแยกวิเคราะห์เอกสารที่ล้มเหลวใหม่ โปรดใช้อินเทอร์เฟซฝังเอกสารที่ล้มเหลวใหม่ หรือแก้ไขไฟล์ต้นทางบน Google Drive สักครั้งเพื่อให้เวลาแก้ไขล่าสุดอัปเดต แล้วอินเทอร์เฟซนี้จึงจะดึงใหม่ได้

การซิงค์จะลบเอกสารความรู้

อินเทอร์เฟซนี้ไม่ได้ทำเพียงการเพิ่มและอัปเดตเท่านั้น แต่ยังลบเอกสารความรู้ตามสถานะปัจจุบันของ Google Drive ด้วย

เมื่อโฟลเดอร์ Google Drive ที่ผูกไว้ว่างเปล่า เอกสารความรู้ที่นำเข้ามาแล้วภายใต้โฟลเดอร์นั้นจะถูกลบทั้งหมด เงื่อนไขการทริกเกอร์คือโฟลเดอร์ยังเข้าถึงได้บน Google Drive แต่ไม่สามารถแจกแจงไฟล์ใด ๆ ได้ ระบบจะตรวจสอบความสามารถในการเข้าถึงโฟลเดอร์ก่อน หากดึงข้อมูลเมทาของโฟลเดอร์ไม่ได้ (โฟลเดอร์ถูกย้าย, สิทธิ์เปลี่ยนแปลง, เข้าถึงไม่ได้ชั่วคราว ฯลฯ) จะข้ามการลบ เพื่อหลีกเลี่ยงการลบผิดพลาด

ขอบเขตการลบจำกัดอยู่ภายใน "โฟลเดอร์นั้น + ฐานความรู้นั้น" เมื่อโฟลเดอร์ Google Drive เดียวกันถูกอ้างอิงโดยหลายฐานความรู้ แต่ละฐานความรู้จะไม่กระทบกัน

พฤติกรรมนี้เหมือนกับการซิงค์ตามกำหนดเวลาของระบบ อินเทอร์เฟซนี้เพียงทำให้มันเกิดขึ้นก่อนเท่านั้น แต่เนื่องจากอินเทอร์เฟซนี้ยังครอบคลุมเอกสารที่ไม่ได้ตั้งค่าแผนการซิงค์ตามกำหนดเวลาตอนนำเข้าด้วย (ส่วนนี้เดิมจะไม่ถูกลบโดยกระบวนการอัตโนมัติใด ๆ) ก่อนเรียกใช้โปรดยืนยันว่าเนื้อหาในโฟลเดอร์ฝั่ง Google Drive เป็นไปตามที่คาดหวัง

ขอบเขตการครอบคลุม

ขอบเขตการซิงค์ครอบคลุมเอกสารทั้งหมดที่มาจาก Google Drive ในฐานความรู้ รวมถึงส่วนที่ไม่ได้ตั้งค่าแผนการซิงค์ตามกำหนดเวลาตอนนำเข้า — เอกสารส่วนนี้จะไม่ถูกประมวลผลโดยรอบตามกำหนดเวลาของระบบ และอัปเดตได้ผ่านอินเทอร์เฟซนี้เท่านั้น

การจำกัดอัตรา

  • แต่ละ Agent / Workflow เรียกได้สูงสุด 1 ครั้งต่อนาที ทั้งสอง path ใช้ตัวนับเดียวกัน การสลับ path จะไม่ทำให้เลี่ยงการจำกัดอัตราได้
  • ยังอยู่ภายใต้ข้อจำกัดจำนวนคำขอต่อนาที (RPM) ของ API ประเภทฐานความรู้ตามแพ็กเกจขององค์กร โดยแชร์โควตานี้ร่วมกับอินเทอร์เฟซฐานความรู้อื่น ๆ
  • เมื่อการซิงค์ครั้งก่อนของ Agent / Workflow เดียวกันยังทำงานไม่เสร็จ การเรียกอีกครั้งจะคืน accepted=false และ reason=SYNC_IN_PROGRESS

ความสัมพันธ์กับการซิงค์ตามกำหนดเวลา

อินเทอร์เฟซนี้กับการซิงค์ตามกำหนดเวลาของระบบเป็นอิสระต่อกันและไม่ขวางกัน เมื่อ scheduled_round_running เป็น true คำขอครั้งนี้ยังคงได้รับการรับเรื่อง จะไม่ถูกปฏิเสธเพราะรอบตามกำหนดเวลากำลังทำงานอยู่

เมื่อทั้งสองประมวลผลเอกสารเดียวกันพร้อมกันจะไม่เกิดเนื้อหาซ้ำ: ระบบตัดสินแบบเพิ่มขึ้นตามเวลาแก้ไขล่าสุดของเอกสารต้นทาง และไฟล์ที่นำเข้ามาแล้วจะไม่ถูกสร้างซ้ำ

การซิงค์ตามกำหนดเวลาจะทำงานอัตโนมัติตามความถี่ที่ตั้งค่าไว้ในฐานความรู้เอง ส่วนอินเทอร์เฟซนี้จะละเว้นความถี่นั้นและทริกเกอร์ทันที ทั้งสองเสริมกัน: การซิงค์ตามกำหนดเวลารับผิดชอบการอัปเดตตามปกติ ส่วนอินเทอร์เฟซนี้รับผิดชอบสถานการณ์ "ต้องการซิงค์เดี๋ยวนี้"