ما الذي يغطّيه هذا الشرح؟

قد يتوقّع العميل طلباً واستجابةً لـ Chat Completions بتنسيق OpenAI، بينما يكون التطبيق خلف نقطة النهاية عبارةً عن سير عمل مبني على LangGraph. هذان جانبان مختلفان. ينتمي تنسيق الطلب والاستجابة إلى الواجهة العامة، بينما تنتمي الحالة، والتوجيه، والأدوات، واستدعاءات النماذج، والبث، والاستمرارية، والتنفيذ بوجود الإنسان ضمن الحلقة إلى تطبيق سير العمل.

يفصل هذا المبدأ التصميمي الأساسي خدمة LangGraph المكشوفة عبر FastAPI. يستقبل محوّل التوافق الطلب العام ويتحقق منه، ثم يستدعي الرسم البياني باستخدام تمثيل تملكه المنظومة، ويُنشئ استجابةً بالتنسيق الذي يتوقّعه العميل. وإذا كان البث متاحاً، فيجب أن يُصدر مُسلسل SSE منفصل الأحداث بالمعاني المقصودة. ويسمح الفصل بين هذه المسؤوليات بتحليل كل حدّ فاصل على حدة، بدلاً من افتراض أن الأحداث الداخلية للرسم البياني تشكّل تلقائياً API عامة متوافقة.

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

المتطلبات والنطاق

• الإلمام بتنسيقات طلبات واستجابات HTTP.
• فهم أساسي لمسارات FastAPI وسير عمل LangGraph.
• عقد موثّق بوضوح للطلبات والاستجابات التي يتعامل معها العميل.
• خطة اختبار للاستجابات غير المتدفقة وSSE، إذا كان البث جزءاً من الواجهة.

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

الخطوة ١: حدّد العقد العام قبل بناء محوّل الرسم البياني

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

لا تساوِ بين جسم JSON المألوف ظاهرياً والتوافق الكامل. يوضح تحليل التوافق الموثّق هذا الفرق صراحةً: فقبول طلب Chat Completions بتنسيق OpenAI، واستدعاء رسم بياني، وإعادة مصفوفة choices يثبت مساراً ناجحاً لطلب واحد. لكنه لا يثبت بحد ذاته أن نقطة النهاية تدعم مساحة الطلب الأوسع أو تحافظ على حقول الاستجابة التي يعتمد عليها العملاء.

أنشئ قائمة تحقق للعقد تجيب عن الأسئلة التالية قبل التنفيذ:

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

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

الخطوة ٢: افصل محوّل API عن حالة LangGraph

استخدم طبقة حدود للترجمة بين البروتوكول العام وسير عمل التطبيق. ومن الناحية المفاهيمية، تتكون الخدمة من خمسة أجزاء: يرسل عميل OpenAI طلباً؛ ويستقبله مسار FastAPI؛ ويفحصه مترجم التحقق والتوافق ويحوّله؛ ثم يستدعي المحوّل LangGraph؛ وأخيراً ينسّق مُنشئ الاستجابة النتيجة. ويمكن لمنشئ الاستجابة بعد ذلك اختيار مُسلسل لاستجابة غير متدفقة أو مُسلسل SSE، وفقاً للطلب والسلوك الموثّق للخدمة.

تعامل مع ذلك بوصفه خريطة للمسؤوليات، لا وصفة تنفيذ:

1. التحقق من الطلب: تأكد من أن الطلب العام الوارد يطابق العقد الذي تدعمه نقطة النهاية فعلياً.
2. ترجمة الطلب: حوّل الحقول العامة المقبولة إلى مدخلات التطبيق التي يتوقعها الرسم البياني.
3. تنفيذ سير العمل: دع LangGraph يمثل تنسيق التطبيق، بدلاً من إجبار الحالة الداخلية للرسم البياني على محاكاة تنسيق خارجي عبر السلك.
4. إنشاء الاستجابة: حوّل النتيجة النهائية للرسم البياني إلى الاستجابة العامة الموثّقة.
5. تسلسل البروتوكول: استخدم المُسلسل المناسب للاستجابة العادية أو لبث SSE.

يحافظ هذا التقسيم على حدّ معماري مهم: لا تحتاج نماذج الحالة والأحداث في LangGraph إلى محاكاة بروتوكول OpenAI عبر السلك. يمكن للتطبيق تمثيل سير عمله الخاص، بينما يتولى المحوّل العقد العام. ويفيد ذلك عند تغيير سير العمل من دون الحاجة إلى تحويل كل تفصيل داخلي في الرسم البياني إلى جزء من API.

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

الخطوة ٣: تعامل مع الاستجابات العادية بوصفها حالة توافق مستقلة

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

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

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

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

الخطوة ٤: تعامل مع بث SSE بوصفه تطبيقاً مستقلاً للبروتوكول

لا يعني البث تقسيم الاستجابة غير المتدفقة إلى أجزاء عشوائية فحسب. يشير التحليل الموثّق إلى أن مسار FastAPI يمكنه إضافة server-sent events، وأن SDK رسمياً قد يستهلكها، لكنه يحذر أيضاً من أن هذه الملاحظة لا تثبت صحة دلالات البث. ويجب اختبار البث كسلسلة كاملة وكأحداث منفردة.

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

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

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

الخطوة ٥: اختبر المسار الكامل، بما في ذلك البوابة

نظّم اختبارات التوافق حول ما يراه العميل. بالنسبة إلى الاستجابات العادية، قارن الطلبات المرسلة والحقول المعادة بعقد نقطة النهاية. وبالنسبة إلى البث، التقط التسلسل الكامل وأعد بناءه. وعندما تُنشر الخدمة خلف بوابة، شغّل الاختبارات نفسها عبر البوابة، بدلاً من الاعتماد على الوصول المباشر إلى مسار FastAPI فقط.

تتضمن مصفوفة اختبار مفيدة حالات مستقلة لما يلي:

• الطلبات المقبولة التي تستخدم الحقول التي توثقها نقطة النهاية.
• الطلبات ذات المدخلات غير الصالحة أو غير المدعومة.
• الاستجابات غير المتدفقة وحقولها الموثّقة.
• توصيل أحداث SSE ومعنى التسلسل المعاد بناؤه.
• السلوك عند مرور الطلب عبر البوابة المستهدفة.

احتفظ بالعقد العام وتوقعات الاختبار معاً. وعند تغيير المحوّل أو الرسم البياني، أعد تشغيل الاختبارات التي تغطي الحد المتأثر. وعند تغيير البوابة، اختبر السلوك المرئي خارجياً من جديد. لا يثبت ذلك ضماناً محدداً للأداء أو التوافر أو الأمان، لكنه يوفر طريقة منهجية للتحقق من استمرار الواجهة القابلة للملاحظة في تلبية سلوكها الموثّق.

يقدم تحليل Hugging Face تحذيراً عملياً للفرق التي تبني نقاط نهاية متوافقة: فمن السهل إعداد عرض ناجح، بينما يصعب وضع مواصفة توافق دقيقة. تعامل مع العرض باعتباره فحص اتصال أولياً، لا دليلاً على التحقق من جميع تفاعلات العملاء أو حقول الاستجابة أو تسلسلات البث أو مسارات البوابة.

أين تندرج الاستمرارية والمراجعة البشرية؟

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

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

يصف بحث منشور ضمن السياق المقدم خلفيةً منفذة باستخدام FastAPI وPostgreSQL لإدارة الجلسات وLangGraph لأتمتة سير العمل وOpenAI GPT-٣.٥-turbo. وهذا مثال ورد في منشور، وليس متطلباً عاماً أو دليلاً على صحة تصميم SQLite أو اختيار النموذج أو شيفرة سير العمل في المسودة. تعامل معه بوصفه دليلاً على استخدام هذه التقنيات معاً في نظام موصوف واحد، لا وصفةً للنشر.

أخطاء شائعة ينبغي تجنبها

• اعتبار طلب ناجح واحد دليلاً على التوافق الكامل. تثبت استجابة المسار الناجح أن مساراً واحداً عمل فقط. عرّف عقد الطلب والاستجابة واختبره على نطاق أوسع.
• خلط حالة سير العمل بتنسيق البيانات العام عبر السلك. دع LangGraph يمثل التطبيق، وأبقِ السلوك الخاص بالبروتوكول عند حدود المحوّل.
• افتراض صحة أجزاء SSE لمجرد وصولها. تحقق من التسلسل المعاد بناؤه ومن معناه بالنسبة إلى العميل.
• الاختبار من دون البوابة فقط. قد تؤثر البوابة في الأحداث أو سلوك الاستجابة، لذلك أدرج المسار العام الفعلي ضمن فحوصات التوافق.
• الادعاء بدعم لم ينفذه المحوّل. وثّق الملف المدعوم لنقطة النهاية واختبر كل وعد.
• نسخ شيفرة أمثلة غير موثّقة إلى بيئة الإنتاج. تحقق من APIs المكتبات وإصداراتها وسلوك الاستمرارية ومتطلبات النشر بالرجوع إلى الوثائق الحالية.

أهم الخلاصات

إن بناء API متوافق مع OpenAI حول LangGraph هو تمرين في تصميم الحدود بقدر ما هو تمرين في تنسيق سير العمل. يمكن لـFastAPI أن يعمل طبقة HTTP، لكن نقطة النهاية تحتاج إلى محوّل توافق محدد بوضوح بين العقد الموجه للعميل والرسم البياني. أبقِ حالة الرسم البياني وأحداثه ضمن طبقة التطبيق، وتحقق من البروتوكول العام وسلسله عند الحافة.

بالنسبة إلى الطلبات غير المتدفقة، اختبر مساحة الطلب المدعومة وحقول الاستجابة التي يتلقاها العملاء. وبالنسبة إلى SSE، تحقق من البث بوصفه تسلسلاً كاملاً، لا حدثاً بعد حدث فقط. وأخيراً، اختبر عبر البوابة المستهدفة. يُعد العرض العامل فحصاً أولياً مفيداً، لكن المصادر الموثّقة لا تدعم اعتباره دليلاً على التوافق الكامل مع الطلبات أو الاستجابات أو البث أو البوابة.

المصادر

• قياس توافق OpenAI لنقاط نهاية LangGraph — حدود التوافق، ومعالجة الطلبات والاستجابات، والتحقق من SSE، واعتبارات البوابات.
• إخفاء هوية PHI على الجهاز واسترجاع التقارير الطبية … — ملخص مصدر يصف خلفية تستخدم FastAPI وPostgreSQL وLangGraph وOpenAI GPT-٣.٥-turbo.
• نهج Agentic AI باستخدام MARARE — ملخص مصدر يصف خلفية Python وFastAPI تستخدم LangGraph وOpenAI Realtime SDK.