ai-agents-for-beginners

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

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

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

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

Фатаморгана је у томе што тргујете моделом из врха облака за Мали Језички Модел (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 build, CUDA/GPU build, или NPU build — тако да не морате ручно да оптимизујете по машини.

Подешавање

Инсталирајте Foundry Local (погледајте документацију за ваш ОС), а затим потврдите да ради:

# Инсталирајте (нпр; пратите документацију за вашу платформу)
winget install Microsoft.FoundryLocal      # Виндоус
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Преузмите и покрените 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 преко фасцикле са документима користећи Chroma.
  5. Користити MCP — повезати се са локалним MCP сервером (са грејсфул скоком ако ниједан није конфигурисан).

Ни на једном месту није коришћен облачни inference.

Проход

Асистент се повезује са 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\")

Обратите пажњу на проверу sandbox-а — чак и локално, алат који чита произвољне путеве представља ризик. Бележница чува све алатке ограничене на једну коренску фасциклу пројекта.

Провера Знања

Тестирајте своје разумевање пре него што пређете на задатак.

1. Наведите два конкретна разлога за покретање агента локално уместо у облаку.

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

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

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

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

Одговор Foundry Local излаже **OpenAI-у компатибилан HTTP ендпоинт**. OpenAI SDK и OpenAI клијент Agent Framework-а раде са њим само променом `base_url` (и коришћењем локалног placeholder 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 убрзава inference али није обавезно — Foundry Local бира CPU build кад нема акцелератора.

Задатак

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

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

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

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

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

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

Резиме

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

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

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

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

Deploying Scalable Agents

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

Securing AI Agents

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

This site is open source. Improve this page.