Базовый чат с Azure AI Foundry

Этот пример — простое приложение Spring Boot, которое подключается к модели Azure AI Foundry с помощью аутентификации без ключа (Microsoft Entra ID) и тестирует вашу настройку. Используется ChatClient из Spring AI.

Содержание

• Требования
• Быстрый старт
• Как работает аутентификация
• Запуск приложения
  • Использование Maven
  • Использование VS Code
  • Ожидаемый вывод
• Справочник по настройке
  • Переменные окружения
  • Конфигурация Spring
• Устранение неполадок
  • Распространённые проблемы
  • Режим отладки
• Следующие шаги
• Ресурсы

Требования

Перед запуском этого примера убедитесь, что у вас есть:

• Ресурс Azure AI Foundry с развертыванием gpt-4o-mini — создайте его с помощью azd up или вручную через руководство по настройке Azure AI Foundry
• Роль Cognitive Services OpenAI User для этого ресурса (шаблоны Bicep назначают её автоматически)
• Установленная Azure CLI (az) и выполнен вход через az login
• Java 21+ и Maven 3.9+

Ключ API не требуется — аутентификация осуществляется без ключа через Microsoft Entra ID.

Быстрый старт

# 1. Перейдите к проекту
cd 02-SetupDevEnvironment/examples/basic-chat-azure

# 2. Войдите в систему, чтобы аутентификация без ключа могла получить токен
az login

# 3. Настройте конечную точку
#    - Если вы запускали `azd up`, файл .env был создан для вас (пропустите этот шаг).
#    - В противном случае скопируйте шаблон и установите AZURE_OPENAI_ENDPOINT:
cp .env.example .env

# 4. Запустите приложение
mvn spring-boot:run

Как работает аутентификация

В этом примере используется аутентификация через Microsoft Entra ID — ключ API не используется.

Если задан только spring.ai.azure.openai.endpoint (и нет api-key), Spring AI создаёт клиент Azure OpenAI с помощью DefaultAzureCredential. Этот метод автоматически получает токен из вашей локальной сессии az login или через управляемую учётную запись при запуске в Azure — поэтому один и тот же код работает в обеих средах без изменений.

Запуск приложения

Использование Maven

mvn spring-boot:run

Использование VS Code

1. Откройте проект в VS Code
2. Нажмите F5 или используйте панель "Run and Debug"
3. Выберите конфигурацию "Spring Boot-BasicChatApplication"

Примечание: Конфигурация VS Code автоматически загружает ваш файл .env

Ожидаемый вывод

Starting Basic Chat with Azure OpenAI...
Environment variables loaded successfully
Connecting to Azure OpenAI...
Sending prompt: What is AI in a short sentence? Max 100 words.

AI Response:
================
AI, or Artificial Intelligence, is the simulation of human intelligence in machines programmed to think and learn like humans.
================

Success! Azure OpenAI connection is working correctly.

Справочник по настройке

Переменные окружения

Переменная	Описание	Обязательно	Пример
AZURE_OPENAI_ENDPOINT	URL конечной точки Foundry (Azure OpenAI)	Да	https://my-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT	Имя развертывания модели чата	Нет	gpt-4o-mini (по умолчанию)

Нет переменной для ключа API — аутентификация осуществляется без ключа (Microsoft Entra ID через az login).

Конфигурация Spring

В файле application.yml настроено:

• Endpoint: ${AZURE_OPENAI_ENDPOINT} — берётся из переменной окружения
• Deployment: ${AZURE_OPENAI_DEPLOYMENT:gpt-4o-mini} — из переменной окружения с запасным значением
• Auth: без ключа — api-key не установлен, поэтому Spring AI использует DefaultAzureCredential
• Temperature: 0.7 — регулирует креативность (0.0 = детерминированно, 1.0 = креативно)
• Max Tokens: 500 — максимальная длина ответа

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

Распространённые проблемы

Ошибка: 401 / "PermissionDenied" / ошибки токена

• Выполните az login — для аутентификации без ключа необходима активная авторизация для получения токена
• Убедитесь, что ваша учётная запись имеет роль Cognitive Services OpenAI User для ресурса
• Если роль была назначена только что, подождите минуту для её распространения
• Проверьте правильность выбранного тенанта/подписки (az account show)

Ошибка: "The endpoint is not valid" / ошибки соединения

• Убедитесь, что AZURE_OPENAI_ENDPOINT — это полный базовый URL (например, https://your-resource.openai.azure.com/)
• Проверьте согласованность завершающего слеша
• Подтвердите, что конечная точка соответствует вашему развернутому ресурсу (azd env get-values)

Ошибка: "The deployment was not found"

• Проверьте, что AZURE_OPENAI_DEPLOYMENT совпадает с именем развертывания в Azure
• Удостоверьтесь, что модель успешно развернута и активна
• Имя развертывания по умолчанию — gpt-4o-mini

VS Code: Переменные окружения не загружаются

• Убедитесь, что файл .env находится в корневой папке проекта (на том же уровне, что и pom.xml)
• Попробуйте запустить mvn spring-boot:run в встроенном терминале VS Code
• Проверьте, что расширение Java для VS Code установлено корректно

Режим отладки

Чтобы включить подробное логирование, раскомментируйте эти строки в application.yml:

logging:
  level:
    org.springframework.ai: DEBUG
    com.azure: DEBUG

Следующие шаги

Настройка завершена! Продолжайте обучение:

Глава 3: Основные техники генеративного ИИ

Ресурсы

• Документация Spring AI Azure OpenAI
• Аутентификация без ключа с Microsoft Entra ID
• Портал Azure AI Foundry
• Документация Azure AI Foundry

---

Отказ от ответственности: Этот документ был переведен с использованием сервиса машинного перевода Co-op Translator. Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода.