unixscript / laravel-iran-ai-chatbot

v1.0.8 2026-09-05 15:33 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.2
• illuminate/http: ^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0

MIT

• Hossein Beiki

• laravel
• ai
• chatbot
• Gemini
• openai
• rag
• avalai
• gapgpt

Published on Packagist.org on 2026-09-05 18:09 UTC

README

یک پکیج جامع، سبک و حرفه‌ای برای راه‌اندازی دستیار هوشمند و چت‌بات در پروژه‌های لاراولی. این پکیج از سرویس‌دهنده‌های مختلف (AvalAI، GapGPT، OpenAI، Gemini و مدل‌های Local)، جستجوی آفلاین در دیتابیس (RAG بومی)، گاردریل‌های امنیتی و سیستم احراز هویت هوشمند پشتیبانی می‌کند.

ویژگی‌های کلیدی

• 🚀 معماری بدون دیتابیس برای تنظیمات (Zero DB Settings): تمام تنظیمات پایه‌ای، محدودیت‌ها و گاردریل‌ها از طریق فایل .env و config مدیریت می‌شوند.
• پشتیبانی از چندین درایور هوش مصنوعی: AvalAI, GapGPT, OpenAI, Gemini و مدل‌های لوکال (با قابلیت انتخاب مدل داینامیک).
• ظاهر کاربری (UI) پیشرفته و مستقل: کامپوننت Vue.js اختصاصی با قابلیت شخصی‌سازی کامل رنگ‌ها، متون، نحوه نمایش (پاپ‌آپ، سایدبار، تمام‌صفحه) توسط Props در فرانت‌اند همراه با انیمیشن‌های نرم (Transitions).
• جستجوی مستقیم دیتابیس (Native RAG): پیدا کردن محصولات و مقالات سایت و پیشنهاد آن‌ها به صورت اسلایدرهای افقی و عکس‌دار (Carousel) بدون نیاز به مصرف توکن API.
• امنیت و گاردریل‌ها: فیلتر اطلاعات حساس (PII Masking)، جلوگیری از حملات Prompt Injection و سیستم Moderation.
• تشخیص هوشمند کاربر (Smart Auth): مدیریت سشن‌ها برای مهمانان و اتصال تاریخچه چت به user_id برای کاربران لاگین شده به صورت کاملاً خودکار.

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

ابتدا پکیج را در پروژه خود نصب کنید:

composer require unixscript/laravel-iran-ai-chatbot

سپس فایل‌های پیکربندی و دارایی‌ها (Vue Components) را منتشر کرده و مایگریشن‌ها (صرفاً برای ذخیره تاریخچه چت‌ها) را اجرا کنید:

php artisan vendor:publish --provider="Unixscript\IranAiChatbot\IranAiServiceProvider"
php artisan migrate

۲. تنظیمات فایل .env (پیکربندی API و امکانات)

تمام تنظیمات حیاتی سیستم، کلیدهای API و فعال/غیرفعال کردن امکانات هوشمند مستقیماً از طریق فایل .env پروژه شما انجام می‌شود:

# ==========================================
# تنظیمات اصلی چت‌بات
# ==========================================
# درایور پیش‌فرض: (avalai, gapgpt, openai, gemini, local_offline)
IRAN_AI_DRIVER=gapgpt
# کلیدهای API سرویس‌دهنده‌ها
AVALAI_API_KEY=""
AVALAI_MODEL=""
GAPGPT_API_KEY=""
GAPGPT_MODEL="gpt-4o-mini"
OPENAI_API_KEY=""
OPENAI_MODEL=""
GEMINI_API_KEY=""
LOCAL_AI_ENDPOINT=""
LOCAL_AI_MODEL=""

# تنظیمات امنیتی، هوش مصنوعی و گاردریلها
IRAN_AI_RAG_ENABLED=true
IRAN_AI_PII_MASKING=true
IRAN_AI_PROMPT_INJECTION=true
IRAN_AI_MODERATION=true
IRAN_AI_MODELS_SEARCH=true

# تنظیمات محدودیت کاربری و لاگین
IRAN_AI_AUTH_REQUIRED=false
IRAN_AI_QUOTA_ENABLED=false
IRAN_AI_MAX_QUESTIONS=20
IRAN_AI_SEARCH_LIMIT=20

IRAN_AI_SYSTEM_PROMPT="شما یک دستیار هوشمند و مودب هستید. به سوالات کاربر به زبان فارسی و با احترام پاسخ دهید."

۳. اتصال به دیتابیس (پیشنهاد محصولات به صورت کارت‌های لینک‌دار)

برای اینکه ربات بتواند در محصولات شما جستجو کند و نتایج را به صورت کارت‌های قابل کلیک نمایش دهد، فایل config/iran-ai-chatbot.php را باز کنید و بخش searchable_models را مقداردهی کنید:

'models_search' => [
    'max_results' => env('IRAN_AI_SEARCH_LIMIT', 4),
    'searchable_models' => [
        \App\Models\Product::class => [
            'columns' => ['title', 'description'], // ستون‌هایی که باید سرچ شوند
            'label' => 'محصول', // نامی که به عنوان بج (Badge) روی کارت نمایش داده می‌شود
            'url_template' => '/products/{id}/{slug}' // الگوی لینک محصول برای باز شدن در تب جدید
        ],
    ]
],

۴. نحوه استفاده در فرانت‌اند (Vue 3) و سناریوهای نمایش

ویجت چت‌بات به عنوان یک کامپوننت Vue طراحی شده است. تمام ظاهر، متون و پیام‌ها مستقیماً از طریق پراپ‌ها (Props) قابل شخصی‌سازی است. تنظیماتی که در فایل کانفیگ به عنوان ui قرار دارند، صرفاً مقادیر پیش‌فرض (Fallback) هستند.

ابتدا کامپوننت را در فایل app.js رجیستر کنید:

import ChatWidget from './vendor/iran-ai-chatbot/ChatWidget.vue';
app.component('chat-widget', ChatWidget);

حالت‌های مختلف نمایش (Scenarios)

شما می‌توانید بسته به نیاز هر صفحه از سایت، چت‌بات را در شکل‌های متفاوتی فراخوانی کنید:

حالت اول: پاپ‌آپ شناور استاندارد (پیش‌فرض) این حالت برای نمایش یک دکمه شناور در گوشه سایت استفاده می‌شود (با قابلیت شخصی‌سازی کامل پیام‌ها):

<chat-widget
    color="#e11d48"
    title="پشتیبانی ویژه"
    position="left"
    display-mode="popup"
    
    initial-message="سلام دوست من! 👋 من دستیار هوشمند فروشگاه هستم. دنبال چه محصولی می‌گردی؟"
    placeholder-text="نام محصول یا سوالت رو اینجا بنویس..."
    
    login-text="کاربر عزیز، لطفا برای پرسیدن سوال ابتدا"
    login-link-text="وارد حساب کاربری خود شوید."
    login-url="/panel/login"
    
    error-text="ارتباط با سرور قطع شد، لطفا چند دقیقه دیگر تلاش کنید."
    rate-limit-text="تعداد پیام‌های شما امروز به اتمام رسیده است."
></chat-widget>

حالت دوم: صفحه اختصاصی تمام‌صفحه (Fullscreen) مناسب برای زمانی که می‌خواهید یک صفحه مجزا (مثلاً /support) فقط برای چت‌بات بسازید. در این حالت دکمه‌های شناور و بستن مخفی می‌شوند:

<chat-widget
    display-mode="fullscreen"
    :default-open="true"
    :hide-fab="true"
    :hide-close-button="true"
></chat-widget>

حالت سوم: باز شدن از طریق دکمه‌های دلخواه سایت (منوی Bottom Nav) اگر می‌خواهید دکمه دایره‌ای پیش‌فرض مخفی باشد و ربات با کلیک روی منوی اختصاصی قالب شما باز شود:

<!-- ۱. قرار دادن ویجت به صورت مخفی در Layout -->
<chat-widget display-mode="sidebar" :hide-fab="true"></chat-widget>

<!-- ۲. باز کردن ربات با دکمه دلخواه شما در فایل Blade -->
<button onclick="window.dispatchEvent(new CustomEvent('toggle-ai-chat'))">
    💬 چت با پشتیبانی
</button>

حالت چهارم: درون‌خطی و ثابت (Inline) برای قرار دادن چت‌بات به صورت ثابت در وسط یک صفحه وبلاگ یا داخل یک فرم:

<div class="col-md-8 mx-auto">
    <chat-widget :inline="true" color="#10b981"></chat-widget>
</div>

حالت پنجم: باز کردن با بنر و لینک (بدون نیاز به نوشتن کد جاوااسکریپت) اگر در سیستم مدیریت محتوای سایت خود (مثلاً بخش تنظیمات بنرها) فقط امکان وارد کردن لینک (URL) را دارید، می‌توانید به سادگی از ترفند زیر استفاده کنید تا چت‌بات باز شود:

javascript:window.dispatchEvent(new CustomEvent('open-ai-chat'))

(با قرار دادن کد بالا در فیلد لینک، مرورگر به جای انتقال کاربر به صفحه دیگر، چت‌بات را در همان صفحه باز می‌کند).

لیست کامل پراپ‌های (Props) کنترلی و ظاهری:

نام پراپ	نوع	پیش‌فرض	توضیحات
color	String	(از کانفیگ)	رنگ اصلی چت‌بات (هدر، دکمه‌ها و...)
title	String	(از کانفیگ)	عنوان بالای چت‌بات
display-mode	String	popup	نحوه نمایش (popup, sidebar, fullscreen)
position	String	right	موقعیت ویجت شناور (left یا right)
inline	Boolean	false	نمایش درون‌خطی و ثابت به جای حالت شناور
hide-fab	Boolean	false	مخفی کردن دکمه دایره‌ای شناور پیش‌فرض
default-open	Boolean	false	باز بودن ویجت به محض بارگذاری صفحه
hide-close-button	Boolean	false	مخفی کردن دکمه ضربدر در هدر ربات
save-history	Boolean	true	ذخیره خودکار چت‌ها در LocalStorage مرورگر
initial-message	String	(پیام سلام)	پیام پیش‌فرض ربات در ابتدای باز شدن
placeholder-text	String	پیام...	متن پس‌زمینه فیلد ورودی پیام
login-text	String	(متن پیش‌فرض)	متن هشدار قبل از لینک ورود به سایت
login-link-text	String	وارد سایت شوید	کلمه‌ای که لینک‌دار می‌شود و کاربر روی آن کلیک می‌کند
login-url	String	/login	آدرس صفحه‌ای که کاربر برای لاگین باید به آن هدایت شود
error-text	String	(متن پیش‌فرض)	پیامی که در صورت قطعی اینترنت یا خطای سرور نمایش داده می‌شود
rate-limit-text	String	(متن پیش‌فرض)	پیامی که در صورت پر شدن سقف سوالات روزانه کاربر نمایش داده می‌شود

۵. مدیریت کاربران (Smart Auth)

سیستم به صورت کاملاً هوشمند با Auth لاراول درگیر می‌شود:

• مدیریت مهمانان: اگر auth_required برابر با false باشد، مکالمات مهمانان با استفاده از شناسه‌های امن کوکی مدیریت و ذخیره می‌شوند.
• مدیریت کاربران لاگین شده: در صورت تشخیص لاگین بودن کاربر، پیام‌ها مستقیماً با user_id آن‌ها ذخیره می‌شود تا در دستگاه‌های دیگر نیز به تاریخچه خود دسترسی داشته باشند.