Imported from microsoft/Generative-AI-for-beginners-java (translations/fi/AGENTS.md). Install upstream with npx skills add microsoft/Generative-AI-for-beginners-java --skill fi. Copyright stays with the author.

AGENTS.md

Projektin yleiskatsaus

Tämä on opetusrekisteri Generatiivisen tekoälyn kehittämisen oppimiseen Java-kielellä. Se tarjoaa kattavan käytännön kurssin, joka kattaa suuret kielimallit (LLM), kehotteiden suunnittelun, upotukset, RAG:n (Retrieval-Augmented Generation) ja Malli-kontekstiprotokollan (MCP).

Keskeiset teknologiat:

Java 21
Spring Boot 3.5.x
Spring AI 1.1.x
Maven
LangChain4j
Azure AI Foundry, Azure OpenAI ja OpenAI SDK:t

Arkkitehtuuri:

Useita itsenäisiä Spring Boot -sovelluksia luvuittain järjestettynä
Esimerkkiprojekteja, jotka demonstroivat erilaisia tekoälykuvioita
GitHub Codespaces -valmiit esikonfiguroiduilla kehityssäiliöillä

Asennuskäskyt

Esivaatimukset

Java 21 tai uudempi
Maven 3.x
Azure-tilaus, jossa on Azure AI Foundry -malliasennus (provisioi azd up komennolla)
Azure CLI (az) ja Azure Developer CLI (azd), kirjauduttu sisään avaimettomaan tunnistautumiseen

Ympäristön asennus

Vaihtoehto 1: GitHub Codespaces (suositus)

# Haarauta repositorio ja luo codespace GitHub-käyttöliittymästä
# Kehityssäiliö asentaa automaattisesti kaikki riippuvuudet
# Odota noin 2 minuuttia ympäristön asennusta varten

Vaihtoehto 2: Paikallinen kehityssäiliö

# Kopioi varasto
git clone https://github.com/microsoft/Generative-AI-for-beginners-java.git
cd Generative-AI-for-beginners-java

# Avaa VS Codessa Dev Containers -laajennuksella
# Avaa uudelleen säiliössä, kun sinua kehotetaan

Vaihtoehto 3: Paikallinen asennus

# Asenna riippuvuudet
sudo apt-get update
sudo apt-get install -y maven openjdk-21-jdk

# Vahvista asennus
java -version
mvn -version

Konfigurointi

Azure AI Foundryn asennus (avaimeton, suositus):

# Määritä Foundry-tili + mallin käyttöönotot koodina
cd 02-SetupDevEnvironment
azd auth login
az login
azd up
# azd kirjoittaa examples/basic-chat-azure/.env tiedoston päätepisteelläsi (ei avainta)

Manuaalinen päätepisteen konfigurointi:

# Jos et käyttänyt azd:tä, aseta päätepiste itse (todentaminen pysyy avaimettomana az loginin kautta)
cd 02-SetupDevEnvironment/examples/basic-chat-azure
cp .env.example .env
# Muokkaa .env: AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/

Kehitystyönkulku

Projektin rakenne

/
├── 01-IntroToGenAI/              # Chapter 1: Introduction
├── 02-SetupDevEnvironment/       # Chapter 2: Environment setup
│   └── examples/                 # Working examples
├── 03-CoreGenerativeAITechniques/ # Chapter 3: Core techniques
├── 04-PracticalSamples/          # Chapter 4: Sample projects
│   ├── calculator/               # MCP service example
│   ├── foundrylocal/            # Local model integration
│   └── petstory/                # Multi-modal app
├── 05-ResponsibleGenAI/         # Chapter 5: Responsible AI
└── translations/                # Multi-language support

Sovellusten käynnistäminen

Spring Boot -sovelluksen käynnistäminen:

cd [project-directory]
mvn spring-boot:run

Projektin rakentaminen:

cd [project-directory]
mvn clean install

MCP-laskimen palvelimen käynnistäminen:

cd 04-PracticalSamples/calculator
mvn spring-boot:run
# Palvelin toimii osoitteessa http://localhost:8080

Asiakasesimerkkien suorittaminen:

# Käynnistämisen jälkeen palvelin toisessa päätelaitteessa
cd 04-PracticalSamples/calculator

# Suora MCP-asiakas
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.SDKClient"

# Tekoälypohjainen asiakas (vaatii AZURE_OPENAI_ENDPOINT + az login)
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.LangChain4jClient"

# Vuorovaikutteinen botti
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.Bot"

Kuuma uudelleenkäynnistys

Spring Boot DevTools sisältyy projekteihin, jotka tukevat kuumaa uudelleenkäynnistystä:

# Java-tiedostojen muutokset ladataan automaattisesti uudelleen tallennettaessa
mvn spring-boot:run

Testausohjeet

Testien suorittaminen

Suorita kaikki testit projektissa:

cd [project-directory]
mvn test

Suorita testit yksityiskohtaisilla tulosteilla:

mvn test -X

Suorita tietty testiluokka:

mvn test -Dtest=CalculatorServiceTest

Testauksen rakenne

Testitiedostot käyttävät JUnit 5:tä (Jupiter)
Testiluokat sijaitsevat kansiossa src/test/java/
Asiakasesimerkit laskuprojektissa ovat kansiossa src/test/java/com/microsoft/mcp/sample/client/

Manuaalinen testaus

Monet esimerkit ovat interaktiivisia sovelluksia, jotka vaativat manuaalista testausta:

Käynnistä sovellus komennolla mvn spring-boot:run
Testaa päätepisteitä tai toimi komentoriviltä
Varmista, että odotettu käyttäytyminen vastaa kunkin projektin README.md-tiedostossa olevaa dokumentaatiota

Testaus Azure AI Foundryn kanssa

Kirjaudu sisään az login -komennolla ennen esimerkkien suorittamista (avaimeton tunnistus)
Varmista, että tililläsi on Cognitive Services OpenAI User -rooli resurssissa
Testaa sisällön suodatus vastuullisen AI-esimerkillä luvussa 5

Koodityyliohjeet

Java-konventiot

Java-versio: Java 21 modernien ominaisuuksien kanssa
Tyyli: Noudata vakiintuneita Java-käytäntöjä
Nimeäminen:
- Luokat: PascalCase
- Metodit/muuttujat: camelCase
- Konstanteille: UPPER_SNAKE_CASE
- Pakettinimet: pienaakkoset

Spring Boot -mallit

Käytä @Service liiketoimintalogiikkaan
Käytä @RestController REST-päätepisteisiin
Konfiguraatio application.yml tai application.properties -tiedostojen kautta
Ympäristömuuttujat mieluummin kovakoodattujen arvojen sijaan
Käytä @Tool-annotaatiota MCP:n julkaisemiin metodeihin

Tiedostojen organisointi

src/
├── main/
│   ├── java/
│   │   └── com/microsoft/[component]/
│   │       ├── [Component]Application.java
│   │       ├── config/
│   │       ├── controller/
│   │       ├── service/
│   │       └── exception/
│   └── resources/
│       ├── application.yml
│       └── static/
└── test/
    └── java/
        └── com/microsoft/[component]/

Riippuvuudet

Hallitaan Mavenin pom.xml:n kautta
Spring AI BOM versionhallintaan
LangChain4j tekoälyintegraatioita varten
Spring Boot starter parent Spring-riippuvuuksille

Koodikommentit

Lisää JavaDoc julkisiin rajapintoihin
Sisällytä selittäviä kommentteja monimutkaisista tekoälytoiminnoista
Dokumentoi MCP-työkalujen kuvaukset selkeästi

Käännäminen ja käyttöönotto

Projektien kääntäminen

Käännä ilman testejä:

mvn clean install -DskipTests

Käännä kaikilla tarkistuksilla:

mvn clean install

Pakkaa sovellus:

mvn package
# Luo JAR-tiedoston target/-hakemistoon

Tulostuskansiot

Käännetyt luokat: target/classes/
Testiluokat: target/test-classes/
JAR-tiedostot: target/*.jar
Maven-artifaktit: target/

Ympäristökohtainen konfiguraatio

Kehitys:

# application.yml (keyless - no api-key; auth via DefaultAzureCredential)
spring:
  ai:
    azure:
      openai:
        endpoint: ${AZURE_OPENAI_ENDPOINT}
        chat:
          options:
            deployment-name: ${AZURE_OPENAI_DEPLOYMENT:gpt-4o-mini}

Tuotanto:

Käytä hallittua identiteettiä az login sijaan avaimettomaan tunnistautumiseen
Aseta AZURE_OPENAI_ENDPOINT tuotantoympäristön Foundryn resurssiin
Hallitse asetukset ympäristömuuttujilla tai Azure Key Vaultilla

Käyttöönottoon liittyvät huomioinnit

Tämä on opetusrekisteri esimerkkisovelluksilla
Ei suunniteltu suoraan tuotantokäyttöön
Esimerkit demonstroivat malleja, joita voi soveltaa tuotantoon
Katso kunkin projektin README:t tarkemmat käyttöönottotiedot

Lisätietoja

Azure AI Foundry

Avaimeton tunnistus: yhdistä Microsoft Entra ID:llä — API-avaimia ei tarvitse hallita
Provisionointi koodina: Bicep + azd (azd up) luo tilin ja malliasennukset
Sama OpenAI-yhteensopiva koodi toimii paikallisesti (az login) ja Azuren hallitulla identiteetillä

Usean projektin työskentely

Jokainen esimerkkiprojekti on itsenäinen:

# Siirry tiettyyn projektiin
cd 04-PracticalSamples/[project-name]

# Jokaisella on oma pom.xml-tiedosto ja ne voidaan kääntää itsenäisesti
mvn clean install

Yleisimmät ongelmat

Java-version ristiriita:

# Vahvista Java 21
java -version
# Päivitä JAVA_HOME tarvittaessa
export JAVA_HOME=/usr/lib/jvm/msopenjdk-current

Riippuvuuksien latausongelmat:

# Tyhjennä Mavenin välimuisti ja yritä uudelleen
rm -rf ~/.m2/repository
mvn clean install

Päätepistettä tai kirjautumista ei löydy:

# Aseta palvelupiste nykyiseen istuntoon ja kirjaudu sisään (avaimeton)
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
az login

# Tai käytä .env-tiedostoa projektihakemistossa
echo "AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/" > .env

Portti on jo käytössä:

# Spring Boot käyttää oletuksena porttia 8080
# Muutos tiedostossa application.properties:
server.port=8081

Monikielinen tuki

Dokumentaatio saatavilla yli 45 kielellä automatisoidun kääntämisen avulla
Käännökset kansiossa translations/
Käännöksiä hallitaan GitHub Actions -työnkululla

Oppimispolku

Aloita 02-SetupDevEnvironment -dokumentilla
Seuraa lukuja järjestyksessä (01 → 05)
Suorita käytännön esimerkit jokaisessa luvussa
Tutustu esimerkkiprojekteihin luvussa 4
Opi vastuullisen tekoälyn käytännöt luvussa 5

Kehityssäiliö

Tiedosto .devcontainer/devcontainer.json konfiguroi:

Java 21 kehitysympäristön
Mavenin valmiiksi asennettuna
VS Code Java -laajennukset
Spring Boot -työkalut
GitHub Copilot -integraation
Docker-in-Docker -tuen
Azure CLI:n

Suorituskykyhuomiot

Azure AI Foundryn asennuksilla on token-/pyyntörajoituksia minuutissa
Käytä sopivan kokoisia eräpaketteja upotuksiin
Harkitse välimuistia toistuvissa API-kutsuissa
Seuraa tokenin käyttöä kustannusten optimointia varten

Turvallisuusmuistutukset

Älä koskaan tallenna .env-tiedostoja versiohallintaan (on jo .gitignore-tiedostossa)
Suosi avaimetonta tunnistautumista (Microsoft Entra ID) API-avainten sijaan
Käytä Azure-ympäristössä hallittuja identiteettejä; paikallisessa kehityksessä az login -kirjautumista
Noudata vastuullisen tekoälyn ohjeita luvussa 5

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.

fi

About