ค้นหาส่วนความรู้ (chunk) ที่เกี่ยวข้องมากที่สุดจากฐานความรู้ที่ผูกกับ Agent / Workflow ตามข้อความคำค้น และส่งคืนเนื้อหาส่วนความรู้ เอกสารต้นทาง และคะแนนความคล้ายคลึง เหมาะสำหรับการสร้าง RAG ด้วยตนเอง การทดสอบคุณภาพการค้นหา และการตรวจสอบอัตราการค้นพบความรู้
ข้อควรทราบ
- ขอบเขตการค้นหาคือฐานความรู้ที่ผูกกับเวอร์ชันที่เผยแพร่แล้วของ Agent / Workflow
- อินเทอร์เฟซนี้เป็นแบบอ่านอย่างเดียว ไม่มีการแก้ไข Agent, Workflow หรือฐานความรู้
- หนึ่งคำขอระบุ
data_idsได้ไม่เกิน 10 รายการ หากเกินจะส่งคืนรหัสข้อผิดพลาด40332
วิธีการร้องขอ
POST
Endpoint
https://api-${endpoint}.gptbots.ai/v1/vector/match
การยืนยันตัวตน
ดูรายละเอียดวิธีการยืนยันตัวตนได้ในหัวข้อ API Overview
การร้องขอ
ตัวอย่างการร้องขอ
ตัวอย่างที่ 1: ค้นหาในฐานความรู้ที่ระบุ
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/vector/match' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "นโยบายการคืนสินค้าเป็นอย่างไร?",
"group_ids": ["6616e3f3d9d5cf1d5b6c8a21"],
"top_k": 5,
"doc_correlation": 0.5
}'
ตัวอย่างที่ 2: จำกัดเฉพาะเอกสารที่ระบุและเปิดใช้การจัดอันดับใหม่
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/vector/match' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "นโยบายการคืนสินค้าเป็นอย่างไร?",
"data_ids": ["6616e4a2d9d5cf1d5b6c8a35", "6616e4a2d9d5cf1d5b6c8a36"],
"top_k": 3,
"embedding_rate": 0.8,
"rerank_version": "BGE-Rerank"
}'
Header ของคำขอ
| ชื่อฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| Authorization | Bearer ${API Key} | ใช้ Authorization: Bearer ${API Key} สำหรับการยืนยันตัวตน รับ API Key ได้จากหน้า API Key |
| Content-Type | application/json | ประเภทข้อมูล; ควรระบุเป็น application/json |
พารามิเตอร์ของคำขอ
| ชื่อฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
|---|---|---|---|
| prompt | string | ใช่ | ข้อความคำค้นหรือคีย์เวิร์ดที่ใช้จับคู่เวกเตอร์กับเนื้อหาในฐานความรู้ |
| top_k | int | ใช่ | ส่งคืนส่วนความรู้ที่มีความคล้ายคลึงสูงสุด K รายการ ช่วงที่ใช้ได้: [1,50] |
| group_ids | array | ไม่จำเป็น | รหัสฐานความรู้ที่ใช้จำกัดขอบเขตการค้นหา |
| data_ids | array | ไม่จำเป็น | รหัสเอกสารที่ใช้จำกัดขอบเขตการค้นหา ไม่เกิน 10 รายการต่อคำขอ หากเกินจะส่งคืนรหัสข้อผิดพลาด 40332 |
| embedding_rate | float | ไม่จำเป็น | อัตราส่วนน้ำหนักระหว่างการค้นหาด้วยคีย์เวิร์ดและความหมาย ช่วงค่า: [0,1] ค่าเริ่มต้นคือ 1 |
| doc_correlation | float | ไม่จำเป็น | เกณฑ์คะแนนความเกี่ยวข้องของความรู้ ส่วนความรู้ที่มีคะแนนต่ำกว่านี้จะไม่ถูกส่งคืน ยิ่งค่าสูงยิ่งเกี่ยวข้อง แต่หากตั้งสูงเกินไปอาจไม่เหลือส่วนความรู้ที่ใช้ได้ ช่วงที่ใช้ได้: [0.1,0.95] |
| rerank_version | string | ไม่จำเป็น | ชื่อโมเดลจัดอันดับใหม่ เมื่อระบุค่าจะเปิดใช้การจัดอันดับใหม่โดยอัตโนมัติ ซึ่งจะเรียงลำดับความรู้ที่เป็นตัวเลือกอีกครั้งเพื่อให้การค้นหาแม่นยำขึ้น เลือกได้หนึ่งรายการ: BGE-Rerank, Jina-reranker-v2-base-multilingual, Jina-colbert-v2, BCE-Rerank |
การใช้ group_ids ร่วมกับ data_ids
| group_ids | data_ids | ขอบเขตการค้นหา |
|---|---|---|
| ไม่ระบุ / null | ไม่ระบุ / null | ทุกฐานความรู้ |
| ระบุ | ไม่ระบุ / null | เอกสารทั้งหมดในฐานความรู้ที่ระบุ |
| ไม่ระบุ / null | ระบุ | เอกสารที่ระบุ |
| ระบุ | ระบุ | ยูเนียน ของทั้งสอง |
| [] | [] | ไม่มีผลลัพธ์ |
แนวทางการใช้งานที่แนะนำ
- ค้นหาแบบ RAG ทั้งฐานความรู้: ระบุเฉพาะ
group_idsและไม่ต้องระบุdata_ids- หากต้องจำกัดเฉพาะเอกสาร: ส่ง
data_idsเป็นชุด ชุดละไม่เกิน 10 รายการ- ไม่ควรใช้
[]เพื่อหมายถึง «ทั้งหมด» เพราะ[]หมายถึง «ไม่ค้นหา»
การตอบกลับ
ตัวอย่างการตอบกลับ
{
"total": 2,
"list": [
{
"content": "สินค้าที่ยังไม่เปิดกล่องสามารถขอคืนได้โดยไม่ต้องระบุเหตุผลภายใน 7 วันนับจากวันที่รับสินค้า…",
"data_id": "6616e4a2d9d5cf1d5b6c8a35",
"document_name": "นโยบายบริการหลังการขาย.pdf",
"score": 0.87
},
{
"content": "ค่าจัดส่งในการคืนสินค้าผู้ซื้อเป็นผู้รับผิดชอบ ยกเว้นกรณีสินค้ามีปัญหาด้านคุณภาพ…",
"data_id": "6616e4a2d9d5cf1d5b6c8a35",
"document_name": "นโยบายบริการหลังการขาย.pdf",
"score": 0.79
}
]
}
คำอธิบายผลลัพธ์ที่สำเร็จ
| ชื่อฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| total | int | จำนวนส่วนความรู้ที่ส่งคืนในครั้งนี้ |
| list | JSON Array | รายการส่วนความรู้ เรียงจากคะแนนความคล้ายคลึงสูงไปต่ำ |
| content | string | เนื้อหาส่วนความรู้ |
| data_id | string | รหัสเอกสารที่ส่วนความรู้นี้อยู่ |
| document_name | string | ชื่อเอกสารที่ส่วนความรู้นี้อยู่ |
| score | float | คะแนนความคล้ายคลึง ยิ่งสูงยิ่งเกี่ยวข้อง |
คำอธิบายผลลัพธ์ที่ล้มเหลว
| ชื่อฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| code | int | รหัสข้อผิดพลาด |
| message | string | รายละเอียดข้อผิดพลาด |
รหัสข้อผิดพลาด
| สถานะ HTTP | รหัส | ข้อความ | คำแนะนำในการแก้ไข |
|---|---|---|---|
| 400 | 40000 | พารามิเตอร์ผิดพลาด | ตรวจสอบพารามิเตอร์ที่จำเป็นและช่วงค่า (top_k [1,50], embedding_rate [0,1], doc_correlation [0.1,0.95]) |
| 401 | 40127 | การยืนยันตัวตนนักพัฒนาล้มเหลว | ตรวจสอบว่า API Key ถูกต้องและเป็นของ Agent / Workflow นี้ |
| 403 | 40332 | data_ids เกิน 10 รายการ | หนึ่งคำขอระบุ data_ids ได้ไม่เกิน 10 รายการ กรุณาแบ่งส่งเป็นชุด หรือใช้ group_ids ระบุฐานความรู้แทน |
| — | 20059 | Agent/Workflow ถูกลบ | ตรวจสอบว่า Agent / Workflow เป้าหมายยังมีอยู่ |
คำถามที่พบบ่อย
Q1: อินเทอร์เฟซ «รายการฐานความรู้» และ «รายการเอกสาร» ใช้งานได้ปกติ แต่ทำไมอินเทอร์เฟซนี้ส่งคืน 403?
A: ส่วนใหญ่เกิดจากการส่ง data_ids เกิน 10 รายการ (รหัสข้อผิดพลาด 40332) อินเทอร์เฟซรายการไม่มีข้อจำกัดจำนวน แต่อินเทอร์เฟซนี้มี กรุณาลดจำนวน data_ids หรือใช้ group_ids ระบุฐานความรู้แทน
Q2: ผลลัพธ์ว่างเปล่า (total เป็น 0) ตรวจสอบอย่างไร?
A: ตรวจสอบตามลำดับ: ส่ง group_ids หรือ data_ids เป็นอาร์เรย์ว่าง [] หรือไม่; เกณฑ์ doc_correlation สูงเกินไปหรือไม่; เอกสารเป้าหมายมีสถานะ AVAILABLE หรือไม่; และฐานความรู้ผูกกับเวอร์ชันที่เผยแพร่แล้วของ Agent / Workflow หรือไม่
