AITerminal

1. ۱ در صفحهٔ ارائه‌دهندگان سرویس اصلی را اضافه کنید (OpenAI، Anthropic، Gemini، OpenRouter، Cloudflare و…). چیپ‌های آماده Base URL و نوع احراز هویت را پر می‌کنند؛ فقط کلید API سرویس را وارد کنید. با «تست اتصال» از درستی تنظیمات مطمئن شوید.
2. ۲ در صفحهٔ مدل‌ها مدل تعریف کنید: «شناسهٔ عمومی» اسمی است که مشتری می‌فرستد (دلخواه شما) و «شناسهٔ مدل در سرویس اصلی» نام واقعی مدل است. قیمت و مدل‌های جایگزین را همین‌جا تعیین کنید.
3. ۳ در کلیدهای دسترسی برای هر مشتری یک کلید بسازید: مدت اعتبار (مثلاً پکیج ۱ ماهه)، سقف توکن/درخواست/هزینه و مدل‌های مجاز. بعد از ساخت، «اطلاعات اتصال» آمادهٔ ارسال به مشتری نمایش داده می‌شود.
4. ۴ با دکمهٔ تست در صفحهٔ مدل‌ها، پاسخ واقعی مدل را ببینید و در گزارش مصرف استفادهٔ مشتری‌ها را دنبال کنید.

کلید سرویس‌های اصلی فقط روی سرور ذخیره می‌شود و هرگز برای مشتری‌ها نمایش داده نمی‌شود؛ مشتری فقط کلید اختصاصی خودش (sk-ait-…) را می‌بیند.

سامانه هم‌زمان دو فرمت استاندارد را سرو می‌کند؛ لازم نیست برای هر ابزار تنظیم جدا بسازید:

• فرمت OpenAI (ZCode، Cursor، اکثر ابزارها): Base URL = https://دامنه-شما/v1 و کلید در هدر Authorization: Bearer
• فرمت Anthropic (Claude Code و…): Base URL = https://دامنه-شما (مسیر /v1/messages خودکار سرو می‌شود) و کلید در هدر x-api-key یا Authorization

تبدیل فرمت در هر دو جهت و به‌صورت کامل انجام می‌شود — پیام‌ها، تصاویر، فراخوانی ابزار (Tool Call) و استریم SSE. یعنی کلاینتی با فرمت Anthropic می‌تواند به مدلی که پشتش OpenAI/Gemini است وصل شود و برعکس.

curl https://your-domain.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ait-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"my-model","messages":[{"role":"user","content":"Hello"}]}'

مسیرهای موجود: POST /v1/chat/completions · POST /v1/messages · GET /v1/models · POST /v1/embeddings — همهٔ مسیرها بدون /v1 هم کار می‌کنند. هدر x-request-id در پاسخ برای پیگیری به پشتیبانی مفید است.

• نوع سرویس: «OpenAI سازگار» (اکثر سرویس‌ها) یا «Anthropic». اگر سرویس شما OpenAI-compatible باشد نوع OpenAI کافی است.
• نوع احراز هویت: Bearer (رایج)، x-api-key (آنتروپیک)، هدر سفارشی، پارامتر URL یا بدون احراز هویت.
• هدرها/فیلدهای اضافی: JSON دلخواهی که به هر درخواست به آن سرویس اضافه می‌شود (مثلاً تنظیمات خاص سرویس).
• غیرفعال‌ کردن یک ارائه‌دهنده تمام مدل‌هایش را فوری از سرویس خارج می‌کند بدون حذف تنظیمات.
• حذف ارائه‌دهنده‌ای که مدل متصل دارد مجاز نیست؛ اول مدل‌ها را حذف یا منتقل کنید.

• شناسهٔ عمومی فقط باید یکتا باشد؛ می‌توانید اسم دلخواه بگذارید (مثلاً gpt-4o که واقعاً به Gemini وصل شود).
• قیمت ورودی/خروجی به‌ازای هر ۱ میلیون توکن برای محاسبهٔ هزینهٔ دلاری هر کلید استفاده می‌شود.
• مدل‌های جایگزین (Fallback): اگر این مدل خطا داد یا قرنطینه شد، به‌ترتیب از این‌ها سرویس گرفته می‌شود.
• آستانهٔ قرنطینه / مدت قرنطینه / حداکثر تلاش مجدد / تایم‌اوت / RPM: رفتار هوشمند هر مدل را همین‌جا تنظیم کنید.
• ستون سلامت: سالم / در حال آزمون / قرنطینه. با «بازگردانی» دستی هم می‌توانید مدل قرنطینه‌شده را برگردانید.

هر کلید یک «اشتراک» است با این محدودیت‌ها (همگی اختیاری؛ صفر یا خالی = نامحدود):

• تاریخ انقضا — مثلاً پکیج ۱ ماهه. کلید منقضی فوری پاسخ 403 می‌گیرد.
• سقف توکن کل / تعداد درخواست / هزینهٔ دلاری — با رسیدن به سقف، درخواست بعدی 429 می‌گیرد.
• سقف توکن روزانه — هر روز از نصف‌شب (UTC) از نو حساب می‌شود.
• RPM — سقف درخواست در دقیقه؛ بیش از آن 429 با هدر Retry-After.
• مدل‌های مجاز — اگر انتخاب نشود همهٔ مدل‌های فعال مجازند.
• محدودیت آی‌پی — لیست آی‌پی یا بازهٔ CIDR (مثل 10.0.0.0/24).

تمدید: روی کلید (حتی منقضی) «ویرایش/تمدید» را بزنید. چیپ‌های «تمدید +۱ ماه/+۳ ماه/+۱ سال» اگر کلید منقضی شده از امروز و اگر فعال است از پایان اعتبار فعلی محاسبه می‌کنند. تیک «شروع مجدد شمارش مصرف» سهمیهٔ دورهٔ جدید را از صفر حساب می‌کند — مصرف دورهٔ قبل به سقف جدید اضافه نمی‌شود اما تاریخچهٔ کامل در گزارش‌ها می‌ماند. کلید و آدرس اتصال مشتری تغییر نمی‌کند.

• تلاش مجدد: خطاهای موقت آپستریم (429 و 5xx و تایم‌اوت) با فاصلهٔ افزایشی تا سقف «حداکثر تلاش مجدد» مدل دوباره امتحان می‌شوند.
• Fallback: اگر مدل اصلی پس از تلاش‌ها پاسخ نداد، به‌ترتیب از مدل‌های جایگزین سرویس گرفته می‌شود تا پاسخ مشتری هرگز قطع نشود.
• قرنطینهٔ هوشمند (Circuit Breaker): بعد از N خطای متوالی (پیش‌فرض ۵)، مدل از سرویس خارج می‌شود و در داشبورد با هشدار قرمز نمایش داده می‌شود. پس از دورهٔ سکون (پیش‌فرض ۳۰۰ ثانیه) یک درخواست آزمایشی عبور می‌کند؛ اگر موفق شد مدل به‌صورت خودکار برمی‌گردد. بازگردانی دستی هم با یک کلیک ممکن است.
• خطاهای 400/413/422 (مشکل از خود درخواست) تلاش مجدد نمی‌گیرند — مستقیم به مدل بعدی یا به کلاینت با توضیح برمی‌گردند.

هر خطا دو زبانه است (انگلیسی استاندارد + فارسی در فیلد message_fa) تا کاربر دقیقاً بداند مشکل کجاست:

• هر درخواست (موفق یا خطا) با زمان، کلید، مدل واقعی سرویس‌دهنده، وضعیت، توکن ورود/خروج، هزینهٔ دلاری، مدت پاسخ و آی‌پی ثبت می‌شود.
• علامت ≈ یعنی سرویس اصلی مصرف را گزارش نکرده و مقدار تخمینی است؛ علامت ⟐ یعنی پاسخ استریمی بوده.
• هزینه = (توکن ورود × قیمت ورودی + توکن خروج × قیمت خروجی) مدل، بر اساس قیمتی که در تنظیمات مدل وارد کرده‌اید.
• فیلترها: کلید، مدل، موفق/خطا، بازهٔ تاریخ؛ با صفحه‌بندی.
• لاگ‌های قدیمی‌تر از «مدت نگهداری» (تنظیمات) خودکار پاک می‌شوند.

• حساب مدیر: اولین کار بعد از نصب، تغییر رمز پیش‌فرض است (حداقل ۸ نویسه). رمزها به‌صورت Hash (PBKDF2) ذخیره می‌شوند.
• عنوان سرویس و آدرس عمومی: در مودال «اطلاعات اتصال» و متن آمادهٔ مشتری استفاده می‌شوند.
• حالت نگهداری: تمام درخواست‌های API موقتاً 503 می‌گیرند (برای ارتقا یا عیب‌یابی).
• پشتیبان‌گیری: «دریافت خروجی JSON» ارائه‌دهندگان و مدل‌ها را ذخیره می‌کند؛ برای بکاپ کامل، فایل دیتابیس را کپی کنید.
• امنیت: کلیدهای API مشتری‌ها برای قابلیت نمایش مجدد، آشکار در دیتابیس ذخیره می‌شوند — فایل دیتابیس و بکاپ‌ها را محرمات بدانید. سامانه را پشت HTTPS (Nginx/Caddy) منتشر کنید و دسترسی مستقیم اینترنت به پورت داخلی را نبازید.

• می‌توانم اسم دلخواه برای مدل بگذارم؟ بله؛ «شناسهٔ عمومی» هر نام یکتایی می‌تواند باشد و mapping به مدل واقعی در سامانه انجام می‌شود.
• اگر سرویس اصلی در ایران فیلتر است؟ سامانه را روی سرور خارج از ایران اجرا کنید؛ کلاینت‌ها فقط به دامنهٔ شما وصل می‌شوند و کلیدهای اصلی روی سرور می‌مانند.
• چند مدل پشتیبان می‌توانم بچینم؟ به هر تعداد؛ به‌ترتیب انتخاب consumed می‌شوند تا یکی پاسخ دهد.
• استریم و Tool Call پشتیبانی می‌شود؟ بله، در هر دو فرمت و حتی در حالت تبدیل فرمت.
• تمدید اشتراک کلید را عوض می‌کند؟ نه؛ همان کلید و همان آدرس باقی می‌ماند و مشتری متوجه چیزی نمی‌شود.
• اگر مصرف سرویس گزارش نشود؟ سامانه تخمین می‌زند (≈) تا سهمیه‌ها همیشه قابل اعمال بمانند.