ai-agents-for-beginners

Kurssin asennus

Johdanto

Tässä osiossa käsitellään, miten kurssin koodiesimerkkejä suoritetaan.

Liity muiden oppijoiden joukkoon ja pyydä apua

Ennen kuin alat kloonata reposi, liity AI Agents For Beginners Discord-kanavalle saadaksesi apua asennukseen, vastauksia kurssia koskeviin kysymyksiin tai yhteyden muihin oppijoihin.

Kloonaa tai haarauta tämä repo

Aloittaaksesi, kloonaa tai haarauta GitHub-repositorio. Tämä luo oman version kurssimateriaalista, jotta voit suorittaa, testata ja muokata koodia!

Tämä onnistuu klikkaamalla linkkiä haara repo

Sinulla pitäisi nyt olla haarautettu versio tästä kurssista seuraavassa linkissä:

Pintakloonaus (suositeltu työpajaa / Codespacesia varten)

Koko repositorio voi olla suuri (~3 GB), kun lataat koko historian ja kaikki tiedostot. Jos osallistut vain työpajaan tai tarvitset vain muutaman oppituntikansion, pintakloonaus (tai osittainen kloonaus) välttää suurimman osan latauksesta lyhentämällä historiaa ja/tai ohittamalla tiedostot.

Nopea pintakloonaus — minimaalinen historia, kaikki tiedostot

Korvaa <your-username> alla olevissa komennoissa haarautuksesi URL-osoitteella (tai alkuperäisellä URL-osoitteella, jos haluat).

Kloonataksesi vain viimeisimmän commit-historian (pieni lataus):

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

Kloonataksesi tietyn haaran:

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

Osittainen (sparse) kloonaus — minimaaliset tiedostot + vain valitut kansiot

Tämä käyttää osittaista kloonausta ja sparse-checkoutia (vaatii Git 2.25+ ja suositellaan modernia Git-versiota osittaisen kloonauksen tuella):

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

Siirry repo-kansioon:

cd ai-agents-for-beginners

Määritä sitten, mitkä kansiot haluat (esimerkki alla näyttää kaksi kansiota):

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

Kun olet kloonannut ja varmistanut tiedostot, jos tarvitset vain tiedostoja ja haluat vapauttaa tilaa (ei git-historiaa), poista repositorion metadata (💀peruuttamaton — menetät kaikki Git-toiminnot: ei committeja, hakuja, pushauksia tai historian käyttöä).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

GitHub Codespacesin käyttö (suositeltu välttämään paikallisia suuria latauksia)

• Luo uusi Codespace tälle repolle GitHub-käyttöliittymän kautta.

• Uuden Codespacen terminaalissa suorita yksi yllä olevista pintakloonaus-/osittaiskloonaus-komennoista tuodaksesi vain tarvitsemasi oppituntikansiot Codespace-työtilaan.
• Valinnainen: kloonauksen jälkeen Codespacesissa poista .git vapauttaaksesi lisätilaa (katso poistokomennot yllä).
• Huomio: Jos haluat avata repositorion suoraan Codespacesissa (ilman ylimääräistä kloonausta), huomaa, että Codespaces rakentaa devcontainer-ympäristön ja saattaa silti varata enemmän kuin tarvitset. Kloonaamalla pintakopion uudessa Codespacessa saat enemmän hallintaa levytilan käytöstä.

Vinkkejä

• Korvaa aina kloonaus-URL haarautuksellasi, jos haluat muokata/commitata.
• Jos myöhemmin tarvitset lisää historiaa tai tiedostoja, voit hakea ne tai säätää sparse-checkoutia sisällyttämään lisää kansioita.

Koodin suorittaminen

Tämä kurssi tarjoaa sarjan Jupyter Notebooks -tiedostoja, joita voit suorittaa saadaksesi käytännön kokemusta AI-agenttien rakentamisesta.

Koodiesimerkit käyttävät joko:

Vaatii GitHub-tilin - Ilmainen:

1) Semantic Kernel Agent Framework + GitHub Models Marketplace. Merkitty nimellä (semantic-kernel.ipynb) 2) AutoGen Framework + GitHub Models Marketplace. Merkitty nimellä (autogen.ipynb)

Vaatii Azure-tilauksen: 3) Azure AI Foundry + Azure AI Agent Service. Merkitty nimellä (azureaiagent.ipynb)

Kannustamme sinua kokeilemaan kaikkia kolmea esimerkkityyppiä nähdäksesi, mikä toimii parhaiten sinulle.

Valitsemasi vaihtoehto määrittää, mitkä asennusvaiheet sinun tulee suorittaa alla:

Vaatimukset

• Python 3.12+

  • NOTE: Jos sinulla ei ole Python3.12 asennettuna, varmista, että asennat sen. Luo sitten venv käyttämällä python3.12 varmistaaksesi, että oikeat versiot asennetaan requirements.txt-tiedostosta.

    Esimerkki

    Luo Python venv-hakemisto:

    python -m venv venv
    

    Aktivoi sitten venv-ympäristö:

    # zsh/bash
    source venv/bin/activate
    

    # Command Prompt for Windows
    venv\Scripts\activate
    

• .NET 10+: Näytekoodien käyttöön .NET:llä, varmista, että asennat .NET 10 SDK tai uudemman. Tarkista sitten asennettu .NET SDK -versio:

    dotnet --list-sdks
  

• GitHub-tili - Pääsy GitHub Models Marketplaceen
• Azure-tilaus - Pääsy Azure AI Foundryyn
• Azure AI Foundry -tili - Pääsy Azure AI Agent Serviceen

Olemme sisällyttäneet requirements.txt-tiedoston tämän repositorion juureen, joka sisältää kaikki tarvittavat Python-paketit koodiesimerkkien suorittamiseen.

Voit asentaa ne suorittamalla seuraavan komennon terminaalissa repositorion juuressa:

pip install -r requirements.txt

Suosittelemme Python-virtuaaliympäristön luomista välttääksemme konflikteja ja ongelmia.

VSCode-asennus

Varmista, että käytät oikeaa Python-versiota VSCode:ssa.

Näytekoodien asennus GitHub Models -käytössä

Vaihe 1: Hanki GitHubin henkilökohtainen käyttöoikeustoken (PAT)

Tämä kurssi hyödyntää GitHub Models Marketplacea, joka tarjoaa ilmaisen pääsyn suuriin kielimalleihin (LLM), joita käytät AI-agenttien rakentamiseen.

GitHub Models -käyttöön sinun tulee luoda GitHubin henkilökohtainen käyttöoikeustoken.

Tämä onnistuu siirtymällä henkilökohtaisten käyttöoikeustokenien asetuksiin GitHub-tililläsi.

Noudata vähimmäisoikeuksien periaatetta tokenia luodessasi. Tämä tarkoittaa, että sinun tulisi antaa tokenille vain ne oikeudet, joita se tarvitsee kurssin koodiesimerkkien suorittamiseen.

1. Valitse Fine-grained tokens -vaihtoehto näytön vasemmasta reunasta siirtymällä Kehittäjäasetuksiin.

   

   Valitse sitten Generate new token.

   

2. Anna tokenille kuvaava nimi, joka heijastaa sen tarkoitusta, jotta se on helppo tunnistaa myöhemmin.

   🔐 Tokenin keston suositus

   Suositeltu kesto: 30 päivää Turvallisemman käytännön vuoksi voit valita lyhyemmän ajan—esimerkiksi 7 päivää 🛡️ Tämä on hyvä tapa asettaa henkilökohtainen tavoite ja suorittaa kurssi, kun oppimismomentum on korkea 🚀.

   

3. Rajoita tokenin käyttöoikeus haarautukseesi tästä repositoriosta.

   

4. Rajoita tokenin käyttöoikeudet: Valitse Permissions-kohdassa Account-välilehti ja klikkaa “+ Add permissions” -painiketta. Näyttöön tulee pudotusvalikko. Etsi Models ja valitse sen ruutu.

   

5. Varmista tarvittavat käyttöoikeudet ennen tokenin luomista.

6. Ennen tokenin luomista varmista, että olet valmis tallentamaan tokenin turvalliseen paikkaan, kuten salasananhallintajärjestelmään, sillä sitä ei näytetä uudelleen luomisen jälkeen.

Kopioi juuri luomasi token. Lisää tämä nyt kurssin mukana tulevaan .env-tiedostoon.

Vaihe 2: Luo .env-tiedostosi

Luo .env-tiedosto suorittamalla seuraava komento terminaalissasi.

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Tämä kopioi esimerkkitiedoston ja luo .env-tiedoston hakemistoosi, jossa täytät ympäristömuuttujien arvot.

Kopioidulla tokenilla avaa .env-tiedosto suosikkitekstieditorissasi ja liitä token GITHUB_TOKEN-kenttään.

Sinun pitäisi nyt pystyä suorittamaan kurssin koodiesimerkit.

Näytekoodien asennus Azure AI Foundry- ja Azure AI Agent Service -käytössä

Vaihe 1: Hanki Azure-projektisi päätepiste

Seuraa ohjeita hubin ja projektin luomiseksi Azure AI Foundryssa täältä: Hub-resurssien yleiskatsaus

Kun olet luonut projektisi, sinun tulee hankkia projektisi yhteysmerkkijono.

Tämä onnistuu siirtymällä projektisi Yleiskatsaus-sivulle Azure AI Foundry -portaalissa.

Vaihe 2: Luo .env-tiedostosi

Luo .env-tiedosto suorittamalla seuraava komento terminaalissasi.

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Tämä kopioi esimerkkitiedoston ja luo .env-tiedoston hakemistoosi, jossa täytät ympäristömuuttujien arvot.

Kopioidulla tokenilla avaa .env-tiedosto suosikkitekstieditorissasi ja liitä token PROJECT_ENDPOINT-kenttään.

Vaihe 3: Kirjaudu Azureen

Turvallisuuskäytännön mukaisesti käytämme avaimetonta autentikointia kirjautuaksemme Azure OpenAI:hin Microsoft Entra ID:n avulla.

Avaa seuraavaksi terminaali ja suorita az login --use-device-code kirjautuaksesi Azure-tiliisi.

Kun olet kirjautunut sisään, valitse tilauksesi terminaalissa.

Lisäympäristömuuttujat - Azure Search ja Azure OpenAI

Agentic RAG -oppitunnilla - Oppitunti 5 - on esimerkkejä, jotka käyttävät Azure Searchia ja Azure OpenAI:ta.

Jos haluat suorittaa nämä esimerkit, sinun tulee lisätä seuraavat ympäristömuuttujat .env-tiedostoosi:

Yleiskatsaus-sivu (Projekti)

• AZURE_SUBSCRIPTION_ID - Tarkista Projektin tiedot projektisi Yleiskatsaus-sivulla.

• AZURE_AI_PROJECT_NAME - Katso projektisi Yleiskatsaus-sivun yläosaa.

• AZURE_OPENAI_SERVICE - Löydät tämän Sisältyvät ominaisuudet-välilehdeltä Azure OpenAI Service kohdasta Yleiskatsaus.

Hallintakeskus

• AZURE_OPENAI_RESOURCE_GROUP - Siirry Projektin ominaisuudet kohtaan Yleiskatsaus-sivulla Hallintakeskuksessa.

• GLOBAL_LLM_SERVICE - Liitetyt resurssit-kohdassa löydät Azure AI Services-yhteyden nimen. Jos ei ole listattu, tarkista Azure-portaali resurssiryhmäsi alta AI Services -resurssin nimi.

Mallit + päätepisteet -sivu

• AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME - Valitse upotusmallisi (esim. text-embedding-ada-002) ja huomioi Deployment name mallin tiedoista.

• AZURE_OPENAI_CHAT_DEPLOYMENT_NAME - Valitse chat-mallisi (esim. gpt-4o-mini) ja huomioi Deployment name mallin tiedoista.

Azure-portaali

• AZURE_OPENAI_ENDPOINT - Etsi Azure AI services, klikkaa sitä, siirry Resurssien hallinta, Avaimet ja päätepiste, selaa alas “Azure OpenAI endpoints” ja kopioi se, jossa lukee “Language APIs”.

• AZURE_OPENAI_API_KEY - Samalta näytöltä kopioi AVAIN 1 tai AVAIN 2.

• AZURE_SEARCH_SERVICE_ENDPOINT - Etsi Azure AI Search-resurssisi, klikkaa sitä ja katso Yleiskatsaus.

• AZURE_SEARCH_API_KEY - Siirry sitten Asetukset ja sitten Avaimet kopioidaksesi ensisijaisen tai toissijaisen hallinta-avaimen.

Ulkoinen verkkosivu

• AZURE_OPENAI_API_VERSION - Käy API-version elinkaari -sivulla kohdassa Latest GA API release.

Avaimeton autentikointi

Sen sijaan, että kovakoodaisimme tunnistetiedot, käytämme avaimetonta yhteyttä Azure OpenAI:n kanssa. Tätä varten tuomme DefaultAzureCredential ja kutsumme myöhemmin DefaultAzureCredential-funktiota saadaksemme tunnisteen.

# Python
from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential

Jäikö jokin epäselväksi?

Jos sinulla on ongelmia tämän asennuksen kanssa, liity Azure AI Community Discordiin tai luo ongelmaraportti.

Seuraava oppitunti

Olet nyt valmis suorittamaan kurssin koodin. Mukavia hetkiä AI-agenttien maailmaan tutustuessa!

Johdatus AI-agentteihin ja agenttien käyttötapauksiin

---

Vastuuvapauslauseke:
Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua Co-op Translator. Vaikka pyrimme tarkkuuteen, huomioithan, että automaattiset käännökset voivat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäisellä kielellä tulisi pitää ensisijaisena lähteenä. Tärkeissä tiedoissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa väärinkäsityksistä tai virhetulkinnoista, jotka johtuvat tämän käännöksen käytöstä.

This site is open source. Improve this page.