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

AGENTS.md

Pregled Projekta

Ovo je edukativni repozitorij za učenje razvoja Generative AI uz Java. Pruža sveobuhvatan praktični tečaj koji pokriva Velike Jezične Modele (LLM-ove), inženjering prompta, ugradnje (embeddings), RAG (Retrieval-Augmented Generation) i Protokol za Kontekst Modela (MCP).

Ključne Tehnologije:

Java 21
Spring Boot 3.5.x
Spring AI 1.1.x
Maven
LangChain4j
Azure AI Foundry, Azure OpenAI i OpenAI SDK-ovi

Arhitektura:

Više samostalnih Spring Boot aplikacija organiziranih po poglavljima
Primjeri projekata koji demonstriraju različite AI obrasce
GitHub Codespaces spreman s unaprijed konfiguriranim razvojnim kontejnerima

Komande za Postavljanje

Preduvjeti

Java 21 ili noviji
Maven 3.x
Azure pretplata s Azure AI Foundry model deployment-om (osigurajte s azd up)
Azure CLI (az) i Azure Developer CLI (azd), prijavljeni za autentifikaciju bez ključeva

Postavljanje Okruženja

Opcija 1: GitHub Codespaces (Preporučeno)

# Napravi fork repozitorija i kreiraj codespace iz GitHub sučelja
# Razvojno okruženje će automatski instalirati sve ovisnosti
# Pričekaj ~2 minute za postavljanje okruženja

Opcija 2: Lokalni Razvojni Kontejner

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

# Otvorite u VS Code s Dev Containers ekstenzijom
# Ponovno otvorite u kontejneru kad se to zatraži

Opcija 3: Lokalno Postavljanje

# Instaliraj ovisnosti
sudo apt-get update
sudo apt-get install -y maven openjdk-21-jdk

# Provjeri instalaciju
java -version
mvn -version

Konfiguracija

Azure AI Foundry Postavljanje (bez ključeva, preporučeno):

# Postavite Foundry račun + implementacije modela kao kod
cd 02-SetupDevEnvironment
azd auth login
az login
azd up
# azd zapisuje examples/basic-chat-azure/.env s vašom krajnjom točkom (bez ključa)

Ručno konfiguriranje krajnje točke:

# Ako niste koristili azd, sami postavite krajnju točku (autentifikacija ostaje bez ključa putem az login)
cd 02-SetupDevEnvironment/examples/basic-chat-azure
cp .env.example .env
# Uredite .env: AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/

Razvojni Tijek

Struktura Projekta

/
├── 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

Pokretanje Aplikacija

Pokretanje Spring Boot aplikacije:

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

Izgradnja projekta:

cd [project-directory]
mvn clean install

Pokretanje MCP Calculator Servera:

cd 04-PracticalSamples/calculator
mvn spring-boot:run
# Poslužitelj radi na http://localhost:8080

Pokretanje Client Primjera:

# Nakon pokretanja poslužitelja u drugom terminalu
cd 04-PracticalSamples/calculator

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

# Klijent s umjetnom inteligencijom (zahtijeva AZURE_OPENAI_ENDPOINT + az prijavu)
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.LangChain4jClient"

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

Hot Reload

Spring Boot DevTools je uključen u projekte koji podržavaju hot reload:

# Promjene na Java datotekama automatski će se ponovno učitati kada se spremi
mvn spring-boot:run

Upute za Testiranje

Pokretanje Testova

Pokreni sve testove u projektu:

cd [project-directory]
mvn test

Pokreni testove s detaljnim ispisom:

mvn test -X

Pokreni određenu test klasu:

mvn test -Dtest=CalculatorServiceTest

Struktura Testova

Test datoteke koriste JUnit 5 (Jupiter)
Test klase su smještene u src/test/java/
Klijentski primjeri u calculator projektu nalaze se u src/test/java/com/microsoft/mcp/sample/client/

Ručno Testiranje

Mnogi primjeri su interaktivne aplikacije koje zahtijevaju ručno testiranje:

Pokrenite aplikaciju s mvn spring-boot:run
Testirajte krajnje točke ili komunicirajte s CLI-em
Provjerite da očekivano ponašanje odgovara dokumentaciji u README.md svakog projekta

Testiranje s Azure AI Foundry

Prijavite se s az login prije pokretanja primjera (autentifikacija bez ključeva)
Osigurajte da vaš račun ima ulogu Cognitive Services OpenAI User na resursu
Testirajte filtriranje sadržaja s primjerom odgovornog AI u Poglavlju 5

Smjernice za Stil Koda

Java Konvencije

Verzija Jave: Java 21 s modernim značajkama
Stil: Slijedite standardne Java konvencije
Nazivi:
- Klase: PascalCase
- Metode/varijable: camelCase
- Konstante: UPPER_SNAKE_CASE
- Imena paketa: mala slova

Spring Boot Obrasci

Koristite @Service za poslovnu logiku
Koristite @RestController za REST krajnje točke
Konfiguracija preko application.yml ili application.properties
Varijable okruženja su preferirane umjesto hardkodiranih vrijednosti
Koristite @Tool oznaku za metode izložene putem MCP-a

Organizacija Datoteka

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

Ovisnosti

Upravljano putem Maven pom.xml
Spring AI BOM za upravljanje verzijama
LangChain4j za AI integracije
Spring Boot starter parent za Spring ovisnosti

Komentari u Kod

Dodajte JavaDoc za javne API-je
Uključite objašnjavajuće komentare za složene AI interakcije
Jasno dokumentirajte opise MCP alata

Izgradnja i Deploy

Izgradnja Projekata

Izgradi bez testova:

mvn clean install -DskipTests

Izgradi sa svim provjerama:

mvn clean install

Paketiraj aplikaciju:

mvn package
# Stvara JAR u direktoriju target/

Izlazni Direktoriji

Kompilirane klase: target/classes/
Test klase: target/test-classes/
JAR datoteke: target/*.jar
Maven artefakti: target/

Konfiguracija Specifična za Okruženje

Razvoj:

# 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}

Produkcija:

Koristite upravljani identitet umjesto az login za autentifikaciju bez ključeva
Postavite AZURE_OPENAI_ENDPOINT na vaš produkcijski Foundry resurs
Upravljanje konfiguracijom preko varijabli okruženja ili Azure Key Vault-a

Razmatranja za Deploy

Ovo je edukativni repozitorij s primjerima aplikacija
Nije dizajniran za produkcijski deploy takav kakav jest
Primjeri demonstriraju obrasce za prilagodbu produkcijskoj upotrebi
Pogledajte README-ove pojedinačnih projekata za specifične napomene o deployu

Dodatne Napomene

Azure AI Foundry

Autentifikacija bez ključeva: povezuje se s Microsoft Entra ID — nema potrebe za upravljanjem API ključevima
Provisioniranje kao kod: Bicep + azd (azd up) kreiraju račun i model deployment-e
Isti OpenAI-kompatibilni kod radi lokalno (az login) i u Azureu (upravljani identitet)

Rad s Više Projekata

Svaki primjer projekta je samostalan:

# Navigiraj do određenog projekta
cd 04-PracticalSamples/[project-name]

# Svaki ima svoj pom.xml i može se graditi neovisno
mvn clean install

Česti Problemi

Neusklađenost verzije Jave:

# Provjerite Java 21
java -version
# Ažurirajte JAVA_HOME ako je potrebno
export JAVA_HOME=/usr/lib/jvm/msopenjdk-current

Problemi s preuzimanjem ovisnosti:

# Očisti Maven predmemoriju i pokušaj ponovno
rm -rf ~/.m2/repository
mvn clean install

Krajnja točka ili prijava nije pronađena:

# Postavite endpoint u trenutnoj sesiji i prijavite se (bez ključa)
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
az login

# Ili koristite .env datoteku u direktoriju projekta
echo "AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/" > .env

Port je već zauzet:

# Spring Boot prema zadanim postavkama koristi port 8080
# Promjena u application.properties:
server.port=8081

Podrška za Više Jezika

Dokumentacija dostupna na 45+ jezika putem automatskog prevođenja
Prijevodi u direktoriju translations/
Prijevod upravljan GitHub Actions workflow-om

Put Učenja

Počnite s 02-SetupDevEnvironment
Slijedite poglavlja redom (01 → 05)
Završite praktične primjere u svakom poglavlju
Istražite primjere projekata u Poglavlju 4
Učite prakse odgovornog AI u Poglavlju 5

Razvojni Kontejner

.devcontainer/devcontainer.json konfigurira:

Java 21 razvojno okruženje
Maven unaprijed instaliran
VS Code Java ekstenzije
Spring Boot alati
GitHub Copilot integracija
Docker unutar Dockera podrška
Azure CLI

Razmatranja Performansi

Azure AI Foundry deploymenti imaju kvote tokena/zahtjeva po minuti
Koristite odgovarajuće veličine batch-a za ugradnje
Razmotrite caching za ponovljene API pozive
Pratite korištenje tokena radi optimizacije troškova

Napomene o Sigurnosti

Nikada ne commitajte .env datoteke (već su u .gitignore)
Preferirajte autentifikaciju bez ključeva (Microsoft Entra ID) umjesto API ključeva
Koristite upravljane identitete u Azureu; az login za lokalni razvoj
Slijedite smjernice odgovornog AI-ja u Poglavlju 5

Napomena: Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa Co-op Translator. Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda.

hr

About