تحديد المعدل

تحمي الحدود المنصة من الذُّرى وتضمن خدمة منتظمة للجميع. تُطبَّق لكل مفتاح API، ويمكنكم تقسيمها بأنفسكم بين مستخدميكم النهائيين.

الحدّان#

الحدود حسب المستوى#

يرتبط المستوى بكل مفتاح ويُحدَّد عند إنشائه : إنه المستوى الافتراضي للمنصة، وهو standard حتى اليوم، بما في ذلك أول مفتاح في حساب جديد ودون شحن مسبق. ويظهر مستوى كل مفتاح في API keys. تحتاجون إلى المزيد؟ راسلونا من Help & Feedback مع تحديد الحجم المستهدف: الانتقال إلى pro مجاني، ويُستخدم فقط لحماية السعة المشتركة.

ترويسات الاستجابة#

تحمل استجابات نقاط النهاية التوليدية حالة نافذتكم الحالية (نقاط نهاية الاستشارة، مثل قائمة النماذج أو الرصيد، لا تحمل ذلك) :

X-Request-Id: 4334a6f1-5889-4999-92b6-8d8fb538dbe4
X-RateLimit-Limit-Requests: 300
X-RateLimit-Remaining-Requests: 287

احتفظوا بـX-Request-Id في سجلاتكم: إنه المرجع الذي يُقدَّم للدعم لإيجاد طلب محدد. إن أرسلتم بأنفسكم ترويسة X-Request-ID، تُعاد كما هي؛ مفيد لمطابقة آثاركم بآثارنا.

العزل حسب المستخدم النهائي#

إن كنتم تعرضون CloudZIR على عملائكم الخاصين، أرسلوا معرّفهم: تُحتسب نافذة RPM حينها بشكل منفصل لكل واحد منهم. المستخدم الذي يفرط في الاستخدام لم يعد يعطّل الآخرين.

{
  "model": "mina-low",
  "messages": [{"role": "user", "content": "Bonjour"}],
  "user": "client-4821"
}

{
  "model": "mina-low",
  "max_tokens": 512,
  "messages": [{"role": "user", "content": "Bonjour"}],
  "metadata": {"user_id": "client-4821"}
}

قيود : سلسلة أبجدية رقمية (الشرطة والشرطة السفلية مقبولتان)، 512 حرفًا كحد أقصى. لا تضعوا فيها أبدًا بيانات شخصية (بريد إلكتروني، هاتف) : استخدموا معرّفًا معتمًا.

حسن التعامل مع خطأ 429#

الرمز 429 ليس خطأً في شيفرتكم: إنه دعوة إلى تبطئة الوتيرة. احترموا Retry-After وأضيفوا انتظارًا أُسيًا مع jitter.

import random, time
import httpx

def appeler_avec_reprise(payload, cle, essais=5):
    for tentative in range(essais):
        r = httpx.post(
            "https://api.cloudzir.com/v1/chat/completions",
            headers={"Authorization": f"Bearer {cle}"},
            json=payload,
            timeout=120,
        )
        if r.status_code not in (429, 503):
            r.raise_for_status()
            return r.json()
        attente = float(r.headers.get("Retry-After", 2 ** tentative))
        time.sleep(attente + random.uniform(0, 0.5))   # jitter
    raise RuntimeError("Limite de débit persistante")

async function appelerAvecReprise(payload, cle, essais = 5) {
  for (let t = 0; t < essais; t++) {
    const r = await fetch("https://api.cloudzir.com/v1/chat/completions", {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${cle}` },
      body: JSON.stringify(payload),
    });
    if (r.status !== 429 && r.status !== 503) {
      if (!r.ok) throw new Error(await r.text());
      return r.json();
    }
    const attente = Number(r.headers.get("Retry-After") ?? 2 ** t) * 1000;
    await new Promise((res) => setTimeout(res, attente + Math.random() * 500));
  }
  throw new Error("Limite de débit persistante");
}

الانتظار أثناء الذُّرى#

حين يبدأ محرك بشكل بارد، يُبقى الاتصال مفتوحًا بدل قطعه :

• في البث المباشر : تُرسل تعليقات SSE : keep-alive كل 15 ثانية؛ عميل SSE لديكم يتجاهلها، فهي أسطر تعليق؛
• في غير البث : يبقى الطلب ببساطة في الانتظار.

احسبوا حساب مهلة عميل لا تقل عن 120 ثانية على mina-full : مهلة قصيرة جدًا تقطع طلبات كانت ستنجح (وستُفوترون بها رغم ذلك إن كان النموذج قد أنتج نصًا بالفعل).

عند تشبع كل السعة#

تُعيد واجهة API الرمز 503 overloaded مع Retry-After. هذه الاستجابة لا تُفوتَر أبدًا. عاملوها كخطأ 429 : أعيدوا المحاولة مع انتظار.