Amazon Bedrock Converse API

추론에 필요한 대화형 AI 모델을 한 곳에서 다루는 데 AWS Bedrock의 Converse API를 쓰게 되는 경우가 많아요. 이 API는 대화형 모델을 위한 통일된 인터페이스를 제공하면서, 함수·도구 호출, 멀티모달 입력, 스트리밍 응답 같은 고급 기능까지 함께 지원해요. Spring AI는 이 Converse API를 기반으로 Bedrock의 채팅 모델들을 통합해요.

출처: 공식문서

Bedrock Converse API가 가진 기능

Converse API는 대화 흐름을 처리하는 데 필요한 요소를 대부분 갖추고 있어요.

도구/함수 호출: 대화 중에 함수 정의와 도구 사용을 지원해요.
멀티모달 입력: 대화에서 텍스트와 이미지를 함께 처리할 수 있어요.
스트리밍 지원: 모델 응답을 실시간으로 스트리밍해요.
시스템 메시지: 시스템 수준의 지시와 맥락 설정을 지원해요.

Converse API는 여러 모델 제공자를 하나의 인터페이스로 묶으면서, AWS 특유의 인증과 인프라 문제는 알아서 처리해줘요. 현재 Converse API가 지원하는 모델로는 Amazon Titan, Amazon Nova, AI21 Labs, Anthropic Claude, Cohere Command, Meta Llama, Mistral AI가 있어요.

Bedrock의 권고에 따라 Spring AI도 모든 채팅 대화 구현을 Converse API로 전환하고 있어요. 기존의 InvokeModel API가 대화 애플리케이션을 지원하긴 하지만, 채팅 대화 모델에는 Converse API를 쓰는 걸 권장해요. 한 가지 짚을 점은 Converse API는 임베딩 연산을 지원하지 않는다는 거예요. 그래서 임베딩 모델 기능은 기존 InvokeModel API에 계속 유지돼요.

자동 설정 (Auto-configuration)

Spring AI의 자동 설정과 스타터 모듈의 아티팩트 이름이 크게 바뀌었어요. 자세한 내용은 업그레이드 노트를 확인해주세요.

프로젝트의 Maven pom.xml이나 Gradle build.gradle에 spring-ai-starter-model-bedrock-converse 의존성을 추가하면 자동 설정이 활성화돼요.

Maven
Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-bedrock-converse</artifactId>
</dependency>

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-bedrock-converse'
}

채팅 속성 (Chat Properties)

AWS Bedrock에 연결하기 위한 속성 프리픽스는 spring.ai.bedrock.aws예요.

Chat Properties | 속성 | 설명 | 기본값 | |---|---|---| | spring.ai.bedrock.aws.region | 사용할 AWS 리전 | us-east-1 | | spring.ai.bedrock.aws.timeout | 전체 API 호출의 최대 지속 시간 | 5m | | spring.ai.bedrock.aws.connection-timeout | 연결을 맺는 동안 기다리는 최대 시간 | 5s | | spring.ai.bedrock.aws.connection-acquisition-timeout | 풀에서 새 연결을 얻기 위해 기다리는 최대 시간 | 30s | | spring.ai.bedrock.aws.async-read-timeout | 비동기 응답을 읽는 최대 시간 | 30s | | spring.ai.bedrock.aws.access-key | AWS 액세스 키 | - | | spring.ai.bedrock.aws.secret-key | AWS 시크릿 키 | - | | spring.ai.bedrock.aws.session-token | 임시 자격 증명용 AWS 세션 토큰 | - | | spring.ai.bedrock.aws.profile.name | AWS 프로필 이름 | - | | spring.ai.bedrock.aws.profile.credentials-path | AWS 자격 증명 파일 경로 | - | | spring.ai.bedrock.aws.profile.configuration-path | AWS 설정 파일 경로 | - |

채팅 자동 설정의 활성·비활성은 이제 spring.ai.model.chat 프리픽스로 관리해요. 활성화하려면 spring.ai.model.chat=bedrock-converse(기본값으로 활성), 비활성화하려면 spring.ai.model.chat=none(또는 bedrock-converse와 일치하지 않는 값)을 쓰면 돼요. 이렇게 바뀐 건 여러 모델을 구성할 수 있게 하기 위해서예요.

Converse API의 채팅 모델 구현을 구성하는 속성 프리픽스는 spring.ai.bedrock.converse.chat이에요.

속성	설명	기본값
spring.ai.bedrock.converse.chat.enabled (제거됨, 더는 유효하지 않음)	Bedrock Converse 채팅 모델 활성화	true
spring.ai.model.chat	Bedrock Converse 채팅 모델 활성화	bedrock-converse
spring.ai.bedrock.converse.chat.model	사용할 모델 ID	없음. AWS Bedrock 콘솔에서 modelId를 선택하세요
spring.ai.bedrock.converse.chat.temperature	출력의 무작위성을 제어. [0.0,1.0] 범위	0.8
spring.ai.bedrock.converse.chat.top-p	샘플링 시 고려할 최대 누적 토큰 확률	AWS Bedrock 기본값
spring.ai.bedrock.converse.chat.top-k	다음 토큰 생성에 선택할 토큰 개수	AWS Bedrock 기본값
spring.ai.bedrock.converse.chat.max-tokens	생성된 응답의 최대 토큰 수	500

런타임 옵션

이식 가능한 ChatOptions나 BedrockChatOptions 빌더로 temperature, maxToken, topP 같은 모델 구성을 만들 수 있어요.

시작 시 기본 옵션은 BedrockConverseProxyChatModel(api, options) 생성자나 spring.ai.bedrock.converse.chat.* 속성으로 구성해요. 런타임에는 Prompt 호출에 요청별 옵션을 추가해 기본값을 덮어쓸 수 있어요.

var options = BedrockChatOptions.builder()
        .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
        .temperature(0.6)
        .maxTokens(300)
        .toolCallbacks(List.of(FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
            .description("Get the weather in location. Return temperature in 36°F or 36°C format. Use multi-turn if needed.")
            .inputType(WeatherService.Request.class)
            .build()))
        .build();

String response = ChatClient.create(this.chatModel)
    .prompt("What is current weather in Amsterdam?")
    .options(options)
    .call()
    .content();

프롬프트 캐싱

AWS Bedrock의 프롬프트 캐싱 기능을 쓰면 자주 쓰는 프롬프트를 캐시해 반복 상호작용의 비용을 줄이고 응답 속도를 높일 수 있어요. 프롬프트를 캐시하면 이후 동일한 요청이 캐시된 내용을 재사용해서, 처리되는 입력 토큰 수가 크게 줄어요.

지원 모델 — AWS Bedrock의 Claude 3.x, Claude 4.x, Amazon Nova 모델에서 프롬프트 캐싱을 지원해요. 토큰 요구사항 — 모델마다 캐시 효과를 위한 최소 토큰 임계값이 달라요. Claude Sonnet 4와 대부분의 모델은 1024+ 토큰이 필요해요. 모델별 요구사항은 다를 수 있으니 AWS Bedrock 문서를 참고하세요.

캐시 전략

Spring AI는 BedrockCacheStrategy enum을 통해 전략적으로 캐시 배치를 제공해요.

NONE: 프롬프트 캐싱을 완전히 비활성화 (기본값)
SYSTEM_ONLY: 시스템 메시지 내용만 캐시
TOOLS_ONLY: 도구 정의만 캐시 (Claude 모델 전용)
SYSTEM_AND_TOOLS: 시스템 메시지와 도구 정의를 모두 캐시 (Claude 모델 전용)
CONVERSATION_HISTORY: 채팅 메모리 시나리오에서 전체 대화 기록을 캐시

이런 전략적 접근은 AWS Bedrock의 4-breakpoint 제한 안에서 최적의 캐시 지점 배치를 보장해요.

Amazon Nova 제약 — Amazon Nova 모델(Nova Micro, Lite, Pro, Premier)은 system과 messages 콘텐츠에 대해서만 캐싱을 지원해요. tools 캐싱은 지원하지 않아요. Nova 모델에 TOOLS_ONLY나 SYSTEM_AND_TOOLS 전략을 쓰면 AWS가 ValidationException을 반환해요. Amazon Nova 모델에는 SYSTEM_ONLY 전략을 사용하세요.

프롬프트 캐싱 활성화

BedrockChatOptions에 cacheOptions를 설정하고 strategy를 선택하면 돼요.

시스템 전용 캐싱

가장 흔한 사용 사례예요. 시스템 지시를 여러 요청에 걸쳐 캐시해요.

// Cache system message content
ChatResponse response = chatModel.call(
    new Prompt(
        List.of(
            new SystemMessage("You are a helpful AI assistant with extensive knowledge..."),
            new UserMessage("What is machine learning?")
        ),
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
                .build())
            .maxTokens(500)
            .build()
    )
);

도구 전용 캐싱

시스템 프롬프트는 동적으로 유지하면서 큰 도구 정의를 캐시해요 (Claude 모델 전용).

// Cache tool definitions only
ChatResponse response = chatModel.call(
    new Prompt(
        "What's the weather in San Francisco?",
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.TOOLS_ONLY)
                .build())
            .toolCallbacks(weatherToolCallbacks)  // Large tool definitions
            .maxTokens(500)
            .build()
    )
);

이 전략은 Claude 모델에서만 지원돼요. Amazon Nova 모델은 ValidationException을 반환해요.

시스템·도구 함께 캐싱

최대 재사용을 위해 시스템 지시와 도구 정의를 모두 캐시해요 (Claude 모델 전용).

// Cache system message and tool definitions
ChatResponse response = chatModel.call(
    new Prompt(
        List.of(
            new SystemMessage("You are a weather analysis assistant..."),
            new UserMessage("What's the weather like in Tokyo?")
        ),
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(weatherToolCallbacks)
            .maxTokens(500)
            .build()
    )
);

이 전략은 2개의 캐시 breakpoint(도구용 1개, 시스템용 1개)를 사용해요. Claude 모델에서만 지원돼요.

대화 기록 캐싱

멀티턴 챗봇과 어시스턴트를 위해 점점 커지는 대화 기록을 캐시해요.

// Cache conversation history with ChatClient and memory
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultSystem("You are a personalized career counselor...")
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
    .build();

String response = chatClient.prompt()
    .user("What career advice would you give me?")
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
    .options(BedrockChatOptions.builder()
        .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
        .cacheOptions(BedrockCacheOptions.builder()
            .strategy(BedrockCacheStrategy.CONVERSATION_HISTORY)
            .build())
        .maxTokens(500)
        .build())
    ...

멀티모달

Bedrock의 Converse API는 대화에서 이미지와 비디오 같은 미디어 입력을 처리할 수 있어요. 예를 들어 비디오 파일을 입력으로 보내고 내용을 설명하도록 요청할 수 있어요.

String response = ChatClient.create(chatModel)
    .prompt()
    .user(u -> u.text("Explain what do you see in this video?")
        .media(Media.Format.VIDEO_MP4, new ClassPathResource("/test.video.mp4")))
    .call()
    .content();

logger.info(response);

test.video.mp4 이미지를 입력으로 받아 텍스트 메시지와 함께 보내면, 응답으로 비디오 내용 설명이 돌아와요.

문서 (Documents)

일부 모델에서는 Bedrock이 Converse API의 문서 지원을 통해 payload에 문서를 포함할 수 있게 해줘요. 문서 지원은 바이트로 제공되며 두 종류가 있어요.

텍스트 문서 유형 (txt, csv, html, md 등): 텍스트 이해에 초점을 맞춰요. 문서의 텍스트 요소를 기반으로 답변하는 데 쓰여요.
미디어 문서 유형 (pdf, docx, xlsx): 시각 기반 이해에 초점을 맞춰 차트·그래프 등을 기반으로 답변해요.

현재 Anthropic의 PDF 지원(beta)과 Amazon Bedrock Nova 모델이 문서 멀티모달리티를 지원해요.

사용자 텍스트와 미디어 문서를 결합한 간단한 예시를 볼게요.

String response = ChatClient.create(chatModel)
    .prompt()
    .user(u -> u.text(
            "You are a very professional document summarization specialist. Please summarize the given document.")
        .media(Media.Format.DOC_PDF, new ClassPathResource("/spring-ai-reference-overview.pdf")))
    .call()
    .content();

logger.info(response);

spring-ai-reference-overview.pdf 문서를 입력으로 받아 전문적인 문서 요약 문구를 보내면, 요약 결과가 응답으로 돌아와요.

샘플 컨트롤러

새 Spring Boot 프로젝트를 만들고 spring-ai-starter-model-bedrock-converse를 의존성에 추가해요.

src/main/resources 아래에 application.properties 파일을 추가해요.

spring.ai.bedrock.aws.region=eu-central-1
spring.ai.bedrock.aws.timeout=10m
spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID}
spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY}
# session token is only required for temporary credentials
spring.ai.bedrock.aws.session-token=${AWS_SESSION_TOKEN}

spring.ai.bedrock.converse.chat.temperature=0.8
spring.ai.bedrock.converse.chat.top-k=15

채팅 모델을 사용하는 예시 컨트롤러를 볼게요.

@RestController
public class ChatController {

    private final ChatClient chatClient;

    @Autowired
    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatClient.prompt(message).call().content());
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return this.chatClient.prompt(message).stream().content();
    }
}

Amazon Bedrock Converse API