ai-agents-for-beginners

Nastavitev tečaja

Uvod

Ta lekcija bo pokrivala, kako zagnati primerke kode tega tečaja.

Pridružite se drugim učencem in poiščite pomoč

Preden začnete s kloniranjem vašega repozitorija, se pridružite kanalu AI Agents For Beginners na Discordu, da dobite pomoč pri nastavitvi, odgovore na vprašanja o tečaju ali se povežete z drugimi učenci.

Klonirajte ali forknite ta repozitorij

Za začetek prosim klonirajte ali forknite GitHub repozitorij. S tem boste ustvarili svojo različico gradiva tečaja, da lahko zaženete, testirate in prilagajate kodo!

To lahko naredite tako, da kliknete na povezavo za fork repozitorija

Sedaj bi morali imeti svojo lastno forkano različico tega tečaja na naslednji povezavi:

Forked Repo

Plitvi klon (priporočeno za delavnico / Codespaces)

Celoten repozitorij je lahko velik (~3 GB), če prenesete celotno zgodovino in vse datoteke. Če obiskujete samo delavnico ali potrebujete le nekaj map lekcij, plitvi klon (ali redki klon) prepreči večino prenosa z omejitvijo zgodovine in/ali izpustitvijo vsebin.

Hitri plitvi klon — minimalna zgodovina, vse datoteke

Zamenjajte <your-username> v spodnjih ukazih z URL vaše fork različice (ali zgornji URL če raje).

Za kloniranje samo zadnje zgodovine ukazov (majhen prenos):

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

Za kloniranje določene veje:

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

Delni (redki) klon — minimalni blobi + samo izbrane mape

To uporablja delni klon in sparse-checkout (zahteva Git 2.25+ in priporočen sodoben Git z delnim klonom):

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

Pojdite v mapo repozitorija:

cd ai-agents-for-beginners

Nato določite, katere mape želite (spodnjega primera prikazuje dve mapi):

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

Po kloniranju in preverjanju datotek, če potrebujete samo datoteke in želite sprostiti prostor (brez git zgodovine), prosim izbrišite metapodatke repozitorija (💀nepopravljivo — izgubili boste vse funkcije Git-a: brez commit-ov, pull-ov, push-ov ali dostopa do zgodovine).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Uporaba GitHub Codespaces (priporočeno za izogibanje velikim lokalnim prenosom)

Nasveti

Zagon kode

Ta tečaj ponuja serijo Jupyter Notebook-ov, ki jih lahko zaženete za praktične izkušnje z gradnjo AI agentov.

Primeri kode uporabljajo Microsoft Agent Framework (MAF) z AzureAIProjectAgentProvider, ki povezuje z Azure AI Agent Service V2 (Responses API) preko Microsoft Foundry.

Vsi Python notebok-i imajo oznako *-python-agent-framework.ipynb.

Zahteve

V korenu tega repozitorija smo vključili requirements.txt datoteko, ki vsebuje vse potrebne Python pakete za zagon primerov kode.

Namestite jih z naslednjim ukazom v terminalu v korenu repozitorija:

pip install -r requirements.txt

Priporočamo, da ustvarite Python virtualno okolje, da se izognete morebitnim konfliktom in težavam.

Nastavitev VSCode

Prepričajte se, da uporabljate pravo različico Pythona v VSCode.

image

Nastavitev Microsoft Foundry in Azure AI Agent Service

Korak 1: Ustvarite Microsoft Foundry projekt

Za zagon notebookov potrebujete Azure AI Foundry hub in projekt z nameščenim modelom.

  1. Obiščite ai.azure.com in se prijavite z Azure računom.
  2. Ustvarite hub (ali uporabite obstoječega). Glejte: Pregled virov hub.
  3. Znotraj huba ustvarite projekt.
  4. Namestite model (npr. gpt-4o) iz Models + Endpoints → Deploy model.

Korak 2: Pridobite URL končne točke projekta in ime nameščenega modela

Iz vašega projekta v Microsoft Foundry portalu:

Project Connection String

Korak 3: Prijava v Azure z az login

Vsi notebook-i uporabljajo AzureCliCredential za avtentikacijo — brez upravljanja API ključev. To zahteva prijavo prek Azure CLI.

  1. Namestite Azure CLI če ga še nimate: aka.ms/installazurecli

  2. Prijavite se z ukazom:

     az login

    Ali če ste v oddaljenem/Codespace okolju brez brskalnika:

     az login --use-device-code

  3. Izberite naročnino če vas vpraša — izberite tisto, ki vsebuje vaš Foundry projekt.

  4. Preverite svojo prijavo:

     az account show

Zakaj az login? Notebook-i se avtenticirajo z AzureCliCredential iz paketa azure-identity. To pomeni, da vaša Azure CLI seja zagotavlja poverilnice — brez API ključev ali skrivnosti v .env datoteki. To je najboljša praksa za varnost.

Korak 4: Ustvarite vašo .env datoteko

Kopirajte primer datoteke:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Odprite .env in vnesite ti dve vrednosti:

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
Spremenljivka Kje jo najti
AZURE_AI_PROJECT_ENDPOINT Foundry portal → vaš projekt → stran Overview
AZURE_AI_MODEL_DEPLOYMENT_NAME Foundry portal → Models + Endpoints → ime vašega nameščenega modela

To je to za večino lekcij! Notebook-i se bodo samodejno avtenticirali preko vaše az login seje.

Korak 5: Namestite Python odvisnosti

pip install -r requirements.txt

Priporočamo, da to izvedete v virtualnem okolju, ki ste ga ustvarili prej.

Dodatna nastavitev za Lekcijo 5 (Agentic RAG)

Lekcija 5 uporablja Azure AI Search za generiranje na osnovi iskanja. Če nameravate zagnati to lekcijo, dodajte te spremenljivke v vašo .env datoteko:

Spremenljivka Kje jo najti
AZURE_SEARCH_SERVICE_ENDPOINT Azure portal → vaš Azure AI Search vir → Overview → URL
AZURE_SEARCH_API_KEY Azure portal → vaš Azure AI Search vir → Settings → Keys → glavni upravljalski ključ

Dodatna nastavitev za Lekcijo 6 in Lekcijo 8 (GitHub modeli)

Nekaj notebook-ov iz lekcij 6 in 8 uporablja GitHub modele namesto Azure AI Foundry. Če boste zagnali te primere, dodajte te spremenljivke v vašo .env datoteko:

Spremenljivka Kje jo najti
GITHUB_TOKEN GitHub → Settings → Developer settings → Personal access tokens
GITHUB_ENDPOINT Uporabite https://models.inference.ai.azure.com (privzeta vrednost)
GITHUB_MODEL_ID Ime modela za uporabo (npr. gpt-4o-mini)

Alternativni ponudnik: MiniMax (združljiv z OpenAI)

MiniMax ponuja modele z velikim kontekstom (do 204K tokenov) preko API-ja, združljivega z OpenAI. Ker Microsoft Agent Framework OpenAIChatClient deluje z vsakim končnim OpenAI združljivim URL-jem, lahko uporabite MiniMax kot alternativo GitHub modelom ali OpenAI.

Dodajte te spremenljivke v vašo .env datoteko:

Spremenljivka Kje jo najti
MINIMAX_API_KEY MiniMax Platform → API ključi
MINIMAX_BASE_URL Uporabite https://api.minimax.io/v1 (privzeta vrednost)
MINIMAX_MODEL_ID Ime modela za uporabo (npr. MiniMax-M2.7)

Na voljo modeli: MiniMax-M2.7 (priporočeno), MiniMax-M2.7-highspeed (hitrejši odgovori)

Primeri kode, ki uporabljajo OpenAIChatClient (npr. potek rezervacije hotela iz Lekcije 14), bodo samodejno zaznali in uporabili vašo MiniMax konfiguracijo, ko je nastavljen MINIMAX_API_KEY.

Dodatna nastavitev za Lekcijo 8 (Bing Grounding Workflow)

Notebook z odvisnim potekom dela v lekciji 8 uporablja Bing grounding preko Azure AI Foundry. Če boste zagnali ta primer, dodajte to spremenljivko v vašo .env datoteko:

Spremenljivka Kje jo najti
BING_CONNECTION_ID Azure AI Foundry portal → vaš projekt → Management → Connected resources → vaša Bing povezava → kopirajte ID povezave

Reševanje težav

Napake pri preverjanju SSL certifikata na macOS

Če uporabljate macOS in naletite na napako, kot je:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

To je znana težava pri Pythonu na macOS, kjer sistemski SSL certifikati niso samodejno zaupani. Poskusite naslednje rešitve v tem vrstnem redu:

Možnost 1: Zaženite Pythonovega namestitvenega skripta za certifikate (priporočeno)

# Zamenjajte 3.XX z vašo nameščeno različico Pythona (npr. 3.12 ali 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Možnost 2: Uporabite connection_verify=False v vašem notebooku (samo za GitHub modele)

V Lekciji 6 notebook-u (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) je že vključen zakomentiran obhodni ukrep. Odkomentirajte connection_verify=False ob ustvarjanju klienta:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Onemogoči preverjanje SSL, če naletiš na napake s certifikatom
)

⚠️ Opozorilo: Onemogočanje SSL preverjanja (connection_verify=False) zmanjša varnost z izpustitvijo validacije certifikatov. To uporabi le kot začasno rešitev v razvojnih okoljih, nikoli v produkciji.

Možnost 3: Namestite in uporabite truststore

pip install truststore

Nato dodajte naslednje na začetek vašega notebooka ali skripte pred izvajanjem omrežnih klicev:

import truststore
truststore.inject_into_ssl()

Se zataknili?

Če imate kakršne koli težave z zagonom te nastavitve, se pridružite našemu Azure AI Community Discordu ali ustvarite zadevo.

Naslednja lekcija

Sedaj ste pripravljeni za zagon kode za ta tečaj. Veselo učenje o svetu AI agentov!

Uvod v AI agente in primere uporabe agentov

Omejitev odgovornosti:
Ta dokument je bil preveden z uporabo storitve umetne inteligence za prevajanje Co-op Translator. Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali nepravilnosti. Izvirni dokument v njegovem izvirnem jeziku velja za avtoritativni vir. Za ključne informacije priporočamo strokovni človeški prevod. Za morebitne nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda, ne prevzemamo odgovornosti.

This site is open source. Improve this page.