🤖
Spring AI 치트시트

Spring Boot 4.1.1 최신 환경 및 Spring AI 2.0.1 GA 기준: ChatClient 2.0 Fluent API, @Tool 기반 ToolCallingAdvisor, Virtual Threads I/O 최적화, Streaming SSE, Structured Output, RAG 파이프라인 및 VectorStore 실전 가이드
#spring-ai#spring-boot-4#spring-ai-2.0#chatclient#tool-calling#rag#vectorstore#virtual-threads#openai#claude#ollama#java#backend최종 업데이트: 2026-10-06
Spring AI 치트시트 핵심 명령어 및 실전 가이드

## 1. Spring AI 2.0 아키텍처 & 최신 의존성 (Spring Boot 4.1.1 + Spring AI 2.0.1)
최신 **Spring Boot 4.1.1** 및 **Spring AI 2.0.1 GA** 환경은 Java 17~26, Jackson 3, HttpClient 5.6, 가상 스레드(Virtual Threads)를 기반으로 하여 대규모 LLM I/O 호출을 고성능·저비용으로 처리할 수 있는 엔터프라이즈 AI 표준 조합입니다.

```text
[Spring Boot 4.1.1 + Spring AI 2.0 아키텍처]
Application     : Spring Boot 4.1.1 (Virtual Threads 활성화, Java 17/21/25/26 지원)
Client Layer    : ChatClient (Fluent 2.0 API, Tools & Advisors 통합)
Advisor Layer   : ToolCallingAdvisor(도구 실행 루프 중앙화), ChatMemoryAdvisor, RAG Advisor
Model Layer     : ChatModel, EmbeddingModel, ImageModel, AudioModel
Data/RAG Layer  : VectorStore (PGvector, Chroma, Qdrant, Milvus), Document, TextSplitter
Provider Layer  : OpenAI (GPT-4o), Anthropic (Claude 3.5), Ollama (로컬 LLM), DeepSeek, Gemini
```

### 📊 버전 호환성 매트릭스 (Compatibility Matrix)
| Spring Boot 버전 | 권장 Spring AI 버전 | Java 요구 사항 | 비고 |
| :--- | :--- | :--- | :--- |
| **Spring Boot 4.1.1 (현재 최신)** | **Spring AI 2.0.1 GA** | **Java 17, 21, 25, 26** | **공식 권장 최신 조합**, Maven Central 정식 배포, JSpecify 널 안전성 |
| Spring Boot 4.0.x | Spring AI 2.0.0 GA | Java 17, 21 | ToolCallingAdvisor 중앙화 도입 |
| Spring Boot 3.3.x / 3.4.x | Spring AI 1.0.0-M6 | Java 17+ | 구버전 마일스톤 레포지토리(`repo.spring.io/milestone`) 필요 |

### 🐘 Gradle (`build.gradle`) 설정
Spring Boot 4.1.1과 Spring AI 2.0.1은 **Maven Central에 정식 배포**되므로 별도의 마일스톤 저장소 추가 없이 즉시 빌드됩니다.
```groovy
plugins {
    id 'java'
    id 'org.springframework.boot' version '4.1.1' // 🚀 최신 Spring Boot 4.1.1
    id 'io.spring.dependency-management' version '1.1.7' // 🚀 최신 의존성 관리 플러그인
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25) // Java 25
    }
}

ext {
    // 🚀 Spring AI 2.0.1 GA (Spring Boot 4.x 공식 베이스라인)
    set('springAiVersion', "2.0.1")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    
    // 1. OpenAI 스타터 (Chat, Embedding, Image, Whisper, Vision 통합)
    implementation "org.springframework.ai:spring-ai-openai-spring-boot-starter"
    
    // 2. 또는 완전 무료 온프레미스 로컬 LLM (Ollama)
    // implementation "org.springframework.ai:spring-ai-ollama-spring-boot-starter"
    
    // 3. 또는 Anthropic Claude 스타터
    // implementation "org.springframework.ai:spring-ai-anthropic-spring-boot-starter"

    // 4. PostgreSQL PGvector 벡터 데이터베이스 연동
    // implementation "org.springframework.ai:spring-ai-pgvector-store-spring-boot-starter"
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.ai:spring-ai-bom:${springAiVersion}"
    }
}
```

### 🪶 Maven (`pom.xml`) 설정
```xml
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
    <relativePath/>
</parent>

<properties>
    <java.version>25</java.version>
    <spring-ai.version>2.0.1</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Maven Central에서 직접 다운로드됩니다 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
</dependencies>
```

## 2. application.yml 프로바이더별 설정 (OpenAI · Claude · Ollama · DeepSeek)
Spring Boot 4.1.1의 `application.yml`에 API 키와 모델 옵션을 지정하면 최적화된 `ChatModel`과 `EmbeddingModel`이 스프링 빈으로 자동 등록됩니다. 특히 긴 네트워크 I/O가 발생하는 AI 서비스 특성상 **가상 스레드(Virtual Threads)** 활성화를 적극 권장합니다.

### 🌐 OpenAI 및 호환 API (vLLM, Groq, DeepSeek)
```yaml
spring:
  # 🚀 Spring Boot 4.1.1 권장: AI I/O 대기 시 톰캣 스레드 고갈 방지 (초고성능 처리)
  threads:
    virtual:
      enabled: true

  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com # vLLM이나 Groq 등 OpenAI 호환 엔드포인트 지원
      chat:
        options:
          model: gpt-4o-mini # gpt-4o, o1-mini, gpt-4-turbo 등
          temperature: 0.7   # 0.0(정밀/논리) ~ 1.0(창의적)
          max-tokens: 4096
      embedding:
        options:
          model: text-embedding-3-small
    # 2.0.1 도구 보안 정책 (명시적 등록 도구만 격리 실행)
    tools:
      resolution:
        fallback:
          enabled: false # 보안 권장: 미등록 도구의 글로벌 디스패치 방지 (CVE-2026-59318 방어)
```

### 🦙 Ollama (로컬 오픈소스 LLM: Llama 3.1, DeepSeek-Coder, Qwen)
GPU/CPU 로컬 서버에서 API 비용 없이 완전 무료로 실행:
```yaml
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3.1:8b # deepseek-r1:8b, qwen2.5:7b 등
          temperature: 0.3
      embedding:
        options:
          model: nomic-embed-text
```

### 🟣 Anthropic Claude & Google Gemini
```yaml
spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-3-5-sonnet-20241022
          max-tokens: 8192
    vertex:
      ai:
        gemini:
          project-id: my-gcp-project
          location: us-central1
          chat:
            options:
              model: gemini-1.5-pro
```

## 3. ChatClient 2.0 Fluent API (현대적 대화형 모델 인터페이스)
Spring AI 2.0의 `ChatClient`는 모델 독립적(Model-agnostic)인 고수준 Fluent API입니다. 빌더를 통해 전역 시스템 프롬프트, 도구, 어드바이저 체인을 모듈식으로 장착합니다.

### 🛠️ ChatClient 빈 등록 (`@Configuration`)
```java
package com.lucky.ai.config;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AiConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                // 모든 대화에 기본 적용될 시스템 프롬프트
                .defaultSystem("당신은 친절하고 전문적인 IT 기술 컨설턴트입니다. 항상 명확한 한국어로 답변하세요.")
                // 모델 기본 파라미터 (온도, 토큰 등)
                .defaultOptions(options -> options.temperature(0.3))
                .build();
    }
}
```

### 💻 Controller에서 ChatClient 호출 실전
```java
@RestController
@RequestMapping("/api/chat")
@RequiredArgsConstructor
public class ChatController {

    private final ChatClient chatClient;

    // 1. 단일 프롬프트 문자열 응답
    @GetMapping("/simple")
    public String simpleChat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content(); // String 텍스트 반환
    }

    // 2. 동적 파라미터 치환 & 메타데이터(토큰, 비용) 획득
    @GetMapping("/expert")
    public ChatResponse expertChat(@RequestParam String topic, @RequestParam String lang) {
        return chatClient.prompt()
                .system(s -> s.text("전문 분야: {field}").param("field", "소프트웨어 아키텍처"))
                .user(u -> u.text("{topic}에 대해 {lang} 언어 관점에서 핵심 주의사항을 3줄 요약해줘.")
                            .param("topic", topic)
                            .param("lang", lang))
                .call()
                .chatResponse(); // ChatResponse: 토큰 사용량, FinishReason 등 전체 메타데이터
    }
}
```

## 4. 스트리밍(Streaming) & Server-Sent Events (SSE) 실시간 응답
모델의 긴 생성 시간을 기다리지 않고 실시간으로 생성되는 토큰을 화면에 즉시 스트리밍합니다. Spring AI 2.0의 `ChatClient.stream()`은 WebFlux `Flux<String>`과 완벽하게 호환됩니다.

### ⚡ Reactive 스트리밍 컨트롤러 (`Flux<String>`)
```java
package com.lucky.ai.controller;

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("/api/ai")
@RequiredArgsConstructor
public class StreamController {

    private final ChatClient chatClient;

    // text/event-stream 으로 실시간 글자 단위 방출
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String prompt) {
        return chatClient.prompt()
                .user(prompt)
                .stream()     // call() 대신 stream() 호출!
                .content();   // Flux<String> 실시간 스트림
    }
}
```

### 🌐 프론트엔드 실시간 SSE 수신 코드
```javascript
// 브라우저에서 Server-Sent Events 수신
const eventSource = new EventSource('/api/ai/stream?prompt=' + encodeURIComponent('Spring AI 2.0 장점'));

eventSource.onmessage = (event) => {
  // 실시간 토큰 누적 렌더링
  document.getElementById('chat-box').textContent += event.data;
};

eventSource.onerror = (err) => {
  console.log('응답 스트림 종료 또는 네트워크 해제');
  eventSource.close();
};
```

## 5. 구조화된 출력 (Structured Output & Record 매핑)
LLM의 자유로운 자연어 응답을 Java 17+ `Record`나 DTO 객체로 엄격하고 안전하게(Type-Safe) 자동 파싱합니다.

### 📋 응답 받을 Java Record 선언
```java
public record TechArticle(
    String title,
    String author,
    List<String> tags,
    int difficultyLevel,
    String summary
) {}

public record CurationResponse(
    String category,
    List<TechArticle> articles
) {}
```

### 🎯 `entity(...)`를 활용한 객체 자동 매핑
```java
@Service
@RequiredArgsConstructor
public class CurationService {

    private final ChatClient chatClient;

    // 단일 Record 자동 역직렬화
    public TechArticle getRecommendedArticle(String keyword) {
        return chatClient.prompt()
                .user(u -> u.text("{keyword} 분야의 베스트 아티클 정보를 추천해줘.")
                            .param("keyword", keyword))
                .call()
                .entity(TechArticle.class); // 내부 JSON 스키마 주입 및 자동 매핑!
    }

    // List 컬렉션 직접 매핑 (ParameterizedTypeReference)
    public List<TechArticle> getArticleList(String keyword) {
        return chatClient.prompt()
                .user(keyword + " 관련 최신 글 3편을 추천해줘.")
                .call()
                .entity(new ParameterizedTypeReference<List<TechArticle>>() {});
    }
}
```

## 6. 프롬프트 템플릿 & 메시지 역할 계층 (PromptTemplate & Roles)
반복되는 프롬프트 패턴을 파일(`.st` StringTemplate)로 분리 관리하고, 역할(System, User, Assistant)별 컨텍스트를 구조화합니다.

### 📝 PromptTemplate과 변수 주입
```java
import org.springframework.ai.chat.prompt.PromptTemplate;

@GetMapping("/review-diff")
public String reviewCodeDiff(@RequestParam String diffText) {
    String templateString = """
        당신은 코드 품질 감사 전문가입니다. 아래 Git Diff를 검토하고:
        1. 잠재적 버그
        2. 성능 병목 지점
        3. 리팩토링 권장 사항을 한국어로 작성하세요.
        
        [Git Diff]:
        {diff}
        """;

    PromptTemplate template = new PromptTemplate(templateString);
    Prompt prompt = template.create(Map.of("diff", diffText));

    return chatClient.prompt(prompt).call().content();
}
```

### 📂 외부 리소스 파일에서 프롬프트 로딩
`src/main/resources/prompts/sql-generator.st` 파일 관리:
```java
@RestController
public class SqlPromptController {

    @Value("classpath:prompts/sql-generator.st")
    private Resource sqlPromptResource;

    private final ChatClient chatClient;

    @PostMapping("/generate-sql")
    public String generateSql(@RequestBody String userQuery) {
        return chatClient.prompt()
                .user(u -> u.text(sqlPromptResource)
                            .param("query", userQuery)
                            .param("dialect", "PostgreSQL 16"))
                .call()
                .content();
    }
}
```

## 7. Spring AI 2.0 도구 호출 (@Tool & ToolCallingAdvisor)
Spring AI 2.0의 최대 변경 사항입니다! 이전의 복잡한 함수 등록 대신, **`@Tool` 어노테이션**을 메서드에 부여하고 `ChatClient.prompt().tools(...)`로 넘기면 `ToolCallingAdvisor`가 모델과의 도구 호출 루프를 완벽하게 자동 처리합니다.

```text
[Spring AI 2.0 도구 실행 루프]
1. 사용자 질문  : "서울 날씨와 환율 알려줘"
2. ChatClient   : 모델에 등록된 도구 스키마(@Tool) 전송
3. LLM 결정     : getWeatherTool(), getExchangeRateTool() 호출 요청
4. ToolCallingAdvisor : 스프링 내 Java 메서드 직접 실행 및 결과 취합
5. LLM 최종 응답: 취합된 도구 결과를 바탕으로 자연스러운 한국어 답변 완성
```

### 🛠️ 1. `@Tool` 컴포넌트 선언
```java
package com.lucky.ai.tools;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
public class ExternalApiTools {

    public record WeatherInfo(String city, double temperature, String condition) {}

    // @Tool: 모델이 읽을 수 있는 도구 설명 명시
    @Tool(description = "주어진 도시의 실시간 날씨와 온도를 조회합니다.")
    public WeatherInfo getWeather(
            @ToolParam(description = "조회할 도시 이름 (예: Seoul, Tokyo)") String city) {
        System.out.println("도구 실행됨: city = " + city);
        // 실제 기상청 API 연동 또는 DB 쿼리
        return new WeatherInfo(city, 23.5, "맑음");
    }

    @Tool(description = "통화 코드(USD, JPY 등)에 대한 현재 원화(KRW) 환율을 조회합니다.")
    public double getExchangeRate(@ToolParam(description = "통화 코드") String currency) {
        if ("USD".equalsIgnoreCase(currency)) return 1380.50;
        if ("JPY".equalsIgnoreCase(currency)) return 920.30;
        return 1000.0;
    }
}
```

### 🚀 2. ChatClient에서 도구 장착 및 실행
```java
@RestController
@RequiredArgsConstructor
public class AssistantController {

    private final ChatClient chatClient;
    private final ExternalApiTools apiTools; // @Tool 컴포넌트 주입

    @GetMapping("/ask-assistant")
    public String askAssistant(@RequestParam String query) {
        return chatClient.prompt()
                .user(query) // 예: "도쿄 날씨 알려주고 100달러는 원화로 얼마야?"
                // 2.0 표준: .tools(...)에 객체를 직접 전달하면 @Tool 메서드가 자동 바인딩!
                .tools(apiTools)
                .call()
                .content();
    }
}
```

## 8. RAG 완벽 가이드 (Ingestion · Embedding · VectorStore · Advisor)
사내 비공개 문서(사규, 매뉴얼, 정책 PDF)를 벡터 DB에 적재한 뒤, 사용자의 질문과 가장 유사한 문서를 찾아 LLM의 지식으로 보강하는 RAG(검색 증강 생성) 파이프라인입니다.

```text
[RAG 데이터 파이프라인]
1. Document Ingestion : PDF/Text 파일 읽기 (PagePdfDocumentReader, TextReader)
2. Text Splitting     : 청킹 (TokenTextSplitter: 500토큰 단위, 100토큰 오버랩)
3. Embedding          : 벡터 수치화 (EmbeddingModel: 1536차원 벡터 변환)
4. VectorStore Save   : pgvector, Chroma, Qdrant 등에 저장
5. Similarity Search  : 사용자 질문 벡터와 코사인 유사도 상위 K건 추출
6. QA Advisor         : 질문과 검색된 지식을 결합하여 환각(Hallucination) 없는 답변 생성
```

### 🗄️ 1. VectorStore 설정 (`application.yml` - PGvector)
```yaml
spring:
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW               # HNSW (초고속 근사 최근접 탐색)
        distance-type: COSINE_DISTANCE # 코사인 거리 측정
        dimensions: 1536               # OpenAI text-embedding-3-small 기준 차원
```

### 📥 2. 문서 수집 & 청킹 & 벡터 DB 적재 (ETL 서비스)
```java
@Service
@RequiredArgsConstructor
public class DocumentIngestionService {

    private final VectorStore vectorStore;

    public void ingestManual(Resource pdfFile) {
        // 1. PDF 문서 파싱
        PagePdfDocumentReader reader = new PagePdfDocumentReader(pdfFile);
        List<Document> documents = reader.get();

        // 2. 토큰 단위 텍스트 분할 (청킹)
        TokenTextSplitter splitter = new TokenTextSplitter(500, 100, 5, 10000, true);
        List<Document> chunks = splitter.apply(documents);

        // 3. 메타데이터 부착 (사후 필터링에 사용)
        chunks.forEach(c -> c.getMetadata().put("department", "HR"));

        // 4. 벡터 스토어에 적재 (임베딩 모델 자동 호출)
        vectorStore.accept(chunks);
    }
}
```

### 🔍 3. QuestionAnswerAdvisor를 통한 RAG 원스톱 질문
```java
@RestController
@RequiredArgsConstructor
public class RagController {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    @GetMapping("/ask-policy")
    public String askPolicy(@RequestParam String question) {
        return chatClient.prompt()
                .user(question)
                // Spring AI가 질문과 유사한 상위 문서를 찾아 프롬프트에 자동 주입
                .advisors(new QuestionAnswerAdvisor(
                        vectorStore,
                        SearchRequest.builder()
                                .topK(4)
                                .similarityThreshold(0.75) // 유사도 75% 이상만 채택
                                .build()
                ))
                .call()
                .content();
    }
}
```

## 9. 대화 메모리 (Chat Memory) & 어드바이저 (Advisor) 체인
Stateless한 HTTP 환경에서 사용자별 이전 대화 문맥(Multi-turn Chat)을 안전하게 유지하고 기억합니다.

### 🧠 1. ChatMemory 빈 등록 (인메모리 또는 Redis)
```java
@Configuration
public class ChatMemoryConfig {

    @Bean
    public ChatMemory chatMemory() {
        // 로컬/테스트 환경: 인메모리 저장소
        // 운영 환경: Redis(spring-ai-autoconfigure-model-chat-memory-repository-redis) 또는 JdbcChatMemory
        return new InMemoryChatMemory();
    }

    @Bean
    public ChatClient memoryChatClient(ChatClient.Builder builder, ChatMemory chatMemory) {
        return builder
                .defaultAdvisors(
                    // 사용자 세션별 최근 10개 메시지를 기억하여 자동 주입
                    new MessageChatMemoryAdvisor(chatMemory, "default", 10)
                )
                .build();
    }
}
```

### 💬 2. 사용자 ID(`conversationId`)별 세션 격리 대화
```java
@GetMapping("/chat")
public String chatWithUserMemory(
        @RequestParam String userId,
        @RequestParam String message) {

    return chatClient.prompt()
            .user(message)
            // 사용자별(userId)로 독립된 대화 맥락 유지
            .advisors(a -> a.param(ChatMemory.CONVERSATION_ID_ATTRIBUTE, userId))
            .call()
            .content();
}
```

### 🛡️ 3. 커스텀 어드바이저 (토큰 감사 및 로깅)
```java
public class AuditLoggingAdvisor implements RequestResponseAdvisor {

    @Override
    public AdvisedRequest adviseRequest(AdvisedRequest request, Map<String, Object> context) {
        System.out.println("🤖 [AI 요청] " + request.userText());
        return request;
    }

    @Override
    public ChatResponse adviseResponse(ChatResponse response, Map<String, Object> context) {
        var usage = response.getMetadata().getUsage();
        System.out.println("📊 [토큰 소비] 입력: " + usage.getPromptTokens() + 
                           " | 생성: " + usage.getGenerationTokens());
        return response;
    }

    @Override
    public int getOrder() { return 0; }
}
```

## 10. 멀티모달 (Multimodal: Vision 이미지 분석 & OCR)
GPT-4o, Claude 3.5 Sonnet, Gemini 등 비전 지원 모델에 이미지, 영수증, 도면 등을 전송하여 분석 및 텍스트 추출을 수행합니다.

### 🖼️ 이미지 분석 및 데이터 추출
```java
@RestController
@RequiredArgsConstructor
public class VisionController {

    private final ChatClient chatClient;

    // 1. URL 기반 이미지 질의
    @GetMapping("/analyze-chart")
    public String analyzeChartUrl() throws MalformedURLException {
        var imageUrl = new URI("https://luckytechworld.pe.kr/samples/sales-chart.png").toURL();
        var media = new Media(MimeTypeUtils.IMAGE_PNG, imageUrl);

        return chatClient.prompt()
                .user(u -> u.text("이 매출 그래프에서 가장 성장이 두드러진 분기를 분석하고 인사이트를 도출해줘.")
                            .media(media))
                .call()
                .content();
    }

    // 2. 사용자가 업로드한 영수증/인보이스 OCR 분석 (Record 매핑)
    public record InvoiceData(String vendor, String date, int totalAmount, List<String> items) {}

    @PostMapping(value = "/invoice", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public InvoiceData parseInvoice(@RequestParam("file") MultipartFile file) {
        var media = new Media(
            MimeTypeUtils.parseMimeType(file.getContentType()), 
            file.getResource()
        );

        return chatClient.prompt()
                .user(u -> u.text("영수증 이미지에서 공급자, 일자, 총액, 품목을 JSON 스키마에 맞춰 추출하세요.")
                            .media(media))
                .call()
                .entity(InvoiceData.class); // Java Record로 자동 역직렬화!
    }
}
```

## 11. 오디오 (Whisper STT / Speech TTS) & 이미지 생성 (DALL-E)
Spring AI는 텍스트 대화 모델뿐 아니라 음성 전사(STT), 음성 합성(TTS), 이미지 생성 모델도 표준 인터페이스로 제공합니다.

### 🎙️ 1. Whisper 음성 전사 (STT - Speech to Text)
```java
@Autowired
private OpenAiAudioTranscriptionModel transcriptionModel;

public String convertAudioToText(Resource audioFile) {
    var options = OpenAiAudioTranscriptionOptions.builder()
            .language("ko") // 한국어 전사 최적화
            .temperature(0.2f)
            .responseFormat(OpenAiAudioApi.TranscriptResponseFormat.TEXT)
            .build();

    AudioTranscriptionPrompt prompt = new AudioTranscriptionPrompt(audioFile, options);
    AudioTranscriptionResponse response = transcriptionModel.call(prompt);
    return response.getResult().getOutput();
}
```

### 🔊 2. TTS 텍스트 음성 합성 (Text to Speech)
```java
@Autowired
private OpenAiAudioSpeechModel speechModel;

public byte[] synthesizeSpeech(String text) {
    var options = OpenAiAudioSpeechOptions.builder()
            .voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY) // alloy, echo, fable, onyx, nova, shimmer
            .speed(1.0f)
            .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
            .build();

    TextToSpeechPrompt prompt = new TextToSpeechPrompt(text, options);
    return speechModel.call(prompt).getResult().getOutput(); // MP3 바이너리 바이트 반환
}
```

### 🎨 3. DALL-E 3 이미지 생성
```java
@Autowired
private ImageModel imageModel;

public String generateImage(String promptText) {
    ImageResponse response = imageModel.call(
        new ImagePrompt(
            promptText,
            OpenAiImageOptions.builder()
                .quality("hd")
                .model("dall-e-3")
                .width(1024)
                .height(1024)
                .build()
        )
    );
    return response.getResult().getOutput().getUrl(); // 생성된 이미지 CDN URL 반환
}
```

## 12. 평가(Evaluation), 모니터링(Observability) & 프로덕션 보안
Spring AI 2.0.1 기반 엔터프라이즈 프로덕션 환경에서 요구되는 관측성(Micrometer) 및 보안 모범 사례입니다.

### 📊 Micrometer & Prometheus 관측성 (Observability)
Spring AI는 별도 코드 작성 없이 모델 호출 시간, 성공률, 토큰 사용량을 표준 메트릭으로 노출합니다.
```yaml
management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, prometheus
  metrics:
    export:
      prometheus:
        enabled: true
```
* `gen_ai.client.token.usage` : 모델별 프롬프트/응답 토큰 소비 수량 추적
* `gen_ai.client.operation.duration` : LLM API 호출 레이턴시 백분위수(p95, p99)

### 🛡️ Spring AI 2.0.1 보안 & 운영 핵심 체크리스트
```text
1. 도구 실행 보안   : 2.0.1부터 spring.ai.tools.resolution.fallback.enabled=false 기본값으로 
                     명시적으로 .tools()에 넘긴 도구만 실행하여 원격 도구 탈취 방지 (CVE-2026-59318)
2. API 키 보호     : Git 커밋 절대 금지. Vault, AWS Secrets Manager 또는 환경변수 주입
3. 프롬프트 인젝션 : 사용자 입력을 SystemMessage와 분리하고 UserMessage 매개변수로 주입
4. 서킷 브레이커   : Resilience4j와 연동하여 LLM 장애 시 Fallback 고정 응답 반환
5. 타임아웃 방어   : RestClient의 readTimeout을 반드시 30~60초로 명시 (무한 블로킹 방지)
```

### ⏱️ RestClient 타임아웃 커스텀 빈
```java
@Bean
public RestClientCustomizer restClientCustomizer() {
    return restClientBuilder -> restClientBuilder
            .requestFactory(new SimpleClientHttpRequestFactory() {{
                setConnectTimeout(Duration.ofSeconds(10)); // 연결 제한 10초
                setReadTimeout(Duration.ofSeconds(60));    // 응답 대기 제한 60초
            }});
}
```
💬
Spring AI 치트시트

의견 및 질문

댓글 수정

댓글 삭제
