Telegram RAG Bot từ GitHub Knowledge Base với Qwen & OpenRouter

1. Tổng quan dự án (Overview)

Đây là workflow biến một file JSON đơn giản trên GitHub thành chatbot Telegram hoàn chỉnh với khả năng trả lời câu hỏi dựa trên tri thức (RAG) — không cần Pinecone, không cần Qdrant, không cần bất kỳ vector database hay dịch vụ trả phí nào thêm. Workflow này hữu ích cho bất kỳ ai muốn xây dựng chatbot hỗ trợ khách hàng, FAQ nội bộ hoặc hệ thống hỏi-đáp dựa trên tài liệu riêng.

Mục tiêu chính: Xây dựng chatbot RAG với chi phí bằng 0 cho phần retrieval, dễ bảo trì và hiếm khi gặp lỗi.

🚀 Điểm nổi bật: Hệ thống dùng keyword matching cục bộ kết hợp Qwen 3 (235B) qua OpenRouter — chỉ những knowledge entry liên quan nhất mới được chọn làm ngữ cảnh cho LLM trả lời, hoàn toàn không gọi API bên ngoài cho bước tìm kiếm.

---

2. Tính năng nổi bật (Key Features)

A. RAG Không Cần Vector Database Hệ thống retrieval hoạt động hoàn toàn cục bộ bằng keyword matching, loại bỏ hoàn toàn chi phí và độ phức tạp của vector database. Phù hợp với knowledge base nhỏ đến trung bình (vài trăm entry) về một chủ đề cụ thể như FAQ, sản phẩm hoặc tài liệu nội bộ.

• Chi tiết 1: Câu hỏi được tách thành từng từ, chấm điểm với mỗi entry trong knowledge base dựa trên số từ trùng khớp, chọn top 2 kết quả liên quan nhất.
• Chi tiết 2: Hoạt động hoàn toàn không cần embeddings, không vector math, không API call cho retrieval — chi phí retrieval bằng 0.

B. Xử Lý Thông Minh & Robust Workflow được thiết kế để luôn phản hồi rõ ràng cho người dùng, không bao giờ im lặng khi có lỗi. Mọi tình huống bất thường đều có thông báo cụ thể giúp người dùng biết chính xác chuyện gì xảy ra.

• Chi tiết 1: Input validation chặt chẽ — nếu người dùng gửi /ask mà không có câu hỏi hoặc tin nhắn quá ngắn, bot trả lời hướng dẫn format ngay lập tức, tránh gọi API không cần thiết.
• Chi tiết 2: Error handling toàn diện — file GitHub không tồn tại, token sai, hoặc LLM trả về rỗng đều có thông báo lỗi cụ thể thay vì crash hoặc im lặng.

C. Dễ Tùy Chỉnh & Mở Rộng Workflow thiết kế như một nền tảng mở, dễ dàng thay đổi model, mở rộng nguồn dữ liệu hoặc tích hợp thêm kênh giao tiếp.

• Chi tiết 1: Thay đổi model LLM bất kỳ (GPT-4o, Claude, Gemini…) chỉ bằng cách sửa tên model trong node, hoặc trỏ sang model tự host bằng cách đổi base URL. Thêm kiến thức chỉ cần sửa file JSON trên GitHub, không cần redeploy.
• Chi tiết 2: Hỗ trợ đa ngôn ngữ tự động — knowledge base viết bằng ngôn ngữ nào, bot sẽ trả lời bằng ngôn ngữ của câu hỏi mà người dùng đặt.

---

3. Hướng dẫn cài đặt chi tiết (Setup Guide)

Để chạy workflow này, bạn cần chuẩn bị các tài nguyên sau:

⚙️ Yêu cầu môi trường (Prerequisites)

• n8n Instance: Bản self-hosted hoặc cloud đều được.
• Telegram Bot Token: Tạo qua BotFather trên Telegram.
• GitHub Personal Access Token: Tạo Fine-grained PAT với quyền read-only, scope vào repository chứa file knowledge base.
• OpenRouter API Key: Hoặc bất kỳ endpoint tương thích OpenAI nào.

Các bước thực hiện:

1. Cấu hình GitHub: Tạo Fine-grained PAT với quyền read access vào repository. Thêm credential GitHub vào n8n, cấu hình node “get gh file” với owner, tên repo và đường dẫn file.
2. Chuẩn bị Knowledge Base: Tạo file JSON dạng array, mỗi entry có trường "text" (cũng chấp nhận "content", "answer", "title").

   [
     { "text": "your knowledge entry here" },
     { "text": "another knowledge entry" }
   ]

3. Kết nối Telegram & OpenRouter: Thêm credential Telegram Bot vào cả 4 node Telegram và credential OpenRouter vào node model Qwen.
4. Active: Bật workflow, gửi /ask <câu hỏi> đến bot Telegram để test ngay.

---

4. Hướng phát triển (What’s Next)

Workflow hiện tại được thiết kế như một nền tảng. Hệ thống keyword matching hoạt động tốt với knowledge base nhỏ, nhưng đây là những hướng mở rộng khi nhu cầu tăng lên:

A. Vector Search Thay thế node keyword matching bằng bước retrieval dựa trên embedding (OpenAI embeddings + Qdrant hoặc Pinecone) — phù hợp với knowledge base lớn hơn vài trăm entry, nơi trùng khớp từ khóa đơn giản không còn đủ.

B. Multi-Source Knowledge Base Kéo dữ liệu từ nhiều file GitHub, Notion database hoặc Google Sheets thay vì chỉ một file JSON duy nhất.

C. Conversation Memory Thêm bộ nhớ ngắn hạn để bot nhớ 3-5 tin nhắn gần nhất trong cuộc hội thoại, cho phép người dùng hỏi tiếp mà không cần lặp lại ngữ cảnh.

D. Web Interface Thêm Webhook trigger bên cạnh Telegram trigger để phục vụ chat widget trên bất kỳ website nào.

E. Auto-Sync Tự động theo dõi thay đổi trên file GitHub và rebuild search index mỗi khi file thay đổi, thay vì fetch lại từ đầu mỗi request.

Phiên bản hiện tại cố ý giữ đơn giản. Đơn giản nghĩa là chạy rẻ, ít lỗi, dễ debug. Độ phức tạp có thể thêm dần khi use case thực tế đòi hỏi.

⚠️ Lưu ý chi phí (Cost Warning): Workflow gọi API OpenRouter cho mỗi câu hỏi người dùng gửi đến. Keyword matching thì miễn phí nhưng token LLM tính theo usage — nên cẩn thận khi bật workflow ở tần suất cao hoặc knowledge base quá lớn. Với knowledge base vài trăm entry, chi phí mỗi request rất thấp.