로드 중
로드 중

AWS Bedrock에 첫 번째 API 요청을 보내려면 세 가지 필수 구성 요소가 필요합니다: 서비스에 연결하기 위한 Bedrock Runtime Client, 실행할 모델을 지정하는 Model ID, 그리고 모델에 입력할 텍스트를 담은 User Message입니다.

Bedrock 클라이언트 설정하기

클라이언트는 모든 요청에 AWS 자격 증명으로 서명하므로, 시작하기 전에 이를 설정해야 합니다. AWS CLI를 설치한 다음, aws configure 또는 AWS CLI 자격 증명 가이드에 나와 있는 다른 방법으로 자격 증명을 설정하세요. 자격 증명이 없으면 첫 번째 요청이 NoCredentialsError와 함께 중단됩니다.

pip install boto3로 boto3를 설치하세요. 그런 다음 Bedrock 런타임 서비스에 연결할 클라이언트를 생성합니다:

python
import boto3

client = boto3.client("bedrock-runtime", region_name="us-west-2")

모델 ID와 리전별 가용성 이해하기

여기서부터 까다로워집니다. 모든 모델이 모든 AWS 리전에서 사용 가능한 것은 아닙니다. 선택한 리전에 존재하지 않는 모델을 실행하려고 하면, 모델이 존재하지 않는다는 알 수 없는 오류 메시지가 나타납니다.

모델 ID "anthropic.claude-v1"을 실행하라는 요청이 AWS 리전 us-west-2에 도착하며, 해당 리전에서 이 모델의 이름은 Claude Sonnet입니다.

예를 들어, Claude Sonnet이 us-west-2에서 사용 가능하지만 us-east-1에서 요청을 보내는 경우, 요청이 실패합니다.

모델 ID "anthropic.claude-v1"을 실행하라는 요청이 모델이 없는 us-east-1에서는 오류를 반환하지만, us-west-2에서는 정상 작동합니다.

추론 프로필 사용하기

추론 프로필(Inference profile)은 선택한 모델이 실제로 호스팅되는 리전으로 요청을 자동으로 라우팅하여 리전별 가용성 문제를 해결합니다.

US Anthropic Claude Sonnet이라는 예시 추론 프로필: 프로필 ID us.profile.claude-v1, 모델 ID anthropic.claude-v1.

어떤 모델이 어떤 리전에 있는지 일일이 추적하는 대신, 모델이 us-west-2와 us-east-2 같은 여러 리전에서 사용 가능하다는 것을 알고 있는 추론 프로필을 사용할 수 있습니다.

us-east-1에서 추론 프로필 "us.profile.claude-v1"을 실행하라는 요청이 us-west-2의 anthropic.claude-v1으로 라우팅됩니다.

추론 프로필을 사용하여 요청을 보내면, 다른 리전에서 연결하고 있더라도 AWS가 모델이 존재하는 올바른 리전으로 자동으로 요청을 라우팅합니다.

추론 프로필 ID를 찾으려면, 기본 모델 카탈로그 페이지에서 모델 ID를 사용하는 대신 AWS Bedrock 콘솔로 이동하여 "Cross-region inference" 항목을 확인하세요.

AWS Bedrock 콘솔의 Cross-region inference 페이지로, 각 프로필 ID 옆에 복사 버튼이 있는 추론 프로필 목록을 보여줍니다.

선택한 모델의 추론 프로필 ID를 복사하세요. 이 과정의 예제에서는 Claude Haiku 4.5를 사용하며, 해당 추론 프로필 ID는 us.anthropic.claude-haiku-4-5-20251001-v1:0입니다:

python
model_id = "us.anthropic.claude-haiku-4-5-20251001-v1:0"

User Message 생성하기

User message는 처음에는 지나치게 복잡해 보일 수 있는 특정 구조를 가지고 있지만, 여기에는 타당한 이유가 있습니다:

python
user_message = {
    "role": "user",
    "content": [
        {"text": "What's 1+1?"}
    ]
}

content가 리스트인 이유는 하나의 메시지가 텍스트, 이미지 또는 다른 미디어 유형 등 다양한 유형의 콘텐츠를 포함할 수 있기 때문입니다. 이 구조를 통해 멀티모달 요청을 보낼 수 있습니다.

content 리스트에 png 형식의 소스 바이트를 가진 이미지 블록과 "What's in this image?"라는 텍스트가 담긴 user message.

요청 보내기

이제 converse 메서드를 사용하여 API 호출을 할 수 있습니다:

python
response = client.converse(
    modelId=model_id,
    messages=[user_message]
)

응답에는 많은 메타데이터가 포함되어 있지만, 생성된 텍스트만 가져오려면 응답 구조를 탐색해야 합니다:

python
response["output"]["message"]["content"][0]["text"]

메시지 유형 이해하기

다루게 될 주요 메시지 유형은 두 가지입니다:

  • User messages - 모델에 입력하고자 하는 콘텐츠입니다 (role: "user")
  • Assistant messages - 모델이 생성한 콘텐츠입니다 (role: "assistant")

채팅 창에서 "Define quantum computing" 메시지를 user message로, AI의 답변을 assistant message로 표시하는 모습.

두 메시지 유형 모두 role과 content 리스트로 이루어진 동일한 구조를 따릅니다. 이러한 일관성 덕분에 user message와 assistant message를 번갈아 가며 대화를 쉽게 구성할 수 있습니다.

Bedrock에서 받는 assistant message는 role만 다를 뿐 user message와 정확히 동일한 형식을 따릅니다. 이러한 표준화된 구조 덕분에 더 긴 대화를 위해 여러 요청을 간단하게 연결할 수 있습니다.