ai-agents-for-beginners

Настройка на курса

Въведение

В този урок ще обясним как да стартирате примерите с код от този курс.

Присъединете се към други обучаеми и получете помощ

Преди да започнете да клонирате вашето хранилище, присъединете се към Discord канал ‘AI Agents For Beginners’ за помощ при настройката, въпроси относно курса или за контакт с други обучаеми.

Клониране или форкване на това хранилище

За да започнете, моля клонирайте или форкнете GitHub хранилището. Това ще създаде ваша собствена версия на материалите от курса, така че да можете да стартирате, тествате и настройвате кода!

Това може да стане чрез кликване на линка към форкнете хранилището

Сега трябва да имате ваша собствена форкната версия на този курс на следния линк:

Форкнато хранилище

Плитко клониране (препоръчително за работилници / Codespaces)

Пълното хранилище може да бъде голямо (~3 GB), когато изтеглите цялата история и всички файлове. Ако присъствате само на работилницата или ви трябват само няколко папки от уроците, плитко клониране (или sparse clone) избягва повечето от това изтегляне чрез съкращаване на историята и/или пропускане на blob-ове.

Бързо плитко клониране — минимална история, всички файлове

Заменете <your-username> в командите по-долу с URL-а на вашия форк (или с upstream URL-а, ако предпочитате).

За да клонирате само последната история на комитите (малко сваляне):

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

За да клонирате конкретен клон:

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

Частично (sparse) клониране — минимални blob-ове + само избрани папки

Това използва partial clone и sparse-checkout (изисква Git 2.25+ и се препоръчва модерна версия на Git с поддръжка за partial clone):

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

Отидете в директорията на хранилището:

cd ai-agents-for-beginners

След това посочете кои папки искате (примерът по-долу показва две папки):

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

След клониране и проверка на файловете, ако ви трябват само файловете и искате да освободите пространство (без git история), моля изтрийте метаданните на хранилището (💀необратимо — ще загубите цялата Git функционалност: няма комити, pulls, pushes или достъп до историята).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Използване на GitHub Codespaces (препоръчително за избягване на локални големи изтегляния)

Съвети

Изпълнение на кода

Този курс предлага серия Jupyter Notebook-и, които можете да изпълнявате, за да получите практическо изживяване при изграждането на AI агенти.

Примерите с код използват Microsoft Agent Framework (MAF) с AzureAIProjectAgentProvider, който се свързва с Azure AI Agent Service V2 (Responses API) чрез Microsoft Foundry.

Всички Python бележници са маркирани като *-python-agent-framework.ipynb.

Изисквания

В корена на това хранилище сме включили файл requirements.txt, който съдържа всички необходими Python пакети за стартиране на примерите с код.

Можете да ги инсталирате, като изпълните следната команда в терминала в корена на хранилището:

pip install -r requirements.txt

Препоръчваме да създадете Python виртуална среда, за да избегнете конфликти и проблеми.

Настройка на VSCode

Уверете се, че използвате правилната версия на Python в VSCode.

изображение

Настройка на Microsoft Foundry и Azure AI Agent Service

Стъпка 1: Създайте проект в Microsoft Foundry

Трябва ви Azure AI Foundry hub и project с разгърнат модел, за да стартирате бележниците.

  1. Отидете на ai.azure.com и влезте с вашия Azure акаунт.
  2. Създайте hub (или използвайте вече съществуващ). Вижте: Hub resources overview.
  3. Вътре в hub-а създайте project.
  4. Разгърнете модел (напр. gpt-4o) от Models + Endpoints → Deploy model.

Стъпка 2: Вземете крайния адрес на проекта и името на разгръщане на модела

От вашия проект в портала Microsoft Foundry:

Връзка към проекта

Стъпка 3: Впишете се в Azure с az login

Всички бележници използват AzureCliCredential за автентикация — няма API ключове за управление. Това изисква да сте вписани чрез Azure CLI.

  1. Инсталирайте Azure CLI ако все още не сте: aka.ms/installazurecli

  2. Впишете се като изпълните:

     az login

    Или ако сте в отдалечена/Codespace среда без браузър:

     az login --use-device-code

  3. Изберете вашия subscription ако бъдете подканени — изберете този, който съдържа Foundry проекта ви.

  4. Проверете дали сте вписани:

     az account show

Защо az login? Бележниците се удостоверяват, използвайки AzureCliCredential от пакета azure-identity. Това означава, че вашата Azure CLI сесия предоставя удостоверенията — няма API ключове или тайни във вашия .env файл. Това е добра практика за сигурност.

Стъпка 4: Създайте вашия .env файл

Копирайте примерния файл:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Отворете .env и попълнете тези две стойности:

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
Variable Къде да го намерите
AZURE_AI_PROJECT_ENDPOINT Foundry портал → вашият проект → страница Overview
AZURE_AI_MODEL_DEPLOYMENT_NAME Foundry портал → Models + Endpoints → името на разгърнатия модел

Това е всичко за повечето уроци! Бележниците ще се удостоверят автоматично чрез вашата az login сесия.

Стъпка 5: Инсталирайте Python зависимости

pip install -r requirements.txt

Препоръчваме да изпълните това вътре във виртуалната среда, която създадохте по-рано.

Допълнителна настройка за Урок 5 (Agentic RAG)

Урок 5 използва Azure AI Search за retrieval-augmented generation. Ако планирате да изпълните този урок, добавете тези променливи във вашия .env файл:

Variable Къде да го намерите
AZURE_SEARCH_SERVICE_ENDPOINT Azure портал → вашият Azure AI Search ресурс → Overview → URL
AZURE_SEARCH_API_KEY Azure портал → вашият Azure AI Search ресурс → Settings → Keys → primary admin key

Допълнителна настройка за Урок 6 и Урок 8 (GitHub Models)

Някои бележници в уроците 6 и 8 използват GitHub Models вместо Azure AI Foundry. Ако планирате да стартирате тези примери, добавете тези променливи във вашия .env файл:

Variable Къде да го намерите
GITHUB_TOKEN GitHub → Settings → Developer settings → Personal access tokens
GITHUB_ENDPOINT Използвайте https://models.inference.ai.azure.com (по подразбиране)
GITHUB_MODEL_ID Името на модела за използване (напр. gpt-4o-mini)

Допълнителна настройка за Урок 8 (Bing Grounding Workflow)

Условният workflow бележник в урок 8 използва Bing grounding чрез Azure AI Foundry. Ако планирате да изпълните този пример, добавете тази променлива във вашия .env файл:

Variable Къде да го намерите
BING_CONNECTION_ID Azure AI Foundry портал → вашият проект → Management → Connected resources → вашата Bing връзка → копирайте connection ID

Отстраняване на неизправности

Грешки при проверка на SSL сертификатите на macOS

Ако сте на macOS и срещнете грешка като:

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

Това е известен проблем с Python на macOS, при който системните SSL сертификати не се доверяват автоматично. Опитайте следните решения в този ред:

Опция 1: Стартирайте Install Certificates скрипта на Python (препоръчително)

# Заменете 3.XX с инсталираната версия на Python (например 3.12 или 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Опция 2: Използвайте connection_verify=False в бележника си (само за бележници с GitHub Models)

В бележника за Урок 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) вече е включено закоментирано решение. Разкоментирайте connection_verify=False при създаване на клиента:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Деактивирайте проверката на SSL, ако срещнете грешки с сертификата
)

⚠️ Warning: Деактивирането на проверката на SSL (connection_verify=False) намалява сигурността, като прескача валидацията на сертификатите. Използвайте това само като временна мярка в развойна среда, никога в продукция.

Опция 3: Инсталирайте и използвайте truststore

pip install truststore

След това добавете следното в горната част на вашия бележник или скрипт преди да правите каквито и да е мрежови повиквания:

import truststore
truststore.inject_into_ssl()

Закъсали ли сте някъде?

Ако имате проблеми при изпълнението на тази настройка, присъединете се към нашия Discord общността на Azure AI или създайте issue.

Следващ урок

Вече сте готови да стартирате кода за този курс. Приятно учене и откриване на света на AI агентите!

Въведение в AI агентите и случаи на използване на агенти

Отказ от отговорност: Този документ е преведен с помощта на AI преводаческа услуга Co-op Translator. Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на езика, на който е написан, трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален превод, извършен от човешки преводач. Не носим отговорност за каквито и да е недоразумения или погрешни тълкувания, произтичащи от използването на този превод.

This site is open source. Improve this page.