Amazon Bedrock API: GPT 및 Claude 연동
Runtime과 Mantle 설정·권한을 확인하고 SDK·HTTP 요청, 스트리밍, 오류, 비용, 데이터 보존을 다룹니다.
이 가이드가 확인한 내용
Amazon Bedrock을 통한 OpenAI GPT와 Anthropic Claude 접근을 다룹니다. 공식 문서 확인일은 2026년 10월 17일입니다. 예제를 클라우드 API에 전송하지 않았으며 특정 계정의 모델 접근, 할당량 또는 승인된 배포를 입증하지 않습니다.
실행 예제의 인증 정보, 리전, 모델·프로필, 계정 값은 자리표시자나 환경 변수에서 가져옵니다. 사용 전에 계정 관리자가 Bedrock 콘솔과 현재 모델 카드에서 확인해야 합니다. 인증 정보는 서버에 두고 승인된 비밀 저장소나 워크로드 신원을 사용합니다. 브라우저 번들, 화면 이미지, 로그에 포함하지 않습니다.
1. 전체 연결 구성을 선택하기
엔드포인트, API, 모델 식별자, 리전은 하나의 구성입니다. 기본 URL만 바꾸면 잘못된 요청이 되거나 데이터 처리 위치가 달라질 수 있습니다. AWS는 새 애플리케이션에서 필요한 모델과 기능을 지원하는 경우 Runtime을 권장합니다.
| 경로 | SDK 기본 URL | 현재 AWS 카드의 식별자 예시 |
|---|---|---|
| GPT-6.1 Sol, Runtime Responses/Chat | https://bedrock-runtime.{region}.amazonaws.com/openai/v1 |
us.openai.gpt-6.1-sol 또는 global.openai.gpt-6.1-sol; 지원되는 출발 리전 필요 |
| GPT-6.1 Sol, Mantle Responses/Chat | https://bedrock-mantle.us-east-1.api.aws/openai/v1 |
openai.gpt-6.1-sol; 버지니아 북부 리전 내 접근 |
| Claude Sonnet 5, Runtime Messages | https://bedrock-runtime.{region}.amazonaws.com/anthropic |
us.anthropic.claude-sonnet-5, 기타 지원 지리 프로필 또는 global.anthropic.claude-sonnet-5 |
| Claude Sonnet 5, Mantle Messages | https://bedrock-mantle.{region}.api.aws/anthropic |
anthropic.claude-sonnet-5; 지원 Mantle 리전 확인 |
문서에 기재된 식별자 예시이지 접근 가능성의 증거가 아닙니다. GPT-6.1 Sol과 Claude Sonnet 5는 Runtime에서 직접 리전 내 호출을 지원하지 않으므로 지원 프로필을 사용합니다. 지리 라우팅과 Global 라우팅은 처리 경계가 다릅니다. 출발 엔드포인트를 처리 위치로 간주하지 말고 선택한 프로필의 출발 및 목적지 리전을 확인합니다.
Bedrock은 비공개 GPT 모델과 오픈 웨이트 gpt-oss 모델을 모두 지원합니다. 서로 다른 계열이므로 모든 구성을 공유할 수 없습니다. GPT OSS는 Runtime의 Chat Completions, Converse, Invoke를 지원하며 Responses는 Mantle이 필요합니다. Mantle 경로 접두사도 달라 GPT-6.1 Sol은 /openai/v1, 일부 모델은 /v1을 사용합니다. 개별 카드의 Programmatic Access 항목을 확인합니다.
2. 접근과 최소 권한 준비하기
AWS 계정, 지원 리전, 결제·약관 조건, 모델 가용성을 확인합니다. 일부 외부 모델 활성화에는 AWS Marketplace 권한이 필요합니다. 관리자가 한 번 활성화하면 모든 실행 호출자에게 구독 권한을 부여할 필요는 없습니다. 활성화 이후에도 계정별 접근이 다를 수 있습니다.
Runtime을 통한 Anthropic 첫 사용에는 사용 사례 양식이 필요합니다. 현재 모델 접근 문서는 Mantle 경로를 이 요건에서 제외합니다. 활성화는 성공했지만 호출이 거절되면 계약 상태를 확인합니다. 미승인 계정이나 리전으로 전환해 접근 문제를 해결하지 않습니다.
인증이 권한을 부여하지는 않습니다. Runtime 추론에는 bedrock:InvokeModel, 스트리밍에는 bedrock:InvokeModelWithResponseStream이 필요합니다. Runtime Responses는 계정의 기본 Project도 권한 대상으로 삼습니다. 저장 응답 조회, 취소, 삭제에는 별도 동작이 있습니다. Mantle 추론은 bedrock-mantle:CreateInference를 사용합니다. 정책 범위를 실제 대상으로 제한하고 추론 프로필 목적지 권한과 조직 정책도 확인합니다.
운영 환경에서는 지원되는 AWS 인증 체인 서명이나 단기 Bedrock bearer 인증 정보를 사용합니다. Bedrock API 키는 OpenAI 또는 Anthropic 직접 서비스 키가 아닙니다. 단기 키는 IAM 권한을 상속하고 만료되며 장기 키는 탐색 용도로 리전에 종속됩니다. 생성 token을 출력하지 않습니다. 아래 예제는 이미 권한을 가진 서버 환경을 전제합니다.
3. OpenAI SDK로 최소 GPT 요청 보내기
애플리케이션 환경에 OpenAI SDK를 설치합니다. 승인된 설정 절차로 BEDROCK_BASE_URL, BEDROCK_MODEL_ID, AWS_BEARER_TOKEN_BEDROCK을 설정합니다. BEDROCK_MODEL_ID는 Runtime의 검증된 프로필 또는 Mantle의 검증된 기반 모델 ID이며 임의의 OpenAI 직접 서비스 ID가 아닙니다.
import os
from openai import OpenAI
# Replace environment placeholders after checking the console/model card.
client = OpenAI(
base_url=os.environ["BEDROCK_BASE_URL"],
api_key=os.environ["AWS_BEARER_TOKEN_BEDROCK"],
)
response = client.responses.create(
model=os.environ["BEDROCK_MODEL_ID"],
input="Explain the difference between input and output tokens.",
max_output_tokens=512,
store=False,
)
print(response.output_text)
대응 HTTP 규약은 POST <BEDROCK_BASE_URL>/responses이며 Content-Type: application/json과 Authorization: Bearer <BEDROCK_API_KEY>를 사용합니다. JSON 본문에는 model, input, max_output_tokens, store가 있습니다. 예시는 다음과 같습니다.
# Replace the model placeholder; BASE_URL/key must already be configured securely.
curl --fail-with-body "$BEDROCK_BASE_URL/responses" \
-H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
-H "Content-Type: application/json" \
--data '{"model":"<VERIFIED_MODEL_OR_PROFILE_ID>","input":"Say hello.","max_output_tokens":512,"store":false}'
Chat Completions에는 /chat/completions와 messages 배열을 사용하고 choices[].message를 읽습니다. Responses의 input 본문을 Chat Completions에 보내지 않습니다. GPT-6.1 Sol 도구 사용은 같은 Chat 규약이라고 가정하지 말고 현재 Responses 지원에 맞춰 설계합니다.
4. 스트리밍은 이벤트 프로토콜
GPT Responses는 stream=True를 설정합니다. 텍스트는 response.output_text.delta로 오고 response.completed가 완료를 나타냅니다. 오류, 실패, 미완료, 예상하지 못한 스트림 종료를 처리합니다. 첫 token 수신이 업무 완료를 뜻하지는 않습니다.
# Uses the same verified client and model configuration as the previous example.
completed = False
for event in client.responses.create(
model=os.environ["BEDROCK_MODEL_ID"],
input="Explain token budgeting briefly.",
max_output_tokens=512, store=False, stream=True,
):
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
completed = True
elif event.type in {"error", "response.failed", "response.incomplete"}:
raise RuntimeError("Generation did not complete")
if not completed:
raise RuntimeError("Stream ended without completion")
Chat Completions는 Responses 이벤트 객체가 아닌 choices[].delta 청크를 사용합니다. Claude Messages는 콘텐츠 블록 이벤트를, AWS ConverseStream은 별도 AWS 이벤트 구조를 사용합니다. 각 파서를 해당 API와 연결합니다. 원시 HTTP 스트리밍은 "stream":true와 SSE 지원 클라이언트를 사용합니다. curl -N은 표시 버퍼링만 끄며 오류 복구를 구현하지 않습니다.
5. Claude: 기본 Messages 또는 Bedrock Invoke/Converse
Anthropic SDK는 /anthropic으로 끝나는 기본 URL을 사용하고 /v1/messages를 추가합니다. 지원 Claude 모델은 Runtime과 Mantle 모두에서 이 경로를 제공할 수 있습니다.
import os
from anthropic import Anthropic
# BASE_URL ends in /anthropic; MODEL_ID is verified for this endpoint/Region.
claude = Anthropic(
base_url=os.environ["BEDROCK_ANTHROPIC_BASE_URL"],
api_key=os.environ["AWS_BEARER_TOKEN_BEDROCK"],
)
with claude.messages.stream(
model=os.environ["BEDROCK_CLAUDE_MODEL_ID"],
max_tokens=512,
messages=[{"role":"user", "content":"Explain token budgeting briefly."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
final_message = stream.get_final_message()
기본 HTTP 요청은 POST <.../anthropic>/v1/messages입니다. x-api-key: <BEDROCK_API_KEY>, anthropic-version: 2023-06-01과 model, messages, max_tokens, 선택적 stream을 포함한 본문을 사용합니다.
boto3 invoke_model에서는 모델·프로필을 modelId 인자로 전달하고 JSON 본문에 "anthropic_version":"bedrock-2023-05-31"을 넣어야 합니다. 이 본문 필드는 기본 Messages HTTP 버전 헤더와 다릅니다. Converse는 messages[].content[].text를 사용하는 또 다른 요청 형식입니다. 페이로드를 혼용하지 않습니다.
import json, os, boto3
# The approved AWS credential chain supplies signing credentials; no embedded keys.
runtime = boto3.client("bedrock-runtime", region_name=os.environ["AWS_REGION"])
result = runtime.invoke_model(
modelId=os.environ["BEDROCK_CLAUDE_MODEL_ID"],
contentType="application/json", accept="application/json",
body=json.dumps({
"anthropic_version":"bedrock-2023-05-31",
"max_tokens":512,
"messages":[{"role":"user", "content":"Say hello."}],
}),
)
body = json.loads(result["body"].read())
print(body["content"])
6. 계층별로 오류 진단하기
| 증상 | 먼저 확인할 것 | 대응 |
|---|---|---|
| 400 또는 미지원 경로·모델 | 경로 접두사, API 본문, 프로필, 기능 지원 | 재시도 전에 설정 수정 |
| 403 / AccessDenied | IAM, Project, Marketplace·계약, FTU, 계정 접근 | 관리자와 부족한 권한 또는 활성화 해결 |
| 잘못되거나 만료된 인증, 리전 범위 메시지 | 인증 만료, 인증 리전, 서명 요청 문맥 | 승인된 신원 경로에서 갱신 |
| 429 / throttling | 계정·모델 할당량, 동시 실행, 합산 token 수요 | 부하 감소, 지터를 넣은 제한적 백오프 |
| 503 / 529 overload | 제공 용량, 응답 헤더, 서비스 상태 | 제한적 백오프, 반환된 Retry-After 준수 |
| 시간 초과 또는 스트림 조기 종료 | 클라이언트·프록시 기한, 네트워크 유휴 제한, 종료 이벤트 | 미완료 기록 후 재시도 전에 결과 확인 |
요청 ID, 시간, 엔드포인트, 모델·프로필, 상태, 민감 정보가 제거된 사용량을 기록합니다. 기본적으로 인증 정보나 전체 민감 프롬프트를 로그에 남기지 않습니다. 재시도 횟수와 전체 경과 시간을 제한합니다. 응답 유실이 token 미소비를 입증하지는 않습니다. 도구가 실행한 업무 쓰기에는 별도 동작 ID와 중복 방지가 필요합니다.
7. 비용과 데이터 처리 검토하기
정확한 모델, 라우팅 옵션, 서비스 계층의 AWS 가격을 사용합니다. 과금 입력, 출력, 캐시 읽기, 캐시 쓰기를 따로 계산하고 해당 검색, 임베딩, 저장, 네트워크, 도구 리소스 비용을 더합니다. 총량에 이미 포함된 캐시 범주를 중복 계산하지 않습니다. GPT-6.1 Sol에는 긴 문맥 기준, 캐시 단가, Standard/Ultrafast 가격이 있으므로 조건 확인 없이 OpenAI 직접 가격을 AWS 추정에 복사하지 않습니다.
Responses는 기본 store:true로 대화 입력과 출력을 30일 동안 보존합니다. 이 예제는 store:false이므로 previous_response_id로 이어갈 수 없습니다. 애플리케이션 로그와 호출 로그는 별도로 검토합니다. Runtime 교차 리전 추론에서 저장 응답은 요청을 처리한 리전에 위치하며 출발 리전과 다를 수 있습니다.
Runtime Responses는 매 요청에 model이 필요하고 기본 Project만 지원하며 background:true를 거절합니다. 애플리케이션 추론 프로필은 지원하지 않습니다. Runtime은 OpenAI 호환 GET /models를 제공하지 않으므로 Bedrock 제어 영역 검색 기능과 모델 카드를 사용합니다. Mantle의 기능과 보존 동작은 다릅니다.
모델별 제한이 넓은 호환성 가정보다 우선합니다. GPT-6.1 Sol 카드는 Responses의 통합 Guardrails를 지원하지 않는다고 명시하며 다른 미지원 기능도 나열합니다. Claude 구조화 출력도 API·엔드포인트에 따라 다릅니다. SDK 호환 요청이라고 모든 Bedrock 제어가 자동 적용된다고 주장하지 않습니다.
실제 운영 전에 승인 요청, 권한 없는 요청, 미지원 구성, 완전한 스트림, 모의 의존 서비스 실패를 검증합니다. 민감 정보를 제거한 근거, 사용량 관찰, 롤백 구성을 전달합니다. 이 가이드는 문서에 기반하며 실제 계정이나 전체 클라우드 검수 시험을 완료했다는 주장이 아닙니다.