# حدود المعدّل

> معدلات الطلبات، وحدود المحادثات، وحدود الأحجام، والترويسات التي يرسلها K-Agent حين تبلغ أحدها — وكيف تتعامل معها.

تحافظ الحدود على سرعة المنصة للجميع، وتحميك من التكاليف الجامحة ومن إساءة الاستخدام. وحين تبلغ أحدها تحصل على خطأ واضح برمز ثابت، ومعه ترويسة `Retry-After` حيث يفيد الانتظار.

## معدلات الطلبات

| مَن | الحد | عند التجاوز |
|---|---|---|
| المفتاح السري | 600 طلب في الدقيقة لكل مفتاح | `429 rate_limited` |
| المفتاح القابل للنشر (الودجت) | 60 طلبًا في الدقيقة لكل عنوان IP، و20 رسالة في الدقيقة لكل جهاز | `429 rate_limited` |
| تسجيل الدخول إلى لوحة التحكم | 10 محاولات في الدقيقة لكل عنوان IP، ولكل بريد | `429 rate_limited` |
| إنشاء الحسابات | 5 في اليوم لكل عنوان IP | `429 rate_limited` |

## حدود المحادثات

| ماذا | الحد | عند التجاوز |
|---|---|---|
| الرسائل المنتظرة في جلسة واحدة (`queue`) | 10 | `409 session_queue_full` |
| رسالة تصل والجلسة ترد (`reject`) | — | `409 session_busy` مع `Retry-After: 2` |
| جلسات الودجت المجهولة | 20 في الساعة لكل عنوان IP | `429 anonymous_limit_reached` مع إشعار مهذب |
| رسائل الودجت المجهولة | 60 في الساعة لكل عنوان IP؛ و40 لكل جلسة | `429 anonymous_limit_reached` مع إشعار مهذب |
| المحادثات المجهولة لكل وكيل | `widget.anonymous_daily_conversations` في اليوم (الافتراضي 200) | إشعار مهذب بالمحاولة لاحقًا |
| تشغيلات لوحة التجربة على نماذج المنصة | 200 في اليوم لكل مشروع (بلا حد مع مفتاح مزوّدك الخاص) | `429 playground_limit_reached` |
| المحادثات الذكية في الخطة المجانية | 100 في الشهر | تُحوَّل الجلسات لموظف مع إشعار؛ وتحصل `ask` على `429 quota_exceeded` |
| تكلفة النماذج اليومية لكل منظمة | المجانية 1 دولار، وStarter ‏10، وBusiness ‏30، وScale ‏100 | تُحوَّل الجلسات لموظف مع إشعار؛ وتحصل `ask` على `429 cost_cap_exceeded` |

## حدود الأدوات

| ماذا | الحد |
|---|---|
| استدعاءات الأدوات المنفَّذة في الجولة | 5 (الاستدعاءات الزائدة تحصل على `too_many_calls`) |
| جولات النموذج والأدوات في الدور | `tools.max_tool_rounds`، من 1 إلى 5 (الافتراضي 3) |
| استدعاءات أدوات HTTP لكل عميل | 20 في الساعة عبر كل أدوات HTTP، مع احتساب كل محاولة؛ ولكل أداة `limits.per_end_user_per_hour` ‏(1–100) |
| `create_ticket` لكل عميل | 5 في اليوم |
| زمن أداة HTTP | حتى 15 ثانية (3 ثوانٍ للاتصال) |
| استجابة أداة HTTP | حتى 1 ميغابايت؛ ولا يصل إلى النموذج أكثر من 20 صفًا و12 حقلًا، ضمن 4 كيلوبايت |
| نتائج أدوات جهة العميل | خلال 10 دقائق |

حين يُبلغ حد في الأدوات يُخبَر النموذج بصياغة محايدة، فيجيب مما لديه أو يحوّل المحادثة إلى فريقك؛ ولا يصل الطلب إلى واجهتك البرمجية أصلًا.

## حدود الأحجام

| ماذا | الحد | عند التجاوز |
|---|---|---|
| `input` مع المفتاح السري | 32,000 حرف | `413 input_too_large` |
| `input` مع مفتاح قابل للنشر أو رمز عميل | 4,000 حرف | `413 input_too_large` |
| جسم الطلب | 1 ميغابايت (5 ميغابايت لمصادر المعرفة) | `413 request_too_large` |
| `messages` في الواجهة المتوافقة مع OpenAI | 100 | يُرفض بخطأ بصيغة OpenAI |
| حجم الصفحة في القوائم | 100 (الافتراضي 20) | يُقتصر على الحد |
| `metadata` | 16 مفتاحًا؛ المفتاح حتى 64 حرفًا والقيمة حتى 512 | `422 validation_failed` |
| `Idempotency-Key` | 255 حرفًا | `400 invalid_idempotency_key` |
| نقاط استقبال الويب هوك لكل مشروع | 10 | `422 webhook_endpoint_limit_reached` |

## الترويسات

| الترويسة | متى | المعنى |
|---|---|---|
| `Retry-After` | استجابات `429` وبعض استجابات `409` | الثواني التي تنتظرها قبل إعادة المحاولة. |
| `RateLimit-Policy` | الاستجابات المحدودة | الحد المطبَّق: حصته ونافذته. |
| `RateLimit` | الاستجابات المحدودة | ما تبقّى في النافذة الحالية ومتى تتجدد. |
| `x-should-retry` | الأخطاء التي لا تفيد فيها إعادة المحاولة | `false` — مثل `quota_exceeded`. |

تتبع `RateLimit-Policy` و`RateLimit` مسودة IETF لحقول ترويسات حدود المعدّل في HTTP.

## التعامل الجيد مع الحدود

- **التزم بـ `Retry-After`.** انتظر هذه المدة على الأقل، وأضف قدرًا عشوائيًا بسيطًا حتى لا يعيد كثير من العملاء المحاولة في اللحظة نفسها.
- **زِد فترات الانتظار تدريجيًا** عند تكرار `429` و`5xx`: مثل 0.5 ثانية، ثم 1، ثم 2، ثم 4، ثم توقف وأبلغ.
- **لا تُعد المحاولة** حين تكون `x-should-retry` قيمتها `false`.
- **اجعل إعادة المحاولة آمنة** بمفتاح `Idempotency-Key`، فلا تُنشئ أبدًا نسخة مكررة.
- **استخدم طابورًا لا دفعات.** عند الاستيراد أو الترحيل بكميات كبيرة شغّل عددًا ثابتًا من العمّال بدل إطلاق كل الطلبات دفعة واحدة.
- **عرّف المستخدمين المسجّلين** في الودجت برموز العميل: فالمستخدمون الموثّقون لا يخضعون لحدود المجهولين.

تحتاج حدودًا أعلى؟ تواصل معنا — الحدود مضبوطة حسب الخطة ويمكن رفعها في اتفاقيات Enterprise.