ai-agents-for-beginners

יצירת סוכני בינה מלאכותית מקומיים באמצעות Microsoft Foundry Local ו-Qwen

יצירת סוכני בינה מלאכותית מקומיים

השיעור הקודם הרחיב את הסוכנים לענן. שיעור זה מביא אותם למטה אל מחשב יחיד. בסיום יהיו לך עוזר הנדסי שעובד, שחושב, מפעיל כלים, קורא את הקבצים שלך ומחפש בתיעוד שלך — בלי קריאת אינפרנס אחת בענן.

למה תרצה את זה? שלוש סיבות שמופיעות לעיתים קרובות בעבודה הנדסית אמיתית:

המלכוד הוא שאתה מחליף דגם ענן מתקדם ב-מכונת שפה קטנה (SLM) שרצה על ה-CPU, GPU או NPU שלך. השיעור עוסק בבניית סוכנים שהם טובים במסגרת הזו ולא מתיימרים שהמגבלה לא קיימת.

מבוא

שיעור זה יכסה:

יעדי למידה

לאחר סיום שיעור זה תדע כיצד:

דרישות מוקדמות

שיעור זה מניח שסיימת את השיעורים הקודמים ונוח לך עם:

תזדקק גם ל:

מכונות שפה קטנות: הכלי הנכון לעבודה מקומית

מודל ענן מתקדם כולל מאות מיליארדי פרמטרים ומרכז נתונים מאחוריו. SLM כולל כמה מיליארדים של פרמטרים וחייב להתאים לזיכרון ה-RAM של הלפטופ שלך. ההבדל הזה קובע את הציפיות.

SLMs טובים ב:

SLMs חלשים ב:

אסטרטגיית הניצחון לסוכנים מקומיים היא לכן: לתת ל-SLM לתזמן, ולתת לכלים לעשות את העבודה הכבדה. המודל לא צריך לדעת את בסיס הקוד שלך — הוא צריך לדעת מתי לקרוא ל-read_file ול-search_docs. זה מתאים ישירות לנקודות החוזק של SLM.

flowchart LR
    U[Developer] --> A[Local SLM Agent]
    A -->|decides which tool| T1[read_file]
    A -->|decides which tool| T2[search_docs RAG]
    A -->|decides which tool| T3[analyze_code]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Answer, fully on-device]

Microsoft Foundry Local

Microsoft Foundry Local היא סביבת ריצה קלה שמורידה, מנהלת ומשרתת מודלים לחלוטין על המחשב שלך. התכונה החשובה ביותר עבורנו היא שהיא חושפת נקודת קצה HTTP תואמת OpenAI — מה שאומר שה-SDK של OpenAI ולקוח OpenAI במסגרת הסוכנים של Microsoft עובדים נגדו בהחלפת base_url בלבד. כל מה שלמדת על בניית סוכנים מועבר ישירות; רק נקודת הקצה עוברת מהענן ל-localhost.

Foundry Local גם בוחרת אוטומטית את הבנייה הטובה ביותר למודל על החומרה שלך — בניית CPU, CUDA/GPU או NPU — כך שלא תצטרך לאופטימיזציה ידנית למחשב.

התקנה

התקן את Foundry Local (ראה את ה-תיעוד למערכת ההפעלה שלך), ואז וודא שזה עובד:

# Install (example; follow the docs for your platform)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Download and run a Qwen model, then start the local service
foundry model run qwen2.5-7b-instruct
foundry service status

ברגע שהשירות רץ יש לך נקודת קצה מקומית תואמת OpenAI (בדרך כלל http://localhost:PORT/v1). הפנקס משתמש ב-foundry-local-sdk כדי לגלות את נקודת הקצה אוטומטית, כך שלא תצטרך לקבוע את הפורט בדפוס קשיח.

קריאת פונקציות Qwen: למה זה חשוב

סוכן הוא רק סוכן אם הוא יכול לקרוא כלים. הרבה SLMs יכולים לשוחח אך מפיקים קריאות כלים שגויות ולא אמינות. מודלי Qwen מאומנים לקריאת פונקציות ומפיקים במדויק מבני קריאת כלים — וזה בדיוק מה שהופך מודל שיחה מקומי ל-סוכן מקומי.

הזרימה היא הלולאה הסטנדרטית של קריאת כלים שכבר מכירים, רק שזו רצה במכשיר:

sequenceDiagram
    participant U as User
    participant A as Qwen Agent (local)
    participant T as Local Tool
    U->>A: "What does auth.py do?"
    A->>A: Decide: call read_file
    A->>T: read_file("auth.py")
    T-->>A: file contents
    A->>A: Reason over contents
    A-->>U: Explanation

RAG מקומי

חיפוש בתיעוד הוא המקום שהסוכנים המקומיים מפיקים ממנו ערך. במקום לקוות ש-SLM זכר את התיעוד של המסגרת שלך, אתה מטמיע את התיעוד הזה במסד וקטורי מקומי ומאפשר לסוכן לאחזר את הקטעים הרלוונטיים לפי דרישה.

אנחנו משתמשים ב-Chroma, מחסן וקטורי מוטמע שרץ בתהליך ללא שרת לניהול. הצינור כולו מקומי: מודל הטמעה מקומי → וקטורים מקומיים → אחזור מקומי → SLM מקומי.

flowchart TB
    D[Your docs / code] --> E[Local embedding model]
    E --> V[(Chroma vector DB - on disk)]
    Q[Agent query] --> QE[Embed query locally]
    QE --> V
    V -->|top-k chunks| A[Qwen agent]
    A --> Ans[Grounded answer]

זה אותו דפוס Agentic RAG משיעור 5 — השינוי היחיד הוא שכל רכיב רץ על המחשב שלך.

שרתי MCP מקומיים

MCP הוא פרוטוקול, לא שירות ענן. שרת MCP יכול לרוץ כתהליך מקומי ב-stdio, לחשוף כלים לסוכן שלך על גבי הפרוטוקול הסטנדרטי. זה מאפשר שימוש חוזר באקוסיסטם ההולך וגדל של שרתי MCP — גישה לקבצים, פעולות גיט, שאילתות למסדי נתונים — כולן ללא חיבור לרשת.

פרופיל האבטחה שונה מהענן, אך לא נעדר: שרת MCP מקומי עדיין רץ בהרשאות המשתמש שלך, לכן הגבל את טווח הנגיעה (ספריית פרויקט, לא כל תיקיית הבית שלך) וטפל ביציאות שלו כקלטים לאימות.

דפוסי היברידיות בין ענן ומקומי

“מקומי תחילה” לא אומר “רק מקומי”. מערכות בוגרות מנותבות לפי רגישות וקושי:

מצב איפה זה רץ
קוד/נתונים רגישים, או לא מקוון SLM מקומי
משימה פשוטה ומוגבלת SLM מקומי (זול ומהיר)
חשיבה קשה מרובת קפיצות על נתונים לא רגישים מודל ענן
הכל, בזמן תקלה SLM מקומי (התדרדרות ממושמעת)

זה משקף את רעיון הניתוב למודל משיעור 16 — רק שאחד ה”מודלים” הוא עכשיו המחשב שלך. עיצוב יציב חוזר למקומי כשהענן לא זמין, כך שהסוכן מתדרדר באיכות במקום לכשל לחלוטין.

flowchart LR
    Q[Request] --> S{Sensitive or offline?}
    S -->|yes| L[Local SLM]
    S -->|no| C{Needs deep reasoning?}
    C -->|no| L
    C -->|yes| Cloud[Cloud model]
    L --> Out[Response]
    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 discovers/downloads the model and gives us a local endpoint.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key is a local placeholder

הכלים הם פונקציות Python רגילות המוגבלות לתיקיית פרויקט:

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?

תשובה כי סוכן חייב להפיק קריאות כלים אמינות ומבניות. הרבה SLMs יכולים לשוחח אך מייצרים מבני קריאות כלים שגויים או לא עקביים. מודלי Qwen מאומנים לקריאות פונקציה ומפיקים קריאות כלים עקביות, וזה מה שהופך מודל שיחה מקומי לסוכן מקומי שעובד.

5. באותה צינור RAG מקומי, אילו רכיבים רצים על המחשב?

תשובה כולם: מודל ההטמעה, מסד הנתונים הוקטורי (Chroma, בדיסק), שלב האחזור, ו-SLM. המסמכים מוטמעים, נשמרים, מאוחזרים ומנותחים מקומית — אף רכיב לא נוגע בענן.

6. שרת MCP מקומי רץ על המחשב שלך. האם זה הופך אותו אוטומטית לבטוח? איזה אמצעי זהירות יש לנקוט?

תשובה לא. שרת MCP מקומי רץ בהרשאות המשתמש שלך, אז הוא יכול לגשת לכל מה שאתה יכול. הזמן אותו למה שהוא צריך (למשל, תיקיית פרויקט בודדת ולא כל תיקיית הבית) וטפל ביציאות שלו כקלטים שיש לאמת לפני לפעול עליהם.

7. תאר כלל ניתוב היברידי מתחשב שכולל מודל מקומי.

תשובה ניתוב בקשות רגישות או לא מקוונות ל-SLM המקומי; ניתוב משימות פשוטות ומוגבלות ל-SLM המקומי בגלל מהירות ועלות; ניתוב חשיבה קשה של קפיצות מרובות על נתונים לא רגישים למודל ענן; וחזרה ל-SLM המקומי אם הענן לא זמין כך שהסוכן מתדרדר בנעימות במקום להיכשל. זה ניתוב מודלים (שיעור 16) כשהמחשב המקומי הוא אחד המודלים.

8. מהו מינימום ריאלי של זיכרון RAM להפעלת הסוכן המקומי בשיעור זה, ומה היתרון של יותר RAM?

תשובה סביב **8 ג"ב** הוא מינימום ריאלי; 16 ג"ב ומעלה זה נוח. יותר RAM מאפשר לך להפעיל מודלים גדולים ומתקדמים יותר ולשמור יותר הקשר בזיכרון. GPU או NPU מזרזים אינפרנס אך אינם דרושים — Foundry Local בוחרת בניית CPU כשאין מאיץ זמין.

משימה

הרחב את העוזר ההנדסי המקומי לבוחן תיעוד מקומי לפרויקט קטן לפי בחירתך (השתמש באחת מתיקיות השיעורים במאגר אם תרצה).

ההגשה שלך צריכה:

  1. לאנדקס תיקיית מסמכים/קוד אמיתית אל Chroma (לפחות חמישה קבצים).
  2. להוסיף כלי find_todos שסורק את הפרויקט אחר הערות TODO/FIXME ומחזיר אותן עם שם הקובץ ומספר השורה — תוך שמירה על אותה בדיקת סנדבוקס כמו read_file.
  3. שאל את הסוכן שלוש שאלות שמאלצות אותו לשלב כלים: שאלה אחת טהורה של RAG, אחת שדורשת קריאת קובץ מסוים, ואחת שדורשת מציאת TODOs.
  4. מדוד את זה: מדוד את זמן התגובה של כל אחת משלוש התגובות ושלח אותן בתא markdown. הגיב אם זמן התגובה מקובל עבור זרימת העבודה המיועדת שלך.

לאחר מכן כתוב פסקה קצרה על מה היית מעביר לענן ומה היית שומר מקומי עבור הסוקר הזה, ומדוע. אתה מוערך על האם הרכיבים המקומיים מחוברים נכון והאם ההיגיון ההיברידי שלך תקין — לא על איכות המודל.

סיכום

בשיעור זה בנית סוכן הפועל כולו על המחשב שלך:

זה משלים את קשת ההטמעה: השיעור ה-16 הגדיל סוכנים לתוך Microsoft Foundry, והשיעור הזה הקטין אותם אל תחנת עבודה יחידה. השיעור הבא מתמקד בשמירת סוכנים מופעלים בטוחים.

משאבים נוספים

שיעור קודם

הטמעת סוכנים מתקדמים

שיעור הבא

אבטחת סוכני בינה מלאכותית

כתב ויתור: מסמך זה תורגם באמצעות שירות תרגום אוטומטי Co-op Translator. למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה.

This site is open source. Improve this page.