ai-agents-for-beginners

Kohalike tehisintellekti agentide loomine Microsoft Foundry Locali ja Qweniga

Kohalike tehisintellekti agentide loomine

Eelmine õppetund laiendas agente pilve. See toob nad alla ühele masinale. Lõpuks on sul töötav inseneriabiline, mis põhjendab, kutsub tööriistu, loeb faile ja otsib dokumentatsiooni — ilma ühegi pilvepõhise ennustuseta.

Miks seda tahaksid? Kolm põhjust, mis päriselus inseneritöös sageli esinevad:

Konks on selles, et sa vahetad tipptasemel pilvemudeli väikese keelemudeli (SLM) vastu, mis jookseb CPU, GPU või NPU peal. See õppetund räägib, kuidas ehitada agente, kes selles piirangus tõhusad on, mitte teeselda, et piirangut pole.

Sissejuhatus

See õppetund hõlmab:

Õpieesmärgid

Selle tunni läbimisel oskad:

Eeldused

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

Vajad ka:

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

Tipptasemel pilvemudelil on sadu miljardeid parameetreid ja andmekeskus selle taga. SLM-il on paar miljardit parameetrit ja see peab mahutuma sinu sülearvuti mälu sisse. See erinevus seab selged ootused.

SLMid sobivad hästi:

SLMid on nõrgemad:

Kohalike agentide võidustrateegia on: laske SLM-il orkestreerida ja tööriistadel teha rasket tööd. Mudelil ei pea olema sinu koodi tundmist — sellest piisab, kui ta teab, millal kutsuda read_file ja search_docs. See mängib SLM-i tugevustele otse vastu.

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_dokumente 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 runtime, mis laadib alla, haldab ja pakub mudeleid täielikult su masinas. Oluline omadus on see, et ta pakub OpenAI-ga ühilduvat HTTP-lõpp-punkti — mis tähendab, et OpenAI SDK ja Microsoft Agent Frameworki OpenAI klient töötavad selle peal lihtsalt, vahetades base_url-i. Kõik, mida agentide ehitamise kohta õpetati, kandub otse üle; ainus erinevus on, et lõpp-punkt liigub pilvest localhosti.

Foundry Local valib mudelist su arvuti jaoks parima versiooni automaatselt — kas CPU-versiooni, CUDA/GPU-versiooni või NPU-versiooni — nii et sul ei ole vaja iga masinat eraldi optimeerida.

Seadistamine

Paigalda Foundry Local (vaata dokumentatsiooni oma OS-ile) ja kontrolli, et see töötab:

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

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

Kui teenus jookseb, on sul kohalik OpenAI-ga ühilduv lõpp-punkt (tavaliselt http://localhost:PORT/v1). Sülearvutuses kasutatakse foundry-local-sdk lõpp-punkti automaatseks leidmiseks, nii et pole vaja porti kõvakodeerida.

Qweni funktsioonikõne: miks see oluline on

Agent on alles agent, kui ta suudab tööriistu kutsuda. Paljud SLMid saavad vestelda, kuid annavad ebausaldusväärseid ja vigaseid tööriistakõnesid. Qwen mudelid on treenitud funktsioonikõneks ja sünnitavad korrapäraselt hästi vormistatud tööriistakõnestruktuure — just see teeb kohalikust vestlusmudelist kohaliku agendi.

Protsess on tavaline tööriistakõne tsükkel, mida sa juba tead, lihtsalt kohapeal jooksutatud:

sequenceDiagram
    participant U as Kasutaja
    participant A as Qwen Agendi (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 põhjal mõtiskle
    A-->>U: Selgitus

Kohalik RAG

Dokumentatsiooni otsing on koht, kus kohalikud agendid tõeliselt väärtust loovad. Selle asemel, et loota, et SLM on sinu raamatu dokumendid meelde jätnud, paigutad dokumendid kohalikku vektorandmebaasi ja lubad agendil päringul vajalikke lõike tuua.

Kasutame Chroma-d, manustatud vektoripoed, mis töötab protsessis ja mille jaoks serverit ei ole. Töövoog on täielikult kohalik: kohalik sisestusmudel → kohalikud vektorid → kohalik otsing → kohalik SLM.

flowchart TB
    D[Teie dokumendid / kood] --> E[Kohalik manustamismudel]
    E --> V[(Chroma vektorandmebaas - kettal)]
    Q[Agendi päring] --> QE[Manusta päring kohapeal]
    QE --> V
    V -->|top-k tükid| A[Qweni agent]
    A --> Ans[Põhineb vastusel]

See on sama Agentic RAG muster nagu õppetunnis 5 — ainus erinevus, et kõiki komponente jookseb sinu masinas.

Kohalikud MCP serverid

MCP on transpordikiht, mitte pilveteenus. MCP server võib jookseda lokaalse protsessina stdio-l, pakkudes tööriistu agendile üle tavaprotokolli. See laseb kasutada kasvavat MCP serverite ökosüsteemi — failisüsteemi ligipääsu, git operatsioone, andmebaasi päringuid — täiesti võrguühenduseta.

Turvapoliitika on pilvest erinev, kuid pole puuduv: kohalik MCP server jookseb sinu kasutajaõigustes, nii et piira, mida see võib puudutada (näiteks projekti kataloog, mitte kogu kodukataloog) ja kohtu tema väljundite usaldusväärsust enne nende kasutamist.

Hübriidpilve ja kohaliku mustrid

Kohalik esimene ei tähenda ainult kohalikku. Küpsed süsteemid marsruutivad tundlikuse ja keerukuse järgi:

Situatsioon Kus jookseb
Tundlik kood / andmed või võrguühenduseta Kohalik SLM
Lihtne, piiratud ülesanne Kohalik SLM (odav, kiire)
Raske mitmehüppelise põhjendusega mitte-tundlikel andmetel Pilvemudel
Kõik katkestuse ajal Kohalik SLM (peenhäälestatud degradeerumine)

See peegeldab õppetunni 16 mudelite marsruutimise mõtteviisi — ainult et üks «mudelitest» oled nüüd sa ise. Tugev disain lülitab pilvest kohaliku peale, kui pilv pole saadaval, nii et agent degradeerub kvaliteedis, mitte ei ebaõnnestu täielikult.

flowchart LR
    Q[Päring] --> S{Tundlik või võrguühenduseta?}
    S -->|jah| L[Kohalik SLM]
    S -->|ei| C{Kas on vaja põhjalikku arutlust?}
    C -->|ei| L
    C -->|jah| Cloud[Pilvemudel]
    L --> Out[Vastus]
    Cloud --> Out

Praktikum: Kohalik inseneriabiline

Ava code_samples/17-local-agent-foundry-local.ipynb ja tööta läbi. Ehita kohalik inseneriabiline, mis töötab ainult su töölaual ja saab:

  1. Kutsuda tööriistu — Qweni funktsioonide kaudu Foundry Locali abil.
  2. Käidelda kohalikke failioperatsioone — projektikataloogis failide nimekiri ja lugemine.
  3. Analüüsida koodi — katta põhistatistika lähtefaili kohta.
  4. Otsida dokumentatsioonist — kohalik RAG dokumendikaustadel Chromaga.
  5. Kasutada MCP-d — ühendada kohaliku MCP serveriga (juhul kui mitte, jätta graatsiliselt vahele).

Ükski pilve ennustus pole kasutusel.

Ülevaade

Abiühendus toimub Foundry Locali OpenAI-ga ühilduva lõpp-punkti kaudu, nii et agendi kood näeb pilveõppetundidest praktiliselt ühesugune välja — ainult klient muutub:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Foundry Local avastab/alla laadib mudeli 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 kohatäide

Tööriistad on tavalised Python funktsioonid, mis on piiritletud konkreetse projekti kataloogiga:

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

Pöörake tähelepanu liivakasti kontrollile — isegi kohapeal on tööriist, mis loeb suvalisi radu, riskantne. Märkmik hoiab iga tööriista ühe projekti juurkaustaga piiritletuna.

Teadmiste kontroll

Testi oma arusaamist enne ülesande juurde asumist.

1. Too kaks konkreetset põhjust, miks agent jooksutada kohapeal, mitte pilves.

Vastus Kaks järgmist: **privaatsus** (kood ja andmed ei lahku masinast), **kulu** (ei ole tokenipõhist arvestust), ja **võrguühenduseta töövõime** (käib võrguta — lennukis, turvalises ruumis või katkestuse ajal). Õigus- ja regulatiivsed piirangud, mis keelavad andmed seadmest välja saata, on tavaline privaatsusmotiiv.

2. Milline on soovitatav tööjaotus SLM-i ja tööriistade vahel kohalikus agendis ning miks?

Vastus Lase SLM-il **orkestreerida** (otsustada, millist tööriista kutsuda ja milliste argumentidega) ning lase **tööriistadel teha raske töö** (failide lugemine, dokumentide otsimine, arvutuste tegemine). SLMid on tugevad piiratud otsustes nagu tööriista valik, kuid nõrgemad laias maailmateadmises ja pikkade mitmehüppeliste põhjuslustega, seega tugineda tööriistadele mängib nende tugevustele vastu.

3. Mis võimaldab taaskasutada pilve-agendi koodi Foundry Localiga?

Vastus Foundry Local pakub **OpenAI-ga ühilduvat HTTP-lõpp-punkti**. OpenAI SDK ja Agent Frameworki OpenAI klient töötavad selle vastu vaid `base_url`-i muutes (kasutades kohalikku kohatäite API võtit). Kõik muu agendi koodis jääb samaks.

4. Miks kasutame spetsiaalselt Qwen funktsioonikõne mudelit, mitte suvalist SLM-i?

Vastus Sest agent peab tooma usaldusväärseid, korrektselt vormistatud **tööriistakõnesid**. Paljud SLMid saavad ülevahelda, kuid esitavad vigaseid või ebajärjekindlaid tööriistakõnestruktuure. Qwen mudelid on spetsiaalselt funktsioonikõneks koolitatud ja sünnitavad järjekindlaid kõnesid, mis muudab kohalikust vestlusmudelist töökorras kohaliku agendi.

5. Millised komponendid jooksevad masina peal kohaliku RAG töövoos?

Vastus Kõik: sisestusmudel, vektorandmebaas (Chroma ketastel), otsingufaas ja SLM. Dokumendid sisestatakse kohapeal, salvestatakse kohapeal, tuuakse kohapeal ja neid põhjendatakse kohalikus mudelis — miski ei puutu pilve.

6. Kohalik MCP server jookseb su masinas. Kas see teeb selle automaatselt turvaliseks? Millist ettevaatusabinõu peaksid siiski järgima?

Vastus Ei. Kohalik MCP server töötab sinu kasutajaõigustes, seega pääseb ligi kõigile, mida sina suudad. Piira ta kasutusala vajalikule (nt ühele projekti kaustale, mitte kogu kodukataloogile) ja käitu tema väljunditega nagu sisenditega, et neid enne valideerida.

7. Kirjelda mõistlikku hübriidset marsruutimispõhimõtet, millesse kuulub ka kohalik mudel.

Vastus Suuna tundlikud või võrguühenduse puudumisega päringud kohalikku SLM-i; suuna lihtsad piiratud ülesanded kohalikku SLM-i kiiruse ja kulu tõttu; suuna rasked mitmehüppelised põhjendused mitte-tundlike andmete puhul pilvemudelisse; ja kasuta kohalikku SLM-i kui pilv ei ole saadaval, nii et agent degradeerub graatsiliselt, mitte ei ebaõnnestu. See on mudelite marsruutimine (tund 16), kus üks mudelitest oled sina ise.

8. Milline on realistlik miinimummälu (RAM) kohalikule agendile selles tunnis, ja mida enam mälu võimaldab?

Vastus Umbes **8 GB** on realistlik miinimum; 16 GB+ on mugav. Rohkem mälu võimaldab jooksutada suuremaid, võimekamaid mudeleid ja hoida rohkem konteksti mälus. GPU või NPU kiirendavad ennustust, kuid pole kohustuslikud — Foundry Local valib CPU-versiooni, kui kiirendajat pole.

Ülesanne

Arenda kohalik inseneriabiline edasi kohalikuks dokumentatsiooni ülevaatajaks väikse projekti jaoks, mida soovid (kasuta selle repositooriumi mõnda õppetunni kausta kui soovid).

Sinu lahendus peaks:

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

  2. Lisa find_todos tööriist, mis otsib projektist TODO/FIXME kommentaare ja tagastab need koos faili ja reanumbriga — hoides 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 TODO-de leidmist.
  4. Mõõtke aeg: ajastage iga kolme vastuse jaoks aeg ja märkige see märkmerakenduse lahtrisse. Kommenteerige, kas latentsus on teie kavandatud töövoo jaoks aktsepteeritav.

Seejärel kirjutage lühike lõik selle kohta, mida te pilve viiksite ja mida kohapeal hoiaksite selleks ülevaatajale ning miks. Teid hinnatakse selle järgi, kas lokaalsed komponendid on õigesti omavahel ühitatud ja kas teie hübriidne mõtlemine on loogiline — mitte mudeli kvaliteedi järgi.

Kokkuvõte

Selles tunnis ehitasite agendi, mis töötab täielikult teie enda masinas:

See lõpetab juurutuskäigu: õppetund 16 skaleeris agendid Microsoft Foundry-sse ja see õppetund vähendas nad üheks töölauaks. Järgmine õppetund keskendub juba juurutatud agentide turvalisuse hoidmisele.

Lisaressursid

Eelmine õppetund

Skaalautuvate 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.