ai-agents-for-beginners

Креирање локалних AI агената коришћењем Microsoft Foundry Local и Qwen

Креирање локалних AI агената

Претходна лекција је скалирала агенте горе у облак. Ова их спушта доле на један рачунар. До краја ћете имати радног инжењерског асистента који расуђује, позива алате, чита ваше фајлове и претражује вашу документацију — без иједног позива за предикцију у облаку.

Зашто бисте то желели? Три разлога која се стално јављају у стварном инжењерском раду:

Фора је у томе што уместо врхунског облачног модела користите Мали језички модел (SLM) који ради на вашем CPU-у, GPU-у или NPU-у. Ова лекција је о прављењу агената који су добри у оквиру тог ограничења, а не о претварању да ограничење не постоји.

Увод

Ова лекција ће обухватити:

Циљеви учења

Након завршетка ове лекције, знаћете како да:

Предуслови

Ова лекција претпоставља да сте завршили претходне лекције и да вам је удобно:

Такође ће вам требати:

Мали језички модели: Прави алат за локални рад

Врхунски облачни модел има стотине милијарди параметара и центар података иза себе. SLM има неколико милијарди параметара и мора да стане у RAM вашег лаптопа. Та разлика поставља јасна очекивања.

SLM-ови су добри у:

SLM-ови су слабији у:

Стратешки успех за локалне агенте је зато: нека SLM оркестрира, а нека алати носе главни терет. Модел не мора да зна ваш код — мора да зна када да позове read_file и search_docs. То одговара јачањима SLM-а.

flowchart LR
    U[Програмер] --> A[Локални СЛМ агент]
    A -->|одлучује који алат| T1[прочитај_датотеку]
    A -->|одлучује који алат| T2[претражуј_документе РАГ]
    A -->|одлучује који алат| T3[анализирај_код]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Одговор, потпуно на уређају]

Microsoft Foundry Local

Microsoft Foundry Local је лаган runtime који преузима, управља и сервира моделе у потпуности на вашем уређају. Његова најважнија особина за нас је што излаже OpenAI-усклађену HTTP крајњу тачку — што значи да OpenAI SDK и Microsoft Agent Framework-ов OpenAI клијент раде против ње само уз промену base_url. Све што сте научили о изради агената преноси се директно; само се крајња тачка помера из облака на localhost.

Foundry Local такође аутоматски бира најбољу верзију модела за ваш хардвер — CPU билд, 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: Објашњење

Локални 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[Локални СЛМ]
    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 преко фасцикле са документацијом помоћу Chrome.
  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 је локални плейсхолдер

Алати су обичне 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. Наведите два конкретна разлога за покретање агента локално, а не у облаку.

Одговор Било која два од: **приватност** (код и подаци никада не напуштају машину), **трошкови** (нема наплате по токену), и **могућност рада без мреже** (ради у авиону, у безбедном објекту или током искључења). Регулаторни/комплајнс захтеви који забрањују слanje података ван уређаја су чест разлог за приватност.

2. Која је препоручена подела рада између SLM-а и његових алата у локалном агенту и зашто?

Одговор Нека SLM **оркестрира** (одлучује који алат позвати и са којим аргументима), а нека **алати обављају тежак посао** (читање датотека, преузимање докумената, израчунавање резултата). SLM-ови су добри у ограниченим одлукама као избор алата, али су слабији у широком знању и дугом вишестепеном расуђивању, па ослањање на алате игра њихове снаге.

3. Шта омогућава поновну употребу кода облачних агената са Foundry Local?

Одговор Foundry Local експонира **OpenAI-усклађену HTTP крајњу тачку**. OpenAI SDK и Agent Framework-ов OpenAI клијент раде против ње само променом `base_url` (и коришћењем локалног API кључа као плейсхолдера). Све остало у коду агента остаје исто.

4. Зашто користимо Qwen модел за позив функција посебно, а не било који SLM?

Одговор Јер агент мора да производи поуздане, добро форматиране **позиве алата**. Многи SLM-ови могу да ћаскају али емитују неисправне или неконзистентне структуре позива алата. Qwen модели су тренирани за позив функција и доследно производе позиве алата, што претвара локални чат модел у радног локалног агента.

5. Које компоненте у локалном RAG пејплајну раде на машини?

Одговор Све: модел уграђивања, векторска база података (Chroma, на диску), корак преузимања и SLM. Документи се локално уграђују, чувају локално, преузимају локално и разматрају од стране локалног модела — ниједна компонента не додирује облак.

6. Локални MCP сервер ради на вашој машини. Да ли то аутоматски значи да је безбедан? Које мере предострожности и даље треба предузети?

Одговор Не. Локални MCP сервер ради са вашим корисничким привилегијама, па може да приступи свему што ви можете. Ограничите га на оно што му треба (нпр. један директоријум пројекта, а не цео ваш кућни фолдер) и третирајте његове излазе као улазе које треба проверити пре коришћења.

7. Опишите смислену хибридну правилину руту која укључује локални модел.

Одговор Рутирајте осетљиве или офлајн захтеве ка локалном SLM-у; једноставне ограничене задатке ка локалном SLM-у због брзине и цене; тешко вишестепено расуђивање на неосетљивим подацима ка облачном моделу; и враћајте се на локални SLM ако облак није доступан да агент благо деградира уместо да потпуно не успе. Ово је рутирање модела (лекција 16) са локалном машином као једним од модела.

8. Која је реална минимална количина RAM-а за покретање локалног агента у овој лекцији и шта вам више RAM-а доноси?

Одговор Око **8 GB** је реална минимална вредност; 16 GB+ је удобан капацитет. Више RAM-а вам омогућава покретање већих и способнијих модела и чување више контекста у меморији. GPU или NPU убрзавају предикцију али нису неопходни — Foundry Local одабира CPU билд када нема доступног акцелератора.

Задатак

Проширите локалног инжењерског асистента у локалног рецензента документације за мали пројекат по свом избору (користите неки од фолдера са лекцијама из овог репозиторијума ако желите).

Ваш рад треба да:

  1. Индексира стварни фолдер са документацијом/кодом у Chroma (најмање пет фајлова).

  2. Дода алат find_todos који скенира пројекат за коментаре TODO/FIXME и враћа их са именом фајла и бројем линије — уз исту проверу песковника као код read_file.

  3. Постаните агенту три питања која га приморавају да комбинује алате: једно чисто РАГ питање, једно које захтева читање одређеног фајла и једно које захтева проналажење TODO ставки.
  4. Измерите то: измерите време сва три одговора и забележите их у markdown ћелију. Коментаришите да ли је латенција прихватљива за ваш намерени радни ток.

Затим напишите кратак пасус о томе шта бисте померили у облак а шта задржали локално за овог рецензента, и зашто. Оцењујете се по томе да ли су локалне компоненте правилно повезане и да ли је ваша хибридна логика исправна — а не по квалитету модела.

Резиме

У овој лекцији сте саставили агента који ради потпуно на вашем рачунару:

Овиме се завршава лук дејства: Лекција 16 је скалирала агенте у Microsoft Foundry, а ова лекција их је свела на један радни сто. Следећа лекција се бави безбедношћу распоређених агената.

Додатни ресурси

Претходна лекција

Deploying Scalable Agents

Следећа лекција

Securing AI Agents

Изјава о одрицању одговорности: Овај документ је преведен коришћењем услуге за аутоматски превод Co-op Translator. Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода.

This site is open source. Improve this page.