اتصال Open WebUI به API پیکو هوش؛ ساخت چت‌بات اختصاصی

افزودن از رابط کاربری

اگر متغیر محیطی نمی‌گذارید: وارد حساب ادمین شوید و مطابق مستندات رسمی به Settings > Admin > Connections بروید (در بخش Manage OpenAI API Connections)، روی Add Connection بزنید و این مقادیر را وارد کنید: URL برابر https://api.picoai.ir/v1 (بدون اسلش پایانی) و API Key برابر YOUR_API_KEY. سپس Verify Connection را بزنید و Save کنید. توجه: ذخیره‌کردن اتصال را تست نمی‌کند و Verify نیز مسیر /models را صدا می‌زند؛ اگر این بررسی برای ارائه‌دهنده‌ای شکست بخورد ولی چت کار کند، شناسه‌ی مدل‌ها را دستی در فیلد Model IDs اضافه کنید. با پیش‌فرض ENABLE_PERSISTENT_CONFIG=True، مقادیر ذخیره‌شده در پنل ادمین بر متغیرهای محیطی اولویت دارند.

انتخاب مدل‌ها

Open WebUI فهرست مدل‌ها را از /v1/models می‌خواند. در بین نتایج، مدل‌های چت را استفاده کنید؛ مدل‌های تصویر و صدا برای گفتگوی متنی مناسب نیستند. اگر فهرست شلوغ بود، در تنظیمات همان اتصال در فیلد Model IDs (allowlist) فقط شناسه‌های دلخواه را بنویسید تا فقط مدل‌هایی مثل gpt-6-sol، claude-sonnet-5-5 و claude-haiku-5-5 دیده شوند. فهرست کامل: کاتالوگ.

مدیریت کاربران و هزینه

نکته‌ی مهم این است که تمام کاربران Open WebUI با یک کلید مصرف می‌کنند. بنابراین:

1. برای این سرویس یک کلید جدا بسازید و سقف ماهانه و سقف درخواست در دقیقه بگذارید.
2. ثبت‌نام عمومی را ببندید (ENABLE_SIGNUP=false) یا تأیید دستی را فعال کنید.
3. گروه‌ها و دسترسی مدل‌ها را محدود کنید تا کاربران عادی به گران‌ترین مدل‌ها دسترسی نداشته باشند.
4. مصرف را در داشبورد پیکو هوش و در این راهنما پیگیری کنید.

قابلیت‌هایی که به embeddings نیاز دارند

بخش RAG و «دانش» (بارگذاری سند و پرسش از آن) در Open WebUI به یک مدل embedding نیاز دارد. به‌طور پیش‌فرض از مدل محلی داخلی استفاده می‌کند؛ اما اگر آن را روی OpenAI تنظیم کنید با پیکو هوش کار نمی‌کند، چون پیکو هوش اندپوینت embeddings ندارد. تنظیم پیش‌فرض (محلی) را نگه دارید. همچنین ویژگی‌های تولید تصویر یا صدای Open WebUI را فقط در صورت تنظیم جداگانه و سازگاری اندپوینت‌ها فعال کنید و آن را با تست بسنجید؛ مسیرهای تصویر و TTS پیکو هوش در مستندات آمده است.

عیب‌یابی

به‌روزرسانی و پشتیبان‌گیری

برای به‌روزرسانی، تصویر جدید را pull کنید و کانتینر را دوباره بسازید؛ چون داده‌ها در volume هستند، چت‌ها و کاربران حفظ می‌شوند. پیش از ارتقا از volume پشتیبان بگیرید. تنظیمات اتصال در دیتابیس ذخیره می‌شود و تغییر متغیر محیطی پس از اولین اجرا ممکن است اثر نکند؛ در این حالت از پنل ادمین تغییر دهید.

پروکسی معکوس و HTTPS

برای دسترسی عمومی، Open WebUI را پشت Nginx یا Caddy با HTTPS بگذارید. نمونه‌ی Nginx برای پشتیبانی از استریم و WebSocket:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

پرامپت‌های آماده و مدل‌های سفارشی

در Open WebUI می‌توانید «مدل سفارشی» بسازید: یک مدل پایه (مثلاً claude-sonnet-5-5) به‌همراه پرامپت سیستم ثابت و پارامترها. برای مثال یک «دستیار نویسنده‌ی فارسی» یا «بازبین کد». این مدل‌ها در فهرست کاربران ظاهر می‌شوند و نیازی نیست هر کاربر پرامپت را تکرار کند. با محدودکردن دسترسی هر مدل سفارشی به گروه‌های مشخص، هم تجربه‌ی کاربر بهتر می‌شود و هم هزینه قابل کنترل می‌ماند. قیمت مدل‌های پایه را از pricing و ویژگی‌ها را از کاتالوگ بخوانید.

سوالات متداول

آیا داده‌های گفتگو روی سرور خودم می‌ماند؟

تاریخچه‌ی چت در دیتابیس Open WebUI روی سرور شما ذخیره می‌شود؛ اما متن درخواست‌ها برای تولید پاسخ به پیکو هوش ارسال می‌شود.

آیا می‌توان چند مدل را مقایسه کرد؟

بله، Open WebUI قابلیت چت هم‌زمان با چند مدل دارد.

آیا باید Docker نصب کنم؟

روش Docker ساده‌ترین است؛ نصب با pip هم در مستندات پروژه هست.

مرجع؟

Open WebUI در یکپارچه‌سازی‌ها، مستندات.