# AgenticRAG

AgenticRAG จะเปิดเผยฐานความรู้ (knowledge bases) ที่กำหนดค่าไว้สำหรับไปป์ไลน์ปัจจุบันให้เป็นเครื่องมือ LLM (LLM Tool) เพื่อให้เอเจนต์สามารถตรวจสอบฐานความรู้ที่มีอยู่และเรียกค้นข้อมูล (retrieve) ส่วนที่เกี่ยวข้องได้ตามต้องการ

## คุณสมบัติหลัก

- ให้บริการเครื่องมือเดียวคือ `query_knowledge`
- รองรับการดำเนินการสองอย่าง:
  - `list`: รายการฐานความรู้ที่พร้อมใช้งานสำหรับไปป์ไลน์ปัจจุบัน
  - `query`: เรียกคืนเอกสารที่เกี่ยวข้องจากฐานความรู้ที่เลือกอย่างน้อยหนึ่งรายการ
- ส่งคืนผลลัพธ์การเรียกคืนข้อมูลเป็นรูปแบบ JSON เพื่อให้เอเจนต์สามารถใช้ในการให้เหตุผลต่อไปได้

## การออกแบบโดยรวม

AgenticRAG ไม่ได้ถูกออกแบบมาให้เป็นแบ็กเอนด์ RAG ใหม่ แต่เป็นปลั๊กอินในระดับการควบคุม (control-layer) ที่เปลี่ยน **ผู้ที่ตัดสินใจว่าการเรียกค้นข้อมูลควรเกิดขึ้นเมื่อใด**

แทนที่จะให้ระบบเรียกค้นข้อมูลโดยอัตโนมัติเสมอก่อนที่โมเดลจะตอบสนอง AgenticRAG ย้ายการเรียกค้นข้อมูลเข้าไปอยู่ในลูปของเอเจนต์:

- โมเดลจะตัดสินใจก่อนว่าจำเป็นต้องเรียกค้นข้อมูลหรือไม่
- โมเดลสามารถตรวจสอบฐานความรู้ที่มีอยู่ได้
- โมเดลสามารถเลือกฐานความรู้เดียวหรือสอบถามหลายรายการพร้อมกันได้
- การเรียกค้นข้อมูลจะเกิดขึ้นเมื่อโมเดลร้องขออย่างชัดเจนเท่านั้น

การออกแบบนี้มีขึ้นเพื่อแก้ปัญหาเฉพาะ: การเรียกค้นข้อมูลอัตโนมัติตลอดเวลา (naive always-on retrieval) นั้นง่าย แต่ก็นำมาซึ่งสัญญาณรบกวน การสิ้นเปลืองบริบท และข้อมูลที่ไม่เกี่ยวข้องในหลายๆ รอบการสนทนา

## รายละเอียดการออกแบบ

ปลั๊กอินนี้ออกแบบมาให้มีความซับซ้อนน้อย โดยไม่ได้ใช้แบ็กเอนด์ RAG ใหม่ แต่เป็นการห่อหุ้ม (wrap) API การเรียกค้นความรู้ในระดับคิวรี (query-scoped) ที่มีอยู่ภายในของ LangBot:

- `list_pipeline_knowledge_bases()` สำหรับการระบุฐานความรู้ที่สามารถมองเห็นได้ในคิวรีปัจจุบัน
- `retrieve_knowledge()` สำหรับการเรียกค้นข้อมูล top-k รายการจากฐานความรู้ที่เลือกอย่างน้อยหนึ่งรายการ

`query_id` จะถูกใส่เข้ามาโดยระบบรันไทม์เมื่อมีการเรียกใช้เครื่องมือ และจะถูกเก็บไว้ใน `QueryBasedAPIProxy` ด้วยเหตุนี้ โค้ดของเครื่องมือจึงเพียงแค่ส่งพารามิเตอร์ทางธุรกิจ เช่น `kb_id` หรือ `kb_ids`, `query_text` และ `top_k`

แม้ว่ารันไทม์เบื้องหลังจะรองรับการกรองเมทาดาตา (metadata filters) แต่ปลั๊กอินนี้ไม่ได้เปิดเผยตัวกรองดิบให้กับเอเจนต์ในขั้นตอนการใช้เครื่องมือของเอเจนต์ปัจจุบัน เนื่องจากกลไกความรู้และแบ็กเอนด์เวกเตอร์ที่แตกต่างกันอาจใช้ฟิลด์เมทาดาตา รูปแบบค่า และความหมายของตัวกรองที่แตกต่างกัน และเอเจนต์ในปัจจุบันยังไม่มีแหล่งที่มาของสคีมา (schema) ที่เชื่อถือได้สำหรับฟิลด์เหล่านั้น

เวอร์ชันในอนาคตอาจเปิดเผยการกรองเมทาดาตาหลังจากที่ระบบนิเวศมีวิธีที่เป็นเอกภาพมากขึ้นในการอธิบายฟิลด์และตัวดำเนินการที่กรองได้สำหรับแต่ละฐานความรู้

## ขั้นตอนการทำงาน

คำขอ AgenticRAG มีสี่ขั้นตอนหลัก:

### 1. ปิดการเรียกค้นข้อมูลแบบเดิม (naive retrieval)

ในระหว่างขั้นตอน `PromptPreProcessing` ปลั๊กอินจะตรวจสอบว่า LLM ที่ใช้งานอยู่รองรับการเรียกใช้เครื่องมือ (tool calling) หรือไม่

- หากรองรับการเรียกใช้เครื่องมือ จะมีการล้างค่า `_knowledge_base_uuids` ของระบบรันไทม์ เพื่อข้ามขั้นตอนการเรียกค้นข้อมูลอัตโนมัติแบบเดิม
- หากไม่รองรับการเรียกใช้เครื่องมือ จะยังคงเปิดใช้งาน RAG แบบเดิมไว้เพื่อเป็นทางเลือกสำรอง เพื่อไม่ให้การเรียกค้นฐานความรู้หายไปทั้งหมด

### 2. ใส่กลยุทธ์การเรียกค้นข้อมูลลงใน system prompt

ในเวลาเดียวกัน AgenticRAG จะใส่ system prompt เพิ่มเติมเพื่อบอกโมเดลว่า:

- ฐานความรู้ที่กำหนดค่าไว้เป็นแหล่งข้อมูลหลักสำหรับข้อเท็จจริงที่อยู่ในขอบเขต
- ไม่มีการเรียกค้นข้อมูลอัตโนมัติสำรอง
- สำหรับคำถามเกี่ยวกับข้อเท็จจริง นโยบาย ขั้นตอน ผลิตภัณฑ์ และคำถามเฉพาะโดเมน โมเดลควรเลือกใช้ `query_knowledge`

สิ่งนี้สำคัญเนื่องจากคำอธิบายเครื่องมือเพียงอย่างเดียวมักจะไม่แข็งแรงพอที่จะเปลี่ยนพฤติกรรมของโมเดลได้อย่างน่าเชื่อถือ

### 3. ให้โมเดลตรวจสอบและสอบถามฐานความรู้

เอเจนต์สามารถใช้ `query_knowledge` ในสองขั้นตอน:

- `action="list"` เพื่อดูว่ามีฐานความรู้ใดบ้างที่พร้อมใช้งาน
- `action="query"` เพื่อค้นหาในฐานความรู้เดียวหรือหลายรายการพร้อมกัน

สำหรับการเรียกค้นข้อมูลจากฐานความรู้เดียว พารามิเตอร์ที่แนะนำคือ `kb_id`
สำหรับการเรียกค้นข้อมูลจากหลายฐานความรู้ ให้ใช้ `kb_ids`

### 4. ส่งคืนผลลัพธ์การเรียกคืนข้อมูลในรูปแบบ JSON ที่มีโครงสร้าง

เครื่องมือจะรวมผลลัพธ์ กำกับด้วย `knowledge_base_id` และส่งคืนรูปแบบ JSON เพื่อให้โมเดลสามารถดำเนินการให้เหตุผล ใช้เครื่องมือ หรือให้คำตอบสุดท้ายต่อไปได้

## พฤติกรรมการเรียกค้นข้อมูล

เมื่อเปิดใช้งาน AgenticRAG ระบบจะปิดการประมวลผล RAG อัตโนมัติแบบเดิมสำหรับไปป์ไลน์ปัจจุบัน

- การเรียกค้นข้อมูลจะไม่เกิดขึ้นโดยอัตโนมัติก่อนที่โมเดลจะตอบอีกต่อไป
- การสอบถามฐานความรู้ตอนนี้เป็นการตัดสินใจที่รอบคอบของโมเดลผ่าน `query_knowledge`
- หากโมเดลไม่เรียกใช้เครื่องมือ จะไม่มีเนื้อหาจากฐานความรู้ถูกใส่เข้าไปในบริบท

มีข้อยกเว้นที่สำคัญประการหนึ่ง:

- หาก LLM ที่ใช้งานอยู่ไม่รองรับการเรียกใช้เครื่องมือ AgenticRAG จะยังคงเปิดใช้งาน RAG แบบเดิมแทนที่จะปิดใช้งาน

สิ่งนี้ช่วยลดสัญญาณรบกวนจากการเรียกค้นข้อมูลโดยไม่มีเงื่อนไข แต่ก็หมายความว่าการเขียนพรอมต์ (prompting) มีความสำคัญ การใช้งานปัจจุบันจึงใช้**ทั้งคู่**:

- พรอมต์เครื่องมือใน `query_knowledge`
- system prompt ที่ใส่เข้ามาในระหว่างขั้นตอน `PromptPreProcessing`

ทั้งสองอย่างนี้จะช่วยโน้มน้าวให้โมเดลหันไปใช้การเรียกค้นข้อมูลสำหรับคำถามที่เป็นข้อเท็จจริง นโยบาย ขั้นตอน ผลิตภัณฑ์ และคำถามเฉพาะโดเมนอื่นๆ

## ทำไมจึงต้องออกแบบเช่นนี้

ปลั๊กอินนี้ได้รับการปรับให้เหมาะสมสำหรับข้อแลกเปลี่ยน (tradeoff) ที่เฉพาะเจาะจง:

- รักษาโครงสร้างพื้นฐานฐานความรู้และการเรียกค้นข้อมูลเดิมของ LangBot ไว้
- ลบการเรียกค้นข้อมูลแบบเปิดตลอดเวลาที่ไม่จำเป็นออก
- ให้โมเดลตัดสินใจเรียกค้นข้อมูลอย่างชัดเจน
- ยังคงจำกัดพฤติกรรมการเรียกค้นข้อมูลไว้ที่ไปป์ไลน์ปัจจุบัน

เมื่อเปรียบเทียบกับ RAG แบบเดิม การออกแบบนี้จะช่วยให้คุณ:

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

ข้อเสียคือ หากโมเดลไม่เคยเรียกใช้เครื่องมือ จะไม่มีเนื้อหาฐานความรู้ปรากฏขึ้น นี่คือเหตุผลที่ปลั๊กอินมีการเพิ่มการเขียนพรอมต์ที่เน้นการเรียกค้นข้อมูลอย่างชัดเจน แทนที่จะสมมติว่าโมเดลจะเลือกเรียกค้นข้อมูลบ่อยพอโดยธรรมชาติ

นี่เป็นเหตุผลที่ปลั๊กอินตรวจสอบความสามารถในการเรียกใช้เครื่องมือก่อนที่จะปิดใช้งาน RAG แบบเดิม หากไม่มีระบบป้องกันนี้ การเปิดใช้งาน AgenticRAG บนโมเดลที่ไม่รองรับเครื่องมือจะทำลายการเรียกค้นฐานความรู้ทั้งหมดโดยไม่ได้ตั้งใจ

## ขอบเขตความปลอดภัย

เครื่องมือนี้ถูกจำกัดขอบเขตไว้ที่ไปป์ไลน์ปัจจุบัน

- ระบบรันไทม์ของ LangBot จะตรวจสอบด้วยว่า `kb_id` ที่ร้องขอเป็นของไปป์ไลน์ปัจจุบันก่อนที่จะดำเนินการเรียกค้นข้อมูล

ซึ่งหมายความว่าการทำ prompt injection เพียงอย่างเดียวไม่ควรอนุญาตให้เอเจนต์สอบถามฐานความรู้ใดๆ ภายนอกการกำหนดค่าไปป์ไลน์ได้

## วิธีใช้

1. ติดตั้งและเปิดใช้งานปลั๊กอิน
2. กำหนดค่าฐานความรู้อย่างน้อยหนึ่งรายการในการตั้งค่าเอเจนต์ท้องถิ่นของไปป์ไลน์ปัจจุบัน
3. ให้เอเจนต์เรียกใช้ `query_knowledge`:
   - เริ่มต้นด้วย `action="list"` เพื่อตรวจสอบฐานความรู้ที่มีอยู่
   - จากนั้นเรียกใช้ `action="query"` พร้อม `kb_id` สำหรับฐานความรู้เดียว หรือ `kb_ids` สำหรับหลายฐานความรู้ที่สอบถามพร้อมกัน
   - ระบุ `query_text` และระบุ `top_k` (ตัวเลือกเสริม) สำหรับจำนวนผลลัพธ์ที่รวมกัน

## พารามิเตอร์

สำหรับ `action="query"` ในปัจจุบันเครื่องมือรับค่า:

- `kb_id`: UUID ของฐานความรู้เป้าหมายสำหรับการเรียกค้นข้อมูลเดียว แนะนำให้ใช้เมื่อสอบถามเพียงฐานความรู้เดียว
- `kb_ids`: อาร์เรย์ UUID ของฐานความรู้เป้าหมายสำหรับการเรียกค้นข้อมูลหลายรายการพร้อมกัน ใช้เฉพาะเมื่อสอบถามหลายฐานความรู้
- `query_text`: ข้อความคิวรีสำหรับการเรียกค้นข้อมูล
- `top_k`: จำนวนเต็มบวก (ตัวเลือกเสริม) ค่าเริ่มต้นคือ `5` ซึ่งใช้กับชุดผลลัพธ์ที่รวมกัน

หากคิวรีฐานความรู้หนึ่งล้มเหลวในขณะที่รายการอื่นสำเร็จ เครื่องมือจะส่งคืนอ็อบเจกต์ JSON พร้อม `results` และ `failed_kbs` เพื่อให้เอเจนต์สามารถดำเนินการต่อด้วยผลลัพธ์บางส่วนได้

## ลำดับขั้นตอนทั่วไป

1. เอเจนต์แสดงรายการฐานความรู้ที่มีอยู่
2. เอเจนต์เลือกฐานความรู้เดียวหรือชุดเล็กๆ โดยพิจารณาจากชื่อและคำอธิบาย
3. เอเจนต์ส่งคิวรีการเรียกค้นข้อมูลที่มุ่งเน้น
4. เอเจนต์ใช้ข้อมูลที่ได้รับมาเพื่อตอบคำถามหรือใช้เครื่องมือต่อไป

## เจตนาของการเขียนพรอมต์

เลเยอร์การเขียนพรอมต์ได้รับการออกแบบเพื่อสื่อสารสองสิ่งกับโมเดล:

- ฐานความรู้เหล่านี้เป็นแหล่งข้อมูลที่เชื่อถือได้สำหรับข้อมูลที่อยู่ในขอบเขต
- ไม่มีการเรียกค้นข้อมูลอัตโนมัติสำรองเมื่อเปิดใช้งาน AgenticRAG แล้ว

หากไม่มีคำแนะนำนั้น LLM อาจเชื่อมั่นในความรู้ที่ได้รับการฝึกฝนมาล่วงหน้ามากเกินไปและใช้การเรียกค้นข้อมูลน้อยเกินไป การใช้งานปัจจุบันจึงตอกย้ำนโยบายเดียวกันทั้งที่เลเยอร์ system-prompt และเลเยอร์ tool-prompt

## การบันทึกข้อมูล (Logging)

ตอนนี้ปลั๊กอินจะแสดงบันทึกข้อมูลในระหว่างการดำเนินการเครื่องมือเพื่อให้คุณสามารถสังเกตว่า LLM ใช้ AgenticRAG อย่างไรในทางปฏิบัติ

คุณจะเห็นบันทึกข้อมูลสำหรับ:

- การเริ่มเรียกใช้เครื่องมือ รวมถึง `query_id`, `action` และคีย์พารามิเตอร์
- การเริ่ม/สิ้นสุดการแสดงรายการฐานความรู้ และจำนวนฐานความรู้ที่มองเห็นได้
- การเริ่มเรียกค้นข้อมูล รวมถึงฐานความรู้ที่เลือก, `top_k` และตัวอย่าง `query_text` สั้นๆ
- การเริ่ม/สำเร็จ/ล้มเหลว ของการเรียกค้นข้อมูลแต่ละฐานความรู้
- สรุปการเรียกค้นข้อมูลสุดท้าย รวมถึงจำนวนผลลัพธ์ที่รวมกัน จำนวนฐานความรู้ที่ล้มเหลว และจำนวนผลลัพธ์ที่ส่งคืน

ตัวอย่างข้อความบันทึกข้อมูล:

```text
[AgenticRAG] tool call started: query_id=123 action=query params_keys=['action', 'kb_id', 'query_text', 'top_k']
[AgenticRAG] retrieval requested: query_id=123 kb_ids=['kb-1'] kb_count=1 top_k=5 query='what is the refund policy'
[AgenticRAG] querying knowledge base: query_id=123 kb_id=kb-1 top_k=5
[AgenticRAG] knowledge base query succeeded: query_id=123 kb_id=kb-1 result_count=4
[AgenticRAG] retrieval completed: query_id=123 merged_results=4 failed_kbs=0
```