كان إنشاء روبوت محادثة في الماضي يعني التعامل مع مصنفات النوايا، وأشجار الحوار، وكم هائل من الحالات الاستثنائية. أما مع واجهة برمجة تطبيقات (API) نموذج اللغة الحديثة، فإن النموذج يتولى الجزء الصعب — وهو الفهم والرد — وتقتصر مهمتك على الربط بين العناصر المحيطة به. باستخدام واجهة برمجة تطبيقات Claude، يمكنك الحصول على روبوت محادثة فعال حقًّا في أقل من ساعة بكثير.
يشرح هذا الدليل المفاهيم والرمز البرمجي بالتفصيل: الإعداد، وإجراء المحادثة، وتوجيه السلوك، وبث الردود، والحد من التكاليف.
أبرز الاستنتاجات
- الدعوة الأساسية وهي واجهة برمجة تطبيقات الرسائل — حيث ترسل قائمة بالرسائل، فيرد «كلود» بردٍ عليها.
- ذاكرة المحادثة هذه هي مهمتك: الاحتفاظ بسجل الرسائل وإعادة إرسالها في كل جولة.
- موجه النظام يحدد دور الروبوت وشخصيته وقواعده.
- البث المباشر يجعل الرد يظهر كلمةً كلمةً، تمامًا مثل الدردشة الحقيقية.
- التخزين المؤقت الفوري يعيد استخدام الأجزاء الثابتة من الموجه لتقليل التكلفة وزمن الاستجابة بشكل كبير.
الخطوة 1: الإعداد
تحتاج إلى شيئين: مفتاح API وحزمة SDK.
- الحصول على مفتاح API — قم بإنشاء حساب في «Anthropic Console» وقم بإنشاء مفتاح API. حافظ على سرية هذا المفتاح: قم بتخزينه في متغير بيئة، ولا تقم أبدًا بكتابته بشكل ثابت في الكود أو إدراجه في نظام التحكم في الإصدارات.
- تثبيت حزمة تطوير البرامج (SDK) — توفر شركة Anthropic حزم تطوير البرامج (SDK) الرسمية. بالنسبة إلى لغة Python:
pip install anthropic
(يتوفر أيضًا حزمة أدوات تطوير البرامج (SDK) لـ Node.js؛ والمفاهيم الواردة أدناه متطابقة.)
الخطوة 2: رسالتك الأولى
جوهر واجهة برمجة تطبيقات «كلود» هو واجهة برمجة تطبيقات الرسائل. ترسل قائمة بالرسائل؛ فيقوم كلود بإرجاع الرسالة التالية. وإليك أبسط استدعاء ممكن:
from anthropic import Anthropic
client = Anthropic() # يقرأ متغير البيئة ANTHROPIC_API_KEY
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "مرحبًا! كيف يمكنني مساعدتك؟"}
],
)
print(response.content[0].text)
هذا روبوت دردشة يعمل — وإن كان شديد النسيان. نموذج يحدد أي شخصية من «كلود» سيتم استخدامها،, max_tokens يحدد الحد الأقصى لطول الرد، و الرسائل هذا هو ما دار في المحادثة حتى الآن.
الخطوة 3: تزويدها بذاكرة
المثال أعلاه لا يتضمن ذاكرة: فكل استدعاء مستقل بذاته. ولإجراء محادثة حقيقية،, أنتَ/أنتِ احتفظ بالسجل وأعد إرساله في كل دور. واجهة برمجة التطبيقات (API) نفسها لا تحتفظ بحالة — فهي لا تعرف سوى ما ترسله إليها.
النمط: الحفاظ على الرسائل قائمة، وإضافة كل رسالة من المستخدم وكل رد من كلود إليها، وتمرير القائمة بأكملها في كل استدعاء.
from anthropic import Anthropic
client = Anthropic()
messages = []
while True:
user_input = input("أنت: ")
if user_input.lower() == "quit":
break
messages.append({"role": "user", "content": user_input})
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=messages,
)
reply = response.content[0].text
print(f"Claude: {reply}")
messages.append({"role": "assistant", "content": reply})
أصبح الآن روبوت دردشة حقيقيًّا — فهو يتذكر كل ما جرى سابقًا في المحادثة، لأن سجل المحادثة يُرسل في كل جولة.
الخطوة 4: تحديد شخصيته باستخدام موجه النظام
نادرًا ما يكون المساعد العام هو ما تريده. إن موجه النظام يحدد دور البوت ونبرة حديثه وقواعده. ويتم تمريره كملف منفصل النظام معلمة، وليس كرسالة.
SYSTEM_PROMPT = """أنت مساعد دعم ودود في خدمة اشتراك
القهوة. كن ودودًا وموجزًا ومتعاونًا. إذا سأل أحد العملاء
عن شيء لا تعرفه، أخبره أنك ستقوم بتحويله إلى
موظف دعم بشري. لا تتحدث أبدًا عن المنافسين."""
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=messages,
)
تعد مطالبات النظام أداتك الرئيسية لتوجيه السلوك — فكرس وقتًا لها. كن محددًا فيما يتعلق بالدور، ونبرة الصوت، وما يجب أن يفعله الروبوت في حالات عدم اليقين، وأي حدود صارمة.
الخطوة 5: بث الاستجابة
في الأمثلة أعلاه، تنتظر وصول الرد بالكامل قبل أن يظهر أي شيء. أما واجهات الدردشة الحقيقية فتعمل بنظام البث المباشر — حيث يصل النص كلمةً كلمةً. وتجعل حزمة SDK هذه العملية سهلةً:
باستخدام client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=messages,
) كـ stream:
for text in stream.text_stream:
print(text, end="", flush=True)
لا يؤدي البث المباشر إلى تسريع عملية التوليد، لكنه يجعل الروبوت الشعور أكثر استجابة بشكل ملحوظ، لأن المستخدم يرى النتيجة على الفور.
الخطوة 6: خفض التكاليف من خلال التخزين المؤقت الفوري
يتم احتساب تكلفة استدعاءات واجهة برمجة التطبيقات (API) على أساس عدد الرموز (tokens)، ويقوم روبوت الدردشة بإعادة إرسال الكثير من النصوص المتكررة في كل جولة — سواء كانت المطالبة التي يطلبها النظام، أو سجل المحادثة الذي لا ينفك يتزايد. التخزين المؤقت الفوري يتيح لك تحديد الأجزاء الثابتة من المطالبة بحيث تعيد واجهة برمجة التطبيقات (API) استخدامها بدلاً من إعادة معالجتها، مما يقلل بشكل كبير من التكلفة وزمن الاستجابة.
تقوم بإضافة علامة التخزين المؤقت إلى المحتوى الذي تريد تخزينه مؤقتًا — وعادةً ما يكون ذلك موجه النظام، وأي سياق طويل وثابت:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"},
}
],
messages=messages,
)
بالنسبة لأي روبوت دردشة يتعامل مع حركة مرور حقيقية، قم بتمكين التخزين المؤقت للمطالبات منذ البداية — فهي واحدة من أكثر عمليات التحسين تأثيرًا المتاحة، ولا يتكلف تفعيلها شيئًا.
اختيار النموذج
يأتي «كلود» في عدة مستويات. وكقاعدة عامة:
- نموذج سريع ومتوازن (مثل باقة «Sonnet») هي الخيار الافتراضي المناسب لمعظم روبوتات الدردشة — جودة عالية، وسرعة جيدة، وتكلفة معقولة.
- الطراز الأكثر كفاءة (فئة Opus) تُعد خيارًا مناسبًا عندما يتعين على الروبوت التعامل مع عمليات استدلال صعبة أو مهام معقدة.
- طراز أصغر حجمًا وأسرع (فئة «هايكو») مناسبة للروبوتات البسيطة ذات الحجم الكبير، حيث تُعد السرعة والتكلفة من أهم العوامل.
ابدأ بالمستوى المتوازن، ولا تنتقل إلى مستوى أعلى أو أدنى إلا بعد أن تلاحظ استخدامًا فعليًّا.
الانتقال إلى مرحلة الإنتاج
الرمز أعلاه هو الجزء الأساسي الفعال. للنشر الفعلي، أضف:
- طبقة الويب — تضمين المنطق في نقطة نهاية واجهة برمجة التطبيقات (API) وربط واجهة مستخدم للدردشة بها.
- حدود التاريخ — المحادثات تستمر إلى ما لا نهاية؛ لذا قم بوضع حد أقصى لعدد المشاركات القديمة أو تلخيصها حتى لا تتضخم المطالبات.
- معالجة الأخطاء — التعامل مع حدود معدل الاستخدام والأعطال المؤقتة من خلال إعادة المحاولة.
- المعرفة — للإجابة استنادًا إلى بياناتك الخاصة، أضف التوليد المعزَّز بالاسترجاع (Retrieval-Augmented Generation) وبالتالي، يقوم البوت باستخراج الوثائق ذات الصلة.
- السلامة — التحقق من صحة المدخلات ووضع حدود واضحة في موجه النظام.
التعامل مع الأخطاء وحدود الاستخدام قبل أن يكتشفها المستخدمون
حتى لو كان روبوت الدردشة يعمل على جهاز الكمبيوتر المحمول الخاص بك، فإنه سيتعطل في بيئة الإنتاج بمجرد وصول حركة مرور حقيقية إليه. تُظهر واجهة برمجة تطبيقات «كلود» نوعين من الأعطال، وكلاهما يتطلب استجابة مختلفة. النوع الأول هو أخطاء مؤقتة في واجهة برمجة التطبيقات (API) — تظهر هذه الحالات كاستثناءات مصحوبة برمز حالة HTTP. والثانية هي الرفض, ، وهو رد ناجح تمامًا يقتصر على رفض الطلب. ويُعد الخلط بين الاثنين أكثر أخطاء الموثوقية شيوعًا التي نراها في الأكواد الأولية لبرامج الدردشة الآلية.
فيما يتعلق بالحالات المؤقتة، هناك رمزان للحالة يكتسيان أهمية قصوى:
- 429 (حد عدد الطلبات) — لقد تجاوزت الحصة المسموح بها لحسابك من حيث عدد الطلبات في الدقيقة أو عدد الرموز في الدقيقة. وتحتوي الاستجابة على
إعادة المحاولة بعدعنوان يوضح لك بالضبط عدد الثواني التي عليك انتظارها. التزم به بدقة؛ فالانتظار لفترة أقل سيؤدي إلى حصولك على 429 أخرى. - 529 (تحميل زائد) — واجهة برمجة تطبيقات (API) شركة Anthropic مشغولة مؤقتًا لجميع المستخدمين. لا يمكنك منع حدوث ذلك عبر الكود، ولن يتم احتساب تكلفة الطلبات المرفوضة برمز الخطأ 529. تراجع وحاول مرة أخرى؛ ولا تقم أبدًا بإرسال طلبات متكررة إلى نقطة نهاية مشغولة.
- 500 (خطأ في الخادم) — خطأ داخلي نادر. تعامل معه كما في الحالة 529: أعد المحاولة مع التراجع.
الخبر السار هو أن حزم SDK الرسمية تعيد بالفعل محاولة معالجة أخطاء 429 و5xx نيابة عنك باستخدام تقنية «التأجيل الأسي» (الحد الافتراضي هو محاولتان). بالنسبة لروبوت الدردشة في بيئة الإنتاج، قم برفع هذا الحد الأقصى ودع حزمة SDK تتولى المهمة بدلاً من كتابة حلقة تكرار خاصة بك:
- تحديث
max_retriesعلى جانب العميل (تُعد القيمة التي تتراوح بين 4 و5 مناسبة للدردشة الموجهة للمستخدم). - التعامل مع الاستثناءات المُحدَّدة —
خطأ في الحد الأقصى لعدد الطلبات,خطأ التحميل الزائد,APIError— بدلاً من مطابقة النص كسلسلة في حالة الخطأ، وهو ما يؤدي إلى حدوث خطأ خفي عند تغيير الصياغة. - عندما تنفد محاولات إعادة المحاولة نهائيًا، اعرض للمستخدم رسالة هادئة تقول: “أنا مشغول قليلاً في الوقت الحالي، يرجى المحاولة مرة أخرى بعد قليل”، بدلاً من عرض تتبع المكدس.
أما حالات الرفض فهي مسار منفصل تمامًا. عندما يأتي الرد على النحو التالي: سبب_الإيقاف: "الرفض", ، الطلب نجح — رفض «كلود» الرد لأسباب تتعلق بالسلامة، وفي النماذج الحالية لا يتم تحصيل أي رسوم منك في حالة عدم إنتاج أي مخرجات. والأهم من ذلك، يجب ألا تكتفي بإعادة إرسال المحادثة نفسها: فسيتكرر الرفض. بدلاً من ذلك، قم بحذف أو إعادة صياغة الجملة التي تسببت في الرفض، أو أعد ضبط سجل المحادثة، ثم اعرض رسالة واضحة للمستخدم. نظرًا لأن الرفض هو حقل في الاستجابة وليس استثناءً، فإن الكود الذي يقتصر على فحص نهاية الدور و استخدام_الأدوات ستتركها تمر كإجابة فارغة ومربكة. احرص دائمًا على إضافة فرع صريح لها.
قم بربط هذه السلوكيات الثلاثة — إعادة المحاولة مع التراجع التدريجي، ومعالجة الاستثناءات المُصنَّفة، وفرع الرفض — وسيعمل روبوت الدردشة الخاص بك بشكل سلس حتى في ظل الأحمال العالية، بدلاً من التعطل بشكل صارخ أمام الأشخاص الذين صممته من أجلهم.
الأسئلة الشائعة
كيف يمكنني إنشاء روبوت دردشة باستخدام واجهة برمجة تطبيقات Claude؟
قم بتثبيت حزمة تطوير التطبيقات (SDK) الخاصة بشركة Anthropic، واحصل على مفتاح واجهة برمجة التطبيقات (API)، ثم استدعِ واجهة برمجة التطبيقات الخاصة بالرسائل (Messages API): أرسل قائمة بالرسائل وسيقوم «كلود» بالرد عليها. ولجعل المحادثة تبدو طبيعية، احتفظ بسجل الرسائل بنفسك وأعد إرساله في كل دور. أضف موجهًا نظاميًا لتحديد الشخصية، واستخدم تقنية البث المباشر لإضفاء إحساس بالتفاعل.
هل تحتفظ واجهة برمجة التطبيقات (API) الخاصة بـ «كلود» بالرسائل السابقة؟
لا — واجهة برمجة التطبيقات (API) لا تحتفظ بحالة. فهي لا تعرف سوى ما ترسله في طلب معين. ولتمكين روبوت الدردشة من تذكر المحادثة، يجب أن يقوم تطبيقك بتخزين سجل المحادثة وإدراجه في الرسائل قائمة في كل مكالمة.
ما المقصود بـ«موجه النظام»؟
تعد “موجهات النظام” تعليمات منفصلة تحدد دور روبوت الدردشة ونبرة حديثه وقواعده — على سبيل المثال، «أنت مساعد دعم موجز؛ قم بتحويل المكالمة إلى موظف بشري عند عدم التأكد». ويتم تمريرها على شكل النظام المعلمة، وهي الطريقة الرئيسية لتحديد سلوك الروبوت.
كم تبلغ تكلفة تشغيل روبوت الدردشة «كلود»؟
تعتمد التكلفة على النموذج وعدد الرموز التي تتم معالجتها. ويُعد النموذج المتوازن خيارًا غير مكلف لحركة الدردشة العادية. ونظرًا لأن روبوتات الدردشة تعيد إرسال موجه النظام وسجل المحادثة المتزايد في كل جولة، فإن تمكين التخزين المؤقت للموجه يمكن أن يقلل التكاليف بشكل كبير — حيث يعيد استخدام الأجزاء الثابتة من الموجه بدلاً من إعادة معالجتها.
ما هو نموذج «كلود» الذي ينبغي أن أستخدمه لإنشاء روبوت محادثة؟
بالنسبة لمعظم روبوتات الدردشة، ابدأ بنموذج سريع ومتوازن (فئة Sonnet) — فهو يوفر جودة عالية بسرعة وتكلفة معقولة. استخدم النموذج الأكثر كفاءة لمهام الاستدلال المعقدة، ونموذجًا أصغر حجمًا وأسرع لروبوتات الدردشة البسيطة ذات الحجم الكبير.
ما معنى الخطأين 429 و529 في واجهة برمجة تطبيقات «كلود»؟
يشير الرمز 429 إلى أنك قد وصلت إلى الحد الأقصى لمعدل الاستخدام لحسابك (عدد الطلبات أو الرموز في الدقيقة)؛ وتتضمن الاستجابة إعادة المحاولة بعد عنوان يوضح مدة الانتظار. الرقم 529 يشير إلى أن واجهة برمجة التطبيقات (API) الخاصة بـ Anthropic تعاني من حمل زائد مؤقتًا على مستوى جميع المستخدمين — ولا يتم احتساب تكلفة هذه الطلبات ولا يمكن تجنبها عبر الكود البرمجي. وكلا الحالتين تتطلبان «التراجع الأسي»، وهو ما تطبقه حزم SDK الرسمية تلقائيًّا بشكل افتراضي.
كيف ينبغي لروبوت الدردشة الخاص بي أن يتعامل مع رفض «كلود»؟
يُعتبر الرفض استجابة طبيعية وناجحة مع سبب_الإيقاف: "الرفض", ، ولا يُعتبر ذلك خطأً، ولن يتم تحصيل أي رسوم منك في حالة عدم إنتاج أي مخرجات. لا تحاول إعادة إرسال الطلب نفسه — فسيتم رفضه مرة أخرى. احذف الرسالة التي تسببت في ذلك أو أعد صياغتها (أو أعد ضبط المحادثة)، ثم اعرض على المستخدم شرحًا واضحًا وودودًا. في Opus 4.7 والإصدارات الأحدث، تتضمن الاستجابة أيضًا تفاصيل_التوقف فئة تشير إلى السياسة التي تم تفعيلها.
هل أحتاج إلى كتابة منطق إعادة المحاولة الخاص بي لواجهة برمجة تطبيقات Claude؟
عادةً لا. فحزم SDK الرسمية من Anthropic تعيد بالفعل محاولة معالجة أخطاء 429 و5xx باستخدام آلية التراجع الأسي بشكل افتراضي، مع تحديد محاولتين كإعداد افتراضي. أما بالنسبة لروبوت الدردشة الموجه للمستخدمين، فإن أبسط إعداد موثوق به هو رفع max_retries إلى حوالي أربعة أو خمسة على جانب العميل، مع التقاط الاستثناءات التي تمت كتابتها (مثل خطأ في الحد الأقصى لعدد الطلبات و خطأ التحميل الزائد) بدلاً من كتابة حلقة التراجع يدويًّا أو البحث عن تطابق مع سلاسل الأخطاء.
الخلاصة
إن إنشاء روبوت محادثة باستخدام واجهة برمجة تطبيقات «كلود» يتعلق في الغالب بعمليات الربط، وليس بالذكاء الاصطناعي. فالنموذج هو الذي يتولى الفهم والرد؛ أما أنت فتقوم بتوفير حلقة التكرار. احرص على الرسائل التاريخ وإعادة إرساله للتذكير، استخدم النظام استخدم الموجهات لتحسين الأداء الشخصي، واستخدم البث لتحسين سرعة الاستجابة، وقم بتفعيل التخزين المؤقت للموجهات للتحكم في التكلفة.
هذا الجزء الأساسي يستغرق فعليًّا ساعة من العمل. أما مسار الوصول إلى مرحلة الإنتاج فيتمثل في الأعمال الهندسية المعتادة المرتبطة به — طبقة الويب، وإدارة السجل، ومعالجة الأخطاء، و RAG إذا كان الروبوت بحاجة إلى معرفة بياناتك. ابدأ بالحلقة البسيطة المذكورة أعلاه، واجعله يتفاعل، ثم قم بالتطوير انطلاقًا من ذلك.
