حدود المعدل والحصص

يملك Synapse سياسة حدود معدل بسيطة وقابلة للتنبؤ مصممة لمنع إساءة الاستخدام دون أن تعيق الاستخدام المشروع.

سياسة حد المعدل

ترويسات حد المعدل

عند استخدام مصادقة ?key=، تتضمن الاستجابات ترويسات حد المعدل:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782567840

عند تجاوز الحد:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Too many requests with query-param auth. Slow down or use Authorization header."
}

عند بلوغ حد المعدل

إذا حصلت على 429:

1. بدّل إلى ترويسة Authorization (موصى به):

   # لا تفعل: ?key=YOUR_MIND_KEY (حد 60/دقيقة)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # افعل: ترويسة Authorization (غير محدودة)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

2. أو انتظر Retry-After ثانية وأعد المحاولة.

لماذا يوجد حد ?key=

معامل الاستعلام ?key= مريح للأدوات التي تفتح عناوين URL فقط (المتصفحات، أوامر open)، لكنه مهمل ومُتحكَّم به من الخادم عبر AUTH_QUERY_KEY_MODE (deny هو الافتراضي؛ قيمة allow تعيد تفعيل مصادقة معامل الاستعلام). له آثار أمنية وأدائية:

• الأمان: تُسجّل معاملات الاستعلام في سجلات الوصول للخادم، وبيانات المتصفح، وترويسات Referer. تحديد الاستخدام يقلل من التعرض.
• الأداء: تتطلب مصادقة معامل الاستعلام مُحدّد معدل قائم على IP (بحث Redis لكل طلب)، مما يضيف زمن استجابة. مصادقة الترويسة تتجاوز هذا.
• منع الإساءة: يمكن مشاركة عنوان URL ?key= المُسرّب وقصفه بالطلبات. يُحجم حد IP دائرة الضرر.

الأنماط الموصى بها

وكلاء LLM

# استخدم دائمًا مصادقة الترويسة
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)

أدوات المتصفح

إذا كانت أداتك تفتح عناوين URL فقط:

# بديل قديم (مهمل، 60/دقيقة لكل IP، مُتحكَّم به عبر AUTH_QUERY_KEY_MODE)
# لا تشارك مثل هذه العناوين أبدًا ولا تحفظها في المفضلة — المفتاح ينتهي في السجلات وسجل المتصفح
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# للاستخدام المتكرر، بدّل إلى أداة تدعم الترويسات
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

خادم MCP

خوادم MCP تستخدم دائمًا مصادقة الترويسة عبر متغير البيئة SYNAPSE_MIND_KEY — لا ينطبق حد معدل.

الاستيراد الكمي

للعمليات الكمية (مثل استيراد 1000 ذاكرة)، استخدم دائمًا مصادقة الترويسة. الاستيراد الكمي عبر ?key= سيبلغ حد المعدل خلال دقيقة واحدة.

الحصص (على مستوى العقل)

لا توجد حاليًا حصص على مستوى العقل لحجم التخزين أو عدد الذكريات. جميع الحدود على مستوى المصادقة/IP، وليس على مستوى البيانات. قد يتغير ذلك مستقبلًا لضمان العدالة في البيئات متعددة المستأجرين.

مراقبة الاستخدام

# ترويسات حد المعدل تُرفق لاستجابات ?key= (المسار القديم):
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# المخرجات:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840

الخطوات التالية

• المصادقة
• الأخطاء ومعالجتها