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

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

Примечание AI University. Примеры кода в оригинале курса рассчитаны на Azure AI Foundry, Azure OpenAI или GitHub Models. Идеи урока не привязаны к Azure: похожих агентов можно собрать на OpenAI API или другом провайдере, но названия классов, параметры и настройка подключения будут отличаться, сверяйтесь с документацией выбранного фреймворка.

Введение

В этом уроке вы узнаете, как запускать примеры кода этого курса.

Присоединяйтесь к другим учащимся и получайте помощь

Прежде чем клонировать репозиторий, присоединитесь к Discord-каналу AI Agents For Beginners, чтобы получить помощь с настройкой, задать вопросы по курсу или связаться с другими учащимися.

Клонируйте или форкните этот репозиторий

Для начала, пожалуйста, клонируйте или форкните репозиторий GitHub. Это позволит создать вашу собственную версию материалов курса, чтобы вы могли запускать, тестировать и настраивать код.

Это можно сделать, перейдя по ссылке, чтобы форкнуть репозиторий.

Теперь у вас должна быть собственная форкнутая версия этого курса по следующей ссылке:

Поверхностное клонирование (рекомендуется для воркшопов / Codespaces)

Полный репозиторий может быть большим (около 3 ГБ), если загружать всю историю и все файлы. Если вы участвуете только в воркшопе или вам нужны лишь несколько папок уроков, поверхностное клонирование (shallow clone) или частичное клонирование (sparse clone) значительно сократит объем загрузки.

Быстрое поверхностное клонирование: минимальная история, все файлы

Замените <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) клонирование: минимальное количество объектов + только выбранные папки

Для этого используется частичное клонирование (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):

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Использование GitHub Codespaces (рекомендуется для избежания больших локальных загрузок)

• Создайте новый Codespace для этого репозитория через пользовательский интерфейс GitHub.

• В терминале только что созданного Codespace выполните одну из команд поверхностного/частичного клонирования, приведённых выше, чтобы загрузить только нужные папки уроков в рабочее пространство Codespace.

• Опционально: после клонирования внутри Codespaces удалите .git, чтобы освободить дополнительное место (см. команды удаления выше).

• Примечание: если вы предпочитаете открывать репозиторий напрямую в Codespaces (без дополнительного клонирования), имейте в виду, что Codespaces создаст среду devcontainer и может выделить больше ресурсов, чем вам нужно.

Советы

• Всегда заменяйте URL клонирования на ваш форк, если вы хотите редактировать/коммитить.
• Если позже вам понадобится больше истории или файлов, вы можете получить их (fetch) или настроить sparse-checkout для включения дополнительных папок.

Запуск кода

Этот курс предлагает серию Jupyter Notebooks, которые вы можете запускать, чтобы получить практический опыт создания ИИ-агентов.

Примеры кода используют Microsoft Agent Framework (MAF) с FoundryChatClient, который подключается к Microsoft Foundry Agent Service V2 (API Responses) через Microsoft Foundry.

Все Python-ноутбуки имеют в названии *-python-agent-framework.ipynb.

Требования

• Python 3.12+

  • ПРИМЕЧАНИЕ: Если у вас не установлен Python 3.12, обязательно установите его. Затем создайте виртуальное окружение (venv) с помощью python3.12, чтобы обеспечить установку правильных версий из файла requirements.txt.

    Пример

    Создайте директорию Python venv:

            ```bash
    

    python -m venv venv

    
    Затем активируйте среду venv для:
    
                ```bash
    # zsh/bash
    source venv/bin/activate
    

            ```dos
    

    Command Prompt for Windows

    venv\Scripts\activate

• .NET 10+: Для примеров кода, использующих .NET, убедитесь, что вы установили .NET 10 SDK или более позднюю версию. Затем проверьте установленную версию .NET SDK:

            ```bash
  

  dotnet --list-sdks

• Azure CLI: Требуется для аутентификации. Установите с aka.ms/installazurecli.

• Подписка Azure: Для доступа к Microsoft Foundry и Microsoft Foundry Agent Service.

• Проект Microsoft Foundry: Проект с развёрнутой моделью (например, gpt-5-mini). См. Шаг 1 ниже.

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

Вы можете установить их, выполнив следующую команду в терминале в корне репозитория:

pip install -r requirements.txt

Мы рекомендуем создать виртуальное окружение Python, чтобы избежать конфликтов и проблем.

Настройка VSCode

Убедитесь, что вы используете правильную версию Python в VSCode.

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

Шаг 1: Создайте проект Microsoft Foundry

Для запуска ноутбуков вам потребуется хаб и проект Microsoft Foundry с развёрнутой моделью.

1. Перейдите на ai.azure.com и войдите в свою учётную запись Azure.
2. Создайте хаб (или используйте существующий). См.: Обзор ресурсов хаба.
3. Внутри хаба создайте проект.
4. Разверните модель (например, gpt-5-mini) через Models + Endpoints → Deploy model.

Шаг 2: Получите URL эндпоинта проекта и имя развёртывания модели

В вашем проекте на портале Microsoft Foundry:

• Project Endpoint: Перейдите на страницу Overview и скопируйте URL эндпоинта.

• Model Deployment Name: Перейдите в Models + Endpoints, выберите развёрнутую модель и запишите Deployment name (например, gpt-5-mini).

Шаг 3: Войдите в Azure с помощью az login

Большинство ноутбуков аутентифицируются через ваш вход в Azure CLI, используя AzureCliCredential или DefaultAzureCredential (обе используют вашу сессию az login) из пакета azure-identity, поэтому они не требуют API-ключей. Некоторые уроки и опциональные интеграции используют API-ключи; проверьте предварительные требования каждого урока на наличие дополнительных переменных среды. Для этого требуется, чтобы вы были авторизованы через Azure CLI.

1. Установите Azure CLI, если вы ещё этого не сделали: aka.ms/installazurecli

2. Войдите, выполнив:

            ```bash
   

   az login

   
   Или, если вы находитесь в удалённой среде/Codespace без браузера:
   
               ```bash
   az login --use-device-code
   

3. Выберите свою подписку, если будет предложено, выберите ту, которая содержит ваш проект Foundry.

4. Проверьте, что вы вошли в систему:

            ```bash
   

   az account show

Зачем az login? Ноутбуки аутентифицируются с помощью AzureCliCredential (или DefaultAzureCredential, которая также использует ваш вход в Azure CLI) из пакета 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-5-mini

На этом настройка большинства уроков завершена! Ноутбуки будут автоматически аутентифицироваться через вашу сессию az login.

Шаг 5: Установите зависимости Python

pip install -r requirements.txt

Мы рекомендуем запускать это внутри виртуального окружения, которое вы создали ранее.

Дополнительная настройка: Azure AI Search (уроки 5 и 16)

Блокноты уроков 5 (Agentic RAG) и 16 запускаются «из коробки» с базой знаний в памяти, никаких дополнительных ресурсов Azure не требуется. Если вы хотите использовать для них реальный индекс Azure AI Search, обратите внимание, что блокнот урока 16 в настоящее время использует аутентификацию по ключу: он переключается с поиска в памяти на Azure AI Search только при установке обеих переменных AZURE_SEARCH_SERVICE_ENDPOINT и AZURE_SEARCH_API_KEY, в противном случае остаётся на поиске в памяти. Таким образом, для запуска его с реальным индексом вы должны установить и ключ администратора. Бесключевая аутентификация с помощью Microsoft Entra ID (RBAC) является рекомендуемым подходом для вашего собственного производственного кода, что соответствует потоку az login, используемому повсеместно в этом курсе.

Приведённые ниже шаги RBAC применимы к примерам из руководства по настройке и к вашему собственному коду. Они не включают бесключевую аутентификацию в блокноте урока 16; урок 16 по-прежнему требует как конечной точки, так и ключа администратора для использования Azure AI Search.

1. Включите управление доступом на основе ролей для вашей службы поиска:

            ```bash
   

   az search service update --name --resource-group --auth-options aadOrApiKey

2. Назначьте себе необходимые роли (создание/загрузка индексов и запросы):

            ```bash
   

   az role assignment create --assignee --role "Search Service Contributor" --scope $(az search service show -g -n --query id -o tsv) az role assignment create --assignee --role "Search Index Data Contributor" --scope $(az search service show -g -n --query id -o tsv)

3. Добавьте конечную точку в ваш файл .env:

Почему бесключевая аутентификация? Ключи администратора предоставляют полный доступ на запись к вашей службе поиска и могут быть скомпрометированы через файлы .env. С RBAC вместо этого используется ваша учётная запись az login, тот же шаблон бесключевой аутентификации Entra ID, который используют блокноты курса (через AzureCliCredential / DefaultAzureCredential). См. Подключение к Azure AI Search с использованием ролей.

Полные примеры создания индексов на Python и .NET см. в руководстве по настройке Azure AI Search.

Дополнительная настройка для уроков, которые напрямую вызывают Azure OpenAI (уроки 6 и 8)

Некоторые блокноты в уроках 6 и 8 напрямую вызывают Azure OpenAI (используя Responses API) вместо того, чтобы проходить через проект Microsoft Foundry. Эти примеры ранее использовали GitHub Models, которые устарели и не поддерживают Responses API. Добавьте эти переменные в ваш файл .env:

Responses API использует стабильную конечную точку /openai/v1/, поэтому api-version не требуется. Войдите с помощью az login, чтобы использовать бесключевую аутентификацию Entra ID.

Альтернативный провайдер: MiniMax (совместимый с OpenAI)

MiniMax предоставляет модели с большим контекстом (до 204K токенов) через API, совместимый с OpenAI. Поскольку OpenAIChatClient Microsoft Agent Framework работает с любой OpenAI-совместимой конечной точкой, вы можете использовать MiniMax в качестве прямой замены для уроков, использующих OpenAIChatClient.

Добавьте эти переменные в ваш файл .env:

Примеры моделей: MiniMax-M3 (рекомендуется), MiniMax-M2.7, MiniMax-M2.7-highspeed (более быстрые ответы). Названия моделей и их доступность могут меняться со временем, а доступ к конкретной модели может зависеть от вашей учётной записи.

Примеры кода, использующие OpenAIChatClient (например, рабочий процесс бронирования отеля в уроке 14), автоматически обнаружат и используют вашу конфигурацию MiniMax, если установлена переменная MINIMAX_API_KEY.

Альтернативный провайдер: Novita AI (совместимый с OpenAI)

Novita AI предоставляет OpenAI-совместимый API для открытых и передовых больших языковых моделей (DeepSeek, Llama, Qwen и другие). Поскольку OpenAIChatClient Microsoft Agent Framework работает с любой OpenAI-совместимой конечной точкой, вы можете использовать Novita AI в качестве прямой замены Azure OpenAI или OpenAI.

Добавьте эти переменные в ваш файл .env:

Примеры моделей: moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-flash-0731. Novita AI также размещает множество других семейств моделей с открытым исходным кодом (Llama, Qwen, GLM и другие). Актуальный список доступных моделей и их идентификаторов см. в библиотеке моделей Novita AI.

Текущие примеры не используют переменные NOVITA_* автоматически. Чтобы использовать Novita AI, передайте эти значения явно при создании OpenAIChatClient в запускаемом вами примере.

Альтернативный провайдер: Foundry Local (запуск моделей на устройстве)

Foundry Local: это легковесная среда выполнения, которая загружает, управляет и обслуживает языковые модели полностью на вашей собственной машине через OpenAI-совместимый API, облако не требуется.

Поскольку OpenAIChatClient Microsoft Agent Framework работает с любой OpenAI-совместимой конечной точкой, Foundry Local является прямой локальной альтернативой Azure OpenAI.

1. Установите Foundry Local

# Windows
winget install Microsoft.FoundryLocal

# macOS
brew install foundrylocal

2. Загрузите и запустите модель (это также запускает локальную службу):

foundry model list          # see available models
foundry model run phi-4-mini

3. Установите Python SDK, используемый для обнаружения локальной конечной точки:

pip install foundry-local-sdk

4. Настройте Microsoft Agent Framework на использование вашей локальной модели:

from foundry_local import FoundryLocalManager
from agent_framework.openai import OpenAIChatClient

# Downloads (if needed) and serves the model locally, then discovers the endpoint/port.
manager = FoundryLocalManager("phi-4-mini")

chat_client = OpenAIChatClient(
    base_url=manager.endpoint,      # e.g. http://localhost:<port>/v1
    api_key=manager.api_key,        # always "not-required" for Foundry Local
    model_id=manager.get_model_info("phi-4-mini").id,
)

agent = chat_client.as_agent(
    name="LocalAgent",
    instructions="You are a helpful assistant running fully on-device.",
)

Примечание: Foundry Local предоставляет OpenAI-совместимую конечную точку Chat Completions. Используйте её для локальной разработки и автономных сценариев. Для полного набора функций Responses API (сохранение состояния бесед и т. д.) используйте Azure OpenAI или проект Microsoft Foundry.

Дополнительная настройка для урока 8 (рабочий процесс Bing Grounding)

Блокнот условного рабочего процесса в уроке 8 использует Bing grounding через Microsoft Foundry. Если вы планируете запустить этот пример, добавьте эту переменную в ваш файл .env:

Устранение неполадок

Ошибки проверки SSL-сертификата на macOS

Если вы используете macOS и сталкиваетесь с ошибкой типа:

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

Это известная проблема Python на macOS, когда системные SSL-сертификаты не доверяются автоматически. Попробуйте следующие решения по порядку:

Вариант 1: Запустите скрипт установки сертификатов Python (рекомендуется)

# Replace 3.XX with your installed Python version (e.g., 3.12 or 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,  # Disable SSL verification if you encounter certificate errors
)

⚠️ Внимание: Отключение проверки SSL (connection_verify=False) снижает безопасность, пропуская проверку сертификата. Используйте это только как временное обходное решение в средах разработки. Никогда не используйте его в продакшене.

Вариант 3: Установите и используйте truststore

pip install truststore

Затем добавьте следующее в начало вашего блокнота или скрипта перед выполнением любых сетевых вызовов:

import truststore
truststore.inject_into_ssl()

Застряли?

Если у вас возникли проблемы с этой настройкой, присоединяйтесь к нашему сообществу Azure AI в Discord или создайте issue.

Следующий урок

Теперь вы готовы запускать код этого курса. Желаем успехов в изучении мира ИИ-агентов!

Введение в ИИ-агенты и сценарии их использования

Источник: урок курса Microsoft «AI Agents for Beginners», © Microsoft Corporation, лицензия MIT. Перевод и адаптация на русский: AI University. Мы не являемся официальным партнёром или представителем Microsoft.