AWS 생성형 AI 자격증 학습요약본원본·요약본 목록은 자료실 페이지에서

01 · Converse API — 대화형 추론의 표준 인터페이스

한 문장 요약: Converse API는 모든 Bedrock 메시지 지원 모델에서 동일하게 작동하는 통일된 대화형 추론 API로, 모델 교체 시 코드 재작성 없이 요청 구조(messages·system·inferenceConfig)와 정규화된 응답(output·stopReason·usage·metrics)만 다루면 되게 만든 것이 목적이다.

개요

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대상 모델 (헤더 필수)—
messagesrole + 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기본 프롬프트 문자열
imagebase64 bytes(Nova는 S3 URI도 가능 — 다른 모델은 검증 오류로 거부)
documentformat 필수(누락 시 ValidationException) · name은 프롬프트 인젝션 취약 → 중립 이름 권장 · citations 활성화 시 txt·pdf만
videomp4 등 · Nova만 S3 URI 지원 · 수임 역할에 s3:GetObject 권한 필요
cachePoint프롬프트 캐싱 체크포인트 — 대화 컨텍스트 캐싱으로 비용·지연 절감
guardContent가드레일이 평가할 입력으로 국한 — 미지정 시 전체 메시지 평가
reasoningContent추론 모델용 — signature로 변조 방지, 후속 요청에 서명+이전 메시지 그대로 포함 필요(변경 시 오류)
toolUse / toolResult도구 호출 사이클 (도구 사용 문서 참조)

응답·스트림 구조

프롬프트 관리(promptVariables) 사용 시 제한

프롬프트 관리 프롬프트를 modelId로 지정하면 additionalModelRequestFields·inferenceConfig·system·toolConfig를 함께 포함할 수 없다.

IAM 권한

Converse 직접 호출 → bedrock:InvokeModel / ConverseStream → bedrock:InvokeModelWithResponseStream.

적용 체크리스트 (시험·실습 관점)

최종 정리

시험에서 Converse는 "모델 간 일관성"이라는 키워드로 출제된다 — 요청은 messages·system·inferenceConfig, 응답은 정규화된 4종(output·stopReason·usage·metrics). 나머지 필드는 이 축에 붙는 확장(도구·가드레일·캐싱·서비스 계층)이다. 실습에서는 boto3 converse() 예제(문서 포함 Python 전문 수록)를 그대로 돌려보고 usage·latency를 확인하는 것이 최단 경로다.


Provenance: 원문 인용·수치는 2026-11-18 수집 본문 기준. 기계 번역 한국어 문서로, 원문 영어와 상충 시 영어가 우선(원문 고지). 해석·체크리스트는 학습용 편집임.