ai-agents-for-beginners

Kohalike tehisintellekti agentide loomine Microsoft Foundry Locali ja Qweni abil

Kohalike tehisintellekti agentide loomine

Eelmine õppetund laiendas agente pilves. See õpetus toob need alla ühele masinale. Lõpuks on sul töökorras inseneriabi, mis mõtleb, kasutab tööriistu, loeb su faile ja otsib dokumentatsiooni — ilma ühegi pilvepõhise järelduse päringuta.

Miks seda soovida? On kolm põhjust, mis reaalses inseneritöös pidevalt ette tulevad:

Kinni on see, et sa vahetad tipptasemel pilvemudeli välja väikese keelemudeli (SLM) vastu, mis jookseb su protsessoril, graafikakaardil või närvivõtmel. See õppetund räägib, kuidas ehitada agente, kes on head selle piirangu sees, mitte ette kujutada, et piirangut ei eksisteeri.

Sissejuhatus

See õppetund käsitleb:

Õpieesmärgid

Pärast selle õppetunni läbimist oskad:

Eeltingimused

Eeldame, et oled läbinud varasemad õppetunnid ja oskad:

Vajalik on ka:

Väikesed keelemudelid: õige tööriist kohaliku töö jaoks

Tipptasemel pilvemudelil on sadu miljardeid parameetreid ja taga andmekeskus. Väikesel keelemudelil on paar miljardit parameetrit ja see peab mahtuma sinu sülearvuti mällu. See vahe seab selged ootused.

SLMid on head:

SLMid on nõrgemad:

Seega on kohalike agentide võidustrateegia: las SLM koordineerib ja tööriistad teevad raske töö. Mudelil ei pea olema teadmist sinu koodibaasist — ta peab teadma, millal kutsuda read_file ja search_docs. See mängib täpselt SLMi tugevuste kasuks.

flowchart LR
    U[Arendaja] --> A[Kohalik SLM-agent]
    A -->|otsustab, millist tööriista kasutada| T1[loe_faili]
    A -->|otsustab, millist tööriista kasutada| T2[otsi_dokumendid RAG]
    A -->|otsustab, millist tööriista kasutada| T3[analüüsi_koodi]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Vastus, täielikult seadmes]

Microsoft Foundry Local

Microsoft Foundry Local on kergekaaluline jooksuaeg, mis laadib, haldab ja teenindab mudeleid täielikult su masinal. Meie jaoks on tähtsaim omadus, et see pakub OpenAI-ühilduvat HTTP lõpp-punkti — mis tähendab, et OpenAI SDK ja Microsoft Agent Frameworki OpenAI klient töötavad selle vastu vaid muutes base_url. Kõik agentide loomise teadmised on otse rakendatavad; ainult lõpp-punkt nihkub pilvest localhosti.

Foundry Local valib automaatselt sobivaima mudeli ehituse sinu riistvarale — kas CPU, CUDA/GPU või NPU — nii ei pea sa iga masina jaoks käsitsi optimeerima.

Paigaldus

Paigalda Foundry Local (vt dokumentatsiooni oma operatsioonisüsteemi kohta), seejärel kinnita, et töötab:

# Paigalda (näiteks; järgi oma platvormi juhiseid)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Laadi alla ja käivita Qweni mudel, seejärel alusta lokaalteenust
foundry model run qwen2.5-7b-instruct
foundry service status

Kui teenus töötab, on sul olemas kohalik OpenAI-ühilduv lõpp-punkt (tavaliselt http://localhost:PORT/v1). Märkmik kasutab foundry-local-sdk automaatseks lõpp-punkti avastamiseks, nii et porti ei pea käsitsi kodeerima.

Qweni funktsioonikutsumine: miks see oluline on

Agent on agent ainult siis, kui ta oskab tööriistu kutsuda. Paljud SLMid oskavad suhelda, kuid toodavad ebausaldusväärseid ja valesti vormistatud tööriistakutseid. Qwen mudelid on koolitatud funktsioonikutsumiseks ja toodavad järjekindlalt õigesti vormistatud tööriistakutseid — mis teeb kohalikust vestlusmudelist tõelise agendi.

Töövoog on juba teada-tuntud tööriistakutseloop, lihtsalt jooksutatakse otse seadmel:

sequenceDiagram
    participant U as Kasutaja
    participant A as Qwen Agent (kohalik)
    participant T as Kohalik tööriist
    U->>A: "Mida teeb auth.py?"
    A->>A: Otsusta: kutsu read_file
    A->>T: read_file("auth.py")
    T-->>A: faili sisu
    A->>A: Sisu üle mõtisklema
    A-->>U: Selgitus

Kohalik RAG

Dokumentatsiooni otsing on koht, kus kohalikud agentid ennast tõestavad. Selle asemel, et loota SLMi mälu peale, sulandad need dokumendid kohalikku vektorandmebaasi ja lased agendil vajadusel sobivad tükid üles otsida.

Kasutame Chromat, sisseehitatud vektorpoodi, mis jookseb protsessis ega vaja serverit. Taim on täiesti kohalik: kohalik embeding mudel → kohalikud vektorid → kohalik otsing → kohalik SLM.

flowchart TB
    D[Teie dokumendid / kood] --> E[Kohalik manustamismudel]
    E --> V[(Chroma vektori andmebaas - kettal)]
    Q[Agendi päring] --> QE[Manusta päring kohalikult]
    QE --> V
    V -->|parimad-k tükid| A[Qweni agent]
    A --> Ans[Põhjuslik vastus]

See on sama Agentic RAG-muster nagu õppetund 5 — ainus erinevus on see, et kõik komponendid jooksevad su masinal.

Kohalikud MCP serverid

MCP on transpordikiht, mitte pilveteenus. MCP server võib jooksutada kohaliku protsessina stdiol, pakkudes tööriistu su agendile standardprotokolli kaudu. See võimaldab taaskasutada kasvavat MCP serverite ökosüsteemi — failisüsteemi ligipääs, git-operatsioonid, andmebaasipäringud — täiesti võrguvabalt.

Turvalisus on erinev pilvest, aga mitte puuduv: kohalik MCP server jookseb su kasutaja õigustega, seega piira, mida ta võib puudutada (nt projekti kaust, mitte kogu kodukaust) ja käsitle selle väljundeid sisenditena, mida vajadusel valideerida.

Hübriidsed pilve- ja kohalikud mustrid

Esmalt kohalik pole sama, mis ainult kohalik. Küpsed süsteemid marsruutivad tundlikkuse ja keerukuse alusel:

Situatsioon Kus jookseb
Tundlik kood/andmed või võrguvaba Kohalik SLM
Lihtne, piiritletud ülesanne Kohalik SLM (odav, kiire)
Raske mitmetasandiline mõtlemine mitte-tundlikel andmetel Pilvemudel
Kõik, katkestuse ajal Kohalik SLM (läbimõeldud degradeerumine)

See peegeldab mudeleid marsruutimise ideed õppetundist 16 — ainult et üks „mudelitest“ on nüüd sinu enda masin. Vastupidav disain lülitub pilve puudumisel automaatselt kohalikule, nii et agent halveneb kvaliteedis, mitte ei vea alt.

flowchart LR
    Q[Päring] --> S{Tundlik või võrguühenduseta?}
    S -->|jah| L[Kohalik SLM]
    S -->|ei| C{Vajab sügavat mõtlemist?}
    C -->|ei| L
    C -->|jah| Cloud[Pilvemudel]
    L --> Out[Vastus]
    Cloud --> Out

Praktiline ülesanne: Kohalik inseneriabimees

Ava code_samples/17-local-agent-foundry-local.ipynb ja tööta sellega. Ehita kohalik inseneriabimees, mis jookseb su töökohal ja suudab:

  1. Kutsuda tööriistu — Qweni funktsioonikutsumise kaudu Foundry Localiga.
  2. Teha kohalikke failitöid — listida ja lugeda faile projekti kaustast.
  3. Analüüsida koodi — anda lihtsad mõõdikud lähtefailist.
  4. Otsida dokumentatsioonist — kohalik RAG dokumentide kaustas Chromat kasutades.
  5. Kasutada MCPd — ühendada kohaliku MCP serveriga (kerge vahelejätmisega, kui pole konfigureeritud).

Ühtegi pilvepõhist järeldust ei tehta.

Läbikäik

Assistendil on ühendus Foundry Localiga OpenAI-ühilduva lõpp-punkti kaudu, nii et agendi kood näeb peaaegu pilveteemaliste õppetundide moodi välja — ainult klient vahetub:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Foundry Local leiab/laadib mudeli alla ja annab meile kohaliku lõpp-punkti.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key on kohalik kohthoidja

Tööriistad on tavapärased Pythoni funktsioonid, mis piiritletud projekti kaustaga:

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\")

Märka liivakasti-kontrolli — isegi kohapeal on tööriist, mis loeb suvalisi teid, risk. Märkmik hoiab iga tööriista piiratuna ühele projekti juurele.

Teadmiste kontroll

Testi oma arusaamist enne ülesande lahendamist.

1. Too kaks konkreetset põhjust, miks agent tööle panna kohapeal, mitte pilves.

Vastus Kõik kaks järgnevatest: **privaatsus** (kood ja andmed ei lahku masinast), **kulud** (ei maksa märgi kohta järelduse eest) ja **võrguvabadus** (töötab ilma võrguühenduseta — lennukis, turvatsoonis või voolukatkestuse ajal). Regulatiivsed ja vastavusnõuded, mis keelavad andmeid seadmeväliselt saatmast, on tihti privaatsuse põhjuseks.

2. Kuidas on SLM ja selle tööriistade tööjaotus kohaliku agendi puhul ning miks?

Vastus Lase SLMil **koordineerida** (otsustada, mida ja kuidas kutsuda) ning lase **tööriistadel teha raske töö** (failide lugemine, dokumentide otsimine, arvutamine). SLMid on head piiritletud otsustes (nt tööriista valik) aga nõrgemad laiema teadmisruumi ja pika mitmeastmelise mõtlemisega, seega tugineda tööriistadele on nende tugevus.

3. Miks on võimalik taaskasutada pilveagentide koodi Foundry Localiga?

Vastus Foundry Local pakub **OpenAI-ühilduvat HTTP lõpp-punkti**. OpenAI SDK ja agendiraamistiku OpenAI klient töötavad selle vastu ainult muutes `base_url` (kasutades kohalikku asendust API võtmele). Kõik muu agentkoodis jääb samaks.

4. Miks kasutame just Qweni funktsioonikutsumist, mitte suvalist SLMi?

Vastus Sest agent peab tootma usaldusväärseid ja hästi vormistatud **tööriistakutseid**. Paljud SLMid oskavad vestelda, aga toodavad valevormis või ebajärjekindlaid tööriistakutseid. Qweni mudelid on koolitatud funktsioonikutsumiseks ja toodavad järjekindlaid tööriistakutseid, mis teeb kohalikust vestlussüsteemist toimiva agendi.

5. Millised komponendid jooksevad masinal kohaliku RAG pipelinis?

Vastus Kõik: embeding-mudel, vektordata baas (Chroma kettal), otsinguetapp ja SLM. Dokumendid embedditakse kohapeal, salvestatakse kohapeal, leitakse kohapeal ja SLM paneb neile mõtlema — ükski komponent ei puutu pilve.

6. Kohalik MCP server töötab su masinal. Kas see teeb selle automaatselt turvaliseks? Milliseid ettevaatusabinõusid peaksid siiski kasutama?

Vastus Ei. Kohalik MCP server töötab su kasutaja õigustes, nii et pääseb ligi kõikjale, kuhu sinu kasutaja pääseb. Piira teda vaid sellele, mida ta vajab (nt ühele projekti kaustale, mitte tervele kodukaustale) ja käsitle selle väljundeid nagu sisendeid, mida enne kasutamist peaks valideerima.

7. Kirjelda mõistlikku hübriidset marsruutimise reeglit, mis hõlmab lokaalset mudelit.

Vastus Saada tundlikud või võrguvabad päringud kohalikule SLMile; saada lihtsad ja piiritletud ülesanded kohalikule SLMile kiiruse ja maksumuse tõttu; saada keerukas mitmesammuline mõtlemine mitte-tundlikel andmetel pilvemudelile; ja lülitu pilve puudumisel tagasi kohalikule SLMile nii, et agent degradeerub sujuvalt, mitte ei vea alt. See on mudelite marsruutimine (õppetund 16) kus ühe mudelina on sinu masin.

8. Mis on selle õppetunni kohaliku agendi jooksutamiseks realistlik miinimum RAM maht ja mida rohkem RAMi annab?

Vastus Ligikaudu **8 GB** on realistlik miinimum; 16 GB+ on mugav. Rohkem RAMi võimaldab jooksutada suuremaid ja võimekamaid mudeleid ning hoida rohkem konteksti mälus. GPU või NPU kiirendab järeldust, aga pole kohustuslik — Foundry Local valib CPU ehituse, kui kiirendajat pole.

Ülesanne

Laienda kohaliku inseneriabi rakendus kohalikuks dokumentatsiooni vaatlejaks väikese valitud projekti jaoks (kasuta soovi korral mõnda selle reposti õppetundide kaustadest).

Sinu lahendus peaks:

  1. Indekseerima reaalse dokumendi/koodi kausta Chromasse (vähemalt viis faili).

  2. Lisama find_todos tööriista, mis skaneerib projekti TODO/FIXME kommentaaride leidmiseks ja tagastab need koos faili ja rea numbriga — säilitades sama liivakasti kontrolli nagu read_file.

  3. Esitage agendile kolm küsimust, mis sunnivad seda tööriistu kombineerima: üks puhas RAG-küsimus, üks, mis nõuab konkreetse faili lugemist, ja üks, mis nõuab TODOde leidmist.
  4. Mõõtke see: aeglustage iga kolme vastuse aeg ja märkige see markdown-rakku. Kommenteerige, kas latentsus on teie planeeritud töövoo jaoks aktsepteeritav.

Kirjutage seejärel lühike lõik mida te pilve viiksite ja mida hoiaksite lokaalselt selle hindaja jaoks ning miks. Teid hinnatakse selle järgi, kas lokaalsed komponendid on õigesti omavahel ühendatud ja kas teie hübriidne mõtlemine on põhjendatud — mitte mudeli kvaliteedi järgi.

Kokkuvõte

Selles õppetükis ehitasite agendi, mis töötab täielikult teie enda masinal:

Sellega lõpeb juurutuse ring: Õppetund 16 skaleeris agendid Microsoft Foundrysse ja see õppetund skaleeris neid ühele tööjaamale. Järgmine õppetund keskendub juurutatud agentide turvalisusele.

Täiendavad ressursid

Eelmine õppetund

Skaleeritavate agentide juurutamine

Järgmine õppetund

AI agentide turvamine

Lahtiütlus: See dokument on tõlgitud kasutades AI tõlketeenust Co-op Translator. Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest.

This site is open source. Improve this page.