ما هو وسيط API: مبدأ العمل، المخاطر الشائعة وقائمة الاختيار

مسار الطلب عبر وسيط API

دعنا نوضح المصطلحات أولاً. "بوابة API" تعني إضافة بوابة تعرض واجهة قياسية بين برنامجك والخلفية التي تشغل النموذج فعلياً. لا يزال كودك يرسل الطلبات بتنسيق OpenAI، فقط قم بتوجيه base_url إلى عنوان البوابة، واستبدل المفتاح بالمفتاح الذي أعطته لك البوابة.

تقوم البوابة عادةً بثلاث مهام في هذه الخطوة.

• إعادة توجيه الطلب: التحقق من تنسيق جسم الطلب، وإكمال المعلمات الافتراضية عند الحاجة، ثم تسليم الطلب للخلفية؛ يتم إرجاع محتوى الخلفية (بما في ذلك أجزاء SSE للبث المتدفق) كما هو أو بمعالجة خفيفة لك.
• تعيين المفاتيح: أنت تملك مفتاحاً أصدرته البوابة، وهو ذو معنى داخل البوابة فقط. تتعرف البوابة بناءً عليه على هويتك، ورصيدك، والنماذج المتاحة لك؛ تبقى بيانات الاعتماد الحقيقية للخلفية داخل البوابة ولا تظهر في كودك.
• الفوترة وحدّ المعدل: بعد كل طلب، يخصم البوابة الرصيد حسب عدد رموز المدخلات والمخرجات في usage، ويعيد 429 عند تجاوز الحد.

بربط هذه المهام الثلاث، يمكنك فهم سبب اختلاف تجربة وسيط API بشكل كبير: يحدد تنفيذ طبقة إعادة التوجيه تذبذب زمن الاستجابة واستقرار البث المتدفق، وتحدد طبقة المفاتيح نطاق الخسارة عند التسرب، وتحدد طبقة الفوترة شفافية الفواترة وإمكانية المراجعة.

الفرق عن الاتصال المباشر بنموذج واحد

الخدمة المباشرة تعني إرسال الطلب إلى النطاق الرسمي لمقدم النموذج، حيث ترتبط حساب واحد بنموذج واحد وقواعد فوترة واحدة. أما الخدمة الوسيطة فلها شكلان، ويختلفان في ما هو متصل بالخلف.

البُعد	الاتصال المباشر بخدمة واحدة	الوسيط التجميعي	الوسيط لنموذج واحد
عدد النماذج	بضعة نماذج من مقدم الخدمة	عشرات أو حتى مئات	نموذج واحد
تنسيق الواجهة	تنسيقات خاصة بكل جهة	موحد ليتوافق مع OpenAI	متوافق مع OpenAI
صعوبة استكشاف الأخطاء	الأدنى، أقصر مسار	الأعلى، تعيينات أسماء النماذج متعددة	منخفض، لنموذج واحد فقط
الحالات المناسبة	الاعتماد على جهة واحدة لأعمال مستقرة	الحاجة إلى تبديل النماذج للمقارنة بشكل متكرر	نموذج ثابت، والسعي لنتائج متوقعة

إذا كان عملك يعتمد على نموذج واحد فقط، فإن فوائد التجميع لن تكون مفيدة، وستتحمل بدلاً من ذلك عدم اليقين بشأن "من يمثل اسم النموذج". على العكس، إذا كنت تبديل النماذج أسبوعياً للمقارنة، فإن النوع التجميعي يوفر الكثير من أعمال التكيف. لا توجد مزايا أو عيوب مطلقة، والمفتاح هو معرفة أي فئة تنتمي إليها.

الموقع ينتمي إلى النوع الأخير: يوفر نموذجاً واحداً فقط، ومعرف النموذج هو uncensored، والواجهة هي إكمال محادثة متوافق مع OpenAI. لمناقشة هذه المقايضات والتكاليف، يمكنك متابعة قراءة تكلفة ومقايضات واجهة API غير المقيدة AI.

ثلاثة أنواع من المخاطر الشائعة

أمان المفتاح

مفتاح الوسيط يعادل بطاقة شحن مسبق الدفع، من يملكه يمكنه إنفاق رصيدك. مسارات التسرب الشائعة تشمل: كتابة المفتاح في كود الواجهة الأمامية، رفعه إلى مستودع عام، لصقه في لقطات شاشة تذاكر الدعم أو مجموعات الدردشة. يُنصح بوضعه في متغيرات البيئة على الخادم فقط، وجعل الواجهة الأمامية تمرر الطلبات عبر خادمك الخاص؛ عند الاشتباه بالتسرب، أعد التعيين فوراً، ويجب أن يصبح المفتاح القديم غير صالح على الفور. راقب أيضاً ما إذا كانت الخدمة تسمح لك بإعادة التعيين ذاتياً، وما إذا كان المفتاح القديم يلغي صلاحية على الفور بعد إعادة التعيين، وليس "بعد بضع ساعات".

استبدال النموذج

هذه هي المشكلة الأكثر مناقشة في خدمات التجميع: تطلب A، لكن الاستجابة الفعلية تكون B الأرخص. من الصعب الحكم عليها عبر المستندات، ويمكن التحقق منها عبر السلوك. يمكنك تثبيت مجموعة من الأسئلة ذات الإجابات القياسية، وتثبيت temperature لإعادة الاختبار وملاحظة استقرار نمط المخرجات؛ أو طلب /v1/models للتحقق من توافق القائمة مع صفحة الفوترة. يجب الحذر من غموض اسم النموذج أو اختلاف الأداء لنفس الاسم في أوقات مختلفة.

حدّ المعدل غير الشفاف

تكتب بعض الخدمات في التوثيق "استخدام معقول" فقط، لكنها تخفض السرعة خلسة أو ترمي الطلبات في أوقات الذروة، مما يظهر في برنامجك كتأخر زمني متقطع. الممارسة الناضجة هي كتابة عدد الطلبات في الدقيقة لكل مفتاح، وإرجاع رمز 429 المعياري عند تجاوز الحد، بدلاً من تعليق الاتصال. عند الاختيار، اسأل بوضوح: هل حدّ المعدل محسوباً حسب المفتاح أم حسب الحساب، وما هو رمز الخطأ عند التجاوز، وما إذا كان يتم إرجاع رمز خطأ مستقل عند انتهاء الرصيد.

قائمة مراجعة لاختيار خدمة التحويل

يمكنك نسخ القائمة أدناه مباشرة إلى وثيقة التقييم الخاصة بك، مع وضع علامة لكل بند.

1. هل يوفر نقطة النهاية GET /v1/models العامة، بحيث تتطابق قائمة النماذج المعادة مع صفحة التسعير؟
2. هل استجابة الخطأ عبارة عن JSON هيكلي يحتوي على code وmessage، مع تمييز واضح لكل من 401 و402 و429 و503؟
3. هل يتم توثيق حدّ المعدل (الطلبات في الدقيقة) لكل مفتاح في المستندات، وليس فقط شفهيًا عبر خدمة العملاء؟
4. هل توجد أرقام واضحة لطول نافذة السياق، والحد الأقصى لرمز (token) للإخراج في الطلب الواحد، وحجم جسم الطلب؟
5. هل يتم خصم التكلفة بدقة بناءً على عدد الرموز (tokens) في usage، وهل يمكن مراجعة الرصيد في أي وقت؟
6. هل سينتهي رصيد مسبق الدفع؟ هل تم تحديد مدة صلاحية رصيد تجريبي بوضوح؟
7. هل يمكن إعادة تعيين المفتاح ذاتيًا، وهل يصبح المفتاح القديم غير صالح على الفور؟
8. هل يدعم البث المتدفق، وهل يحتوي الإخراج النهائي على إحصائيات usage لتسهيل المراجعة الذاتية؟
9. هل يوجد بيان واضح وموجز حول ما إذا كانت الموجّهات تُستخدم في التدريب؟
10. هل يتم تحديد القدرات غير المدعومة (مثل التضمين، الصور، الصوت) بدقة، وليس بشكل غامض؟

الدرجة الكاملة غير واقعية، لكن إذا لم تتمكن من الإجابة على أي من البنين الأولين، يُنصح بالتجربة بمبلغ صغير وعدم شحن رصيد مسبق الدفع الكبير دفعة واحدة.

التحقق الأساسي خلال عشر دقائق بعد الحصول على المفتاح

بغض النظر عن الخدمة التي تختارها، يستحق الأمر قضاء عشر دقائق لإجراء التحقق الأساسي قبل النشر. الخطوة الأولى: قائمة النماذج، للتأكد من أن المعرفات (id) المعادة تتطابق مع توقعاتك:

复制curl -s https://api.llmzhongzhuan.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

الخطوة الثانية: إرسال طلب صغير ومراقبة حقل usage في الاستجابة للتأكد من وجوده ومعقولية قيمه. المثال أدناه يجعل النموذج يكرر التاريخ لملاحظة ما إذا كان سيخترع معلومات لا يعرفها؛ هذا اختبار سلوكي تقريبي وليس تقييمًا صارمًا:

复制curl -s https://api.llmzhongzhuan.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "用一句话介绍你自己，然后复述今天的日期是几号。"}],
    "max_tokens": 200
  }' 

أدرج هاتين الخطوتين في سكريبت النشر الخاص بك، وشغّلها في كل مرة تستبدل فيها المفتاح أو الخدمة. إذا لم يحتوي الاستجابة على usage، أو إذا كانت أرقام usage لا تتطابق بشكل واضح مع طول الإدخال، فهذا يشير إلى مشكلة في شفافية التسعير، ويجب توضيحها قبل شحن مبالغ كبيرة. للاطلاع على كيفية التكامل مع أطر العمل المختلفة، راجع دليل تكوين أطر العمل.

معلمات الموقع، لمساعدتك في مطابقة القائمة

نقوم هنا بتحديد معلمات الموقع الفعلية لتسهيل مطابقة القائمة أعلاه بنودًا بنود، دون الحاجة للتنقل بين المستندات.

• عنوان نقطة النهاية: https://api.llmzhongzhuan.com/v1، يدعم POST /v1/chat/completions و GET /v1/models، مع المصادقة باستخدام مفتاح Bearer.
• نموذج واحد فقط، المعرف uncensored؛ للنصوص فقط، بدون تضمين، صور، صوت، فيديو أو ضبط دقيق.
• تتسع نافذة السياق لـ 100,000 رمز (إدخال وإخراج)، مع تعيين max_tokens الافتراضي على 2048، والحد الأقصى لكل طلب 32,000؛ ولا يتجاوز حجم طلب البيانات 8 ميجابايت.
• 300 طلب في الدقيقة لكل مفتاح، مع إرجاع 429 عند تجاوز الحد؛ يشير upstream_busy في 503 إلى إمكانية إعادة المحاولة لاحقًا؛ إرجاع no_credit في 402 عند نفاد الرصيد أو انتهاء صلاحية التجربة.
• السعر: 0.25 دولار لكل مليون رمز (token) للإدخال، و1.00 دولار لكل مليون رمز (token) للإخراج، شحن مسبق، بدون اشتراك، الرصيد لا ينتهي.
• لا تُستخدم الموجّهات في التدريب.

تعتمد الأرقام المحددة على صفحة التسعير والمستند. يحتوي الحساب الجديد على رصيد تجريبي بقيمة 0.50 دولار، صالح لمدة 7 أيام، ولا يتطلب تسجيل معلومات الدفع، يمكنك استخدامه لإكمال عملية التحقق أعلاه.