# كيف تختبر توافق البث واستدعاءات الأدوات قبل تغيير LLM API؟ > اختبر انتقال LLM API بوساطة fixtures تعاقدية مسجلة، لا بعرض دردشة واحد. تحقق من بث النص والأداة الإجبارية والوسائط المجزأة والاستدعاءات المتعددة ودورة النتائج والإلغاء والأخطاء وحساب الاستخدام. قد يفوت اختبار دردشة لمدة عشر دقائق أخطر المشكلات: استدعاء مكرر بعد retry، أو تنفيذ JSON قبل حدث البث النهائي، أو إعادة نتيجة أداة بالدور الخطأ، أو استمرار كتابة بعد الإلغاء. تمرر بوابة الانتقال الفعالة طلبات ثابتة عبر parser والمنفذ الحقيقيين، ثم تفحص الثوابت البنيوية. يجب أن تكون الحزمة الأولى صغيرة لتعمل سريعًا وحتمية لتقارن بين النماذج. هدفها ليس ترتيب الذكاء، بل إثبات أن API الجديد يقود حلقة الوكيل الحالية بأمان. ## عرّف العقد الذي يعتمد عليه العميل دوّن السلوك المطلوب قبل اختبار المزود. لا تكتفِ بعبارة غامضة مثل «متوافق مع OpenAI». | مجال العقد | الثابت المطلوب | الدليل المحفوظ | |---|---|---| | المصادقة | يقبل endpoint المفتاح | الحالة وrequest ID | | بث النص | تتجمع الدلتا في رسالة نهائية | أحداث خام مرتبة | | بث الأداة | يكتمل الاستدعاء قبل التنفيذ | buffer الاستدعاء والحدث النهائي | | الارتباط | ترتبط النتيجة بالاستدعاء الصحيح | خريطة call ID | | Retry | ينفذ الاستدعاء مرة واحدة كحد أقصى | سجل idempotency | | Usage | العدادات موجودة أو معلّمة unavailable | بيانات الاستجابة النهائية | يعتمد دعم البروتوكول على النموذج. يقدم Atlas Cloud صيغ طلب متعددة، لذا راجع دليل [`supported_apis`](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis) الحالي قبل اختيار مسار الاختبار. ## أنشئ أربع أدوات حتمية استخدم fixtures تكشف أنماط فشل مختلفة: * `echo_json` يعيد الوسائط المتحقق منها من دون تغيير. * `read_fixture` يقرأ ملفًا معروفًا داخل sandbox. * `delayed_value` يكتمل بعد تأخير مضبوط. * `always_error` يعيد خطأ منظمًا ثابتًا. امنح كل أداة مخططًا صارمًا يتضمن `additionalProperties: false` ومعرف fixture فريدًا لكشف التنفيذ المكرر. لا تعتمد على الطقس أو نتائج البحث أو repository متغير. ## شغّل مصفوفة توافق مرحلية اختبر من دون بث قبل البث، واستدعاء واحدًا قبل عدة استدعاءات. | المرحلة | سلوك prompt | شرط النجاح | |---|---|---| | A | إرجاع نص عادي | وصول النص النهائي وحالة الإيقاف | | B | فرض `echo_json` | وصول الاسم والوسائط الصالحة | | C | بث `echo_json` | تجميع الأجزاء مرة واحدة | | D | استدعاء أداتي قراءة | ارتباط النتيجتين صحيحًا | | E | تلقي خطأ أداة | يصلح النموذج أو يخرج نظيفًا | | F | الإلغاء أثناء البث | لا يحدث تنفيذ متأخر | استخدم المخطط والطلب الدلالي نفسيهما لكل مرشح. إذا احتاج البروتوكول الأصلي غلافًا مختلفًا، فغيّر تمثيل wire فقط. ## التقط الأحداث الخام تحت SDK كائنات SDK عالية المستوى مريحة في الإنتاج لكنها قد تخفي فروق الانتقال. أضف debug transport يسجل رقمًا متزايدًا وresponse ID وoutput index وcall ID ونوع الحدث وطول payload بعد إزالة الحسّاس. وسائط الدوال المتدفقة تراكمية. اجمعها لكل استدعاء وانتظر حدث الوسائط النهائي: ```text START -> CALL_OPEN -> ARGUMENT_DELTAS -> CALL_DONE -> VALIDATED -> EXECUTED | | +-> CANCELLED <---+ ``` ارفض الانتقالات العكسية والتنفيذ المكرر. إذا انقطع الاتصال بعد `EXECUTED` وقبل أن يتلقى النموذج النتيجة، فاستخدم idempotency key بدل تكرار الكتابة بلا تمييز. ## اختبر دورة نتيجة الأداة كاملة استدعاء أداة صالح هو نصف العقد فقط. أعد النتيجة بنوع الرسالة أو العنصر الذي يتوقعه البروتوكول، ثم اطلب إجابة نهائية تستخدم حقلًا معروفًا من النتيجة. اختبر النتائج الكبيرة والفارغة وUnicode والأخطاء المنظمة. قيّد الحجم قبل إعادة النتيجة إلى context. قد لا يظهر افتراض خفي في المهايئ حتى أول نتيجة كبيرة. ## قارن الثوابت لا الصياغة لا تفشل الحزمة لأن نموذجين يصوغان الإجابة النهائية بشكل مختلف. تحقق من أن: * اسم الأداة المتوقع اختير. * الوسائط اجتازت JSON Schema. * كل call ID فريد ومرتبط صحيحًا. * كل أداة نُفذت صفرًا أو مرة واحدة كما هو مقصود. * انتهت الحلقة ضمن ميزانية الاستدعاءات. * استخدمت الإجابة النهائية نتيجة fixture. احتفظ بلقطات خاصة بالمرشح للتصحيح فقط، واجعل معايير النجاح محايدة للمزود. ## أضف حالات الفشل والإلغاء اقطع البث بعد أول جزء وسيط، وبعد اكتمال الاستدعاء، وبعد تنفيذ الأداة. احقن 429 وtimeout وJSON غير صالح واسم أداة مجهولًا. تحقق من retry آمن أو استئناف صحيح أو توقف بخطأ مفيد. أخطر خطأ هو retry غامض يكرر أداة تغيّر الحالة. اطلب idempotency صريحة لعمليات الكتابة. ## اجعل الحزمة بوابة إصدار احتفظ بمجموعة smoke سريعة لتغييرات الإعداد ومصفوفة كاملة لترقية SDK أو gateway. احفظ النموذج والبروتوكول وBase URL وhash المخطط وعلم البث وإصدار العميل وtimestamp مع النتائج. يدعم Atlas Cloud طلبات LLM المتدفقة وغير المتدفقة، ويتيح استكشاف المرشحين في [كتالوج نماذج](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis) واحد. الوصول المشترك لا يعني قدرات متطابقة، لذا شغّل البوابة نفسها لكل نموذج. ## الخلاصة اختبر انتقال LLM API كتغيير بروتوكول ذي حالة. ابدأ بأدوات حتمية، وسجّل الأحداث الخام، ولا تجمع الوسائط إلا بعد اكتمالها، وتحقق من دورة النتيجة، ثم احقن retry والإلغاء. لا تعتمد النموذج الجديد لمجرد أن إجابة دردشة واحدة تبدو صحيحة؛ اعتمده بعد نجاح حزمة العقد. ## FAQ ### ما الذي يجب أن يغطيه أول اختبار توافق؟ ابدأ بطلب نصي واحد من دون بث واستدعاء إجباري واحد لأداة قراءة، لعزل مشكلات endpoint والمصادقة والمخطط وشكل الاستجابة الأساسي. ### لماذا يجب تسجيل أحداث البث الخام؟ قد تخفي أدوات SDK ترتيب الأحداث واختلاف الحقول. تكشف الأحداث الخام كيفية وصول call ID وأجزاء الوسائط وعلامات الإكمال والأخطاء والاستخدام. ### هل يمكن مقارنة المزودين بتطابق النص حرفيًا؟ غالبًا لا. قارن ثوابت بنيوية مثل صحة الاستدعاء والحقول المطلوبة وعدد مرات التنفيذ والحالة النهائية ونتيجة المهمة. ### كيف أختبر وسائط أداة غير صالحة؟ أعد خطأ تحقق منظمًا للنموذج وتأكد من أن الحلقة تصلح الطلب أو تنهيه ضمن ميزانية محددة من دون تنفيذ مدخل غير آمن. ### هل ينبغي أن تستخدم حزمة الاختبار أدوات كتابة؟ ابدأ بأدوات قراءة حتمية. لا تضف fixture كتابة داخل sandbox إلا بعد نجاح التجميع والتحقق ومنع التكرار والتعافي من الخطأ. ### كم مرة يجب تشغيل اختبارات التوافق؟ شغّل مجموعة smoke قصيرة قبل كل تغيير للنموذج أو البروتوكول، والمجموعة الكاملة عند تغيير SDK أو المخطط أو gateway أو stream parser.