เริ่มต้นใช้งาน MCP-RagMax

เผยแพร่ 12 สิงหาคม 2569 · อัปเดต 11 กันยายน 2569

ภาพประกอบ: เริ่มต้นใช้งาน MCP-RagMax

MCP-RagMax คือ RAG backend ที่รันบนเครื่องและไม่ใช้ LLM ภายใน backend สำหรับการค้นหา, query expansion, ranking, build decisions, metadata validation หรือ file writes ตัวระบบรับผิดชอบ retrieval และ lifecycle ของ knowledge base แบบ deterministic แล้วเปิดให้ AI agent ตัวอื่นเรียกผ่าน MCP stdio

โปรเจกต์นี้มาแทน architecture เดิมของ ENDEAVOR_RAG_LITE บน public repo โดยเปลี่ยนจาก RAG ที่มี chat agent ของตัวเอง ไปเป็น knowledge backend ที่แยกจาก agent ชัดเจน

ทำอะไรได้บ้าง

  • ค้นหาแบบ Hybrid: multilingual MiniLM dense search + Thai-aware BM25 แล้วรวมอันดับด้วย Reciprocal Rank Fusion (RRF)
  • Build knowledge base แบบ incremental พร้อม exact-hash dedup และ deterministic semantic duplicate rejection
  • รัน background build ที่คืน job_id ทันที พร้อม progress, ETA และ cooperative cancellation
  • เปิด MCP stdio 9 tools สำหรับ retrieval, file access ภายใน KB, build, health และ orientation index
  • มี rag_index.json lifecycle แบบ prepare/commit ซึ่ง caller LLM ช่วยเสนอได้เฉพาะ high-level topic labels ส่วน counts/tags/source types/fingerprint ยังคงเป็น backend truth
  • มี local HTML console ที่ 127.0.0.1:8770 สำหรับ Search / Files / Health / Build / Cancel / Rag Index
  • เปิดไฟล์ที่อยู่ใน KB จาก UI ไปยัง Finder ได้ โดย endpoint รับเฉพาะ registered files

สถาปัตยกรรม

MCP client ──stdio──► mcp_server.py ───────────────┐
                                                    │
Browser ──127.0.0.1:8770──► web_ui.py ────────────┤
                                                    ▼
                                  deterministic RAG core
                           MiniLM + BM25 + RRF + registry
                                                    │
                           workspace/.rag_state/ (derived)
                                                    ▲
                           workspace/knowledge/ (source)

MCP-RagMax ไม่มี chat agent และไม่ start local/cloud LLM เอง ดังนั้นการคิด วางแผน และสรุปคำตอบเป็นหน้าที่ของ agent ที่เรียกใช้

MCP 9 tools

Tool หน้าที่
rag_retrieve Hybrid retrieval; รับ query เดียวหรือ same-intent variants พร้อม filters
rag_list แสดงไฟล์ที่ register อยู่ใน KB
rag_search_files ค้นชื่อไฟล์แบบ deterministic
rag_read_file อ่านไฟล์ที่ register แล้วเท่านั้น
build_kb เริ่ม background build และคืน persistent job_id
build_status ดู phase / progress / ETA
cancel_build ขอ cooperative cancellation
rag_rebuild_index prepare/commit canonical rag_index.json
rag_health ตรวจ Chroma / BM25 / registry / pipeline / jobs / orientation health

MCP surface ไม่มี shell, Python execution หรือ arbitrary filesystem read

ติดตั้ง

git clone https://github.com/halochamp/MCP-RagMax.git
cd MCP-RagMax
bash install_library/install.sh
source .venv/bin/activate

Installer ติดตั้ง dependency เท่านั้น ยังไม่ scan ไฟล์, ไม่ build index และไม่ start model

ใส่เอกสารและ Build KB

วางเอกสารใต้:

workspace/knowledge/

รองรับ .md, .txt, .pdf, .csv, .json

ตรวจ environment:

python tools/doctor.py

Build แบบ foreground:

python tools/build_index.py

หรือให้ MCP client เรียก build_kb แล้ว poll build_status(job_id) จนเสร็จ

เปิด HTML console

python main.py

แล้วเปิด http://127.0.0.1:8770 หรือบน macOS ใช้ Start MCP-RagMax UI.command

หน้าเว็บนี้เป็น RAG console ไม่ใช่ chat UI ใช้ค้น, ดู health, รายการไฟล์, build/cancel และ prepare/commit orientation index

Retrieval ทำงานอย่างไร

query normalization
  → multilingual MiniLM embedding
  → Thai-aware BM25
  → RRF fusion
  → deterministic unique-parent selection

rag_retrieve รับ query variants ได้ แต่ variants ทุกตัวต้องเป็น เจตนาเดียวกัน เช่นประโยคไทยเดิม, แปลอังกฤษ, keyword ไทย และ keyword อังกฤษ ไม่ควรใช้ variants เพื่อแตกเป็นคำถามย่อยใหม่

rag_index.json กับ caller LLM

MCP-RagMax ไม่เรียก LLM เอง แต่ caller agent สามารถช่วยสร้าง topic labels ผ่าน protocol ที่จำกัด:

  1. rag_rebuild_index(mode="prepare") คืน deterministic snapshot + expected_fingerprint
  2. caller LLM สร้าง topic labels 1–30 รายการจาก snapshot
  3. rag_rebuild_index(mode="commit", topics=..., expected_fingerprint=...)
  4. backend validate topics, recompute metadata และ recheck fingerprint ก่อน atomic install

ถ้า KB เปลี่ยนระหว่าง prepare/commit จะเกิด conflict และไม่ทับ index เดิม

ขอบเขตและความเป็นส่วนตัว

  • Source reads ถูกจำกัดใต้ configured knowledge root
  • Derived state อยู่ใน workspace/.rag_state/ และไม่ควร commit
  • rag_read_file อ่านได้เฉพาะ registered file
  • symlink/path traversal ที่หนี knowledge root ถูกปฏิเสธ
  • UI bind ที่ 127.0.0.1 เท่านั้น
  • Backend ไม่มี cloud LLM call

ดูเพิ่มเติม

ความคิดเห็น

กำลังโหลดความคิดเห็น...