🤖 چت‌بات هوشمند فروشگاه — Store Chatbot

یک چت‌بات با Python + Flask + Groq، طراحی‌شده برای اینکه فقط و فقط به سوالات مرتبط با فروشگاه شما پاسخ دهد. با ویرایش یک فایل JSON تمام اطلاعات فروشگاه(محصولات، قیمت‌ها، سیاست‌ها، ساعات کاری، آدرس و…) را به چت‌بات معرفی می‌کند و چت‌بات به‌صورت خودکار در حوزه همان فروشگاه پاسخ می‌دهد

📑 فهرست

ویژگی‌ها
معماری
پیش‌نیازها
مرحله ۱ — نصب
مرحله ۲ — دریافت کلید API از Groq
مرحله ۳ — تنظیم فایل env.
مرحله ۴ — تنظیم اطلاعات فروشگاه (store_config.json)
مرحله ۵ — اجرای چت‌بات
استفاده از API
پنل ادمین
تست
استقرار (Deployment)
عیب‌یابی
ساختار فایل‌ها
مجوز

✨ ویژگی‌ها

🎯 پاسخگویی محدود به فروشگاه: با Prompt Engineering دقیق، چت‌بات فقط به سؤالات مرتبط با فروشگاه شما پاسخ می‌دهد. سؤالات off-topic (مثل «۲+۲ چند می‌شه؟» یا «کد پایتون بنویس») مؤدبانه رد می‌شوند.
⚡ متصل به Groq: سریع‌ترین inference موجود برای LLM (پشتیبانی از Llama 3.3 70B، Llama 3.1 8B، Mixtral و Gemma).
🌍 دوزبانه (فارسی + انگلیسی): تشخیص خودکار زبان کاربر و پاسخ به همان زبان.
🧠 حافظه گفتگو: با SQLite تاریخچه‌ی گفتگوها به‌صورت پایدار ذخیره می‌شود.
🔥 Hot-reload تنظیمات: هرگونه تغییر در store_config.json بدون restart سرور بلافاصله اعمال می‌شود.
🛡️ Rate limiting و مدیریت خطا و retry خودکار در برابر خطاهای Groq.
🎨 رابط کاربری مدرن: چت UI ریسپانسیو با تم روشن/تاریک، فونت وزیرمتن، پشتیبانی از RTL/LTR.
🐳 آماده Docker: فایل Dockerfile و docker-compose.yml برای استقرار سریع.
🧪 تست‌های واحد: پوشش تست برای بخش‌های حیاتی.
🔐 پنل ادمین: مشاهده آمار، ویرایش کانفیگ فروشگاه به‌صورت زنده از طریق API.

🏗 معماری پروژه

User ──▶ Flask API ──▶ ChatService ──▶ PromptBuilder ──▶ Groq API
              │                              ▲
              │                              │
              ▼                    reads from store_config.json
          SQLite DB
      (sessions + messages)

جریان یک پیام:

کاربر پیام می‌فرستد → /api/chat/message
ChatService تاریخچه گفتگو را از SQLite می‌خواند
PromptBuilder اطلاعات فروشگاه را از store_config.json به system prompt تبدیل می‌کند
GroqService درخواست را به Groq می‌فرستد
پاسخ در دیتابیس ذخیره و به کاربر برگردانده می‌شود

🔧 پیش‌نیازها

Python 3.10 یا بالاتر
pip (مدیر بسته پایتون)
کلید API از Groq (رایگان — console.groq.com)
(اختیاری) Docker برای استقرار containerized

📥 مرحله ۱ — نصب

الف) کلون پروژه

git clone https://github.com/ImMrShervin/store-ai-chatbot

یا اگر فایل‌ها را به‌صورت zip دارید، آن را اکسترکت کنید و وارد پوشه شوید.

ب) ایجاد محیط مجازی (Virtual Environment)

# Linux / macOS
python3 -m venv venv
source venv/bin/activate

# Windows (PowerShell)
python -m venv venv
venv\Scripts\Activate.ps1

# Windows (CMD)
python -m venv venv
venv\Scripts\activate.bat

ج) نصب پکیج‌ها

pip install --upgrade pip
pip install -r requirements.txt

🔑 مرحله ۲ — دریافت کلید API از Groq

Groq یک سرویس LLM بسیار سریع است که در پلن رایگان هم quota قابل‌قبولی می‌دهد.

به آدرس https://console.groq.com/keys بروید
با ایمیل یا گوگل اکانت رایگان بسازید
روی "Create API Key" کلیک کنید
یک نام برای کلید انتخاب کنید (مثلاً store-chatbot)
کلید تولیدشده را کپی کنید (فرمت آن gsk_... است)

⚙️ مرحله ۳ — تنظیم فایل `.env`

فایل نمونه را کپی کنید:

cp .env.example .env

سپس .env را با ویرایشگر باز کنید و مقادیر زیر را تنظیم کنید:

GROQ_API_KEY=gsk_کلیدی_که_از_Groq_گرفتید
GROQ_MODEL=llama-3.3-70b-versatile

FLASK_ENV=development
FLASK_HOST=0.0.0.0
FLASK_PORT=5000
FLASK_SECRET_KEY=یک_رشته_تصادفی_طولانی_برای_production

MAX_TOKENS=1024
TEMPERATURE=0.4
MAX_HISTORY_MESSAGES=20
SESSION_TIMEOUT_MINUTES=60

DATABASE_PATH=data/chatbot.db
STORE_CONFIG_PATH=data/store_config.json

RATE_LIMIT_PER_MINUTE=20

مدل‌های پیشنهادی Groq

مدل	توضیح	سرعت	کیفیت
`llama-3.3-70b-versatile` ⭐	پیش‌فرض — بهترین تعادل	خیلی خوب	عالی
`llama-3.1-8b-instant`	سبک، پاسخ خیلی سریع	فوق‌العاده	خوب
`mixtral-8x7b-32768`	context طولانی (32k)	خوب	خوب
`gemma2-9b-it`	جایگزین کم‌مصرف	عالی	خوب

🏪 مرحله ۴ — تنظیم اطلاعات فروشگاه (`store_config.json`)

این مهم‌ترین مرحله است. تمام «هویت» چت‌بات از این فایل می‌آید.

فایل data/store_config.json را باز کنید و اطلاعات فروشگاه واقعی خود را جایگزین مقادیر نمونه کنید. ساختار به این شکل است:

{
  "store": {
    "name": "نام فروشگاه شما",
    "name_en": "Your Store Name",
    "tagline": "شعار فروشگاه",
    "description": "توضیحات کامل فروشگاه",
    "established_year": 1400,
    "website": "https://your-store.com"
  },
  "contact": {
    "phone": "021-...",
    "mobile": "0912...",
    "email": "info@your-store.com",
    "address": "آدرس کامل",
    "instagram": "@your_store"
  },
  "business_hours": {
    "saturday": "9:00 - 21:00",
    ...
  },
  "categories": [
    { "id": "cat_1", "name": "...", "name_en": "..." }
  ],
  "products": [
    {
      "id": "prod_1",
      "name": "نام محصول",
      "category_id": "cat_1",
      "price": 1500000,
      "currency": "IRR",
      "stock": 25,
      "description": "...",
      "features": ["ویژگی ۱", "..."],
      "warranty_months": 12
    }
  ],
  "shipping": { ... },
  "payment_methods": [ ... ],
  "policies": { ... },
  "faq": [ ... ],
  "chatbot_settings": {
    "bot_name": "دستیار فروشگاه",
    "welcome_message": "سلام! 👋 من دستیار {store_name} هستم...",
    "off_topic_response": "من فقط به سوالات مرتبط با {store_name} پاسخ می‌دهم.",
    "primary_color": "#0ea5e9",
    "accent_color": "#0284c7"
  }
}

💡 نکات مهم

{store_name}: در فیلدهای welcome_message و off_topic_response به‌صورت خودکار با نام فروشگاه جایگزین می‌شود.
زبان دوگانه: فیلدهای _en برای پاسخ‌های انگلیسی به مشتریان استفاده می‌شوند.
قیمت‌ها: به ریال بنویسید (بدون کاما).
موجودی (stock): اگر ۰ باشد، چت‌بات محصول را ناموجود اعلام می‌کند.
Hot-reload: هر تغییری در این فایل انجام دهید، بدون restart سرور بلافاصله اعمال می‌شود ✨

🚀 مرحله ۵ — اجرای چت‌بات

حالت توسعه (Development)

python run.py

خروجی مورد انتظار:

============================================================
🚀 Store Chatbot running on http://0.0.0.0:5000
🤖 Model: llama-3.3-70b-versatile
📁 Store config: data/store_config.json
💾 Database:     data/chatbot.db
============================================================

حالا مرورگر را باز کنید و به آدرس زیر بروید:

👉 http://localhost:5000

حالت Production (با Gunicorn)

gunicorn "run:app" -b 0.0.0.0:5000 -w 4 --timeout 120

📡 استفاده از API

اگر می‌خواهید چت‌بات را در اپ خودتان جاسازی کنید:

۱) ایجاد session جدید

curl -X POST http://localhost:5000/api/chat/session/new

پاسخ:

{
  "session_id": "uuid-here",
  "welcome_message": "سلام! ...",
  "bot_name": "دستیار فروشگاه"
}

۲) ارسال پیام

curl -X POST http://localhost:5000/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"message":"سلام، محصولاتتون چیه؟","session_id":"uuid-here"}'

پاسخ:

{
  "reply": "سلام! ما در حال حاضر دو محصول داریم...",
  "session_id": "uuid-here",
  "tokens_used": 145,
  "model": "llama-3.3-70b-versatile"
}

۳) دریافت تاریخچه

curl http://localhost:5000/api/chat/session/<session_id>/history

۴) پاک‌کردن تاریخچه

curl -X POST http://localhost:5000/api/chat/session/<session_id>/clear

🔐 پنل ادمین

برای حفاظت از endpoint‌های ادمین، در .env این مقدار را اضافه کنید:

ADMIN_API_KEY=your_secret_admin_key

سپس در تمام درخواست‌های ادمین، هدر X-Admin-Key را ارسال کنید.

دریافت آمار

curl -H "X-Admin-Key: your_secret_admin_key" http://localhost:5000/api/admin/stats

به‌روزرسانی کانفیگ (بدون restart)

curl -X PUT http://localhost:5000/api/admin/config \
  -H "X-Admin-Key: your_secret_admin_key" \
  -H "Content-Type: application/json" \
  -d @data/store_config.json

🧪 تست

pip install pytest
pytest tests/ -v

🐳 استقرار (Deployment)

گزینه ۱: Docker Compose (پیشنهادی)

# ابتدا .env را تنظیم کنید
docker compose up -d --build

چت‌بات روی http://localhost:5000 در دسترس خواهد بود.

گزینه ۲: Docker ساده

docker build -t store-chatbot .
docker run -d -p 5000:5000 --env-file .env -v $(pwd)/data:/app/data store-chatbot

گزینه ۳: استقرار روی سرور (systemd)

فایل /etc/systemd/system/store-chatbot.service بسازید:

[Unit]
Description=Store Chatbot
After=network.target

[Service]
User=www-data
WorkingDirectory=/opt/store_chatbot
Environment="PATH=/opt/store_chatbot/venv/bin"
ExecStart=/opt/store_chatbot/venv/bin/gunicorn "run:app" -b 0.0.0.0:5000 -w 4
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now store-chatbot

گزینه ۴: Nginx + HTTPS

server {
    listen 443 ssl http2;
    server_name chat.your-store.com;

    ssl_certificate     /etc/letsencrypt/live/chat.your-store.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.your-store.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🩹 عیب‌یابی (Troubleshooting)

مشکل	راه‌حل
❌ `GROQ_API_KEY is not configured`	مطمئن شوید `.env` وجود دارد و `GROQ_API_KEY` مقدار درست دارد.
❌ `store_config.json not found`	مسیر فایل در `.env` را چک کنید یا فایل نمونه را در `data/` بسازید.
❌ `Rate limited` از Groq	مقدار `RATE_LIMIT_PER_MINUTE` را کاهش دهید یا به پلن بالاتر Groq بروید.
🌐 صفحه چت لود نمی‌شود	مطمئن شوید Flask روی پورت درست اجرا شده و فایروال باز است.
💬 چت‌بات به سؤالات فروشگاه پاسخ نمی‌دهد	‏`store_config.json` را دقیق پر کنید — هرچه کامل‌تر، پاسخ‌ها بهتر.
🇮🇷 پاسخ‌ها به زبان اشتباه	Prompt به‌صورت خودکار زبان را تشخیص می‌دهد. اگر مشکل ادامه دارد، سؤال را واضح‌تر بپرسید.
🔄 تغییرات در `store_config.json` اعمال نمی‌شود	فایل مستقیماً از disk خوانده می‌شود. اگر hot-reload کار نکرد، سرور را restart کنید.

📂 ساختار فایل‌ها

store_chatbot/
├── app/
│   ├── __init__.py           # App factory
│   ├── config.py             # Configuration
│   ├── models/
│   │   └── database.py       # SQLite layer
│   ├── routes/
│   │   ├── main.py           # Landing page
│   │   ├── chat.py           # Chat API
│   │   └── admin.py          # Admin API
│   └── services/
│       ├── groq_service.py      # Groq API wrapper
│       ├── store_service.py     # Config loader
│       ├── prompt_builder.py    # System prompt generator
│       ├── chat_service.py      # Orchestrator
│       └── rate_limiter.py      # In-memory rate limiter
├── data/
│   ├── store_config.json     # ★ Your store data
│   └── chatbot.db            # SQLite (auto-created)
├── static/
│   ├── css/style.css
│   └── js/chat.js
├── templates/
│   └── index.html
├── tests/
│   ├── test_prompt_builder.py
│   └── test_store_service.py
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── run.py                    # Entry point
└── README.md

🔒 توصیه‌های امنیتی برای Production

کلید ADMIN_API_KEY حتماً تنظیم شود.
FLASK_SECRET_KEY را با یک رشته تصادفی طولانی جایگزین کنید (python -c "import secrets;print(secrets.token_hex(32))").
CORS را در app/__init__.py روی دامنه واقعی خود محدود کنید.
Rate limiter در حال حاضر in-memory است — برای مقیاس بالا از Redis استفاده کنید.
HTTPS با Let's Encrypt استفاده کنید.

📜 مجوز

MIT License — آزادانه استفاده، تغییر و توزیع کنید.

ساخته شده با ❤️

اگر سوال یا پیشنهادی داشتید issue باز کنید

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
app		app
data		data
static		static
templates		templates
tests		tests
.env.example		.env.example
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt
run.py		run.py

Folders and files

Latest commit

History

Repository files navigation