راهنمای اتصال OpenWebUI به API گپ جیپیتی
این راهنما برای زمانی است که میخواهید OpenWebUI را به عنوان رابط کاربری خودمیزبان استفاده کنید، اما مدلها، پرداخت ریالی، لاگ مصرف و مدیریت کلید را از API گپ جیپیتی بگیرید. OpenWebUI با APIهای سازگار با OpenAI کار میکند و اتصال اصلی گپ جیپیتی هم از همین مسیر انجام میشود.
نکته مهم: خود OpenWebUI میتواند روی سرور یا کامپیوتر شما اجرا شود، اما وقتی گپ جیپیتی را به عنوان Provider تنظیم میکنید، متن، تصویر، صدا و فایلهایی که برای مدل ارسال میشوند از OpenWebUI به API گپ جیپیتی فرستاده میشوند. بنابراین این حالت «کاملاً آفلاین» نیست.
۱. پیشنیازها
برای شروع به این موارد نیاز دارید:
- یک OpenWebUI نصبشده و در حال اجرا؛ مثلاً
http://localhost:3000 - دسترسی Admin در OpenWebUI، چون اتصال Provider از بخش Admin Settings انجام میشود
- یک کلید API از گپ جیپیتی
- اعتبار کافی در کیف پول API
برای ساخت کلید:
- وارد بخش کلیدهای API شوید.
- یک کلید جدید بسازید.
- کلید را همان لحظه در جای امن نگه دارید؛ این مقدار بعداً دوباره کامل نمایش داده نمیشود.
مقادیر اصلی اتصال:
| گزینه | مقدار |
|---|---|
| Base URL | https://api.gapgpt.app/v1 |
| Authentication | Bearer YOUR_GAPGPT_API_KEY |
| نوع اتصال در OpenWebUI | OpenAI-compatible / Standard |
| Azure | خاموش / استفاده نشود |
در فیلد API Key خود OpenWebUI فقط مقدار کلید گپ جیپیتی را وارد کنید؛ Bearer را به ابتدای آن اضافه نکنید. OpenWebUI هنگام درخواست، خودش Header را به شکل Bearer میسازد.
اگر در شبکه یا CDN خاصی نیاز به مسیر جایگزین دارید، در مستندات شروع سریع گپ جیپیتی مسیر https://api.gapapi.com/v1 هم به عنوان گزینه جایگزین ذکر شده است؛ اما برای شروع همان https://api.gapgpt.app/v1 را تنظیم کنید.
۲. نصب سریع OpenWebUI
اگر OpenWebUI را از قبل نصب نکردهاید، سادهترین مسیر Docker است:
docker run -d \
-p 3000:8080 \
--add-host=host.docker.internal:host-gateway \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
سپس آدرس زیر را باز کنید:
http://localhost:3000
روشهای دیگر مثل pip install open-webui یا uvx open-webui هم پشتیبانی میشوند. برای محیط production بهتر است از Docker یا نصب Python پایدار استفاده کنید و داده OpenWebUI را روی volume دائمی نگه دارید.
۳. اتصال مدلهای متنی و چت
این بخش اتصال اصلی OpenWebUI به مدلهای متنی، مدلهای vision و مدلهای دارای function calling است.
- در OpenWebUI وارد حساب Admin شوید.
- از پایین صفحه روی پروفایل خود کلیک کنید و وارد Admin Panel شوید.
- به مسیر Settings > Connections بروید.
- در بخش OpenAI روی گزینه Manage یا آیکن آچار کلیک کنید.
- روی Add New Connection بزنید.
- نوع اتصال را روی حالت Standard / Compatible بگذارید، نه Azure.
- این مقادیر را وارد کنید:
Connection Type: External
URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
- اگر فیلد API Version وجود دارد، آن را خالی بگذارید.
- اگر فقط میخواهید چند مدل مشخص دیده شوند، در Model IDs / Model IDs Filter نام دقیق مدلها را وارد کنید.
- ذخیره کنید.
OpenWebUI معمولاً مدلها را از مسیر GET /v1/models میخواند. گپ جیپیتی این مسیر را روی API عمومی پشتیبانی میکند. اگر لیست مدلها نمایش داده نشد یا میخواهید صفحه انتخاب مدل سبکتر باشد، مدلها را دستی در Model IDs Filter وارد کنید.
نمونه Model IDs:
gpt-4o
gpt-4o-mini
gemini-2.5-pro
gapgpt-deepseek-v4.1-flash
claude-sonnet-5
نام مدلها ممکن است تغییر کند. برای انتخاب دقیق مدل، همیشه صفحه مدلها و قیمتها را معیار قرار دهید.
نکته درباره Prefix ID
اگر در OpenWebUI فقط گپ جیپیتی را به عنوان OpenAI-compatible provider دارید، Prefix ID را خالی بگذارید. اگر چند Provider دارید و نام مدلها با هم تداخل دارند، میتوانید Prefix بگذارید، اما در این حالت همان نام prefixدار در Model Selector دیده میشود.
تست سریع اتصال
پس از ذخیره اتصال، یک چت جدید باز کنید و یکی از مدلهای گپ جیپیتی را از Model Selector انتخاب کنید. سپس پیام کوتاهی بفرستید:
سلام! خودت را در یک جمله معرفی کن.
اگر مدل پاسخ داد، اتصال چت درست است. اگر خطای 401 گرفتید، کلید API اشتباه است یا با Bearer درست ارسال نشده است. اگر مدلها دیده نمیشوند، Model IDs Filter را دستی تنظیم کنید.
۴. تنظیم با Environment Variable
اگر OpenWebUI را با Docker Compose یا Kubernetes اجرا میکنید، میتوانید اتصال گپ جیپیتی را از ابتدا با environment variable بسازید:
services:
open-webui:
image: ghcr.io/open-webui/open-webui:main
ports:
- "3000:8080"
volumes:
- open-webui:/app/backend/data
environment:
ENABLE_OPENAI_API: "True"
OPENAI_API_BASE_URLS: "https://api.gapgpt.app/v1"
OPENAI_API_KEYS: "YOUR_GAPGPT_API_KEY"
ENABLE_BASE_MODELS_CACHE: "True"
volumes:
open-webui:
اگر چند OpenAI-compatible provider دارید، OPENAI_API_BASE_URLS و OPENAI_API_KEYS را با ; جدا کنید و ترتیبشان را یکی نگه دارید:
OPENAI_API_BASE_URLS=https://api.openai.com/v1;https://api.gapgpt.app/v1
OPENAI_API_KEYS=OPENAI_KEY;GAPGPT_API_KEY
OpenWebUI بعضی تنظیمات را بعد از اجرای اول در دیتابیس خودش نگه میدارد. اگر یک مقدار را در env تغییر دادید ولی UI همچنان مقدار قبلی را نشان داد، از داخل Admin Panel مقدار را تغییر دهید یا فقط در صورتی که دقیقاً میدانید چه میکنید ENABLE_PERSISTENT_CONFIG=False بگذارید. در حالت دوم تغییرات UI بعد از restart باقی نمیمانند.
۵. مدلهای متنی، Vision و ابزارها
OpenWebUI برای چت معمولی از مسیر زیر استفاده میکند:
POST https://api.gapgpt.app/v1/chat/completions
این مسیر برای مدلهای متنی و بسیاری از مدلهای چندرسانهای استفاده میشود. نکات مهم:
- برای چت ساده، فقط مدل را انتخاب کنید و پیام بفرستید.
- برای ورودی تصویر، مدلی را انتخاب کنید که در صفحه قیمتها ورودی تصویر را پشتیبانی میکند.
- اگر از قابلیت Native Tool Calling در OpenWebUI استفاده میکنید، مدل انتخابی باید از
toolsوtool_choiceپشتیبانی کند. - اگر مدل کوچکتر یا ارزانتر با ابزارها خطا میدهد، در تنظیمات همان مدل در OpenWebUI، Native Function Calling یا Builtin Tools را غیرفعال کنید.
- برای گفتگوهای طولانی یا RAG، مدلی با context مناسب انتخاب کنید.
در گپ جیپیتی مسیر /v1/responses هم در API عمومی وجود دارد، اما اتصال معمول OpenWebUI برای OpenAI-compatible provider بر پایه Chat Completions است. فقط وقتی سراغ Open Responses بروید که در نسخه OpenWebUI شما اتصال Open Responses جداگانه فعال است و مدل مدنظر را جداگانه تست کردهاید.
۶. Embedding و RAG در OpenWebUI
OpenWebUI برای RAG میتواند Embedding را از OpenAI-compatible API بگیرد. در گپ جیپیتی مسیر مربوطه این است:
POST https://api.gapgpt.app/v1/embeddings
تنظیم از UI:
- وارد Admin Panel > Settings > Documents شوید.
- بخش Embedding را روی OpenAI یا OpenAI-compatible بگذارید.
- Base URL را وارد کنید:
https://api.gapgpt.app/v1
- API Key گپ جیپیتی را وارد کنید.
- مدل embedding را از صفحه مدلها و قیمتها انتخاب کنید؛ برای مثال اگر در لیست فعال بود:
gemini-embedding-001
تنظیم با env:
RAG_EMBEDDING_ENGINE=openai
RAG_OPENAI_API_BASE_URL=https://api.gapgpt.app/v1
RAG_OPENAI_API_KEY=YOUR_GAPGPT_API_KEY
RAG_EMBEDDING_MODEL=gemini-embedding-001
RAG_EMBEDDING_OPENAI_BATCH_SIZE=1
اگر مدل embedding انتخابی prefix خاصی برای document/query لازم دارد، فقط طبق مستندات همان مدل مقدارهای RAG_EMBEDDING_CONTENT_PREFIX و RAG_EMBEDDING_QUERY_PREFIX را تنظیم کنید. برای مدلهایی که چنین نیازی ندارند، این فیلدها را خالی بگذارید.
۷. تولید تصویر
تولید تصویر در OpenWebUI جدا از Provider چت تنظیم میشود. حتی اگر چت متنی کار میکند، برای تصویر باید بخش Images را هم فعال کنید.
- وارد Admin Panel > Settings > Images شوید.
- گزینه Image Generation را فعال کنید.
- مقدار Image Generation Engine را روی OpenAI یا Open AI بگذارید.
- این مقادیر را تنظیم کنید:
API Base URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
Image Generation Model: gpt-image-2
Image Size: 1024x1024
میتوانید به جای gpt-image-2 از هر مدل تصویری فعال در صفحه قیمتها استفاده کنید. برای مثال اگر در لیست شما فعال است، gapgpt/qwen-image-2.1 هم یک مدل تصویری گپ جیپیتی است.
نکته مهم درباره خروجی URL و Base64
در بسیاری از مدلهای تصویر گپ جیپیتی، پاسخ نهایی شامل URL فایل تولیدشده است. OpenWebUI برای مدلهایی که نامشان با gpt-image شروع میشود، طبق تنظیم پیشفرض خودش انتظار URL را درستتر مدیریت میکند. برای مدلهایی مثل gapgpt/qwen-image-2.1 که با gpt-image شروع نمیشوند، اگر OpenWebUI خطای مربوط به response_format: b64_json یا نمایش ندادن تصویر داد، این env را به الگوی مدلهای URL-based گسترش دهید:
IMAGE_URL_RESPONSE_MODELS_REGEX_PATTERN=^(gpt-image|gapgpt/qwen-image)
اگر از IMAGE_SIZE=auto استفاده میکنید، فقط برای مدلهایی این کار را انجام دهید که واقعاً اندازه auto را پشتیبانی میکنند. برای شروع، 1024x1024 انتخاب کمریسکتری است.
ویرایش تصویر
OpenWebUI قابلیت Image Editing هم دارد، اما پشتیبانی آن به مدل و endpoint بستگی دارد. اگر فقط تولید تصویر میخواهید، همین تنظیمات کافی است. اگر ویرایش تصویر میخواهید، در همان صفحه Images مقدارهای Image Edit Engine و Image Edit Model را فقط با مدلی تنظیم کنید که در گپ جیپیتی برای ویرایش تصویر تست شده یا در صفحه مدلها به عنوان مدل مناسب ویرایش معرفی شده باشد.
۸. Speech-to-Text یا تبدیل گفتار به متن
برای STT، OpenWebUI میتواند به جای Whisper محلی از OpenAI-compatible API استفاده کند. مسیر گپ جیپیتی:
POST https://api.gapgpt.app/v1/audio/transcriptions
تنظیم از UI:
- وارد Admin Panel > Settings > Audio شوید.
- در بخش Speech-to-Text مقدار Engine را روی OpenAI بگذارید.
- مقدارها را وارد کنید:
API Base URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
STT Model: gapgpt/whisper-1
Supported Content Types: خالی بگذارید یا audio/wav,audio/mpeg,audio/webm
تنظیم با env:
AUDIO_STT_ENGINE=openai
AUDIO_STT_OPENAI_API_BASE_URL=https://api.gapgpt.app/v1
AUDIO_STT_OPENAI_API_KEY=YOUR_GAPGPT_API_KEY
AUDIO_STT_MODEL=gapgpt/whisper-1
اگر فایل صوتی در OpenWebUI قبل از ارسال رد شد، مشکل ممکن است از پسوند فایل باشد، نه API. OpenWebUI برای STT فهرست پسوندهای مجاز دارد. فرمتهای کمریسک برای شروع: mp3، wav، m4a و webm.
۹. Text-to-Speech یا تبدیل متن به گفتار
برای TTS، OpenWebUI باید بتواند مدل را از مسیر OpenAI-compatible زیر صدا بزند:
POST https://api.gapgpt.app/v1/audio/speech
تنظیم از UI:
- وارد Admin Panel > Settings > Audio شوید.
- در بخش Text-to-Speech مقدار Engine را روی OpenAI بگذارید.
- مقدارها را وارد کنید:
API Base URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
TTS Model: نام مدل TTS سازگار با /v1/audio/speech
TTS Voice: alloy
تنظیم با env:
AUDIO_TTS_ENGINE=openai
AUDIO_TTS_OPENAI_API_BASE_URL=https://api.gapgpt.app/v1
AUDIO_TTS_OPENAI_API_KEY=YOUR_GAPGPT_API_KEY
AUDIO_TTS_MODEL=YOUR_TTS_MODEL
AUDIO_TTS_VOICE=alloy
قبل از تنظیم TTS در OpenWebUI، مدل TTS را در صفحه مدلها و قیمتها بررسی کنید. اگر یک مدل TTS در نمونه کدهای گپ جیپیتی با API بومی Gemini یا مسیر models/...:generateContent معرفی شده باشد، ممکن است برای OpenWebUI TTS مناسب نباشد، چون OpenWebUI در حالت OpenAI TTS مسیر /audio/speech را صدا میزند. برای OpenWebUI مدلی را انتخاب کنید که با /v1/audio/speech تست شده باشد.
برای تست، بعد از دریافت پاسخ از یک مدل متنی، روی آیکن بلندگو کنار پیام Assistant کلیک کنید. اگر صدا پخش نشد، Base URL، API Key، مدل، voice و دسترسی مرورگر به پخش صدا را بررسی کنید.
۱۰. ویدئو، موسیقی و قابلیتهای غیر استاندارد
OpenWebUI اتصال OpenAI-compatible را برای چت، مدلها، embedding، تصویر، STT و TTS به صورت آماده پشتیبانی میکند. اما ویدئو، موسیقی یا endpointهای اختصاصی دیگر معمولاً در UI استاندارد OpenWebUI دکمه و جریان آماده ندارند.
اگر میخواهید از مدلهای ویدئو یا موسیقی گپ جیپیتی داخل OpenWebUI استفاده کنید، سه مسیر امنتر دارید:
- یک Tool / Function در OpenWebUI بسازید که با HTTP به endpoint مورد نظر گپ جیپیتی درخواست بزند.
- از یک workflow بیرونی مثل n8n استفاده کنید و نتیجه را به OpenWebUI یا کاربر برگردانید.
- اگر نسخه OpenWebUI شما برای آن modality افزونه یا Action آماده دارد، آن را جداگانه تست کنید.
برای این قابلیتها صرفاً اضافه کردن Provider در Connections کافی نیست.
۱۱. چکلیست تست قبل از استفاده تیمی
قبل از اینکه OpenWebUI را برای چند کاربر باز کنید، این موارد را تست کنید:
- Model list: مدلها در Model Selector دیده میشوند یا Model IDs Filter دستی تنظیم شده است.
- Chat: یک درخواست ساده با
streamجواب میدهد. - Vision: اگر لازم دارید، یک تصویر کوچک با مدل vision تست شده است.
- RAG: یک فایل کوچک آپلود، پردازش و با مدل embedding انتخابی جستوجو شده است.
- Image: یک تصویر با مدل انتخابی تولید و در چت نمایش داده شده است.
- STT: یک فایل صوتی کوتاه با
gapgpt/whisper-1یا مدل STT انتخابی تبدیل شده است. - TTS: یک پاسخ Assistant با مدل TTS انتخابی به صدا تبدیل شده است.
- Cost: مصرف در صفحه آمار استفاده دیده میشود.
- Access: کاربران غیر Admin فقط به مدلهایی دسترسی دارند که میخواهید.
۱۲. خطایابی
مدلها در OpenWebUI دیده نمیشوند
- Base URL باید دقیقاً
https://api.gapgpt.app/v1باشد، نهhttps://gapgpt.app/api/v1. - API Key را دوباره بررسی کنید.
- اگر OpenWebUI در دریافت
/v1/modelsخطا دارد، Model IDs Filter را دستی پر کنید. - اگر چند provider دارید، Prefix ID یا مدلهای تکراری را بررسی کنید.
ENABLE_BASE_MODELS_CACHE=Trueمیتواند کندی بارگذاری لیست مدلها را کم کند.
خطای 401 یا 403 میگیرم
- کلید API را از بخش کلیدها دوباره بسازید.
- مطمئن شوید مقدار در OpenWebUI بدون
Bearerذخیره شده است؛ OpenWebUI خودش هنگام درخواست آن را به شکل Bearer ارسال میکند. - اعتبار کیف پول و محدودیت کلید را بررسی کنید.
چت کار میکند اما تصویر یا صدا کار نمیکند
اتصال چت فقط بخش Connections را تنظیم میکند. تصویر و صدا تنظیمات جدا دارند:
- تصویر: Admin Panel > Settings > Images
- STT/TTS: Admin Panel > Settings > Audio
- RAG/Embedding: Admin Panel > Settings > Documents
تصویر تولید میشود ولی در OpenWebUI نمایش داده نمیشود
- مدل را با
gpt-image-2تست کنید. - اگر از مدل URL-based دیگری استفاده میکنید،
IMAGE_URL_RESPONSE_MODELS_REGEX_PATTERNرا تنظیم کنید. - اندازه تصویر را از
1024x1024شروع کنید.
STT از مرورگر استفاده میکند و به گپ جیپیتی نمیرسد
در OpenWebUI دو نوع STT وجود دارد: تنظیم User-level مثل Web API که از قابلیت مرورگر استفاده میکند، و تنظیم Admin-level که backend را به OpenAI-compatible STT وصل میکند. برای استفاده از گپ جیپیتی باید Admin Panel > Settings > Audio را تنظیم کنید و AUDIO_STT_ENGINE=openai باشد.
۱۳. تست مستقیم با curl
اگر نمیدانید مشکل از OpenWebUI است یا API، بیرون از OpenWebUI تست کنید.
مدلها:
curl https://api.gapgpt.app/v1/models \
-H "Authorization: Bearer YOUR_GAPGPT_API_KEY"
چت:
curl https://api.gapgpt.app/v1/chat/completions \
-H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "سلام!"}]
}'
تصویر:
curl https://api.gapgpt.app/v1/images/generations \
-H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product photo on a white background",
"size": "1024x1024"
}'
تبدیل گفتار به متن:
curl https://api.gapgpt.app/v1/audio/transcriptions \
-H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
-F model="gapgpt/whisper-1" \
-F file="@audio.mp3"
تبدیل متن به گفتار:
curl https://api.gapgpt.app/v1/audio/speech \
-H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_TTS_MODEL",
"voice": "alloy",
"input": "سلام! این یک تست صداست."
}' \
--output speech.mp3
۱۴. منابع بیشتر
- دریافت و مدیریت کلید API
- مدلها و قیمتهای API گپ جیپیتی
- آمار استفاده API
- مستندات رسمی OpenWebUI
- راهنمای اتصال Provider در OpenWebUI
- راهنمای OpenAI-compatible در OpenWebUI
- تنظیمات Environment Variable در OpenWebUI
- تنظیم تصویر در OpenWebUI
- تنظیم STT در OpenWebUI
- تنظیم TTS در OpenWebUI
در صورت بروز مشکل، ابتدا تستهای curl بخش قبل را اجرا کنید. اگر curl موفق بود ولی OpenWebUI خطا داشت، مشکل معمولاً در مسیر تنظیمات جداگانه OpenWebUI، Model IDs Filter، یا تنظیمات Image/Audio/Documents است.