راهنمای کامل Portal-AI Local-AI Connector
نسخه Connector Pack: 1.1.0

============================================================
1) این Connector چه کاری انجام می‌دهد؟
============================================================

این برنامه، LM Studio روی کامپیوتر یا سرور شما را به Portal-AI متصل می‌کند.

Connector فقط یک فایل اصلی دارد:

portal_ai_connector.py

لازم نیست خودتان مشخص کنید سایت از کدام روش اتصال استفاده می‌کند.
Connector در شروع کار به صورت امن از سایت سؤال می‌کند کدام روش فعال است و سپس همان روش را اجرا می‌کند.

روش‌های قابل تشخیص:

1. HTTPS Long Polling
2. HTTPS Short Polling
3. WebSocket Relay

اگر مدیر سایت بعداً روش اتصال را تغییر دهد، Connector پس از قطع اتصال، پاسخ ناسازگار یا زمان تشخیص مجدد، دوباره وضعیت سایت را بررسی می‌کند و روش جدید را انتخاب می‌کند.

Connector هرگز Token را در خروجی Console چاپ نمی‌کند.

============================================================
2) پیش‌نیاز مهم: نصب Python
============================================================

برای اجرای Connector باید Python روی سیستم نصب باشد.

پیشنهاد:

Python 3.9 یا جدیدتر

برای Windows:

1. وارد سایت رسمی Python شوید:

https://www.python.org/downloads/

2. Python را دانلود و نصب کنید.

3. در صفحه نصب Windows حتماً گزینه زیر را فعال کنید:

Add Python to PATH

4. بعد از نصب، Command Prompt را باز کنید و بنویسید:

python --version

اگر نسخه Python نمایش داده شد، نصب صحیح است.

اگر دستور python کار نکرد، این دستور را امتحان کنید:

py --version

برای Linux:

در بسیاری از توزیع‌ها Python از قبل نصب است.

بررسی:

python3 --version

در Ubuntu/Debian در صورت نیاز:

sudo apt update
sudo apt install python3 python3-pip

نکته مهم:
Connector خودش کتابخانه‌های Python مورد نیاز را بررسی می‌کند.
اگر سایت WebSocket را انتخاب کرده باشد و کتابخانه websocket-client نصب نباشد، Connector خودش تلاش می‌کند آن را با pip نصب کند.

اگر pip روی Python موجود نباشد، Connector ابتدا تلاش می‌کند با ensurepip آن را فعال کند.

در دو روش HTTPS کتابخانه خارجی لازم نیست و Connector از کتابخانه‌های داخلی Python استفاده می‌کند.

============================================================
3) نصب LM Studio
============================================================

1. LM Studio را از سایت رسمی آن دانلود و نصب کنید.

2. برنامه LM Studio را باز کنید.

3. یک مدل مناسب سیستم خود دانلود کنید.

پیشنهاد انتخاب مدل:

- سیستم با RAM کم: مدل‌های کوچک‌تر و Quantized
- سیستم متوسط: مدل‌های 7B تا 14B بسته به RAM/VRAM
- سیستم قوی: مدل‌های بزرگ‌تر

4. مدل را در LM Studio Load کنید.

5. Local Server یا API Server داخلی LM Studio را روشن کنید.

نام دقیق دکمه ممکن است بین نسخه‌های LM Studio کمی تفاوت داشته باشد، اما هدف این است که API سازگار با OpenAI روی سیستم شما اجرا شود.

آدرس پیش‌فرض مورد انتظار Connector:

http://127.0.0.1:1234/v1/chat/completions

اگر LM Studio را روی پورت دیگری اجرا کرده‌اید، آدرس را در config.json تغییر دهید.

مثال پورت 1235:

http://127.0.0.1:1235/v1/chat/completions

مهم:
قبل از اجرای Connector مطمئن شوید:

- مدل Load شده است
- Local Server روشن است
- Endpoint چت در دسترس است

============================================================
4) آماده‌سازی فایل Connector
============================================================

فایل ZIP را Extract کنید.

محتویات اصلی:

portal_ai_connector.py
config.example.json
run-windows.bat
run-linux.sh
راهنما.txt

بار اول در Windows می‌توانید run-windows.bat را اجرا کنید.
اگر config.json وجود نداشته باشد، فایل نمونه به config.json کپی می‌شود و برنامه از شما می‌خواهد ابتدا آن را ویرایش کنید.

در Linux نیز run-linux.sh همین کار را انجام می‌دهد.

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

config.example.json

به:

config.json

============================================================
5) تنظیم اتصال به Portal-AI.net
============================================================

اگر مقصد شما سرویس Portal-AI.net است، داخل config.json مقدار site_url را این‌طور بگذارید:

"site_url": "https://portal-ai.net"

سپس Connector ID و Connector Token اختصاصی خود را وارد کنید.

نمونه:

{
  "site_url": "https://portal-ai.net",
  "connector_id": "PASTE_CONNECTOR_ID_HERE",
  "connector_token": "PASTE_CONNECTOR_TOKEN_HERE",
  "lm_studio_url": "http://127.0.0.1:1234/v1/chat/completions"
}

مقادیر Connector ID و Connector Token را دقیقاً همان‌طور که برای حساب شما ارائه شده وارد کنید.

============================================================
6) تنظیم اتصال به سایت شخصی خودتان
============================================================

اگر Portal-AI روی سایت خودتان نصب است، فقط دامنه همان سایت را وارد کنید.

مثال:

"site_url": "https://example.com"

نمونه کامل:

{
  "site_url": "https://example.com",
  "connector_id": "PASTE_CONNECTOR_ID_HERE",
  "connector_token": "PASTE_CONNECTOR_TOKEN_HERE",
  "lm_studio_url": "http://127.0.0.1:1234/v1/chat/completions"
}

Connector خودش Endpoint کشف روش اتصال را از روی دامنه می‌سازد و نیازی نیست Pull URL، Result URL، Heartbeat URL یا WebSocket URL را دستی وارد کنید.

============================================================
7) فایل config.json و معنی فیلدها
============================================================

site_url
--------
آدرس Portal-AI مقصد.

مثال:

https://portal-ai.net

یا:

https://example.com

connector_id
------------
شناسه اختصاصی Connector شما.

connector_token
---------------
Token محرمانه Connector.
این مقدار را در اختیار شخص دیگری قرار ندهید.

lm_studio_url
-------------
آدرس API محلی LM Studio.
پیش‌فرض:

http://127.0.0.1:1234/v1/chat/completions

lm_studio_api_key
-----------------
اختیاری.
اگر برای Local Server خود API Key گذاشته‌اید، اینجا وارد کنید.
اگر نیاز ندارید خالی بگذارید.

device_name
-----------
نامی برای تشخیص دستگاه.
مثال:

Office-PC
Home-GPU
Server-1

verify_tls
----------
پیشنهاد: true

بررسی SSL سایت را فعال نگه می‌دارد.
در استفاده واقعی false نکنید.

heartbeat_seconds
-----------------
فاصله Heartbeat هنگام پردازش Job.
پیش‌فرض:

20

rediscover_seconds
------------------
Connector هر چند ثانیه یک بار در اتصال طولانی، روش فعال سایت را دوباره بررسی کند.
پیش‌فرض:

300

یعنی 5 دقیقه.

spool_dir
---------
محل نگهداری موقت نتیجه‌هایی که LM Studio تولید کرده ولی هنوز تحویل سایت نشده‌اند.
پیش‌فرض:

~/.portal-ai-local-connector/spool

============================================================
8) اجرای Connector در Windows
============================================================

روش ساده:

روی فایل زیر دوبار کلیک کنید:

run-windows.bat

اگر config.json وجود نداشته باشد، ساخته می‌شود.
آن را ویرایش کنید و دوباره run-windows.bat را اجرا کنید.

روش Command Prompt:

cd PATH_TO_CONNECTOR
python portal_ai_connector.py --config config.json

اگر سیستم شما به جای python از py استفاده می‌کند:

py portal_ai_connector.py --config config.json

============================================================
9) اجرای Connector در Linux
============================================================

ابتدا وارد پوشه Connector شوید:

cd /path/to/connector

اجرا:

./run-linux.sh

یا:

python3 portal_ai_connector.py --config config.json

برای اجرای طولانی‌مدت می‌توانید از systemd، Supervisor، tmux یا screen استفاده کنید.

============================================================
10) هنگام شروع چه اتفاقی می‌افتد؟
============================================================

مراحل خودکار:

1. config.json خوانده می‌شود.
2. آدرس Discovery امن ساخته می‌شود.
3. Connector ID و Token برای احراز هویت ارسال می‌شوند.
4. سایت روش فعال را اعلام می‌کند.
5. Connector همان روش را اجرا می‌کند.

مثال خروجی:

روش اتصال فعال سایت تشخیص داده شد: http_poll

یا:

روش اتصال فعال سایت تشخیص داده شد: http_pull

یا:

روش اتصال فعال سایت تشخیص داده شد: websocket

============================================================
11) تفاوت روش‌ها از نگاه کاربر Connector
============================================================

HTTPS Long Polling
------------------
Connector یک درخواست HTTPS می‌فرستد و سایت چند ثانیه برای Job منتظر می‌ماند.

HTTPS Short Polling
-------------------
درخواست سریع پاسخ می‌گیرد و Connector بعد از فاصله تعیین‌شده دوباره درخواست می‌فرستد.

WebSocket
---------
اتصال دائمی WebSocket برقرار می‌شود.
اگر کتابخانه websocket-client روی Python نصب نباشد، Connector خودش تلاش می‌کند آن را نصب کند.

شما لازم نیست یکی از این روش‌ها را در config.json انتخاب کنید.

============================================================
12) نصب خودکار کتابخانه‌ها
============================================================

این Connector تا جای ممکن Self-Bootstrap است.

برای HTTPS:

کتابخانه خارجی لازم نیست.

برای WebSocket:

اگر websocket-client وجود نداشته باشد:

1. Connector وجود pip را بررسی می‌کند.
2. اگر pip نبود، تلاش می‌کند ensurepip را اجرا کند.
3. سپس این پکیج را نصب می‌کند:

websocket-client>=1.7,<2

4. بعد از نصب، اتصال WebSocket ادامه پیدا می‌کند.

بنابراین معمولاً لازم نیست کاربر دستی pip install انجام دهد.

نیاز اصلی همچنان این است که Python روی سیستم نصب باشد.

============================================================
13) Spool چیست و چرا مهم است؟
============================================================

فرض کنید:

- LM Studio پاسخ را تولید کرده
- اینترنت در همان لحظه قطع شده

Connector نتیجه را داخل Spool محلی ذخیره می‌کند.

بعد از اتصال دوباره:

- نتیجه قبلی Replay می‌شود
- تا زمان تأیید تحویل، فایل حذف نمی‌شود

این کار احتمال اجرای دوباره مدل و گم‌شدن پاسخ را کاهش می‌دهد.

============================================================
14) Heartbeat و Lease
============================================================

وقتی یک Job طولانی در LM Studio در حال اجرا است، Connector Heartbeat می‌فرستد.

هدف:

- سایت بداند Connector زنده است
- Job بی‌دلیل منقضی نشود
- Lease پردازش تمدید شود

============================================================
15) تغییر روش اتصال توسط مدیر سایت
============================================================

لازم نیست config.json را تغییر دهید.

اگر روش سایت تغییر کند:

- Connector در تشخیص دوره‌ای دوباره وضعیت را می‌خواند
- یا اگر Endpoint قبلی دیگر معتبر نباشد دوباره Discovery می‌کند
- یا بعد از قطع WebSocket دوباره Discovery انجام می‌شود

سپس روش جدید خودکار انتخاب می‌شود.

============================================================
16) تست سریع LM Studio قبل از Connector
============================================================

ابتدا مطمئن شوید Local Server روشن است.

می‌توانید با ابزارهایی مثل curl یا Postman Endpoint را تست کنید.

نمونه کلی Request:

POST http://127.0.0.1:1234/v1/chat/completions
Content-Type: application/json

Body نمونه:

{
  "model": "MODEL_NAME",
  "messages": [
    {
      "role": "user",
      "content": "سلام"
    }
  ]
}

MODEL_NAME باید با مدلی که در LM Studio در دسترس است هماهنگ باشد.

اگر Portal-AI Payload را با نام مدل مناسب ارسال می‌کند، Connector همان Payload را بدون تبدیل غیرضروری به LM Studio می‌فرستد.

============================================================
17) خطاهای رایج
============================================================

خطا: config file not found
----------------------------
فایل config.json وجود ندارد.
config.example.json را به config.json کپی کنید.

خطا: missing config fields
---------------------------
یکی از مقادیر ضروری خالی است:

site_url
connector_id
connector_token
lm_studio_url

خطای 401
--------
Connector ID یا Token اشتباه است یا اتصال حساب معتبر نیست.

خطای 404 Discovery
------------------
ممکن است Local-AI روی سایت مقصد غیرفعال باشد یا نسخه سایت از Auto Discovery پشتیبانی نکند.

خطای SSL
--------
گواهی HTTPS سایت را بررسی کنید.
پیشنهاد نمی‌شود verify_tls را در استفاده واقعی خاموش کنید.

خطای LM Studio Connection Refused
---------------------------------
Local Server روشن نیست یا پورت اشتباه است.

بررسی کنید:

http://127.0.0.1:1234

یا پورتی که خودتان تنظیم کرده‌اید.

خطای websocket-client
----------------------
Connector معمولاً خودش آن را نصب می‌کند.
اگر نصب خودکار شکست خورد، اینترنت، دسترسی pip و مجوزهای Python را بررسی کنید.

خطای pip
--------
Python باید نصب کامل داشته باشد.
در Windows بهتر است Python رسمی از python.org نصب شود و Add Python to PATH فعال باشد.

============================================================
18) نکات امنیتی
============================================================

- Connector Token را منتشر نکنید.
- فایل config.json را عمومی نکنید.
- آن را داخل GitHub عمومی قرار ندهید.
- برای سایت واقعی از HTTPS استفاده کنید.
- verify_tls را true نگه دارید.
- Token در Console چاپ نمی‌شود.
- اگر Token لو رفت، آن را تعویض کنید.

============================================================
19) پیشنهاد اجرای دائم
============================================================

Windows:

- Task Scheduler
- NSSM
- اجرای دستی در Startup

Linux:

- systemd
- Supervisor
- tmux
- screen

برای استفاده حرفه‌ای، systemd یا Supervisor مناسب‌تر است.

============================================================
20) خلاصه شروع سریع
============================================================

1. Python را نصب کنید.
2. در Windows گزینه Add Python to PATH را فعال کنید.
3. LM Studio را نصب کنید.
4. مدل را دانلود و Load کنید.
5. Local Server را روشن کنید.
6. ZIP Connector را Extract کنید.
7. config.example.json را به config.json تبدیل کنید.
8. site_url را وارد کنید.
9. Connector ID را وارد کنید.
10. Connector Token را وارد کنید.
11. lm_studio_url را بررسی کنید.
12. run-windows.bat یا run-linux.sh را اجرا کنید.
13. Connector خودش روش فعال سایت را تشخیص می‌دهد.
14. اگر WebSocket نیاز باشد، کتابخانه لازم خودکار نصب می‌شود.

پایان راهنما
