Telegram RAG Helpdesk

یک ربات پاسخگوی هوشمند سازمانی مبتنی بر معماری RAG (Retrieval-Augmented Generation) و پایگاه‌دانش برداری؛ با قابلیت پاسخگویی خودکار بر اساس اسناد شرکت و ارجاع تیکت به ادمین انسانی.

Made ❤️ by Mohammad (@llllxyz)

---

مشکل چی بود؟

تیم‌های پشتیبانی روزانه باید به صدها سوال تکراری مشتریان (درباره قیمت‌ها، شرایط بازگشت وجه، فاکتور، گارانتی و قوانین) پاسخ بدن. ربات‌های سنتی تلگرام که با دکمه و منو کار می‌کنن خیلی محدود هستن و نمی‌تونن متوجه سوالات زبان طبیعی کاربر بشن.

از طرفی اگر ربات رو مستقیم به هوش مصنوعی وصل کنید، اطلاعات اشتباه و ساختگی (Hallucination) درباره شرکت به مشتری می‌ده.

راهکار ما

این پروژه با پیاده‌سازی اصولی معماری RAG روی تلگرام (با کتابخانه Pyrogram) کار می‌کنه و ویژگی‌های زیر رو داره:

1. ایندکس اسناد در دیتابیس برداری (SQLite): تمام فایل‌های راهنما و سوالات متداول شرکت (.txt یا .md) رو چانک‌بندی می‌کنه و بردارهای معنایی اون‌ها رو می‌سازه.
2. پاسخگویی دقیق بر اساس پایگاه‌دانش: وقتی کاربر سوالی می‌پرسه، ابتدا مرتبط‌ترین بخش‌های مستندات شرکت رو استخراج می‌کنه و به عنوان کانتکست به هوش مصنوعی (OpenAI / DeepSeek) می‌ده تا فقط بر اساس واقعیت‌های شرکت جواب بده.
3. موتور آفلاین جایگزین (TF-IDF Lexical Fallback): حتی اگر کلید API هوش مصنوعی تنظیم نشده باشه یا سرور AI قطع بشه، سیستم از کار نمی‌افته و با موتور شباهت کسینوسی داخلی بهترین بخش مستندات رو به کاربر تحویل می‌ده.
4. سیستم ارجاع به انسان (Human Escalation Ticket System): اگر سوال کاربر در اسناد شرکت نبود یا کاربر درخواست اپراتور داشت، ربات خودکار یک تیکت می‌سازه و برای ادمین انسانی می‌فرسته؛ ادمین با دستور /reply جواب می‌ده و پاسخ مستقیماً به تلگرام کاربر ارسال می‌شه.

---

معماری سیستم

[User Telegram Question] --> [Pyrogram Client]
                                   |
                                   v
                      [Embedding & Cosine Similarity]
                                   |
                                   v
                      [SQLite Vector Knowledge Base]
                                   |
                     +-------------+-------------+
                     |                           |
         (Similarity >= Threshold)     (Similarity < Threshold / Human Request)
                     |                           |
                     v                           v
          [LLM RAG Generation]        [Ticket Escalation to Admin]
                     |                           |
                     v                           v
          [Smart Answer to User]      [/reply <id> by Admin]

---

نصب و راه‌اندازی

۱. پیش‌نیازها

• پایتون 3.12 یا بالاتر (یا Docker)
• مشخصات API تلگرام (API_ID و API_HASH) از my.telegram.org
• توکن ربات از @BotFather (یا شماره تلفن برای اجرای حالت Userbot)

۲. تنظیمات اولیه

پروژه رو دانلود کنید و فایل .env رو بسازید:

git clone https://github.com/mmdverse/telegram-rag-helpdesk.git
cd telegram-rag-helpdesk
cp .env.example .env

فایل .env رو ویرایش کنید:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_telegram_api_hash
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
ADMIN_USER_ID=102325921
OPENAI_API_KEY=sk-your_api_key_here
LLM_MODEL_NAME=gpt-4o-mini
EMBEDDING_MODEL_NAME=text-embedding-3-small
SIMILARITY_THRESHOLD=0.30
DATABASE_PATH=data/helpdesk.db
DOCS_DIRECTORY=data/docs

۳. افزودن اسناد شرکت

کافیست فایل‌های راهنما، کاتالوگ یا سوالات متداول شرکت با پسوند .txt یا .md را در پوشه data/docs/ قرار دهید (یک نمونه فایل آماده در پوشه قرار دارد).

۴. اجرا روی سیستم (بدون داکر)

# نصب وابستگی‌ها
make install

# اجرای تست‌های خودکار
make test

# اجرای ربات
make run

۵. اجرا با داکر (Docker Compose)

docker-compose up -d --build

---

دستورات ربات

دستورات کاربران:

دستور	توضیح	مثال
ارسال متن عادی	دریافت پاسخ فوری و هوشمند از پایگاه‌دانش شرکت	فاکتور رسمی چطور صادر می‌شه؟
/ticket <سوال>	ثبت مستقیم تیکت و ارسال سوال برای ادمین انسانی	/ticket مشکل در ورود به پنل

دستورات ادمین سازمانی (ADMIN_USER_ID):

دستور	توضیح	مثال
/index	بازسازی و ایندکس مجدد تمام اسناد از پوشه data/docs/	/index
/tickets	مشاهده لیست تیکت‌های باز و در انتظار پاسخ	/tickets
/reply <id> <text>	ارسال پاسخ رسمی به تیکت شماره id	/reply 10 سلام، برای فاکتور...
/close <id>	بستن و مختومه‌کردن تیکت بدون پاسخ	/close 10
/stats	نمایش آمار تعداد چانک‌ها، کوئری‌ها و تیکت‌ها	/stats

(نکته: ادمین می‌تواند فایل‌های .txt یا .md جدید را مستقیماً در پی‌وی ربات ارسال کند تا به طور خودکار به پایگاه‌دانش اضافه شوند.)

---

تست‌ها

برای اجرای تست‌های خودکار برنامه (چانک‌بندی متون فارسی، شباهت برداری کسینوسی و خط لوله RAG):

pytest -v

---

ارتباط با ما

این پروژه آزاد و متن‌باز است و برای استفاده در پروژه‌های شخصی یا تجاری محدودیتی ندارد.

• Made ❤️ by Mohammad
• Telegram: @llllxyz