ai-agents-for-beginners

إنشاء وكلاء ذكاء اصطناعي محليين باستخدام Microsoft Foundry Local و Qwen

إنشاء وكلاء ذكاء اصطناعي محليين

الدرس السابق قام بتوسيع الوكلاء للسحابة. هذا الدرس يُنزلهم إلى كمبيوتر واحد. بنهاية هذا الدرس سيكون لديك مساعد هندسي يعمل يفكر، يستدعي الأدوات، يقرأ ملفاتك، ويبحث في توثيقاتك — دون أي طلب استدلال للسحابة.

لماذا تريد ذلك؟ هناك ثلاثة أسباب تتكرر باستمرار في العمل الهندسي الحقيقي:

التحدي هو أنك تستبدل نموذج سحابي متقدم بـ نموذج لغة صغير (SLM) يعمل على معالجك المركزي، أو معالج الرسوميات، أو معالج الشبكة العصبية. هذا الدرس يركز على بناء وكلاء جيدين ضمن هذا القيد بدلاً من التظاهر بأن القيد غير موجود.

مقدمة

هذا الدرس سيغطي:

أهداف التعلم

بعد إكمال الدرس، ستعرف كيف:

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

يفترض هذا الدرس أنك أتممت الدروس السابقة وتشعر بالراحة مع:

ستحتاج أيضًا إلى:

نماذج اللغة الصغيرة: الأداة المناسبة للعمل المحلي

نموذج سحابي متقدم يحتوي على مئات المليارات من المعاملات ويتطلب مركز بيانات ضخم. النموذج الصغير (SLM) يحتوي على بضعة مليارات معاملات ويجب أن يتناسب مع رام الحاسوب المحمول لديك. هذا الفرق يحدد توقعات واضحة.

نماذج SLM جيدة في:

نماذج SLM أضعف في:

الإستراتيجية الفائزة للوكلاء المحليين هي: دع SLM ينسق، ودع الأدوات تقوم بالعمل الشاق. النموذج لا يحتاج لأن يعرف قاعدة شيفرتك — يحتاج أن يعرف متى يستدعي read_file وsearch_docs. هذا يلعب مباشرة على نقاط قوة الـ SLM.

flowchart LR
    U[مطور] --> A[وكيل SLM محلي]
    A -->|يقرر الأداة المناسبة| T1[قراءة_الملف]
    A -->|يقرر الأداة المناسبة| T2[بحث_المستندات RAG]
    A -->|يقرر الأداة المناسبة| T3[تحليل_الكود]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[الإجابة، كلها على الجهاز]

Microsoft Foundry Local

Microsoft Foundry Local هو بيئة تشغيل خفيفة تقوم بتنزيل وإدارة وخدمة النماذج بالكامل على جهازك. أهم ميزته لنا أنه يفتح نقطة نهاية HTTP متوافقة مع OpenAI — مما يعني أن SDK الخاص بـ OpenAI وعميل OpenAI في إطار عمل Microsoft Agent يعملان ضده بتغيير بسيط في base_url. كل ما تعلمته حول بناء الوكلاء يُنقل مباشرة؛ فقط نقطة النهاية تنتقل من السحابة إلى localhost.

يقوم Foundry Local أيضًا باختيار أفضل نسخة نموذج مناسبة لهاردويرك تلقائيًا — نسخة لمعالج مركزي، أو نسخة CUDA/GPU، أو نسخة NPU — لتجنب تحسينات يدوية لكل جهاز.

الإعداد

قم بتثبيت Foundry Local (راجع التوثيق لنظام التشغيل الخاص بك)، ثم تحقق من عمله:

# التثبيت (مثال؛ اتبع المستندات الخاصة بمنصتك)
winget install Microsoft.FoundryLocal      # ويندوز
# brew install microsoft/foundrylocal/foundrylocal   # ماك أو إس

# قم بتنزيل وتشغيل نموذج Qwen، ثم ابدأ الخدمة المحلية
foundry model run qwen2.5-7b-instruct
foundry service status

بمجرد تشغيل الخدمة ستحصل على نقطة نهاية متوافقة مع OpenAI محليًا (عادة http://localhost:PORT/v1). يستخدم الكود foundry-local-sdk لاكتشاف نقطة النهاية تلقائياً، لذا لا تحتاج إلى ترميز المنفذ بشكل يدوي.

استدعاء دوال Qwen: لماذا هو مهم

لا يكون الوكيل وكيلًا إلا إذا كان يستطيع استدعاء الأدوات. العديد من نماذج SLM يمكنها الدردشة لكن تنتج استدعاءات أدوات غير موثوقة أو مشوهة. نماذج Qwen مدرّبة لاستدعاء الدوال وتصدر بنى استدعاء أدوات صحيحة باستمرار — وهذا بالضبط ما يحول نموذج دردشة محلي إلى وكيل محلي.

التدفق هو حلقة استدعاء أدوات قياسية تعرفها، فقط تعمل على الجهاز:

sequenceDiagram
    participant U as المستخدم
    participant A as وكيل كوين (محلي)
    participant T as أداة محلية
    U->>A: "ماذا يفعل auth.py؟"
    A->>A: قرار: استدعاء read_file
    A->>T: read_file("auth.py")
    T-->>A: محتويات الملف
    A->>A: التفكير في المحتويات
    A-->>U: شرح

RAG محلي

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

نستخدم Chroma، مخزن متجهات مضمن يعمل ضمن العملية بدون إدارة خادم. العملية بالكامل محلية: نموذج التضمين المحلي → المتجهات المحلية → الاسترجاع المحلي → SLM محلي.

flowchart TB
    D[مستنداتك / الشفرة] --> E[نموذج التضمين المحلي]
    E --> V[(قاعدة بيانات متجهات Chroma - على القرص)]
    Q[استعلام الوكيل] --> QE[تضمين الاستعلام محليًا]
    QE --> V
    V -->|أفضل قطع k| A[وكيل Qwen]
    A --> Ans[إجابة مؤيدة]

هذا هو نفس نمط Agentic RAG من الدرس 5 — التغيير الوحيد هو أن كل مكون يعمل على جهازك.

خوادم MCP محلية

MCP هو بروتوكول نقل، وليس خدمة سحابية. يمكن تشغيل خادم MCP كعملية محلية على stdio، ليكشف أدوات لوكيلك عبر البروتوكول القياسي. هذا يسمح لك بإعادة استخدام النظام البيئي المتزايد من خوادم MCP — وصول إلى نظام الملفات، عمليات git، استعلامات قواعد البيانات — بالكامل دون اتصال.

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

أنماط هجينة بين السحابة والمحلي

“محلي أولاً” لا يعني “محلي فقط”. الأنظمة المتطورة توجه حسب الحساسية والصعوبة:

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

هذا يعكس فكرة توجيه النموذج من الدرس 16 — باستثناء أن أحد “النماذج” هو جهازك الخاص. تصميم قوي يعود إلى المحلي إذا كانت السحابة غير متاحة، فتتحلل جودة الوكيل بدلاً من أن يفشل تمامًا.

flowchart LR
    Q[طلب] --> S{هل هو حساس أم غير متصل؟}
    S -->|نعم| L[SLM محلي]
    S -->|لا| C{هل يحتاج إلى تفكير عميق؟}
    C -->|لا| L
    C -->|نعم| Cloud[نموذج سحابي]
    L --> Out[استجابة]
    Cloud --> Out

المختبر العملي: مساعد هندسي محلي

افتح code_samples/17-local-agent-foundry-local.ipynb واتبعه خطوة بخطوة. ستبني مساعد هندسي محلي يعمل بالكامل على محطة العمل الخاصة بك ويستطيع:

  1. استدعاء الأدوات — عبر استدعاء وظائف Qwen من خلال Foundry Local.
  2. تنفيذ عمليات ملفات محلية — سرد وقراءة ملفات مجلد المشروع.
  3. تحليل الشيفرة — الإبلاغ عن مقاييس أساسية لملف مصدر.
  4. البحث في التوثيق — RAG محلي على مجلد التوثيقات باستخدام Chroma.
  5. استخدام MCP — الاتصال بخادم MCP محلي (مع تخطي مهذب إذا لم يكن مكوّنًا).

لا يُستخدم أي استدلال سحابي في أي نقطة.

شرح خطوة بخطوة

يتصل المساعد بـ Foundry Local عبر نقطة نهاية متوافقة مع OpenAI، لذا يبدو كود الوكيل مشابهًا جدًا لدروس السحابة — فقط يتغير العميل:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# يكتشف / ينزل نموذج Foundry Local ويعطينا نقطة نهاية محلية.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key هو عنصر نائب محلي

الأدوات هي دوال بايثون عادية مخصصة لمجلد مشروع:

def read_file(path: str) -> str:
    \"\"\"Read a file, but only inside the sandboxed project directory.\"\"\"
    full = (PROJECT_ROOT / path).resolve()
    if PROJECT_ROOT not in full.parents and full != PROJECT_ROOT:
        return \"Access denied: path is outside the project directory.\"
    return full.read_text(encoding=\"utf-8\")

لاحظ التحقق من البيئة المعزولة — حتى محلياً، أداة تقرأ مسارات عشوائية تمثل خطراً. يحتفظ الدفتر بكل أداة مقيدة لجذر مشروع واحد.

اختبار المعرفة

اختبر فهمك قبل الانتقال إلى التمرين.

1. قدم سببين محددين لتشغيل وكيل محلي بدلاً من السحابة.

الإجابة أي اثنين من: **الخصوصية** (لا تخرج الشيفرة والبيانات من الجهاز)، **التكلفة** (لا توجد فاتورة استدلال لكل رمز)، و**العمل بدون اتصال** (يعمل بدون شبكة – على الطائرة، في منشأة آمنة، أو أثناء انقطاع). القيود التنظيمية/الامتثال التي تمنع إرسال البيانات خارج الجهاز هي سبب شائع للخصوصية.

2. ما هو تقسيم العمل الموصى به بين SLM وأدواته في وكيل محلي، ولماذا؟

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

3. ما الذي يجعل من الممكن إعادة استخدام كود الوكيل السحابي مع Foundry Local؟

الإجابة يقوم Foundry Local بفتح **نقطة نهاية HTTP متوافقة مع OpenAI**. يعمل SDK الخاص بـ OpenAI وعميل OpenAI في إطار العمل ضدها بتغيير فقط الـ `base_url` (واستخدام مفتاح API وهمي محلي). كل شيء آخر في كود الوكيل يبقى كما هو.

4. لماذا نستخدم تحديدًا نموذج استدعاء دوال Qwen وليس أي SLM؟

الإجابة لأن الوكيل يجب أن ينتج استدعاءات أدوات موثوقة وصحيحة الهيكل. العديد من نماذج SLM يمكنها الدردشة لكنها تصدر استدعاءات مشوهة أو غير متسقة. نماذج Qwen مدرّبة لاستدعاء الدوال وتنتج استدعاءات أدوات متسقة، وهو ما يحول نموذج الدردشة المحلي إلى وكيل محلي فعال.

5. في مسار RAG المحلي، أي المكونات تعمل على الجهاز؟

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

6. خادم MCP محلي يعمل على جهازك. هل هذا يجعله آمنًا تلقائيًا؟ ما الاحتياطات التي يجب اتخاذها؟

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

7. صف قاعدة توجيه هجينة منطقية تتضمن نموذجًا محليًا.

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

8. ما هو الحد الأدنى الواقعي للذاكرة العشوائية (RAM) لتشغيل الوكيل المحلي في هذا الدرس، وماذا تجلب لك المزيد من الذاكرة؟

الإجابة حوالي **8 جيجابايت** هو الحد الأدنى الواقعي؛ 16 جيجابايت أو أكثر مريحة. المزيد من الذاكرة يسمح لك بتشغيل نماذج أكبر وأكثر قدرة والحفاظ على المزيد من السياق في الذاكرة. وحدة معالجة الرسوميات أو وحدة المعالجة العصبية تسرع الاستدلال لكنها غير مطلوبة — يختار Foundry Local بناءً على المعالج المركزي إذا لم يكن هناك مسرع متاح.

التمرين

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

يجب أن يتضمن تسليمك:

  1. فهرسة مجلد توثيق/شيفرة حقيقي في Chroma (خمسة ملفات على الأقل).

  2. إضافة أداة find_todos تفحص المشروع عن تعليقات TODO/FIXME وتُرجعها مع اسم الملف ورقم السطر — مع الحفاظ على التحقق من البيئة المعزولة نفس read_file.

  3. اطرح على الوكيل ثلاثة أسئلة تجبره على دمج الأدوات: سؤال RAG خالص، واحد يتطلب قراءة ملف محدد، وآخر يتطلب العثور على TODOs.
  4. قِس الأداء: وقت كل من الإجابات الثلاث وسجّلها في خلية ماركداون. علّق على ما إذا كان الكمون مقبولًا لسيناريو عملك المقصود.

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

الملخص

في هذا الدرس قمت ببناء وكيل يعمل بالكامل على جهازك الخاص:

يُكمل هذا قوس النشر: الدرس 16 وسّع الوكلاء داخل Microsoft Foundry، وهذا الدرس قلصهم إلى محطة عمل واحدة. الدرس التالي يتجه إلى الحفاظ على أمان الوكلاء المنشورين.

موارد إضافية

الدرس السابق

نشر وكلاء قابلين للتوسع

الدرس التالي

تأمين وكلاء الذكاء الاصطناعي

تنويه: تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي Co-op Translator. بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.

This site is open source. Improve this page.