Amazon Bedrock API 요청 완벽 가이드: 파라미터와 페이로드 구조 총정리

TL;DR: Amazon Bedrock API를 통해 텍스트를 생성하려면 모델 ID, 프롬프트, 온도(temperature), 최대 토큰 수 등의 파라미터를 포함한 JSON 페이로드를 구성하고 InvokeModel 엔드포인트로 POST 요청을 보내면 됩니다.

Amazon Bedrock이란 무엇인가?

Amazon Bedrock은 AWS가 제공하는 완전 관리형 AI 서비스로, Anthropic의 Claude, Meta의 Llama, AI21 Labs의 Jurassic, Cohere, Stability AI 등 다양한 파운데이션 모델(Foundation Model)을 단일 API를 통해 사용할 수 있게 해줍니다. 개발자는 복잡한 인프라 구축 없이 바로 최첨단 AI 모델을 애플리케이션에 통합할 수 있습니다.

Amazon Bedrock의 가장 큰 장점은 일관된 API 인터페이스를 통해 여러 모델을 손쉽게 전환하고 비교할 수 있다는 점입니다. 또한 AWS의 보안 및 컴플라이언스 체계 안에서 데이터를 안전하게 처리할 수 있어 기업 환경에서도 적극 활용됩니다.

API 요청 전 준비사항

Amazon Bedrock API를 호출하기 전에 몇 가지 준비 단계가 필요합니다.

• AWS 계정 및 IAM 권한 설정: Bedrock 서비스에 접근하기 위한 IAM 역할과 정책이 필요합니다. bedrock:InvokeModel 권한이 반드시 포함되어야 합니다.

• 모델 액세스 신청: AWS 콘솔에서 사용하려는 모델에 대한 액세스를 별도로 신청해야 합니다. 일부 모델은 승인 후 사용이 가능합니다.

• AWS SDK 설치: Python의 경우 boto3 라이브러리를 설치합니다. pip install boto3 명령어로 간단히 설치할 수 있습니다.

• 리전 확인: Amazon Bedrock은 모든 AWS 리전에서 사용 가능하지 않으므로, 지원되는 리전(예: us-east-1, us-west-2)을 확인해야 합니다.

기본 API 요청 구조 이해하기

Amazon Bedrock의 텍스트 생성 API 요청은 크게 두 가지 방식으로 이루어집니다. 하나는 InvokeModel로 단일 응답을 받는 방식이고, 다른 하나는 InvokeModelWithResponseStream으로 스트리밍 방식의 실시간 응답을 받는 방식입니다.

핵심 파라미터 설명

API 요청 시 페이로드에 포함되는 주요 파라미터는 다음과 같습니다:

• modelId: 사용할 AI 모델의 고유 식별자입니다. 예를 들어 Claude 3 Sonnet은 anthropic.claude-3-sonnet-20240229-v1:0입니다.

• prompt / messages: 모델에게 전달할 입력 텍스트 또는 대화 형식의 메시지 배열입니다.

• max_tokens: 생성할 최대 토큰 수를 지정합니다. 토큰은 단어나 단어의 일부를 의미하며, 응답 길이를 제어합니다.

• temperature: 0에서 1 사이의 값으로, 높을수록 더 창의적이고 다양한 응답을 생성합니다. 낮을수록 일관되고 예측 가능한 응답이 나옵니다.

• top_p: 누적 확률 기반 샘플링으로, 다양성을 조절하는 또 다른 파라미터입니다.

• stop_sequences: 모델이 특정 문자열을 만나면 생성을 멈추도록 지정합니다.

실제 API 요청 코드 예제

아래는 Python과 boto3를 사용하여 Claude 3 모델로 텍스트를 생성하는 실제 코드 예제입니다.

import boto3
import json

# Bedrock 클라이언트 생성
bedrock = boto3.client(
    service_name='bedrock-runtime',
    region_name='us-east-1'
)

# 요청 페이로드 구성 (Claude 3 모델용)
payload = {
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 1024,
    "temperature": 0.7,
    "top_p": 0.9,
    "messages": [
        {
            "role": "user",
            "content": "인공지능의 미래에 대해 간략하게 설명해주세요."
        }
    ]
}

# API 요청 실행
response = bedrock.invoke_model(
    modelId='anthropic.claude-3-sonnet-20240229-v1:0',
    contentType='application/json',
    accept='application/json',
    body=json.dumps(payload)
)

# 응답 파싱
response_body = json.loads(response['body'].read())
generated_text = response_body['content'][0]['text']
print(generated_text)

위 코드에서 주목해야 할 점은 anthropic_version 필드입니다. 이 필드는 Claude 모델 사용 시 반드시 포함해야 하는 필수 파라미터로, API 버전 호환성을 보장합니다.

Amazon Titan 모델 요청 예제

모델마다 요청 페이로드 형식이 다릅니다. Amazon 자체 모델인 Titan을 사용할 때는 다음과 같은 형식을 사용합니다:

# Amazon Titan 모델용 페이로드
titan_payload = {
    "inputText": "한국의 전통 음식에 대해 설명해주세요.",
    "textGenerationConfig": {
        "maxTokenCount": 512,
        "temperature": 0.5,
        "topP": 0.9,
        "stopSequences": []
    }
}

titan_response = bedrock.invoke_model(
    modelId='amazon.titan-text-express-v1',
    contentType='application/json',
    accept='application/json',
    body=json.dumps(titan_payload)
)

titan_body = json.loads(titan_response['body'].read())
print(titan_body['results'][0]['outputText'])

모델별 페이로드 형식 차이점

Amazon Bedrock에서 가장 중요한 점 중 하나는 각 모델 제공업체마다 요청 및 응답 형식이 다르다는 것입니다. 이를 미리 파악하지 않으면 불필요한 오류가 발생할 수 있습니다.

• Anthropic Claude: messages 배열과 anthropic_version 필드 필수, 응답은 content[0].text에서 추출

• Amazon Titan: inputText 단일 문자열 사용, textGenerationConfig 객체로 설정 구성

• Meta Llama 2: prompt 필드 사용, 특수한 프롬프트 형식 태그 필요 ([INST], [/INST])

• Cohere Command: prompt 필드와 max_tokens, temperature 등 직관적인 구조

• AI21 Jurassic: prompt 필드와 다양한 고급 설정 옵션 제공

이러한 복잡성을 줄이고 싶다면 Anakin.ai와 같은 플랫폼을 활용하는 것이 좋습니다. Anakin.ai는 다양한 AI 모델을 통합된 인터페이스로 제공하므로, 모델별 API 형식 차이를 신경 쓰지 않고도 빠르게 AI 애플리케이션을 구축하고 테스트할 수 있습니다. 특히 비기술적 사용자도 쉽게 AI 워크플로우를 만들 수 있어 팀 전체의 생산성을 높이는 데 효과적입니다.

성능 최적화 및 실전 팁

Amazon Bedrock API를 실제 서비스에 적용할 때 고려해야 할 실용적인 팁들을 소개합니다.

비용 관리 전략

Bedrock은 사용한 토큰 수에 따라 비용이 청구됩니다. max_tokens 값을 필요 이상으로 높게 설정하지 않는 것이 중요합니다. 또한 개발 및 테스트 단계에서는 더 저렴한 모델을 사용하고, 프로덕션에서만 고성능 모델로 전환하는 전략이 효과적입니다.

오류 처리 및 재시도 로직

API 호출 시 ThrottlingException이나 ServiceUnavailableException이 발생할 수 있습니다. 지수 백오프(Exponential Backoff) 방식의 재시도 로직을 구현하면 안정성을 크게 높일 수 있습니다. boto3의 Config 객체를 활용하면 자동 재시도 설정도 가능합니다.

스트리밍 응답 활용

긴 텍스트를 생성할 때는 InvokeModelWithResponseStream을 사용하면 사용자 경험이 크게 향상됩니다. 전체 응답이 완성될 때까지 기다리지 않고, 생성되는 즉시 텍스트를 화면에 표시할 수 있어 챗봇이나 실시간 콘텐츠 생성 애플리케이션에 특히 유용합니다.

자주 묻는 질문 (FAQ)

Q1. Amazon Bedrock API와 직접 OpenAI API를 사용하는 것의 차이점은 무엇인가요?

Amazon Bedrock은 AWS 인프라 내에서 동작하므로 데이터가 AWS 보안 경계 안에서 처리됩니다. 또한 단일 API로 Claude, Titan, Llama 등 여러 모델을 사용할 수 있어 벤더 종속성을 줄일 수 있습니다. 반면 OpenAI API는 GPT 계열 모델에 특화되어 있으며 독자적인 생태계를 가집니다. 기업 환경에서 AWS를 이미 사용 중이라면 Bedrock이 통합 관리 측면에서 유리합니다.

Q2. temperature와 top_p 파라미터를 어떻게 조합해야 최적의 결과를 얻을 수 있나요?

일반적으로 temperature와 top_p 중 하나만 조정하는 것이 권장됩니다. 창의적인 콘텐츠 생성에는 temperature를 0.7~0.9로 높게 설정하고, 코드 생성이나 사실 기반 답변에는 0.1~0.3으로 낮게 설정하세요. top_p는 기본값인 0.9를 유지하는 경우가 많습니다. 두 파라미터를 동시에 극단적으로 변경하면 예측 불가능한 결과가 나올 수 있습니다.

Q3. API 호출 시 "모델 액세스 거부" 오류가 발생하면 어떻게 해야 하나요?

이 오류는 두 가지 원인으로 발생합니다. 첫째, AWS 콘솔의 Amazon Bedrock 섹션에서 해당 모델에 대한 액세스를 신청하지 않은 경우입니다. Bedrock 콘솔 → Model access 메뉴에서 사용하려는 모델을 활성화해야 합니다. 둘째, IAM 정책에 bedrock:InvokeModel 권한이 없는 경우입니다. IAM 콘솔에서 해당 사용자 또는 역할에 적절한 권한을 추가하면 해결됩니다.