Peruskeskustelu Azure AI Foundryn kanssa

July 2, 2026 · View on GitHub

Tämä esimerkki on yksinkertainen Spring Boot -sovellus, joka yhdistää Azure AI Foundry -malliin käyttämällä avaimetonta todennusta (Microsoft Entra ID) ja testaa asetuksesi. Se käyttää Spring AI:n ChatClient-luokkaa.

Sisällysluettelo

Esivaatimukset

Ennen tämän esimerkin suorittamista varmista, että sinulla on:

  • Azure AI Foundry -resurssi, jossa on gpt-4o-mini -käyttöönotto — ota se käyttöön komennolla azd up tai manuaalisesti Azure AI Foundryn asennusohjeen avulla
  • Cognitive Services OpenAI User -rooli kyseisessä resurssissa (Bicep-mallit asettavat tämän automaattisesti)
  • Azure CLI (az), kirjautuneena sisään komennolla az login
  • Java 21+ ja Maven 3.9+

API-avainta ei vaadita — todennus tapahtuu avaimettomasti Microsoft Entra ID:n kautta.

Pika-aloitus

# 1. Siirry projektiin
cd 02-SetupDevEnvironment/examples/basic-chat-azure

# 2. Kirjaudu sisään, jotta keyless-todennus voi saada tokenin
az login

# 3. Määritä päätepiste
#    - Jos kävit `azd up`, .env tiedosto on kirjoitettu puolestasi (hyppää tämä yli).
#    - Muussa tapauksessa kopioi mallipohja ja aseta AZURE_OPENAI_ENDPOINT:
cp .env.example .env

# 4. Suorita sovellus
mvn spring-boot:run

Miten todennus toimii

Tässä esimerkissä todentaminen tapahtuu Microsoft Entra ID:n avulla — API-avainta ei tarvita.

Kun on asetettu vain spring.ai.azure.openai.endpoint (eikä api-avain), Spring AI rakentaa Azure OpenAI -asiakkaan käyttäen DefaultAzureCredential -todennustietoja. Tämä tunnistus hakee automaattisesti tokenin paikallisesta az login -sessionistasi tai hallitun identiteetin avulla, kun sovellus ajetaan Azure-ympäristössä — joten sama koodi toimii molemmissa ympäristöissä ilman muutoksia.

Sovelluksen suorittaminen

Mavenin käyttö

mvn spring-boot:run

VS Coden käyttö

  1. Avaa projekti VS Codessa
  2. Paina F5 tai käytä "Run and Debug" -paneelia
  3. Valitse "Spring Boot-BasicChatApplication" -konfiguraatio

Huom: VS Code -konfiguraatio lataa automaattisesti ympäristömuuttujat sisältävän .env -tiedoston

Odotettu tuloste

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.

Konfiguraatioiden viite

Ympäristömuuttujat

MuuttujaKuvausPakollinenEsimerkki
AZURE_OPENAI_ENDPOINTFoundryn (Azure OpenAI) päätepisteen URL-osoiteKyllähttps://my-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENTChat-mallin käyttöönoton nimiEigpt-4o-mini (oletus)

API-avaimen muuttujaa ei ole — todennus on avaimetonta (Microsoft Entra ID az login -käytöllä).

Spring-konfiguraatio

application.yml-tiedosto määrittelee:

  • Päätepisteen: ${AZURE_OPENAI_ENDPOINT} – ympäristömuuttujasta
  • Käyttöönoton: ${AZURE_OPENAI_DEPLOYMENT:gpt-4o-mini} – ympäristömuuttujasta, oletuksella
  • Todennuksen: avaimeton — ei asetettu api-key, joten Spring AI käyttää DefaultAzureCredential-luokkaa
  • Lämpötila: 0.7 – ohjaa luovuutta (0.0 = deterministinen, 1.0 = luova)
  • Maksimi tokenit: 500 – suurin vastauksen pituus

Vianetsintä

Yleiset ongelmat

Virhe: 401 / "PermissionDenied" / token-virheet
  • Suorita az login — avaimeton todennus tarvitsee aktiivisen sisäänkirjautumisen saadakseen tokenin
  • Varmista, että tililläsi on Cognitive Services OpenAI User -rooli kyseisessä resurssissa
  • Jos rooli on juuri myönnetty, odota hetki, että se ehtii voimaan
  • Tarkista, että olet oikeassa vuokralaisessa/tilaajassa (az account show)
Virhe: "The endpoint is not valid" / yhteysvirheet
  • Varmista, että AZURE_OPENAI_ENDPOINT on koko perus-URL (esim. https://your-resource.openai.azure.com/)
  • Tarkista, että osoitteen loppuosa (vinoviiva) on yhteneväinen
  • Varmista, että osoite vastaa varattua resurssiasi (azd env get-values)
Virhe: "The deployment was not found"
  • Varmista, että AZURE_OPENAI_DEPLOYMENT vastaa käyttöönoton nimeä Azuressa
  • Tarkista, että malli on onnistuneesti otettu käyttöön ja aktiivinen
  • Oletuskäyttöönoton nimi on gpt-4o-mini
VS Code: Ympäristömuuttujat eivät lataudu
  • Varmista, että .env-tiedosto on projektin juurihakemistossa (samalla tasolla kuin pom.xml)
  • Kokeile suorittaa mvn spring-boot:run VS Coden integroidussa terminaalissa
  • Tarkista, että VS Coden Java-laajennus on asennettu oikein

Vikailmoitukset

Yksityiskohtaisen lokituksen käyttämiseksi ota nämä rivit käyttöön application.yml-tiedostossa:

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

Seuraavat askeleet

Asennus valmis! Jatka oppimismatkaasi:

Luku 3: Keskeiset generatiivisen tekoälyn tekniikat

Resurssit

Vastuuvapauslauseke: Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua Co-op Translator. Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista.