وصف المقال: يحتفظ AI Chat v2 بطريقة الاستدعاء البسيطة لواجهة المحادثة الأصلية، وفي الوقت نفسه يضيف إدخالًا متعدد الوسائط، وتدفق أحداث منظمًا، واستدعاءً تلقائيًا للأدوات، وإيقافًا واستئنافًا، وتنفيذًا غير متزامن، وإدارة للجلسات. يبدأ هذا المقال من ترحيل لا يكاد يتطلب إعادة كتابة الكود، ويوضح كيف تؤثر هذه التغييرات في تطوير المنتجات الحقيقية.
تكون العديد من واجهات المحادثة سهلة الاستخدام جدًا في مرحلة العرض التوضيحي: مرّر سؤالًا، وانتظر حتى يعيد النموذج فقرة من النص، ثم اعرض النص على الصفحة.
عندما يستمر المنتج في التقدم، لا تعود الأمور مجرد «سؤال واحد، وإجابة واحدة». سيرفع المستخدمون ملفات PDF ولقطات شاشة، وسيحتاج النموذج إلى البحث في الويب وقراءة الملفات، بل وحتى استدعاء أدوات GitHub وNotion وغيرها التي تم تفويضها بالفعل. قد تستمر مهمة واحدة لعدة جولات، وقد تتوقف في المنتصف لتسأل عن معلومات ناقصة. في هذه الحالة، إذا كانت الواجهة لا تزال تعيد فقط سلسلة نصية تتزايد باستمرار، فسيصعب على الواجهة الأمامية معرفة ما الذي يفعله النموذج، كما سيكون من الصعب على الواجهة الخلفية تحديد ما إذا كانت المهمة قد انتهت بالفعل.
هذا بالضبط هو ما تحله Ace Data Cloud AI Chat v2 API. فهي لا تقلب طريقة المحادثة الأصلية، بل تقسم الإجابة، على أساس التوافق مع الاستدعاءات البسيطة، إلى أحداث يمكن للبرنامج تمييزها ومعالجتها: المتن هو متن، واستدعاء الأداة هو استدعاء أداة، وللاقتباسات والملفات والأخطاء والحالة النهائية مواضع واضحة خاصة بها.

الشكل: لم يعد AI Chat v2 يضغط المهمة بأكملها في فقرة نصية واحدة، بل يحافظ على بنية أحداث الإدخال والأدوات والإخراج.
¶ يمكن أن يبدأ الترحيل بتغيير عنوان واحد
إذا كان المشروع يستخدم الإصدار القديم /aichat/conversations، فلا حاجة أولًا إلى إعادة كتابة بنية الرسائل، ولا إلى إنشاء واجهة Agent كاملة أولًا. يستمر V2 في قبول حقول مثل model وquestion وstateful وid وreferences وpreset الأصلية. لا يتطلب الحد الأدنى من الترحيل سوى تغيير عنوان الطلب إلى:
https://api.acedata.cloud/aichat2/conversations
ولا يزال الطلب الأساسي قصيرًا جدًا:
curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
-H 'accept: application/json' \
-H 'authorization: Bearer YOUR_API_TOKEN' \
-H 'content-type: application/json' \
-d '{
"model": "YOUR_SUPPORTED_MODEL",
"question": "请概括这份需求里最重要的三个问题。",
"stateful": true
}'
في وضع JSON العادي، لا تزال الواجهة تعيد النتيجة المألوفة:
{
"answer": "...",
"id": "conversation-uuid"
}
احفظ id المعاد، وأرسل الطلب التالي مع id نفسه، وستتمكن من متابعة المحادثة. القيمة الافتراضية لـ stateful هي true، وتُستخدم للتحكم في ما إذا كان سيتم تحميل سياق المحادثة المحفوظة ومتابعته.
هذه الخطوة مناسبة جدًا للمشاريع الحقيقية: تحقق أولًا من أن المصادقة والنموذج وزمن الاستجابة والأعمال القديمة تعمل بصورة طبيعية، ثم ادمج القدرات الجديدة تدريجيًا. لا يلزم ربط الترحيل بإعادة تصميم الواجهة في عملية إطلاق واحدة.
¶ عندما تدخل الملفات والصور إلى المحادثة، يصبح الترتيب أيضًا جزءًا من المعلومات
يصلح question القديم للنص الخالص. لكن عند الوصول إلى مهام مثل «راجع التقرير أولًا، ثم قارنه بلقطة الشاشة، وأعطِ النتيجة أخيرًا»، لا تعود قائمة المرفقات البسيطة دقيقة بما يكفي. يضيف V2 مصفوفة message منظمة، يمكن وضع النصوص والصور والملفات فيها بالترتيب:
{
"model": "YOUR_SUPPORTED_MODEL",
"stateful": true,
"message": [
{
"type": "text",
"text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
},
{
"type": "file_url",
"file_url": {"url": "https://example.com/report.pdf"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/dashboard.png"}
}
]
}
تشمل كتل المحتوى المتاحة text وimage_url وfile_url. والمهم ليس فقط «دعم المرفقات»، بل إن العلاقات بين المحتويات لا تضيع أثناء النقل. يمكن للعميل أن يخبر النموذج بوضوح: أي جزء هو وصف المهمة، وأي ملف هو المادة الأصلية، وما الذي يجب مقارنته بعد ذلك.
ولتمكين العملاء القدامى من الترحيل بسلاسة، لا يزال V2 يتعرف على references. ستُعالج عناوين URL المطابقة لامتدادات الصور كصور، بينما ستُعالج عناوين URL الأخرى كملفات. إذا كنت تقوم فقط بترقية الواجهة، فيمكنك الاحتفاظ بالصيغة القديمة مؤقتًا؛ أما إذا كان ترتيب الإدخال يؤثر في الفهم، فيُنصح باستخدام message.
¶ لم تعد الاستجابة المتدفقة مجرد «كتابة جارية»
عادةً ما يحتوي الإخراج المتدفق التقليدي على زيادات نصية فقط. بعد أن يبدأ النموذج في البحث أو قراءة الملفات أو استدعاء أدوات خارجية، تبدو الصفحة وكأنها متوقفة، فلا يعرف المستخدم ما إذا كانت المهمة مستمرة، ولا يحصل المطور على حالة واضحة.
يوفر AI Chat v2 ثلاث طرق للاستجابة عبر رأس الطلب accept:
| سيناريو الاستخدام | accept |
طريقة الإرجاع |
|---|---|---|
| طلب بسيط من جهة الخادم | application/json |
يعيد {answer, id} بعد الاكتمال |
| Node أو Python أو CLI أو Worker | application/x-ndjson |
حدث JSON واحد في كل سطر |
| الواجهة الأمامية للويب | text/event-stream |
تدفق أحداث SSE |
في وضعي NDJSON وSSE، لا يكون المعاد مجرد token، بل مجموعة من الأحداث ذات الأنواع. يُستخدم text_delta لزيادات المتن، ويشير tool_use إلى أن النموذج يستعد لاستدعاء أداة، ويعيد tool_result نتيجة الأداة، ويوفر citation مصدر الاقتباس، ويحمل card وartifact بطاقات أو مخرجات يمكن عرضها بشكل منفصل، ويشير error إلى فشل هذه الجولة، بينما يقدم done معلومات الاستخدام وسبب الإنهاء.
يقوم عميل Python التالي بتجميع المتن من جهة، والاحتفاظ بالحالات الرئيسية من جهة أخرى:
import json
import os
import requests
url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
"accept": "application/x-ndjson",
"authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
"content-type": "application/json",
}
payload = {
"model": os.environ["ACEDATA_CHAT_MODEL"],
"question": "检索资料,给出带来源的简要结论。",
"stateful": True,
}
with requests.post(url, json=payload, headers=headers,
stream=True, timeout=120) as response:
response.raise_for_status()
answer = []
for raw_line in response.iter_lines():
if not raw_line:
continue
event = json.loads(raw_line)
event_type = event.get("type")
if event_type == "text_delta":
answer.append(event.get("content", ""))
elif event_type == "tool_use":
print("开始调用:", event.get("tool_name"))
elif event_type == "tool_result":
print("工具是否失败:", event.get("is_error"))
elif event_type == "error":
raise RuntimeError(event.get("message", "未知错误"))
elif event_type == "done":
print("用量:", event.get("usage"))
print("终止原因:", event.get("terminal_reason"))
print("".join(answer))
إذا كان المنتج يهتم فقط بالنص النهائي، فيكفي ربط جميع text_delta.content معًا؛ وإذا كان يريد إنشاء واجهة Agent قابلة للمراقبة، فيمكنه عرض استدعاءات الأدوات، والمراجع، والمخرجات، والحالات بشكل منفصل. يستخدم الاحتياجان الواجهة نفسها، ولا حاجة إلى صيانة مجموعتين من البروتوكولات من أجل «الدردشة البسيطة» و«المهام المعقدة».
¶ استدعاء الأدوات متاح افتراضيًا، لكن لا يزال على المنتج رسم الحدود بوضوح
يمكن لـ V2 أن يتيح للنموذج، وفقًا لاحتياجات المهمة، استدعاء قدرات مدمجة مثل البحث في الويب، واستخراج الصفحات، وقراءة الملفات؛ وبعد أن يربط المستخدم الخدمات المقابلة ويمنحها التفويض، يمكنه أيضًا استخدام أدوات MCP لمعالجة البيانات الخارجية مثل GitHub وNotion.
سيظهر في التدفق كل من tool_use وtool_result، ويُزاوَجان عبر tool_id. وبناءً على ذلك، يمكن للواجهة الأمامية عرض التقدم الحقيقي، كما يمكن للواجهة الخلفية تسجيل وقت استهلاك كل أداة وموضع الفشل.
كون الأدوات يمكن استدعاؤها تلقائيًا لا يعني أن نطاق التنفيذ ينبغي أن يُفتح بلا حدود. يُستخدم max_turns لتقييد عدد جولات تكرار Agent ضمن طلب واحد، والنطاق المذكور في الوثائق هو 1—500؛ وعند ضبطه على 1، لا تُجرى في هذه الجولة سوى مكالمة نموذج واحدة، ولن يستمر في الدخول إلى استدعاء الأدوات. ينبغي لبيئة الإنتاج ضبطه بصورة استباقية وفقًا لتعقيد المهمة، ووقت الاستجابة، وميزانية التكلفة، بدلًا من الاعتماد طويلًا على حد افتراضي كبير.
بالنسبة إلى مهام Webhook أو CI/CD أو المراقبة، يدعم V2 async: true، ويمكن تنفيذ المهمة في الخلفية والحصول على النتيجة من خلال الاستعلام أو callback_url. لكن الإجراءات التي تتضمن الإرسال أو النشر أو الكتابة تحتاج إلى تفويض مسبق واضح عبر allowed_skills أو allowed_mcp_servers أو unattended_policy.
يعالج الاتصال مسألة «هل يمكن الوصول»، وتعالج سياسة التفويض مسألة «هل يمكن في هذه المرة التصرف نيابةً عن المستخدم». لا يمكن خلط هذين الأمرين معًا.
¶ عندما يفتقر Agent إلى المعلومات، لا حاجة إلى التظاهر بأن المهمة قد اكتملت
غالبًا ما تتعطل المهام المعقدة عند أسئلة محددة: إلى أي قناة يتم النشر، وأي تنسيق يُعتمد، وهل تُستبدل الملفات الموجودة. يوفر V2 لهذا الغرض حدث ask_user_question. بعد ظهور الحدث، تدخل الجلسة في حالة انتظار إدخال المستخدم.
يحفظ العميل id الخاص بالجلسة الحالية وtool_id المقابل، ويعرض السؤال ويجمع الإجابة، ثم يستخدم id الجلسة نفسه لإعادة الإجابة عبر tool_results، وبذلك يمكن للمهمة متابعة التنفيذ من نقطة التوقف. هذه الآلية مناسبة أيضًا لإنشاء نقاط الموافقة. بدلًا من أن يدع النموذج يخمّن بنفسه عند نقص المعلومات، من الأفضل إعادة الخيارات الناقصة إلى المستخدم.
¶ يمكن أيضًا إدارة الجلسة نفسها
يضيف V2 عمليات CRUD خفيفة للجلسات ضمن نقطة النهاية نفسها، ويميز بين retrieve وretrieve_batch وupdate وdelete عبر action.
يعيد retrieve_batch ملخصات من دون تضمين messages الكاملة، وهو مناسب للشريط الجانبي للجلسات؛ وعندما يفتح المستخدم الجلسة فعليًا، يُستدعى retrieve لقراءة النص الكامل. وبالنسبة إلى الجلسات الطويلة، لن تستخدم معالجة السياق من جانب الخادم الملخصات لاستبدال الرسائل الأصلية المحفوظة. عند الحاجة إلى الاستمرار في تعديل المقالة، أو التحقق من الأرقام، أو الاستعداد للنشر، ينبغي مع ذلك قراءة النص الأصلي، بدلًا من استخدام الملخص بدلًا من المتن.
¶ قبل الإطلاق، لا تتحقق فقط من «هل عاد نص»
بعد ربط واجهة Agent، فإن تلقي جزء من النص لا يعني أن هذه الجولة قد اكتملت بشكل موثوق؛ كما أن انتهاء التدفق لا يعني بالضرورة نجاح المهمة. ينبغي للعميل معالجة error، وتسجيل usage وterminal_reason بعد تلقي done. في SSE، لا يشير [DONE] إلا إلى انتهاء النقل، ولا يمكنه تجاوز أحداث الخطأ التي ظهرت سابقًا.
ينبغي حفظ API Token على جانب الخادم فقط؛ ويجب أن يكون محلل التدفق قادرًا على معالجة تجزئة الشبكة والأحداث الجديدة غير المعروفة مؤقتًا؛ ويجب إقران استدعاءات الأدوات وفقًا لـ tool_id؛ ويجب عرض روابط المراجع والمخرجات بأمان؛ ويجب أن تستمر الاتصالات القابلة للكتابة في الاحتفاظ بالتأكيد البشري أو بتفويض غير مراقب ضيق بما يكفي. قد تتغير أسماء النماذج، والفوترة، والقدرات المتاحة، وعند الربط الرسمي ينبغي الاعتماد على الوثائق الحالية، وصفحة الخدمة، ووحدة التحكم، وعدم تثبيت إعدادات الأمثلة لفترة طويلة.
أكثر ما يستحق الاهتمام في AI Chat v2 ليس إضافة بضعة أزرار أخرى إلى نافذة الدردشة. بل إنه يتيح للتطبيق أخيرًا رؤية ما يحدث داخل مهمة AI واحدة: متى يُخرج النموذج نصًا، ومتى يستدعي الأدوات، وأين ينتظر المستخدم، وبأي حالة ينتهي.
إذا كان المشروع الحالي لا يزال مجرد مربع أسئلة وأجوبة عادي، فيمكن البدء بتغيير عنوان الواجهة والاستمرار في استخدام جسم الطلب الأصلي. وبعد استقرار هذه الخطوة، يمكن ربط message وNDJSON أو SSE والخط الزمني للأدوات والإيقاف والاستئناف. يمكن أن تكون الترقية صغيرة، لكنها تترك مساحة كبيرة بما يكفي لأشكال المنتجات اللاحقة.
