بناء وكلاء الذكاء الاصطناعي باستخدام Cloudflare Workers و LangChain

يعد بناء وكيل ذكاء اصطناعي باستخدام Cloudflare Workers الخطوة التالية في الانتقال من مجرد كتابة الأوامر البسيطة (prompts) إلى إنشاء مسارات عمل ذاتية التشغيل. تستخدم هذه الأنظمة، والمعروفة باسم وكلاء الذكاء الاصطناعي (AI agents)، نماذج لغوية كبيرة (LLMs) لاستدعاء أدوات خارجية واتخاذ القرارات وتنفيذ المهام بمفردها. في حين أن تشغيل هؤلاء الوكلاء كان يتطلب تقليديًا خوادم ضخمة، فإن هذا الدليل العملي يشرح كيفية بناء واستضافة وكلاء ذكاء اصطناعي بدون خادم (serverless) باستخدام Cloudflare Workers ومكتبة LangChain.js .

ملخص سريع

• فهم وكلاء الذكاء الاصطناعي: يستخدم الوكلاء نماذج LLM لاتخاذ القرارات واستدعاء واجهات برمجة التطبيقات الخارجية (الأدوات/tools) لحل استفسارات المستخدمين بشكل ذاتي.
• استخدام LangChain.js على الحافة (edge): تتوافق مكتبة LangChain.js تمامًا مع بيئة تشغيل V8 الخفيفة الخاصة بـ Cloudflare Workers.
• كتابة أدوات مخصصة لجلب البيانات، أو القراءة من قواعد البيانات، أو تشغيل المنطق البرمجي من داخل معالج جلب الطلبات (fetch handler) الخاص بالـ Worker.
• الاستفادة من الروابط بدون خادم (bindings): اربط وكيلك بقاعدة بيانات Cloudflare D1 لحفظ ذاكرة الحالة بصيغة SQL، أو خدمة KV لتخزين جلسات العمل مؤقتًا.
• تطبيق حواجز الحماية ومهلات التشغيل (timeouts) لمنع حلقات التكرار اللانهائية والتحكم في تكاليف واجهة برمجة التطبيقات للرموز (tokens).

ما هو وكيل الذكاء الاصطناعي؟

يعمل روبوت الدردشة التقليدي وفق حلقة بسيطة من الطلب والاستجابة: ترسل أمرًا، فيعيد النموذج نصًا. في المقابل، يعمل وكيل الذكاء الاصطناعي المبني على Cloudflare Workers بشكل مستقل؛ حيث تحدد هدف الوكيل وتوفر له مجموعة من “الأدوات” (وهي دوال JavaScript مخصصة تجلب بيانات من واجهات برمجة التطبيقات، أو تبحث في قواعد البيانات، أو تنفذ عمليات حسابية). يقرر النموذج بعد ذلك أي الأدوات يستدعي، ويتفحص مخرجاتها، ويكرر الدورة حتى يحل طلبك. هذا المنطق الذاتي مناسب جدًا لأنظمة دعم العملاء المعقدة، والعمليات التلقائية في الخلفية، وإدارة قواعد البيانات. لمزيد من التفاصيل حول إعداد واجهات برمجة التطبيقات الأساسية على الحافة، راجع دليلنا حول بناء واجهة برمجة تطبيقات بدون خادم باستخدام Cloudflare Workers .

المتطلبات الأساسية

قبل أن تبدأ، تأكد من توفر ما يلي:

• حساب Cloudflare مع تفعيل خدمة Workers (الخطة المجانية كافية للمتابعة).
• إصدار Node.js 18 أو أحدث وأداة Wrangler CLI مثبتة عبر الأمر (npm install -g wrangler).
• مفتاح واجهة برمجة تطبيقات OpenAI (API key)، أو بيانات اعتماد لمزود آخر تدعمه مكتبة LangChain.js.
• معرفة أساسية بوعود JavaScript (Promises) ومعالج fetch في Workers.

قم بتثبيت حزم LangChain التي تحتاجها. يفضل الاستيراد بدقة وتجنب استيراد الإطار بالكامل لتفادي تجاوز حدود حجم الملف المضغوط التي تفرضها Workers:

 1{
 2  "dependencies": {
 3    "@langchain/openai": "^0.3.0",
 4    "@langchain/core": "^0.3.0",
 5    "langchain": "^0.3.0"
 6  },
 7  "devDependencies": {
 8    "wrangler": "^3.0.0"
 9  }
10}

دمج LangChain.js مع Workers

تعد LangChain إطار عمل شائعًا لبناء تطبيقات النماذج اللغوية الكبيرة. صُممت نسخة JavaScript منها (LangChain.js) لتعمل على واجهات برمجة تطبيقات الويب القياسية، مما يجعلها متوافقة تمامًا مع بيئة تشغيل V8 الخفيفة من Cloudflare.

للبدء، قم بتهيئة الوكيل داخل معالج fetch الخاص بالـ Worker:

 1import { ChatOpenAI } from "@langchain/openai";
 2import { initializeAgentExecutorWithOptions } from "langchain/agents";
 3import { DynamicTool } from "@langchain/core/tools";
 4
 5export default {
 6  async fetch(request, env) {
 7    // 1. Define custom tools for the agent
 8    const databaseTool = new DynamicTool({
 9      name: "DatabaseQuery",
10      description: "Queries the customer database for billing status.",
11      func: async (input) => {
12        // Query database (e.g. Cloudflare D1)
13        return `Customer ${input} billing status is Active.`;
14      }
15    });
16
17    const tools = [databaseTool];
18
19    // 2. Initialize the reasoning model
20    const model = new ChatOpenAI({ 
21      apiKey: env.OPENAI_API_KEY,
22      modelName: "gpt-4o-mini"
23    });
24
25    // 3. Create the executor
26    const executor = await initializeAgentExecutorWithOptions(tools, model, {
27      agentType: "openai-functions",
28    });
29
30    // 4. Run the query
31    const result = await executor.call({ input: "Check status for Customer 101" });
32    return Response.json(result);
33  }
34};

يعمل هذا الإعداد بالكامل على الحافة (edge)، بالقرب من المستخدمين، مع زمن تشغيل أولي (cold start) يقارب الصفر. إذا كنت ترغب في تهيئة نماذج محلية بدون خادم بدلاً من استدعاء OpenAI، فاطلع على دليل Cloudflare Workers AI .

تهيئة مشروع Worker

تعتمد مكتبة LangChain.js على بعض ميزات Node.js المدمجة، ولذلك لن يتم تجميع كود الـ Worker الخاص بك حتى تقوم بتفعيل خيار nodejs_compat. اضبط ذلك في ملف wrangler.toml إلى جانب أي روابط (bindings) تستخدمها أدواتك:

1name = "ai-agent-worker"
2main = "src/index.js"
3compatibility_date = "2024-09-23"
4compatibility_flags = ["nodejs_compat"]
5
6[[d1_databases]]
7binding = "DB"
8database_name = "agent-memory"
9database_id = "<your-database-id>"

لا تقم مطلقًا بكتابة مفتاح واجهة برمجة التطبيقات الخاص بك بشكل صريح في الكود. بدلاً من ذلك، قم بتخزينه كسر مشفر (secret):

1npx wrangler secret put OPENAI_API_KEY

للتطوير المحلي، ضع نفس القيمة في ملف .dev.vars (والذي يجب إضافته إلى .gitignore) حتى تتمكن أداة wrangler dev من قراءته دون كشف المفتاح في نظام التحكم بالإصدارات (Git).

إدارة الحالة وذاكرة الوكيل

نظرًا لأن بيئة تشغيل Workers بدون خادم تكون عديمة الحالة (stateless) بين الطلبات، يجب عليك تزويد الوكيل بنظام ذاكرة لحفظ تاريخ المحادثات.

يمكنك ربط وكيلك بقاعدة بيانات SQL بدون خادم مثل Cloudflare D1. عندما يتلقى الوكيل طلبًا، فإنه يستعلم من D1 لاسترجاع سلسلة الرسائل السابقة، ويمررها إلى نموذج التفكير، ثم يحفظ الرد الجديد في قاعدة البيانات. لمعرفة كيفية إعداد الجداول، راجع دليل إعداد قاعدة بيانات Cloudflare D1 على الحافة .

عمليًا، يحتاج مخزن الرسائل البسيط إلى دالتين مساعدتين فقط: واحدة لتحميل السجل والأخرى لإضافة كل رد جديد. أنشئ الجدول باستخدام الأمر CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP); ثم قم بربطه برمجياً:

 1async function loadHistory(db, sessionId) {
 2  const { results } = await db
 3    .prepare(
 4      "SELECT role, content FROM messages WHERE session_id = ? ORDER BY created_at ASC"
 5    )
 6    .bind(sessionId)
 7    .all();
 8  return results ?? [];
 9}
10
11async function saveMessage(db, sessionId, role, content) {
12  await db
13    .prepare("INSERT INTO messages (session_id, role, content) VALUES (?, ?, ?)")
14    .bind(sessionId, role, content)
15    .run();
16}

قم بتحميل السجل في بداية كل طلب، ومرره إلى النموذج كمتغير سياق سابق، ثم احفظ مدخلات المستخدم وإجابة الوكيل النهائية قبل إرسال الرد. لجلسات العمل قصيرة المدى حيث لا تهم ديمومة البيانات، تعد خدمة Cloudflare KV خيارًا أقل تكلفة من D1.

حواجز الحماية والتحكم في التكاليف في بيئة الإنتاج

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

• تحديد الحد الأقصى للتكرار (Max Iterations): ضع حدًا أقصى لعدد الحلقات التي يمكن للوكيل تنفيذها (على سبيل المثال، حددها بـ 5 دورات).
• إعداد مهلات التشغيل (Timeouts): تفرض Cloudflare Workers قيودًا على وقت تشغيل المعالج (CPU). تأكد من إنهاء عمل أدواتك بسرعة لتجنب إلغاء الطلبات.
• تطبيق تحديد معدل الطلبات (Rate Limiting): احمِ نقطة النهاية الخاصة بك من استهلاك الرموز العشوائي عبر فرض قيود على معدل الطلبات.

في الكود، تجعل خيارات المنفذ (executor) أول حاجزين صريحين:

1const executor = await initializeAgentExecutorWithOptions(tools, model, {
2  agentType: "openai-functions",
3  maxIterations: 5,
4  earlyStoppingMethod: "generate",
5  verbose: false,
6});

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

للحصول على نظرة تفصيلية حول إدارة السياق، راجع دليلنا حول بناء روبوت دردشة باستخدام واجهة برمجة تطبيقات OpenAI .

المشاكل الشائعة وإصلاحها

تفشل معظم عمليات النشر الأولى لأسباب متوقعة ومحدودة. يوضح الجدول التالي الأعراض الشائعة والسبب المحتمل وكيفية الإصلاح:

هناك تفصيلان دقيقان يستحقان الانتباه. أولاً، تفصل بيئة تشغيل Workers بين الوقت الفعلي ووقت المعالج (CPU time)؛ حيث يُحتسب انتظار رد النموذج اللغوي أو قاعدة البيانات كعمليات إدخال وإخراج (I/O) وليس من وقت المعالج، لذا فإن استدعاءات النماذج الطويلة نادرًا ما تتجاوز حدود المعالج بمفردها، بينما قد يتسبب تحليل ملفات JSON الضخمة داخل حلقة تكرار ضيقة في ذلك. ثانيًا، تعتمد جودة قرارات الوكيل بشكل كبير على كيفية وصفك لأدواته؛ لذا تعامل مع حقل الوصف (description) كأنه أمر موجه للنموذج وكن دقيقًا بشأن المدخلات المتوقعة، وإلا فقد يستدعي النموذج الأداة الخاطئة.

الاختبار والنشر في بيئة الإنتاج

قم بالتطوير والتحقق محليًا قبل النشر. يشغل الأمر wrangler dev الـ Worker الخاص بك في بيئة تشغيل تحاكي تمامًا خوادم Cloudflare الحقيقية:

1npx wrangler dev      # local iteration with hot reload
2npx wrangler deploy   # publish to the edge

بمجرد تشغيل النظام بكفاءة، ستحتاج إلى مراقبة حلقات تفكير الوكيل. قم بتفعيل ميزة المراقبة (observability) لتسجيل استدعاءات الأدوات والأخطاء، وتدفق السجلات في الوقت الفعلي:

1[observability]
2enabled = true

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

أهم النقاط المستفادة

• يستخدم وكلاء الذكاء الاصطناعي نماذج التفكير لتحديد الأدوات المخصصة المناسبة لحل الاستفسارات المعقدة.
• تعمل مكتبة LangChain.js بكفاءة داخل بيئة تشغيل V8 الخفيفة لـ Cloudflare Workers.
• يتم تعريف الأدوات المخصصة كدوال JavaScript تتصل بقواعد البيانات أو واجهات برمجة التطبيقات أو الملفات.
• يمكن حفظ ذاكرة الوكيل عبر الطلبات عديمة الحالة باستخدام قاعدة بيانات SQL بدون خادم Cloudflare D1.
• يساعد فرض حدود على حلقات التكرار ومهلات الاستجابة في التحكم بتكاليف واجهات برمجة التطبيقات ومنع تعطل النظام.

توسيع مسارات عمل الوكلاء الخاصة بك

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

الأسئلة الشائعة (FAQ)

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

هل يمكنني تشغيل LangChain على Cloudflare Workers؟ نعم. صُممت مكتبة LangChain.js باستخدام واجهات برمجة تطبيقات الويب القياسية، مما يجعلها متوافقة تمامًا مع محرك تشغيل V8 الخاص بـ Cloudflare Workers والذي لا يتطلب بيئة تشغيل Node.js كاملة.

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

كيف أمنع وكيل الذكاء الاصطناعي من الدخول في حلقة تكرار لانهائية؟ تستطيع تحديد الحد الأقصى للتكرار في منفذ الوكيل (مثل maxIterations: 5) وتعيين مهلات تشغيل صارمة على دوال أدواتك المخصصة.

ما هي أفضل بيئة استضافة لوكلاء الذكاء الاصطناعي؟ تعد بيئة الاستضافة على الحافة بدون خادم مثل Cloudflare Workers مثالية؛ لأنها توفر انتشارًا عالميًا، وزمن تشغيل أولي يقارب الصفر، وترتبط مباشرة بقواعد البيانات الموزعة مثل D1 و R2.