使用说明
Spring AI Examples Collection
Spring AI의 다양한 핵심 기능과 실전 활용 패턴을 모아놓은 멀티모듈 예제 레포지토리입니다.
📂 모듈별 예제 목록
블로그 연재 「스프링 AI (Google Gemini) 실전 엔지니어링 가이드」의 포스트별 예제입니다. (포스트 1 API 키 발급은 코드가 없어 모듈이 없습니다.)
Part 1. 환경 구축 & ChatClient
| 포스트 | 모듈 | 설명 | 포트 | 인프라 |
|---|---|---|---|---|
| 2 | generate-text |
ChatClient Fluent API, 기본 옵션, 모델 스위칭 | 8081 |
- |
| 3 | chat-sse |
Flux / SseEmitter 실시간 스트리밍, 연결 종료 시 업스트림 취소 (웹 UI) |
8082 |
- |
| 4 | chat-memory-redis |
MessageChatMemoryAdvisor + Redis 영속화, 슬라이딩 윈도우 |
8083 |
Redis |
Part 2. 멀티모달 & 이미지 & 안전성
| 포스트 | 모듈 | 설명 | 포트 | 인프라 |
|---|---|---|---|---|
| 5 | structured-output |
BeanOutputConverter, 중첩/Enum DTO, Gemini 네이티브 JSON Schema |
8084 |
- |
| 6 | image-generation |
Google GenAI ImageModel, @Async 생성 작업, 스토리지 저장 |
8085 |
- |
| 7 | multimodal |
영수증 이미지 → DTO, 회의 음성 → 요약/액션 아이템 | 8086 |
- |
| 8 | safety-settings |
SafetySettings 정책, SAFETY 차단 시 400 응답 변환 | 8087 |
- |
Part 3. Tool Calling & 검색 & MCP
| 포스트 | 모듈 | 설명 | 포트 | 인프라 |
|---|---|---|---|---|
| 9 | tool-calling |
@Tool 기반 Function Calling, 도구 예외 처리 |
8088 |
- |
| 10 | search-grounding |
Google Search Grounding, 출처 메타데이터 추출 | 8089 |
- |
| 11 | tool-search |
ToolSearchToolCallingAdvisor 동적 도구 검색 vs 정적 등록 비교 |
8090 |
- |
| 12 | mcp-client |
MCP Client (STDIO / Streamable HTTP), 도구 허용 목록 | 8091 |
- |
| 13 | mcp-server-stdio |
MCP Server (STDIO), Claude Desktop 연동 | STDIO | - |
| 13 | mcp-server-webmvc |
MCP Server (Streamable HTTP / SSE), @McpTool / @McpResource |
8092 |
- |
Part 4. RAG & 벡터 스토어 & 비용 최적화
| 포스트 | 모듈 | 설명 | 포트 | 인프라 |
|---|---|---|---|---|
| 14 | rag-etl |
PDF/Markdown 리더, TokenTextSplitter 청킹, 메타데이터 인리치먼트 |
8093 |
- |
| 15 | rag-pgvector |
PGvector + Google GenAI Embedding, QuestionAnswerAdvisor |
8094 |
PostgreSQL(pgvector) |
| 16 | context-caching |
Gemini Context Caching 생성/질의/무효화 | 8095 |
- |
| 17 | observability-evaluation |
Micrometer 메트릭·트레이싱, RelevancyEvaluator / FactCheckingEvaluator |
8096 |
Prometheus·Grafana·Zipkin(선택) |
인프라가 필요한 모듈은 모듈 디렉터리의
compose.yaml을 Spring Boot Docker Compose 연동이bootRun시 자동으로 띄웁니다. Docker가 실행 중이어야 합니다.
🛠 기술 스택 & 개발 환경
- Language: Kotlin 2.3.21
- JDK: Java 25 (Temurin 25.0.4.1)
- Framework: Spring Boot 4.1.1
- AI Engine: Spring AI 2.0.1 (
spring-ai-starter-model-google-genai) - Default Model:
gemini-3.5-flash-lite - Build Tool: Gradle 9.7.1 (Multi-Module Project)
⚙️ 사전 설정 (환경 변수)
모든 예제 모듈은 **Google Gemini (GenAI)**를 사용하도록 구성되어 있습니다.
터미널에서 Spring AI 표준 환경 변수인 SPRING_AI_GOOGLE_GENAI_API_KEY를 설정해 주세요:
export SPRING_AI_GOOGLE_GENAI_API_KEY="AIzaSy-your-gemini-api-key"
또는 .env.template을 .env로 복사해 키를 넣고 셸에 불러올 수 있습니다(.env는 .gitignore에 포함되어 있습니다):
cp .env.template .env # 키 입력 후
set -a && source .env && set +a
실제 Gemini를 호출하는 통합 테스트는 이 환경 변수가 있을 때만 실행되고, 없으면 건너뜁니다(
@EnabledIfEnvironmentVariable). Gradle은 환경 변수를 테스트 입력으로 추적하지 않으므로, 키를 설정한 뒤 다시 실행할 때는cleanTest를 함께 지정하세요:./gradlew cleanTest test
🚀 실행 및 빌드 방법
1. 전체 프로젝트 빌드 & 테스트
./gradlew build
2. 특정 예제 모듈 실행
./gradlew :<모듈명>:bootRun
# 예) ./gradlew :chat-sse:bootRun → http://localhost:8082 에서 실시간 채팅 UI
모듈별 엔드포인트와 curl 예시는 각 모듈의 README를 참고하세요.
3. MCP STDIO 서버
./gradlew :mcp-server-stdio:bootJar
# mcp-server-stdio/build/libs/mcp-server-stdio-0.1.0.jar 를 Claude Desktop 설정에 등록
➕ 새로운 예제 모듈 추가 가이드
이 프로젝트는 루트 build.gradle.kts에 Kotlin, Java 25, Spring Boot, Spring AI BOM 등 공통 설정이 구성되어 있습니다:
settings.gradle.kts에 모듈 등록:include("your-new-example")- 새 모듈 폴더 생성 및
build.gradle.kts작성:// your-new-example/build.gradle.kts dependencies { implementation("org.springframework.boot:spring-boot-starter-web") implementation("org.springframework.ai:spring-ai-starter-model-google-genai") } src/main/resources/application.yaml및src/main/kotlin소스 작성 후 바로 실행할 수 있습니다.
