قوانین کلید و گروه مدل

هر کلید API در هوشوانا می‌تواند قوانین خودش را داشته باشد: چه مدل‌هایی را صدا بزند، چقدر خرج کند، از کجا استفاده شود و تا کی معتبر باشد. علاوه بر آن، قوانین سطح حساب روی همه‌ی کلیدها اعمال می‌شوند. این صفحه همه‌ی قوانین را با یک سناریوی واقعی توضیح می‌دهد.

قوانین حساب و قوانین کلید

• قوانین حساب مرز بیرونی هستند و روی همه‌ی کلیدهای شما اعمال می‌شوند.
• قوانین کلید فقط می‌توانند این مرز را تنگ‌تر کنند، نه گشادتر.

مثلاً اگر در حساب، ارائه‌دهنده‌ی xAI را غیرفعال کرده باشید، هیچ کلیدی نمی‌تواند مدل‌های xAI را صدا بزند، حتی اگر در قوانین آن کلید مجاز شده باشد. یا اگر سقف هزینه‌ی ماهانه‌ی حساب یک میلیون تومان باشد، کلیدی با سقف دو میلیون تومان در عمل از یک میلیون بیشتر خرج نمی‌کند.

قوانین سطح حساب

قوانین کلید با سناریو

مدل‌ها و گروه‌های مجاز

کلید را به چند مدل یا گروه مدل محدود کنید. سناریو: تیم پشتیبانی شما فقط به یک مدل ارزان برای پاسخ به تیکت‌ها نیاز دارد. کلید را به openai/gpt-4o-mini محدود می‌کنید تا اگر کسی اشتباهاً مدل گران‌تری را در کد گذاشت، درخواست با model_not_allowed رد شود.

endpointهای مجاز

endpointهای قابل انتخاب: chat، responses، messages، embeddings، images، speech، transcriptions و kb. سناریو: سرویس جستجوی معنایی شما فقط embedding می‌سازد. کلید آن را فقط به embeddings محدود کنید. هر درخواست دیگری با endpoint_not_allowed رد می‌شود.

سقف هزینه‌ی روزانه و ماهانه

مبلغ را به تومان وارد می‌کنید. سناریو: یک ربات تلگرامی آزمایشی دارید و نمی‌خواهید یک حلقه‌ی بی‌پایان در کد کل کیف پول را خالی کند. سقف روزانه‌ی ۲۰٬۰۰۰ تومان می‌گذارید. پس از رسیدن به سقف، درخواست‌ها با spend_cap_reached (HTTP ۴۰۲) رد می‌شوند تا روز بعد.

بودجه‌ی کل

سقفی برای کل عمر کلید. سناریو: به یک فریلنسر برای یک پروژه‌ی دوهفته‌ای کلید می‌دهید و بودجه‌ی کل ۵۰۰٬۰۰۰ تومان تعیین می‌کنید. بعد از مصرف این مبلغ کلید دیگر خرج نمی‌کند.

محدودیت RPM و TPM

حداکثر تعداد درخواست و توکن در دقیقه. سناریو: یک اسکریپت پردازش دسته‌ای دارید که نباید سهم سرویس اصلی را بگیرد. روی کلید اسکریپت RPM را ۳۰ می‌گذارید. درخواست‌های اضافه با rate_limited (HTTP ۴۲۹) و هدر Retry-After رد می‌شوند. جزئیات در محدودیت نرخ.

فهرست IP مجاز

یک IP دقیق یا محدوده‌ی CIDR. سناریو: کلید سرور تولید را به 203.0.113.10 یا 203.0.113.0/24 محدود می‌کنید. حتی اگر کلید لو برود، از جای دیگری قابل استفاده نیست و خطای ip_not_allowed برمی‌گردد.

فهرست referrer مجاز

نام دامنه‌هایی که درخواست می‌تواند از آن‌ها بیاید. سناریو: یک دمو روی demo.example.ir دارید. این لایه برای کاهش سوءاستفاده‌ی ساده مفید است، ولی هدر referrer قابل جعل است و جایگزین پراکسی سمت سرور نیست.

تاریخ انقضا

سناریو: کلید یک کارگاه آموزشی را تا پایان هفته معتبر می‌کنید. بعد از آن تاریخ، درخواست‌ها با key_expired رد می‌شوند و لازم نیست یادتان بماند کلید را باطل کنید.

سقف max_tokens هر درخواست

اگر درخواست مقدار max_tokens بزرگ‌تری بخواهد، به این سقف کاهش داده می‌شود (رد نمی‌شود). سناریو: جلوگیری از پاسخ‌های بسیار طولانی و پرهزینه در یک چت‌بات عمومی.

مدل پیش‌فرض

اگر درخواست فیلد model نداشته باشد، از این مدل استفاده می‌شود. سناریو: ابزار داخلی شما مدل را مشخص نمی‌کند و می‌خواهید بعداً بدون تغییر کد مدل را عوض کنید.

ثبت بدنه‌ی درخواست

تنظیم حساب برای ثبت متن درخواست و پاسخ را برای این کلید بازنویسی می‌کند. سناریو: برای کلید محیط توسعه ثبت بدنه را روشن می‌کنید تا اشکال‌زدایی ساده باشد، ولی برای کلید تولید که داده‌ی کاربران را جابه‌جا می‌کند خاموش می‌ماند. بیشتر در لاگ درخواست‌ها.

پایگاه دانش متصل

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

وضعیت کلید

فعال، متوقف (key_paused) یا باطل‌شده (invalid_api_key).

ترتیب ارزیابی

قوانین به این ترتیب بررسی می‌شوند و اولین قانونی که برقرار نباشد، خطای مربوط به خودش را برمی‌گرداند:

1. فعال بودن و منقضی نبودن کلید (invalid_api_key، key_paused، key_expired)
2. IP و referrer (ip_not_allowed)
3. endpoint مجاز (endpoint_not_allowed)
4. تعیین مدل: نام مستعار، مدل پیش‌فرض کلید یا مدل پیش‌فرض گروه (model_not_found)
5. مجاز بودن مدل در کلید و حساب (model_not_allowed)
6. محدودیت نرخ (rate_limited)
7. سقف هزینه (spend_cap_reached)
8. موجودی کیف پول (insufficient_balance)

این ترتیب در اشکال‌زدایی کمک می‌کند. مثلاً اگر خطای rate_limited می‌گیرید، یعنی کلید، IP، endpoint و مدل همه درست بوده‌اند.

گروه‌های مدل

گروه مدل مجموعه‌ای از مدل‌ها با یک مدل پیش‌فرض است. به جای این‌که ده مدل را یکی‌یکی در قوانین کلید وارد کنید، کلید را به یک گروه محدود می‌کنید.

گروه‌های سیستمی

هوشوانا این گروه‌ها را نگهداری و به‌روز می‌کند: محبوب، کدنویسی، تولید محتوا، اقتصادی، بینایی، صدا و استدلال. وقتی مدل مناسب جدیدی منتشر شود، به گروه مربوط اضافه می‌شود و کلیدهای محدود به آن گروه بدون تغییر به آن دسترسی پیدا می‌کنند.

گروه‌های سفارشی

در داشبورد می‌توانید گروه خودتان را بسازید، مثلاً «مدل‌های تأییدشده‌ی تیم» شامل سه مدل مشخص، و یکی را مدل پیش‌فرض گروه کنید.

استفاده از گروه در درخواست

می‌توانید به جای شناسه‌ی مدل، نام گروه را بفرستید. در این حالت مدل پیش‌فرض آن گروه استفاده می‌شود:

{
  "model": "group:coding",
  "messages": [{ "role": "user", "content": "Write a Python function that validates an Iranian national ID." }]
}

اگر درخواست اصلاً model نداشته باشد و کلید به یک گروه محدود باشد، مدل پیش‌فرض کلید یا گروه استفاده می‌شود. شناسه‌ی مدل واقعی‌ای که پاسخ داده است در فیلد model پاسخ و در لاگ‌ها دیده می‌شود.

پیشنهادهای کاربردی

• برای هر سرویس یک کلید با حداقل دسترسی لازم بسازید.
• روی همه‌ی کلیدهای تولید سقف هزینه‌ی روزانه بگذارید، حتی اگر عدد بزرگی باشد.
• کلیدهای سرور را به IP سرور محدود کنید.
• آستانه‌ی هشدار موجودی کم را در حساب فعال کنید تا سرویس به خاطر تمام شدن اعتبار متوقف نشود.