Основен чат с 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. Този credential автоматично намира токен от вашата сесия 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 на ресурса
• Ако току-що сте присвоили ролята, изчакайте минута за разпространение
• Потвърдете, че сте в правилния tenant/абонамент (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: Основни техники за генеративен AI

Ресурси

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

---

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