ai-agents-for-beginners

Paikallisten tekoälyagenttien luominen Microsoft Foundry Localin ja Qwenin avulla

Paikallisten tekoälyagenttien luominen

Edellinen oppitunti skaalasi agentteja pilveen. Tämä tuo ne alas yhdelle koneelle. Lopuksi sinulla on toimiva insinöörin assistentti, joka perustelee, kutsuu työkaluja, lukee tiedostojasi ja etsii dokumentaatiostasi — ilman yhtään pilvipohjaista päättelykutsua.

Miksi haluaisit niin? Kolme syytä, jotka nousevat jatkuvasti esiin todellisessa insinöörityössä:

Kiintiönä on, että vaihdat eturivin pilvimallin pieneen kielimalliin (SLM), joka toimii CPU:llasi, GPU:llasi tai NPU:llasi. Tämä oppitunti käsittelee agenttien rakentamista, jotka ovat hyviä tämän rajoitteen puitteissa sen sijaan, että teeskentelet ettei rajoitetta ole.

Johdanto

Tässä oppitunnissa käsitellään:

Oppimistavoitteet

Oppitunnin suorittamisen jälkeen osaat:

Esitiedot

Tämä oppitunti olettaa, että olet suorittanut aikaisemmat oppitunnit ja olet perehtynyt:

Tarvitset myös:

Pienet Kielimallit: Oikea työkalu paikalliseen työhön

Eturivin pilvimallissa on satoja miljardeja parametreja ja datakeskus takana. SLM:llä on muutama miljardi parametria ja se täytyy mahtua kannettavan tietokoneen muistiin. Tämä ero luo selkeät odotukset.

SLM:t ovat hyviä:

SLM:t ovat heikompia:

Menestyksen avain paikallisissa agenteissa on siis: anna SLM:n orkestroida, ja anna työkalujen hoitaa raskas työ. Mallin ei tarvitse tuntea koodikantaasi — sen täytyy tietää milloin kutsua read_file ja search_docs. Tämä sopii suoraan SLM:n vahvuuksiin.

flowchart LR
    U[Kehittäjä] --> A[Paikallinen SLM-agentti]
    A -->|päättää työkalun| T1[lue_tiedosto]
    A -->|päättää työkalun| T2[hae_dokumentteja RAG]
    A -->|päättää työkalun| T3[analysoi_koodi]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Vastaus, täysin laitteessa]

Microsoft Foundry Local

Microsoft Foundry Local on kevyt suoritusaikaympäristö, joka lataa, hallinnoi ja tarjoaa malleja kokonaan koneellasi. Tärkein ominaisuus meille on, että se tarjoaa OpenAI-yhteensopivan HTTP-päätepisteen — mikä tarkoittaa, että OpenAI SDK ja Microsoft Agent Frameworkin OpenAI-asiakas toimivat sen kanssa vain vaihtamalla base_url:n. Kaikki agentin rakentamiseen liittyvä oppimasi siirtyy suoraan; vain päätepiste muuttaa pilvestä localhost:iin.

Foundry Local valitsee myös automaattisesti parhaan malliversion laitteistollesi — CPU-buildin, CUDA/GPU-buildin tai NPU-buildin — joten sinun ei tarvitse optimoida konetta kohden manuaalisesti.

Asennus

Asenna Foundry Local (katso dokumentaatio omalle käyttöjärjestelmällesi), ja tarkista toiminta:

# Asenna (esimerkki; seuraa alustan ohjeita)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Lataa ja suorita Qwen-malli, käynnistä sitten paikallinen palvelu
foundry model run qwen2.5-7b-instruct
foundry service status

Kun palvelu on käynnissä, sinulla on paikallinen, OpenAI-yhteensopiva päätepiste (tyypillisesti http://localhost:PORT/v1). Muistikirja käyttää foundry-local-sdk:ta löytääkseen päätepisteen automaattisesti, joten porttia ei tarvitse kovakoodata.

Qwen-funktiokutsu: Miksi se on tärkeä

Agentti on agentti vain jos se voi kutsua työkaluja. Moni SLM voi keskustella mutta tuottaa epäluotettavia, virheellisiä työkalukutsuja. Qwen-mallit on koulutettu funktiokutsuihin ja ne tuottavat johdonmukaisia, hyvin muodostettuja työkalukutsurakenteita — ja juuri tämä tekee paikallisesta keskustelumallista paikallisen agentin.

Kulku on tuttu työkalukutsusilmukka, mutta se toimii laitteellasi:

sequenceDiagram
    participant U as Käyttäjä
    participant A as Qwen Agentti (paikallinen)
    participant T as Paikallinen Työkalu
    U->>A: "Mitä auth.py tekee?"
    A->>A: Päätä: kutsu read_file
    A->>T: read_file("auth.py")
    T-->>A: tiedoston sisältö
    A->>A: Perustele sisällön perusteella
    A-->>U: Selitys

Paikallinen RAG

Dokumentaation haku on se, missä paikalliset agentit ansaitsevat paikkansa. Sen sijaan, että toivoisit SLM:n muistaneen kehyskirjastosi dokumentaation, sijoitat dokumentit paikalliseen vektoripohjaiseen tietokantaan ja annat agentin hakea asiaankuuluvat palat tarpeen mukaan.

Käytämme Chromaa, upotettua vektorivarastoa, joka toimii prosessin sisällä ilman palvelimen hallintaa. Prosessi on täysin paikallinen: paikallinen upotusmalli → paikalliset vektorit → paikallinen haku → paikallinen SLM.

flowchart TB
    D[Sinun dokumenttisi / koodisi] --> E[Paikallinen upotusmalli]
    E --> V[(Chroma-vektoritietokanta - levyllä)]
    Q[Agenttikysely] --> QE[Upota kysely paikallisesti]
    QE --> V
    V -->|top-k osat| A[Qwen-agentti]
    A --> Ans[Perusteltu vastaus]

Tämä on sama Agentic RAG -kuvio kuin Oppitunnissa 5 — ainoa ero, että kaikki komponentit toimivat koneellasi.

Paikalliset MCP-palvelimet

MCP on tiedonsiirtoprotokolla, ei pilvipalvelu. MCP-palvelin voi toimia paikallisena prosessina stdio:lla, tarjoten työkaluja agentillesi standardiprotokollan kautta. Tällä voit käyttää uudelleen kasvavaa MCP-palvelimien ekosysteemiä — tiedostojärjestelmän käyttö, git-toiminnot, tietokantakyselyt — täysin offline-tilassa.

Turvallisuusnäkökulma on eri kuin pilvessä, mutta ei poissa: paikallinen MCP-palvelin toimii käyttäjäoikeuksillasi, joten rajoita mitä se voi käsitellä (esim. projektihakemisto, ei koko kotihakemistoasi) ja käsittele sen tulosteita syötteinä tarkistuksen kautta.

Hybridiset pilvi- ja paikalliskuvio

Paikallinen ei tarkoita vain paikallista. Kypsissä järjestelmissä ohjaus perustuu herkkyyteen ja vaikeuteen:

Tilanne Missä toimii
Herkkä koodi/data tai offline-tila Paikallinen SLM
Yksinkertainen, rajallinen tehtävä Paikallinen SLM (halpa, nopea)
Vaativa monivaiheinen päättely ei-herkällä datalla Pilvimalli
Kaikki sähkökatkon aikana Paikallinen SLM (sujuva vikaantuminen)

Tämä peilaa mallin reititystä Oppitunnista 16 — paitsi että yksi “malleista” on nyt oma koneesi. Vankka rakenne palaa paikalliseen, kun pilvi ei ole käytettävissä, jolloin agentti heikkenee laadullisesti eikä kaadu kokonaan.

flowchart LR
    Q[Pyyntö] --> S{Herkkä tai offline?}
    S -->|kyllä| L[Paikallinen SLM]
    S -->|ei| C{Tarvitseeko syvää päättelyä?}
    C -->|ei| L
    C -->|kyllä| Cloud[Pilvimalli]
    L --> Out[Vastaus]
    Cloud --> Out

Käytännön harjoitus: Paikallinen insinöörin avustaja

Avaa code_samples/17-local-agent-foundry-local.ipynb ja käy se läpi. Rakennat paikallisen insinöörin avustajan, joka toimii kokonaan työasemallasi ja voi:

  1. Kutsua työkaluja — Qwen-funktiokutsujen kautta Foundry Localin välityksellä.
  2. Tehdä paikallisia tiedostotoimia — listata ja lukea tiedostoja projektihakemistossa.
  3. Analysoida koodia — raportoida perustason mittarit lähdetiedostosta.
  4. Etsiä dokumentaatiosta — paikallinen RAG dokumenttihakemistolle Chroman avulla.
  5. Käyttää MCP:tä — yhdistää paikalliseen MCP-palvelimeen (hyväksyen tyylikkään ohituksen, jos palvelin ei ole konfiguroitu).

Pilvijohdannaisia ei käytetä missään vaiheessa.

Läpi kulku

Avustaja yhdistyy Foundry Localiin OpenAI-yhteensopivan päätepisteen kautta, joten agenttikoodi näyttää lähes yhtä hyvältä kuin pilvioppitunneilla — vain asiakas muuttuu:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Foundry Local löytää/lataa mallin ja antaa meille paikallisen päätepisteen.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key on paikallinen paikkamerkki

Työkalut ovat tavallisia Python-funktioita, jotka on rajattu projektihakemistoon:

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

Huomaa hiekkalaatikkotarkistus — vaikka paikallisesti, työkalu, joka lukee mielivaltaisia polkuja, on riski. Muistikirja pitää kaikki työkalut rajattuina yhteen projektiin.

Tietämystesti

Testaa ymmärryksesi ennen tehtäviin siirtymistä.

1. Anna kaksi konkreettista syytä ajaa agentti paikallisesti pilven sijaan.

Vastaus Kaksi mistä tahansa: **yksityisyys** (koodi ja data eivät koskaan poistu koneelta), **kustannukset** (ei laskutusta per token) ja **offline-toimivuus** (toimii ilman verkkoa — lentokoneessa, turvallisessa tilassa tai sähkökatkon aikana). Yksityisyyssyynä on usein sääntely, joka kieltää datan lähettämisen laitteen ulkopuolelle.

2. Mikä on suositeltu työnjako SLM:n ja sen työkalujen välillä paikallisessa agentissa, ja miksi?

Vastaus Anna SLM:n **orkestroida** (päätellä, mitä työkalua kutsutaan ja millä argumenteilla) ja anna **työkalujen tehdä raskas työ** (lukeminen, dokumenttien hakeminen, tulosten laskeminen). SLM:t ovat hyviä rajoitettuihin päätöksiin kuten työkalun valintaan, mutta heikompia laajassa tiedossa ja pitkissä monivaiheisissa päättelyissä, joten työkalujen käyttäminen hyödyntää niiden vahvuuksia.

3. Mikä tekee mahdolliseksi pilviagenttikoodin uudelleenkäytön Foundry Localin kanssa?

Vastaus Foundry Local tarjoaa **OpenAI-yhteensopivan HTTP-päätepisteen**. OpenAI SDK ja Agent Frameworkin OpenAI-asiakas toimivat sen kanssa vaihtamalla vain `base_url`:n (ja käyttämällä paikallista paikantimen API-avainta). Muuten agenttikoodi pysyy samana.

4. Miksi käytämme nimenomaan Qwen-funktiokutsumallia eikä mitä tahansa SLM:ää?

Vastaus Koska agentin täytyy tuottaa luotettavia ja hyvin muodostettuja **työkalukutsuja**. Monet SLM:t voivat keskustella, mutta tuottavat virheellisiä tai epäjohdonmukaisia työkalukutsurakenteita. Qwen-mallit on koulutettu funktiokutsuihin ja ne tuottavat johdonmukaisia työkalukutsuja, mikä muuttaa paikallisen keskustelumallin toimivaksi paikalliseksi agentiksi.

5. Mitkä komponentit paikallisessa RAG-putkessa toimivat koneella?

Vastaus Kaikki: upotusmalli, vektoripohjainen tietokanta (Chroma, levyllä), hakuvaihe ja SLM. Dokumentit upotetaan paikallisesti, tallennetaan paikallisesti, haetaan paikallisesti ja niistä päättelyä tekee paikallinen malli — mikään komponentti ei kosketa pilveä.

6. Jos paikallinen MCP-palvelin toimii koneellasi, tekeekö se siitä automaattisesti turvallisen? Mitä varotoimia kannattaa silti noudattaa?

Vastaus Ei. Paikallinen MCP-palvelin toimii käyttäjäoikeuksillasi, joten se voi käsitellä mitä sinä voit. Rajoita sen oikeudet tarvittavaan (esim. yksi projektihakemisto, ei koko kotihakemistoasi) ja käsittele sen tuottamat tiedot syötteinä, jotka validoit ennen käyttöä.

7. Kuvaile järkevä hybridireitityssääntö, joka sisältää paikallisen mallin.

Vastaus Reititä herkkä tai offline-pyyntö paikalliselle SLM:lle; reititä yksinkertaiset rajalliset tehtävät paikalliselle SLM:lle nopeuden ja kustannusten vuoksi; reititä vaikea monivaiheinen päättely ei-herkällä datalla pilvimallille; ja palaa paikalliseen SLM:ään jos pilvi ei ole käytettävissä, jolloin agentti heikkenee tyylikkäästi eikä epäonnistu kokonaan. Tämä on mallin reititystä (Oppitunti 16), jossa paikallinen kone on yksi malleista.

8. Mikä on realistinen vähimmäismuisti paikallisen agentin ajamiseen tässä oppitunnissa, ja mitä enemmän muisti tarjoaa?

Vastaus Noin **8 GB** on realistinen minimi; 16 GB+ on mukava. Enemmän muistia mahdollistaa suurempien, kyvykkäämpien mallien ajon ja enemmän kontekstin muistamisen. GPU tai NPU nopeuttaa päättelyä mutta ei ole pakollinen — Foundry Local valitsee CPU-buildin, jos kiihdytintä ei ole saatavilla.

Tehtävä

Laajenna paikallista insinöörin assistenttia paikalliseksi dokumenttien tarkastajaksi pienelle valitsemallesi projektille (voit käyttää tätä repo-kansion oppitunnin kansiota, jos haluat).

Palautuksesi tulisi:

  1. Indeksoida oikea dokumentti-/koodihakemisto Chromaan (vähintään viisi tiedostoa).

  2. Lisätä find_todos-työkalu, joka skannaa projektista TODO/FIXME-kommentit ja palauttaa ne tiedoston ja rivinumeron kanssa — säilyttäen saman hiekkalaatikkotarkistuksen kuin read_file.

  3. Kysy agentilta kolme kysymystä, jotka pakottavat sen yhdistämään työkaluja: yksi puhdas RAG-kysymys, yksi joka vaatii tietyn tiedoston lukemista, ja yksi joka vaatii TODO-kohteiden löytämistä.
  4. Mittaa se: aikata kolme vastausta ja kirjaa ne muotoilusoluun. Kommentoi, onko viive hyväksyttävä suunnitellussa työnkulussasi.

Kirjoita sitten lyhyt kappale siitä, mitä siirtäisit pilveen ja mitä pitäisit paikallisena tälle arvioijalle ja miksi. Sinua arvioidaan sen perusteella, onko paikalliset komponentit kytketty oikein ja ovatko hybridiratkaisusi järkeviä — ei mallin laadun perusteella.

Yhteenveto

Tässä oppitunnissa rakensit agentin, joka toimii kokonaan omalla koneellasi:

Tämä päättää käyttöönoton: Oppitunti 16 suurensi agentteja Microsoft Foundryyn, ja tämä oppitunti pienensi niitä yhdelle työasemalle. Seuraava oppitunti käsittelee käyttöönotettujen agenttien turvallisuuden varmistamista.

Lisäresurssit

Edellinen oppitunti

Skalautuvien agenttien käyttöönotto

Seuraava oppitunti

AI-agenttien turvallisuuden varmistaminen

Vastuuvapauslauseke: Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua Co-op Translator. Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista.

This site is open source. Improve this page.