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

AGENTS.md

Преглед пројекта

Ово је образовни репозиторијум за учење развоја генеративне вештачке интелигенције уз Јава. Пружа свеобухватан практичан курс који покрива велике језичке моделе (LLMs), инжењеринг упита, уграђене представке (embeddings), РАГ (Retrieval-Augmented Generation) и протокол контекста модела (Model Context Protocol, MCP).

Кључне технологије:

Јава 21
Spring Boot 3.5.x
Spring AI 1.1.x
Maven
LangChain4j
Azure AI Foundry, Azure OpenAI и OpenAI SDK-ови

Архитектура:

Више самосталних Spring Boot апликација организованих по поглављима
Примерни пројекти који демонстрирају различите обрасце у вештачкој интелигенцији
Припремљено за GitHub Codespaces са предконфигурисаним развојним контејнерима

Команде за подешавање

Захтеви

Јава 21 или новија
Maven 3.x
Azure претплата са развојем Azure AI Foundry модела (постављање са azd up)
Azure CLI (az) и Azure Developer CLI (azd), пријављени за аутентификацију без кључа

Подешавање окружења

Опција 1: GitHub Codespaces (препоручено)

# Направите форк репозиторијума и креирајте codespace преко GitHub корисничког интерфејса
# Дев контејнер ће аутоматски инсталирати све зависности
# Сачекајте ~2 минута за подешавање окружења

Опција 2: Локални развојни контејнер

# Клонирај репозиторијум
git clone https://github.com/microsoft/Generative-AI-for-beginners-java.git
cd Generative-AI-for-beginners-java

# Отвори у VS Code-у са Dev Containers екстензијом
# Поново отвори у контејнеру када буде затражено

Опција 3: Локално подешавање

# Инсталирајте зависности
sudo apt-get update
sudo apt-get install -y maven openjdk-21-jdk

# Проверите инсталацију
java -version
mvn -version

Конфигурација

Подешавање Azure AI Foundry (безкључна, препоручена):

# Обезбедите налог Foundry и распоређивања модела као код
cd 02-SetupDevEnvironment
azd auth login
az login
azd up
# azd пише examples/basic-chat-azure/.env са вашим крајњим тј. тачком (без кључа)

Ручна конфигурација крајње тачке:

# Ако нисте користили azd, сами подесите крајњу тачку (аутентификација остаје без кључа преко az login)
cd 02-SetupDevEnvironment/examples/basic-chat-azure
cp .env.example .env
# Уредите .env: AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/

Развојни ток рада

Структура пројекта

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

Покретање апликација

Покретање Spring Boot апликације:

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

Изградња пројекта:

cd [project-directory]
mvn clean install

Покретање MCP Calculator сервера:

cd 04-PracticalSamples/calculator
mvn spring-boot:run
# Сервер ради на http://localhost:8080

Покретање примера клијената:

# Након покретања сервера у другом терминалу
cd 04-PracticalSamples/calculator

# Директни MCP клијент
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.SDKClient"

# Клијент са вештачком интелигенцијом (захтева AZURE_OPENAI_ENDPOINT + az login)
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.LangChain4jClient"

# Интерктивни бот
mvn exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.Bot"

Хот Релоад

Spring Boot DevTools је укључен у пројекте који подржавају хот релоад:

# Промене у Java фајловима ће се аутоматски поново учитати када се сачувају
mvn spring-boot:run

Упутства за тестирање

Покретање тестова

Покрени све тестове у пројекту:

cd [project-directory]
mvn test

Покрени тестове са детаљним излазом:

mvn test -X

Покрени одређену класу тестова:

mvn test -Dtest=CalculatorServiceTest

Структура тестова

Тест датотеке користе JUnit 5 (Jupiter)
Тест класе се налазе у src/test/java/
Клијентски примери у калькулатор пројекту су у src/test/java/com/microsoft/mcp/sample/client/

Ручно тестирање

Многи примери су интерактивне апликације које захтевају ручно тестирање:

Покрените апликацију помоћу mvn spring-boot:run
Тестирајте крајње тачке или интерагујте са CLI-јем
Потврдите да је очекивано понашање у складу са документацијом у README.md сваког пројекта

Тестирање са Azure AI Foundry

Пријавите се са az login пре покретања примера (безкључна аутентификација)
Уверите се да ваш налог има улогу Cognitive Services OpenAI User на ресурсу
Тестирајте филтрирање садржаја помоћу примера одговорне вештачке интелигенције у Поглављу 5

Водич за стил кода

Јава конвенције

Верзија Јаве: Јава 21 са модерним функцијама
Стил: Пратите стандардне Јава конвенције
Намена:
- Класе: PascalCase
- Методи/променљиве: camelCase
- Константе: UPPER_SNAKE_CASE
- Имена пакета: мала слова

Обрасци у Spring Boot-у

Користите @Service за бизнис логику
Користите @RestController за REST крајње тачке
Конфигурација преко application.yml или application.properties
Преферирајте променљиве окружења уместо фиксних вредности
Користите @Tool анотацију за методе изложене преко MCP-а

Организација фајлова

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

Зависности

Управљање преко Maven pom.xml
Spring AI BOM за управљање верзијама
LangChain4j за AI интеграције
Spring Boot стартер родитељ за Spring зависности

Коментари у коду

Додајте JavaDoc за јавне API-је
Укључите објашњавајуће коментаре за сложене AI интеракције
Јасно документајте описе MCP алата

Изградња и имплементација

Изградња пројеката

Изградња без тестова:

mvn clean install -DskipTests

Изградња са свим проверницама:

mvn clean install

Паковање апликације:

mvn package
# Креира JAR у директоријуму target/

Директоријуми за излаз

Скомпилиране класе: target/classes/
Тест класе: target/test-classes/
JAR фајлови: target/*.jar
Maven артефакти: target/

Конфигурација по окружењима

Развој:

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

Производња:

Користите управљани идентитет уместо az login за безкључну аутентификацију
Поставите AZURE_OPENAI_ENDPOINT на ваш продукцијски Foundry ресурс
Управљајте конфигурацијом преко променљивих окружења или Azure Key Vault-а

Разматрања при имплементацији

Ово је образовни репозиторijум са пример апликацијама
Нису намењени директно за продукцијску имплементацију
Примери показују обрасце које треба прилагодити за продукцијску употребу
Погледајте README сваког појединачног пројекта за специфичне белешке о имплементацији

Додатне напомене

Azure AI Foundry

Безкључна аутентификација: повезује се са Microsoft Entra ID — нема потребе за управљањем API кључевима
Постављено као код: Bicep + azd (azd up) креира налог и развоје модела
Исти OpenAI-компатибилан код ради локално (az login) и у Azure-у (управљани идентитет)

Рад са више пројеката

Сваки примерни пројекат је самосталан:

# Идите до конкретног пројекта
cd 04-PracticalSamples/[project-name]

# Сваки има свој pom.xml и може се независно градити
mvn clean install

Чести проблеми

Неусклађеност верзије Јаве:

# Проверите Java 21
java -version
# Ажурирајте JAVA_HOME ако је потребно
export JAVA_HOME=/usr/lib/jvm/msopenjdk-current

Проблеми са преузимањем зависности:

# Очистите Maven кеш и покушајте поново
rm -rf ~/.m2/repository
mvn clean install

Крајња тачка или пријава нису пронађени:

# Подеси крајњу тачку у тренутној сесији и пријави се (без кључа)
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
az login

# Или користи .env фајл у директоријуму пројекта
echo "AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/" > .env

Порт је већ у употреби:

# Spring Boot подразумевано користи порт 8080
# Промена у application.properties:
server.port=8081

Подршка за више језика

Документација доступна на 45+ језика преко аутоматског превођења
Преводи у директоријуму translations/
Превод се управља преко GitHub Actions радног тока

Пут учења

Почните са 02-SetupDevEnvironment
Пратите поглавља узастопно (01 → 05)
Завршите практичне примере у сваком поглављу
Истражите примерне пројекте у Поглављу 4
Научите праксе одговорне вештачке интелигенције у Поглављу 5

Развојни контејнер

Конфигурација .devcontainer/devcontainer.json укључује:

Развојно окружење са Јава 21
Прединсталирани Maven
VS Code Java екстензије
Spring Boot алате
GitHub Copilot интеграцију
Подршку за Docker-in-Docker
Azure CLI

Разматрања перформанси

Azure AI Foundry развоји имају квоте за токене/захтеве по минути
Користите одговарајуће величине пакета за embeddings
Размислите о кеширању за поновљене API позиве
Пратите употребу токена ради оптимизације трошкова

Напомене о безбедности

Никада не комитујте .env фајлове (већ у .gitignore)
Преферирајте безкључну аутентификацију (Microsoft Entra ID) уместо API кључева
Користите управљане идентитете у Azure-у; az login за локални развој
Пратите смернице одговорне вештачке интелигенције у Поглављу 5

Изјава о одрицању одговорности: Овај документ је преведен коришћењем услуге за аутоматски превод Co-op Translator. Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода.

sr

About