إنتقل إلى المحتوى الرئيسي

بناء وكلاء ذكاء اصطناعي محليّين

متقدّم

الوكيل المحلّي للذكاء الاصطناعي حلقة مستقلّة تعمل بالكامل على عتادك الخاص: نموذج مفتوح الأوزان (يُقدَّم عبر Ollama أو LM Studio) يقرّر ما يفعله، ويستدعي أدوات تعطيه إياها، ويقرأ النتائج، ويستمرّ حتى تكتمل المهمة — دون أن يغادر شيءٌ جهازك. لا واجهة برمجية سحابية، ولا فاتورة لكل استدعاء، ولا حاجة إلى إنترنت. المقابل: نموذجٌ صغير بما يكفي ليعمل على حاسوب محمول يكون أضعف في الاستدلال الصعب والتخطيط بعيد المدى من نموذج متقدّم، وأنت من يملك موثوقيّته وسلامته. تغطّي هذه الصفحة الحُجّة الصادقة للوكلاء المحلّيين، والبنية الدنيا، وما الذي يعمل فعلًا محلّيًا، ومسارًا واقعيًا نحو أوّل وكيل لك.

What you'll learn
  • معرفة لماذا قد تبني وكيلًا يعمل محلّيًا — والمقايضات الصادقة مقابل وكيلٍ يعمل عبر واجهة برمجية سحابية
  • فهم البنية الدنيا: نموذج محلّي + حلقة استدعاء أدوات + أدوات + حاجز حماية/شرط توقّف
  • اختيار نموذج محلّي يستطيع فعلًا القيام باستخدام الأدوات / العمل الوكيلي
  • معرفة أيّ أطر الوكلاء تعمل محلّيًا بتوجيهها إلى نقطة نهاية محلّية (LangGraph، CrewAI، OpenAI Agents SDK)
  • اتّباع مسار 'ابدأ بسيطًا' من استدعاء أداة لمرة واحدة إلى حلقة محروسة
  • عزل الوكيل في صندوق رمل ووضع سقفٍ لميزانيّته كي لا تُلحق حلقةٌ مستقلّة ضررًا حقيقيًا

لماذا تبني وكيلًا محلّيًا (ومتى لا تفعل)​

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

  • الخصوصية — الموجّهات ومدخلات الأدوات ومخرجاتها لا تغادر الجهاز أبدًا. هذا هو السبب الكامل الذي يجعل الفِرق في البيئات المنظَّمة أو الحسّاسة أو المعزولة عن الشبكة تبني وكلاء محلّيين: البيانات لا تستطيع فيزيائيًا أن تذهب إلى طرف ثالث.
  • دون اتصال — لا إنترنت، ولا اعتماد على واجهة برمجية، ولا انقطاع من المزوّد. الوكيل ملفّاتٌ على قرصك؛ يعمل على متن طائرة أو خلف جدار ناري.
  • بلا تكلفة لكل استدعاء — قد تُطلق حلقة الوكيل عشرات الاستدعاءات للنموذج في المهمة الواحدة. محلّيًا تكون تلك الاستدعاءات "مجّانية" (تدفع كهرباءً وعتادًا، لا رموزًا)، فتستطيع أن تدعه يكرّر دون مراقبة عدّاد.
  • تحكّم كامل — ثبّت إصدار نموذج محدّدًا بدقّة، وخصّص السلوك، وشغّل دون حدود معدّل أو مفاجآت في شروط الخدمة.

المقايضات الصادقة — كن واضح الرؤية بشأنها قبل أن تلتزم:

  • فجوة القدرة. أصعب ما في الوكيل هو الاستدلال: التخطيط لعملٍ متعدّد الخطوات، والتعافي من استدعاء أداة فاشل، ومعرفة متى يتوقّف. النموذج الذي تستطيع تشغيله على حاسوب محمول (تقريبًا من مليار إلى 14 مليار معامِل) أضعف هنا بوضوح من نموذج متقدّم. الحلقات البسيطة المحدّدة النطاق تعمل جيّدًا محلّيًا؛ أما المهامّ بعيدة المدى المفتوحة النهاية فهي حيث ينحرف الوكلاء المحلّيون عن السكّة غالبًا.
  • أنت من يملك الموثوقية والسلامة. لا مزوّد يُرشِّح أو يراقب أو يضع حواجز حماية نيابةً عنك. إن دخل الوكيل في حلقة لا نهائية، أو استدعى الأداة الخطأ، أو نفّذ إجراءً تدميريًا، فذلك على عاتق تصميمك. (انظر التحذير أدناه — هذا هو الجزء الذي يستهين به الناس.)
  • حدود العتاد. النماذج الأكبر والأذكى تحتاج ذاكرة وصول عشوائي/ذاكرة رسومية أكثر مما تملكه معظم الأجهزة. عادةً ما تختار أكبر نموذج قادر يستطيع عتادك تشغيله، لا أفضل نموذج موجود.

قاعدة إبهام صامدة: ابدأ محلّيًا، وصعّد حين تتطلّب المهمة ذلك. استخدم وكيلًا محلّيًا للعمل الخاصّ/دون الاتصال/الرخيص على نطاق واسع وللحلقات المحدّدة النطاق؛ والجأ إلى وكيلٍ يعمل عبر واجهة برمجية متقدّمة حين تحتاج المهمة فعلًا إلى استدلال إضافي. البنية أدناه متطابقة في الحالتين — تتغيّر نقطة النهاية فقط — فتستطيع أن تصنع نموذجًا أوّليًا محلّيًا وتبدّل النماذج لاحقًا.

البنية الدنيا​

جرّد الوكيل إلى جوهره تجد أربعة أجزاء. وكلّ ما عداها راحةٌ مبنيّة فوقها.

        ┌─────────────────────────────────────────────┐
        │                                             │
        │   1. LOCAL MODEL  ──►  decides next action  │
        │      (Ollama / LM Studio, tool-capable)     │
        │                  │                          │
        │                  ▼                          │
        │   2. TOOL-CALLING LOOP                       │
        │      parse the model's tool request,         │
        │      run it, feed the result back            │
        │                  │                          │
        │                  ▼                          │
        │   3. TOOLS  ──►  search / read file /        │
        │      run code / call an API (your code)      │
        │                  │                          │
        │                  ▼                          │
        │   4. GUARDRAIL / STOP CONDITION              │
        │      max steps, budget, approval gate,       │
        │      "done" check ──► exit the loop          │
        │                                             │
        └─────────────────────────────────────────────┘
  1. نموذج محلّي يدعم استدعاء الأدوات. يجب أن يكون النموذج قادرًا على إصدار طلبٍ مُنظَّم لاستدعاء أداة (يُعرف أيضًا بـ استدعاء الدوال)، لا مجرّد الدردشة. يكشف Ollama هذا عبر واجهته البرمجية وعبر نقطة نهاية متوافقة مع OpenAI على http://localhost:11434/v1، فيستطيع أيّ إطار يتكلّم صيغة OpenAI أن يقود نموذجًا محلّيًا.
  2. حلقة استدعاء الأدوات. قلب الوكيل: أرسِل المحادثة إلى النموذج، وانظر إن طلب استدعاء أداة، وشغّل تلك الأداة، وألحِق النتيجة، وكرّر. حين يجيب النموذج دون طلب أداة، تنتهي الحلقة.
  3. الأدوات. دوالّ بسيطة تكشفها للنموذج — ابحث في الويب، اقرأ ملفًّا، شغّل أمر صدفة، استعلِم قاعدة بيانات، اطرق واجهة برمجية. لكل أداة اسم، ووصف، ومخطّط مدخلات مُنمَّط كي يعرف النموذج متى وكيف يستخدمها.
  4. حاجز حماية / شرط توقّف. غير قابل للتفاوض من أجل الاستقلالية. حدًّا أدنى سقفٌ لعدد الخطوات كي لا تعمل الحلقة إلى الأبد، زائد — لأي شيء يكتب أو يحذف أو يُنفق أو يُرسل — بوّابة موافقة أو صندوق رمل. من دون هذا ليس لديك وكيل، بل حلقة لا نهائية تملك وصولًا إلى الملفّات.

الحلقة في الخطوة 2 صغيرة فعلًا. إليكها بشِبه كود بايثون مقابل نقطة نهاية Ollama محلّية:

حلقة وكيل محلّي دنيا (شِبه كود بايثون، تشير إلى Ollama محلّي)

from openai import OpenAI

# Point the OpenAI client at your LOCAL Ollama endpoint — nothing leaves the machine
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

tools = [{
  "type": "function",
  "function": {
      "name": "read_file",
      "description": "Read a UTF-8 text file and return its contents",
      "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"],
      },
  },
}]

def run_tool(name, args):
  if name == "read_file":
      # GUARDRAIL: only allow reads inside a sandboxed directory
      return safe_read(args["path"])
  raise ValueError(f"unknown tool: {name}")

messages = [{"role": "user", "content": "Summarize ./notes/today.md"}]

for step in range(8):                       # GUARDRAIL: hard step cap
  resp = client.chat.completions.create(
      model="llama3.1", messages=messages, tools=tools,
  )
  msg = resp.choices[0].message
  messages.append(msg)

  if not msg.tool_calls:                  # STOP: model answered, we're done
      print(msg.content)
      break

  for call in msg.tool_calls:
      result = run_tool(call.function.name, json.loads(call.function.arguments))
      messages.append({
          "role": "tool", "tool_call_id": call.id, "content": str(result),
      })
else:
  print("Stopped: hit the step cap without finishing.")

هذا هو النمط بأكمله. تضيف الأطر الذاكرة، وإعادة المحاولات، وتنسيق تعدّد الوكلاء، والتتبّع، والحالة المُنظَّمة فوقه — لكن كلّ واحدٍ منها نسخةٌ أمتن من هذه الحلقة.

أيّ النماذج المحلّية تلائم العمل الوكيلي / استخدام الأدوات​

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

  • يجب أن يكون نموذجًا قادرًا على الأدوات. يوسِمها Ollama — تصفّح فئة Tools للقائمة الحالية بدل الافتراض. من النماذج التي كثيرًا ما تُذكر لاستخدام أدوات محلّي متين عائلتا Qwen وLlama المضبوطتان على التعليمات؛ والاختيار الأفضل بالضبط يتحرّك من ربعٍ إلى ربع.
  • يجب أن يلائم عتادك مع فسحة للسياق. تتراكم في حلقات الوكيل سجلّات رسائل طويلة (كلّ نتيجة أداة تُلحَق)، فتحتاج إلى الأوزان وأيضًا نافذة سياق سخيّة في الذاكرة. نموذجٌ أصغر يلائم بارتياح ويعمل بسرعة كثيرًا ما يتفوّق على أكبر منه يتبادل مع القرص ويتوقّف في منتصف الحلقة.

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

أطر تعمل محلّيًا​

تستطيع أن تصنع الحلقة أعلاه بيدك، ولأوّل وكيل تلك طريقة رائعة للتعلّم. أمّا لأي شيء جادّ، فالإطار يمنحك إعادة المحاولات، والذاكرة، وتنسيق تعدّد الوكلاء، والتتبّع. الحقيقة المفتاحية: أطر الوكلاء الشائعة محايدة تجاه النموذج — لا يعنيها أكان النموذج في السحابة أم على localhost، ما دمت توجّهها إلى نقطة النهاية الصحيحة.

  • LangGraph — إطار تنسيق منخفض المستوى للوكلاء ذوي الحالة (تنفيذ متين، وثبات، وإنسان-في-الحلقة). محايد تجاه النموذج؛ اربطه بنموذج محلّي عبر تكامل LangChain مع Ollama دون التفافات. جيّد حين تحتاج تحكّمًا صريحًا في رسم حالة الوكيل.
  • CrewAI — إطار أعلى مستوى لتنسيق وكيلٍ أو أكثر قائمين على الأدوار ("crews"). محايد تجاه النموذج عبر LiteLLM؛ وجّه وكيلًا إلى نموذج محلّي بـ LLM(model="ollama/llama3.1", base_url="http://localhost:11434"). جيّد حين تريد تركيب عدّة وكلاء متعاونين بسرعة.
  • OpenAI Agents SDK — إطار تعدّد وكلاء خفيف. رغم الاسم فهو محايد تجاه المزوّد: عبر تكامله مع LiteLLM تستطيع توجيهه إلى نموذج Ollama محلّي بدلًا من نموذج OpenAI. جيّد حين تريد أريحيّة وكلاء OpenAI على خلفيّة محلّية.

اختر إطارًا واحدًا وتعلّمه جيّدًا بدل تذوّق الثلاثة. المفاهيم (الوكلاء، الأدوات، الحلقات، الحالة) تنتقل؛ والواجهات البرمجية تفاصيل.

ابنِ أوّل وكيل محلّي لك​

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

Guided walkthrough1 of 5
  1. ثبّت Ollama (انظر تشغيل النماذج محلّيًا)، ثم اسحب نموذجًا موسومًا للأدوات، مثل ollama pull llama3.1. تأكّد أنه يُقدَّم على http://localhost:11434 وأن ollama list يُظهره. لا وكيل بعد — مجرّد نموذج تستطيع استدعاءه.
Watch out
  • الوكيل المحلّي بأدوات يظلّ قادرًا على اتّخاذ إجراءات حقيقية — اعزله في صندوق رمل، واشترِط الموافقة للخطوات التدميرية، وضع سقفًا لحلقاته/ميزانيّته.

اختبر نفسك​

اختبر نفسك

0/4
  1. ما السبب الأهمّ الأوحد الذي يجعل الفِرق تبني وكلاء يعملون محلّيًا بدلًا من مقابل واجهة برمجية سحابية؟
  2. أيّ أربعة أجزاء تُكوّن البنية الدنيا للوكيل المحلّي؟
  3. ماذا يعني أن LangGraph وCrewAI وOpenAI Agents SDK 'محايدة تجاه النموذج' للاستخدام المحلّي؟
  4. أنت تبني أوّل وكيل محلّي لك. ماذا ينبغي أن تفعل قبل إضافة أي أداة تكتب ملفّات أو تشغّل أوامر؟
اضغط Enter أو مفتاح المسافة لقلب البطاقة. استخدم مفتاحي السهمين الأيسر والأيمن للتنقل بين البطاقات.تم إظهار المصطلح.
1 / 6
Key takeaways
  • الوكيل المحلّي هو حلقة استخدام الأدوات المعيارية مع استبدال النموذج السحابي بنموذج مفتوح الأوزان على جهازك — خاصّ، دون اتصال، ومجّاني التكرار.
  • البنية الدنيا = نموذج محلّي قادر على الأدوات + حلقة استدعاء أدوات + أدوات + حاجز حماية/شرط توقّف. والحلقة نفسها ضئيلة.
  • نقطة نهاية Ollama المتوافقة مع OpenAI ‏(/v1) تدعم استدعاء الأدوات، فيستطيع أيّ إطار بصيغة OpenAI قيادة نموذج محلّي.
  • LangGraph وCrewAI وOpenAI Agents SDK محايدة تجاه النموذج — وجّهها إلى نقطة نهاية محلّية بدلًا من السحابة.
  • اختر نموذجًا قادرًا على الأدوات يلائم عتادك، ثم قرّر بتقييم صغير لمهمّتك أنت — لا بلوحة صدارة.
  • كن صادقًا بشأن فجوة القدرة وامتلِك السلامة: ضع سقفًا للحلقات والميزانية، واعزل الأدوات في صندوق رمل، واشترِط الموافقة لأي شيء تدميري.
  • ابدأ بسيطًا: استدعاء أداة واحد نظيف ← حلقة محدودة للقراءة فقط ← أدوات تدميرية محروسة ← (اختياريًا) إطار.

المصادر وقراءات إضافية​