ai-agents-for-beginners

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

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

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

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

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

مقدمة

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

أهداف التعلم

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

المتطلبات السابقة

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

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

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

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

نماذج اللغة الصغيرة جيدة في:

نماذج اللغة الصغيرة أضعف في:

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

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 وكيل Qwen (محلي)
    participant T as أداة محلية
    U->>A: "ماذا يفعل auth.py؟"
    A->>A: قرار: استدعاء read_file
    A->>T: read_file("auth.py")
    T-->>A: محتويات الملف
    A->>A: التفكير في المحتويات
    A-->>U: شرح

البحث المستند إلى المحتوى المحلي (Local RAG)

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

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

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 المحلي لا يزال يعمل بأذونات المستخدم الخاص بك، لذا قم بتحديد نطاق ما يمكنه الوصول إليه (مثل مجلد مشروع، وليس كل مجلد المنزل) وتعامل مع مخرجاته كمدخلات تتحقق منها.

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

الأولوية للمحلي لا تعني فقط محلي. الأنظمة الناضجة توجه بناءً على الحساسية والصعوبة:

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

هذا يعكس فكرة توجيه النموذج من الدرس 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

# فاوندري لوكال يكتشف / ينزل النموذج ويعطينا نقطة نهاية محلية.
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 قوية في اتخاذ قرارات محدودة مثل اختيار الأداة لكنها أضعف في المعرفة الواسعة والاستدلال متعدد الخطوات الطويل، لذا الاعتماد على الأدوات يلعب إلى نقاط قوتها.

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

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

4. لماذا نستخدم تحديدًا نموذج استدعاء الوظائف Qwen بدلاً من أي نموذج لغة صغيرة؟

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

5. في خط أنابيب البحث المستند إلى المحتوى المحلي، أي المكونات تعمل على الجهاز؟

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

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

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

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

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

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

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

المهمة

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

يجب أن يشمل تقديمك:

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

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

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

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

ملخص

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

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

موارد إضافية

الدرس السابق

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

الدرس التالي

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

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

This site is open source. Improve this page.