01 · Converse API — 대화형 추론의 표준 인터페이스
한 문장 요약: Converse API는 모든 Bedrock 메시지 지원 모델에서 동일하게 작동하는 통일된 대화형 추론 API로, 모델 교체 시 코드 재작성 없이 요청 구조(messages·system·inferenceConfig)와 정규화된 응답(output·stopReason·usage·metrics)만 다루면 되게 만든 것이 목적이다.
- 태스크: T-DOC-01 · 연계 주차: 2주차(모델 통합)
- 원본: docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/conversation-inference.html (2026-11-18 수집·본문 30,466자)
- 원문 사본:
downloads/03-converse/conversation-inference.html
개요
Converse API는 bedrock-runtime 엔드포인트에서만 사용 가능하며, Converse(단일 응답)와 ConverseStream(스트리밍) 두 작업으로 모델과 메시지를 주고받는다. 기존 InvokeModel/InvokeModelWithResponseStream도 대화 애플리케이션에 사용할 수 있으나, Converse는 메시지를 지원하는 모든 모델에서 일관된 API를 제공한다 — 코드를 한 번만 작성하면 다른 모델에서도 사용할 수 있다. 모델 고유 추론 파라미터는 additionalModelRequestFields로 전달하고, 도구 사용·가드레일도 이 API로 구현한다.
핵심 메시지 3
1. "한 번 쓰면 모델 간 이동이 된다" — 응답은 모델 네이티브 필드를 버리고 output·usage·stopReason·metrics의 정규화된 봉투로 반환한다(네이티브 필드 필요 시 additionalModelResponseFieldPaths에 JSON 포인터로 지정).
2. 대화 컨텍스트는 응답자가 관리한다 — 후속 요청에 지금까지의 모든 메시지를 messages 배열로 되보내고 role(user/assistant)로 순서를 구분한다. API가 세션을 보관하지 않는다.
3. 데이터는 저장되지 않는다(공식 서술) — "Amazon Bedrock은 사용자가 내용으로 제공하는 텍스트, 이미지 또는 문서를 저장하지 않습니다. 데이터는 응답을 생성하는 용도로만 사용됩니다." (도메인 3 보안 문제의 근거 문구)
주제별 심화
요청 필드 구조
| 필드 | 용도 | 비고 |
|---|---|---|
modelId | 대상 모델 (헤더 필수) | — |
messages | role + ContentBlock 배열 | 대화의 본체 |
system | 시스템 프롬프트(지침·페르소나) | 예: "라디오 방송국 플레이리스트 앱…" |
inferenceConfig | 공통 추론 파라미터 | maxTokens·stopSequences·temperature·topP |
additionalModelRequestFields | 모델 고유 파라미터 | 예: Claude의 top_k |
guardrailConfig | 가드레일 적용 | 블록 단위 지정 시 guardContent |
toolConfig | 도구 정의 | Tool Use의 진입점 |
serviceTier | 서비스 계층 | reserved·priority·default·flex |
requestMetadata | 호출 로그 필터용 태그 | 팀·앱·환경별 집계 |
ContentBlock 종류 (messages.content)
| 블록 | 핵심 규칙 |
|---|---|
text | 기본 프롬프트 문자열 |
image | base64 bytes(Nova는 S3 URI도 가능 — 다른 모델은 검증 오류로 거부) |
document | format 필수(누락 시 ValidationException) · name은 프롬프트 인젝션 취약 → 중립 이름 권장 · citations 활성화 시 txt·pdf만 |
video | mp4 등 · Nova만 S3 URI 지원 · 수임 역할에 s3:GetObject 권한 필요 |
cachePoint | 프롬프트 캐싱 체크포인트 — 대화 컨텍스트 캐싱으로 비용·지연 절감 |
guardContent | 가드레일이 평가할 입력으로 국한 — 미지정 시 전체 메시지 평가 |
reasoningContent | 추론 모델용 — signature로 변조 방지, 후속 요청에 서명+이전 메시지 그대로 포함 필요(변경 시 오류) |
toolUse / toolResult | 도구 호출 사이클 (도구 사용 문서 참조) |
응답·스트림 구조
- Converse 응답:
output.message(role=assistant + content) ·stopReason(예: end_turn, max_tokens) ·usage(inputTokens/outputTokens/totalTokens) ·metrics.latencyMs. 캐싱 사용 시cacheReadInputTokens/cacheWriteInputTokens추가. - 공식 예제 수치: input 125 + output 60 = total 185 토큰, latency 1175ms
- ConverseStream 이벤트 순서:
messageStart→ (블록별)contentBlockStart(도구 전용) →contentBlockDelta(text/reasoning/toolUse 부분 JSON) →contentBlockStop→messageStop(stopReason) →metadata(usage+metrics).contentBlockIndex로 블록별 이벤트를 상호 연관시킨다. - 스트림 예제 수치: 47+20=67 토큰, latency 100ms, stopReason=max_tokens
프롬프트 관리(promptVariables) 사용 시 제한
프롬프트 관리 프롬프트를 modelId로 지정하면 additionalModelRequestFields·inferenceConfig·system·toolConfig를 함께 포함할 수 없다.
IAM 권한
Converse 직접 호출 → bedrock:InvokeModel / ConverseStream → bedrock:InvokeModelWithResponseStream.
적용 체크리스트 (시험·실습 관점)
- ☐ messages-role-content 3층 구조를 그림 없이 쓸 수 있는가 (도메인 2)
- ☐ temperature·topP·maxTokens·stopSequences가 inferenceConfig의 공통 4종임을 암기했는가
- ☐ 대화 유지 방식(전체 메시지 재전송 + role 구분)을 설명할 수 있는가
- ☐ "Bedrock은 입력 텍스트·이미지·문서를 저장하지 않는다"는 공식 서술을 기억하는가 (도메인 3)
- ☐ reasoningContent의 signature 규칙(변경 시 오류)을 아는가
- ☐ cachePoint·serviceTier(flex 등)가 비용 최적화 수단임을 연결할 수 있는가 (도메인 4)
최종 정리
시험에서 Converse는 "모델 간 일관성"이라는 키워드로 출제된다 — 요청은 messages·system·inferenceConfig, 응답은 정규화된 4종(output·stopReason·usage·metrics). 나머지 필드는 이 축에 붙는 확장(도구·가드레일·캐싱·서비스 계층)이다. 실습에서는 boto3 converse() 예제(문서 포함 Python 전문 수록)를 그대로 돌려보고 usage·latency를 확인하는 것이 최단 경로다.
Provenance: 원문 인용·수치는 2026-11-18 수집 본문 기준. 기계 번역 한국어 문서로, 원문 영어와 상충 시 영어가 우선(원문 고지). 해석·체크리스트는 학습용 편집임.