أساسيات LLM API: أدوار الطلب والاستجابة والرسالة

المكاسب:

• يمكن وصف البنية الأساسية لطلب LLM API (نقطة النهاية، النموذج، الرسائل، max_tokens)
• يفهم الفرق بين أدوار النظام والمستخدم والمساعد وسجل المحادثات عديمة الحالة
• يمكن قراءة وتفسير الحقول (كتل المحتوى، وstop_reason، والاستخدام) للاستجابة التي تم إرجاعها

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

كيف تعمل واجهة برمجة التطبيقات؟

التدفق الأساسي في واجهة برمجة التطبيقات هو: إرسال طلب بتنسيق معين؛ يقوم الخادم بإرجاع استجابة بتنسيق معين. في LLMs، يكون هذا عادةً عبارة عن استدعاء HTTP (HTTP: بروتوكول قياسي لنقل استجابة الطلب على الويب) إلى عنوان واحد (نقطة النهاية، العنوان الثابت على الخادم الذي يتعامل مع طلبك). على سبيل المثال، في واجهة برمجة التطبيقات للمراسلة، تذهب جميع الطلبات إلى عنوان واحد ويتم نقلها في النص كـ JSON (ترميز كائن JavaScript - تنسيق نص يتكون من أزواج المفاتيح/القيم التي يمكن قراءتها بواسطة كل من البشر والآلات).

في الطلب، يمكنك تحديد هذه الأشياء الثلاثة على الأقل:

• النموذج: النموذج الذي ستستخدمه (على سبيل المثال، نموذج سريع ورخيص أو نموذج قوي).
• max_tokens: الحد الأقصى لعدد الرموز المميزة (أصغر وحدة تتم فيها معالجة النص، والتي ستتم معالجتها بالتفصيل في الوحدة التالية) التي يمكن للنموذج إنتاجها؛ أي حد الإخراج.
• الرسائل: قائمة الرسائل التي تتكون منها المحادثة.

خطوة بخطوة: كيفية إعداد الطلب

1. قم بإعداد نقطة النهاية وبيانات الاعتماد. يمكنك إضافة مفتاح API الخاص بك (السلسلة السرية التي تثبت هويتك) إلى الطلب في الرأس. لا تقم أبدًا بتضمين المفتاح في الكود؛ سنقوم بتغطية التخزين الآمن في الوحدة 9.
2. حدد النموذج والحد الأقصى للإخراج. نموذج خفيف الوزن + رموز صغيرة بحد أقصى لمهمة بسيطة؛ نموذج قوي + حد أكبر لمهمة معقدة.
3. قم بإعداد قائمة الرسائل. List the system instruction, user message, and past rounds (if any).
4. أرسل الطلب وقم بتحليل الرد. اقرأ محتوى النص وسبب الإيقاف واستخدام الرمز المميز من JSON الذي تم إرجاعه.

أدوار الرسالة: النظام، المستخدم، المساعد

تتكون المحادثة من رسائل مرتبة بالتسلسل، ولكل رسالة دور. يحدد الدور كيفية تعامل النموذج مع هذا النص.

الدور

من يكتب

الغرض

نظام

المطور/المشغل

التعليمات الدائمة والشخصية والقواعد التي تنطبق طوال المحادثة بأكملها

user

المستخدم النهائي

السؤال أو الإدخال الحالي للمستخدم

مساعد

نموذج

الاستجابة التي ينتجها النموذج (والاستجابات السابقة)

يتوفر دور النظام كحقل نظام منفصل في نص الطلب في معظم مقدمي الخدمة؛ يتم إدراج المستخدم والمساعد بالتسلسل في قائمة الرسائل. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.

{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "أنت مساعد دعم في الشركة. قدم إجابة قصيرة ورسمية وموثقة. لا تقم باختلاق معلومات لست متأكدًا منها.", "messages": [ { "role": "user", "content": "كيف أبدأ عملية الإرجاع؟" } ]}

الكلام عديم الجنسية

إليك المفهوم الخاطئ الأكثر شيوعًا: استدعاءات LLM API عديمة الحالة — لا يحتفظ الخادم بأي ذاكرة بين طلبين. النموذج لا يتذكر طلبك السابق. إذا كنت تقوم بإعداد محادثة متعددة الجولات، فستحتاج إلى إعادة إرسال الجولات السابقة مع كل طلب جديد. تتكون "ذاكرة" النموذج من قائمة الرسائل التي أرسلتها.

{ "model": "claude-opus-4-8"، "max_tokens": 512، "messages": [ { "role": "user"، "content": "مرحبًا، اسمي Deniz." }, { "role": "assistant"، "content": "مرحبًا دنيز، كيف يمكنني مساعدتك؟" }, { "role": "user", "content": "لقد قلت اسمي للتو، هل تتذكر؟" } ]}

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

نصيحة: في المحادثات الطويلة، يؤدي تلخيص الجولات القديمة ونقلها (الملخص + الجولات القليلة الأخيرة) بدلاً من إرسال السجل بالكامل إلى تقليل التكلفة والحفاظ على نافذة السياق. سوف نقوم بتعميق هذا في الوحدتين 6 و 11.

اقرأ الجواب

عندما يقوم النموذج بإرجاع استجابة، فإنك تتلقى كائنًا منظمًا، وليس نصًا عاديًا. المناطق النموذجية:

{ "id": "msg_01ABC..."، "model": "claude-opus-4-8"، "role": "assistant"، "content": [ { "type": "text"، "text": "لبدء الإرجاع، انتقل إلى صفحة "طلباتي" في حسابك..." } ]، "stop_reason": "end_turn"، "usage": { "input_tokens": 47، "output_tokens": 88 }}

• المحتوى: الرد نفسه؛ إنها قائمة كتل المحتوى. حقل النص الخاص بكتلة النص هو الإجابة الفعلية.
• stop_reason: لماذا توقف النموذج. end_turn = النهاية الطبيعية؛ max_tokens = عالق عند حد الإخراج (قد تكون الاستجابة غير مكتملة)؛ رفض = رفض لأسباب أمنية. يجب أن ينظر الكود الخاص بك دائمًا إلى stop_reason أولاً.
• الاستخدام: أرقام الإدخال والإخراج المميزة. هذا هو أساس التكلفة والحد من التتبع.

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

موجه ضعيف / موجه قوي

نفس المهمة مع اثنين من مطالبات النظام المختلفة:

# ضعيف أنت مساعد. الإجابة على الأسئلة.

# قوي أنت مساعد دعم الشركة. القواعد: - الاعتماد فقط على المعلومات الواردة في وثيقة السياسة المقدمة؛ إذا لم تكن موجودة في المستند، فقل "ليس لدي هذه المعلومات، سأقوم بتوجيهها إلى الوحدة المعنية". - يجب ألا تتجاوز الإجابات 3 جمل، وأن تكون رسمية وواضحة. - لا تطلب بيانات شخصية (رقم هوية TC، رقم البطاقة) ولا تكررها. - لا تخمن عندما لا تكون متأكداً.

نسخة قوية؛ فهو يحدد النطاق والشكل وهامش الأمان والسلوك في حالة عدم اليقين. ويأتي اتساق مخرجات النموذج مباشرة من هذا الوضوح.

ثلاث حالات صغيرة

الحالة 1 - روبوت الدعم (فخ انعدام الجنسية). قام فريق التجارة الإلكترونية بنقل الروبوت مباشرة؛ عندما قال المستخدم "إلغاء الطلب السابق"، "نسي" الروبوت رقم الطلب. السبب: كانوا يرسلون كل طلب بالرسالة الأخيرة فقط. الحل: أضافوا آخر 6 جولات إلى قائمة الرسائل. النتيجة: الحفاظ على السياق، ولكن زيادة المدخلات لكل طلب من 40 رمزًا مميزًا إلى 600 رمزًا تقريبًا - سنغطي درس التكلفة في الوحدة 2.

الحالة 2 - ملخص العقد غير مكتمل. كان الفريق القانوني لديه عقود مكونة من 10 صفحات؛ max_tokens: بقي 300 منخفضًا، وكانت الملخصات تقطع منتصف الجملة. كان stop_reason هو الحد الأقصى من الرموز في كل مرة ولكن لم يكن أحد يبحث. زيادة الحد الأقصى للرموز إلى 1500 وإضافة التحقق من سبب الإيقاف؛ انخفض معدل الملخص المقتطع من 18% إلى 0%.

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

الأخطاء الشائعة

• نسيان إرسال الماضي: يُعتقد أن النموذج "لا يتذكر"؛ في حين أنها عديمة الجنسية. أنت تحمل السياق.
• عدم النظر إلى `stop_reason`: الاستجابة المتوقفة باستخدام max_tokens تعتبر كاملة.
• تضمين التعليمات في "المستخدم": القواعد الثابتة في النظام؛ الإدخال الفوري يذهب إلى المستخدم. الخلط يخلق ثغرات أمنية.
• الخلط بين "المحتوى" وسلسلة عادية: الإجابة هي قائمة الكتل؛ اقرأ حقل النص الخاص بالكتلة النصية الأولى، وتحقق من نوعه قبل الحصول على المحتوى[0] باستخدام فهرس أعمى.
• تضمين المفتاح في الكود: استخدم متغير البيئة (الوحدة 9).

أعمق: كتل المحتوى وإجابات متعددة الأجزاء

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

ما يفعله هذا التمييز عمليًا هو أنه يمكنك تسجيل منطق النموذج (إن وجد) دون الكشف عنه للمستخدم، وإعادة توجيه استدعاءات الأداة إلى منطق منفصل، وطباعة الإجابة الفعلية فقط على الشاشة. مع تقدم الوحدة (خاصة في الوحدتين 4 و11) سترى مدى فائدة بنية الكتلة هذه للتحقق من صحة المخرجات وتوجيهها.

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

باختصار

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

مهمة التطبيق

اختر مهمة من مهنتك (مثل فرز البريد الإلكتروني الوارد وإنشاء ملخصات مختصرة). على قطعة من الورق: (1) اكتب موجه النظام مع 4-5 قواعد، (2) قم بإعداد نموذج رسالة مستخدم وسجل من جولتين إن وجد، (3) حدد قيمة معقولة لـ max_tokens واكتب التبرير، (4) قم بإدراج قيم stop_reason التي ستتعامل معها في الاستجابة التي تم إرجاعها وكيف.

قائمة مرجعية

• [ ] يمكنني حساب الأجزاء الإلزامية الثلاثة للطلب (النموذج، max_tokens، الرسائل).
• [ ] يمكنني شرح الفرق بين أدوار النظام والمستخدم والمساعد.
• [ ] أعلم أن المكالمات عديمة الجنسية وأنني بحاجة إلى حمل الماضي.
• يمكنني القراءة والتعليق على محتوى [ ] وstop_reason وحقول الاستخدام.
• [ ] باستخدام max_tokens يمكنني ملاحظة الاستجابة المقتطعة والتعامل معها.