پرش به محتوا
هوشی

حساب و محدودیت‌ها

محدودیت نرخ (Rate Limits)

هر کلید API یک سقف «درخواست در دقیقه» دارد که خودت در کنسول تعیینش می‌کنی. این سقف از سرویس تو در برابر حلقه‌های بی‌پایان و مصرف ناخواسته محافظت می‌کند.

نحوهٔ کار

  • سقف پیش‌فرض هر کلید جدید ۶۰ درخواست در دقیقه است و از کنسول بین ۱ تا ۳۰۰۰ قابل تغییر است.
  • شمارش برای هر کلید جداگانه و در پنجره‌های ۶۰ ثانیه‌ای انجام می‌شود که با اولین درخواست پنجره شروع می‌شوند.
  • همهٔ endpointهای احرازشده (API یکپارچه و بومی) شمرده می‌شوند؛ یک درخواست استریم هم فقط یک درخواست است.
  • GET /v1/models چون کلید نمی‌خواهد، مشمول این محدودیت نیست.
  • اگر به سقف بالاتری نیاز داری، چند کلید بساز یا سقف کلید را افزایش بده.

هدرهای پاسخ

هر پاسخ موفق (و هر پاسخ خطایی که بعد از احراز هویت تولید شود) این هدرها را دارد. این هدرها در CORS هم expose شده‌اند.

هدرتوضیح
X-RateLimit-Limitسقف درخواست در دقیقهٔ این کلید.
X-RateLimit-Remainingتعداد درخواست باقی‌مانده در پنجرهٔ فعلی.
Retry-Afterفقط در پاسخ 429: تعداد ثانیه تا آزاد شدن پنجره.
X-Request-Idشناسهٔ یکتای درخواست برای پیگیری.
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: chatcmpl-r1Vq9Lk2P0aZ...
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57

وقتی از سقف عبور کنی

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "error": {
    "message": "Rate limit exceeded for this key (60 req/min).",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

دو نوع 429

rate_limit_exceeded یعنی سقف کلید خودت پر شده. rate_limit_error یعنی پروایدر بالادستی محدودیت گذاشته و هوشی همهٔ مسیرهای جایگزین را امتحان کرده است؛ در این حالت با backoff صبر کن یا به مدل دیگری سوییچ کن.

مدیریت در کد

from openai import OpenAI

client = OpenAI(base_url="https://api.hooshi.ai/v1", api_key="hk-...")

raw = client.chat.completions.with_raw_response.create(
    model="openai/gpt-6-luna",
    messages=[{"role": "user", "content": "سلام"}],
)
print("remaining:", raw.headers.get("x-ratelimit-remaining"))
completion = raw.parse()

پیشنهادها برای حجم بالا

  • درخواست‌ها را با یک صف (مثلاً Redis + worker) و concurrency ثابت بفرست، نه با حلقهٔ موازی بی‌حد.
  • برای embedding، چند متن را در یک درخواست (input آرایه‌ای) بفرست.
  • هدر X-RateLimit-Remaining را بخوان و وقتی نزدیک صفر شد، سرعت را کم کن.
  • سقف نرخ را کنار سقف هزینهٔ ماهانه تنظیم کن تا هم از نظر سرعت و هم هزینه در امان باشی.