Bedrock API로 사용 가능한 모델 목록을 프로그래밍 방식으로 조회하는 완벽 가이드

TL;DR: AWS Bedrock API의 `list_foundation_models()` 메서드를 사용하면 사용 가능한 모든 AI 모델과 버전을 프로그래밍 방식으로 손쉽게 조회할 수 있습니다.

AWS Bedrock API란 무엇인가?

AWS Bedrock은 Amazon Web Services에서 제공하는 완전 관리형 AI 서비스로, Anthropic의 Claude, Meta의 Llama, Amazon의 Titan 등 다양한 파운데이션 모델을 하나의 통합 API를 통해 사용할 수 있게 해줍니다. 개발자들은 별도의 인프라 구축 없이도 최신 AI 모델을 애플리케이션에 통합할 수 있습니다.

그런데 실제 개발 현장에서는 종종 이런 질문이 생깁니다. "현재 어떤 모델이 사용 가능한가? 내 계정에서 접근할 수 있는 모델 버전은 무엇인가?" 이 질문에 대한 답을 코드로 자동화하는 것이 바로 이 글의 핵심입니다.

사전 준비 사항

Bedrock API를 통해 모델 목록을 조회하기 전에 몇 가지 준비가 필요합니다.

• AWS 계정: 활성화된 AWS 계정이 필요합니다.

• IAM 권한 설정: bedrock:ListFoundationModels 권한이 포함된 IAM 정책이 필요합니다.

• AWS CLI 또는 SDK 설치: Python의 경우 boto3 라이브러리를 설치해야 합니다.

• 리전 설정: Bedrock은 특정 AWS 리전에서만 사용 가능하므로 올바른 리전을 설정해야 합니다.

boto3 설치 방법

Python 환경에서 boto3를 설치하려면 다음 명령어를 실행하세요.

pip install boto3

프로그래밍 방식으로 모델 목록 조회하기

AWS Bedrock에서 사용 가능한 모델 목록을 조회하는 핵심 API는 Amazon Bedrock Runtime이 아닌 Amazon Bedrock 클라이언트의 `list_foundation_models()` 메서드입니다. 이 두 가지를 혼동하는 경우가 많으니 주의하세요.

기본 모델 목록 조회 코드

import boto3
import json

# Bedrock 클라이언트 생성 (bedrock-runtime이 아닌 bedrock 사용)
client = boto3.client(
    service_name='bedrock',
    region_name='us-east-1'  # 사용하는 리전으로 변경
)

# 사용 가능한 모든 파운데이션 모델 목록 조회
response = client.list_foundation_models()

# 모델 정보 출력
models = response.get('modelSummaries', [])
print(f"총 {len(models)}개의 모델을 찾았습니다.\n")

for model in models:
    print(f"모델 ID: {model['modelId']}")
    print(f"모델 이름: {model['modelName']}")
    print(f"제공업체: {model['providerName']}")
    print(f"입력 모달리티: {model.get('inputModalities', [])}")
    print(f"출력 모달리티: {model.get('outputModalities', [])}")
    print(f"응답 스트리밍 지원: {model.get('responseStreamingSupported', False)}")
    print("-" * 50)

위 코드를 실행하면 현재 AWS 리전에서 사용 가능한 모든 파운데이션 모델의 상세 정보가 출력됩니다. 각 모델에 대해 모델 ID, 이름, 제공업체, 지원하는 입출력 형식 등을 확인할 수 있습니다.

필터링 옵션으로 원하는 모델만 조회하기

`list_foundation_models()` 메서드는 다양한 필터 옵션을 지원합니다. 수십 개의 모델 중에서 원하는 조건에 맞는 모델만 선택적으로 조회할 수 있어 매우 실용적입니다.

제공업체별 필터링

특정 AI 회사의 모델만 조회하고 싶다면 `byProvider` 파라미터를 활용하세요. 예를 들어 Anthropic의 Claude 모델만 조회하려면 다음과 같이 작성합니다.

import boto3

client = boto3.client(
    service_name='bedrock',
    region_name='us-east-1'
)

# Anthropic 모델만 필터링
response = client.list_foundation_models(
    byProvider='Anthropic'
)

anthropic_models = response.get('modelSummaries', [])
print(f"Anthropic 모델 수: {len(anthropic_models)}")

for model in anthropic_models:
    print(f"  - {model['modelId']} ({model['modelName']})")

# 추론 타입별 필터링 (ON_DEMAND만 조회)
response_on_demand = client.list_foundation_models(
    byInferenceType='ON_DEMAND'
)

print(f"\nOn-Demand 지원 모델 수: {len(response_on_demand.get('modelSummaries', []))}")

# 커스터마이제이션 지원 모델 필터링
response_custom = client.list_foundation_models(
    byCustomizationType='FINE_TUNING'
)

print(f"파인튜닝 지원 모델 수: {len(response_custom.get('modelSummaries', []))}")

지원되는 필터 파라미터

• byProvider: 특정 제공업체(예: Anthropic, Amazon, Meta, Cohere)로 필터링

• byCustomizationType: 커스터마이제이션 유형(FINE_TUNING, CONTINUED_PRE_TRAINING)으로 필터링

• byOutputModality: 출력 형식(TEXT, IMAGE, EMBEDDING)으로 필터링

• byInferenceType: 추론 타입(ON_DEMAND, PROVISIONED)으로 필터링

실무에서 활용하는 고급 팁

단순히 모델 목록을 조회하는 것을 넘어, 실제 프로덕션 환경에서 유용하게 활용할 수 있는 패턴들을 소개합니다.

모델 가용성 자동 확인 시스템 구축

CI/CD 파이프라인이나 배포 스크립트에서 특정 모델이 현재 사용 가능한지 자동으로 확인하는 로직을 추가하면, 모델 중단이나 버전 변경으로 인한 장애를 사전에 방지할 수 있습니다. 특히 여러 리전에 서비스를 배포하는 경우 각 리전별로 지원되는 모델이 다를 수 있으므로 이 점을 반드시 고려해야 합니다.

모델 ID 동적 로딩으로 유지보수 간소화

애플리케이션 코드에 모델 ID를 하드코딩하는 대신, 런타임에 API를 통해 최신 모델 정보를 가져오는 방식을 채택하면 모델 업데이트 시 코드 변경 없이도 자동으로 최신 버전을 사용할 수 있습니다. 다만 성능을 위해 결과를 캐싱하는 것을 권장합니다.

Anakin.ai와 함께하는 AI 워크플로우 자동화

AWS Bedrock API를 직접 다루는 것이 복잡하게 느껴진다면, Anakin.ai를 활용해 보세요. Anakin.ai는 다양한 AI 모델을 노코드 또는 로우코드 방식으로 통합할 수 있는 플랫폼으로, Bedrock을 포함한 여러 AI 서비스를 시각적으로 연결하고 자동화된 워크플로우를 구축할 수 있습니다. 개발자가 아닌 팀원들도 AI 모델을 손쉽게 활용할 수 있어 팀 전체의 생산성을 높이는 데 도움이 됩니다.

자주 발생하는 오류와 해결 방법

Bedrock API로 모델 목록을 조회할 때 자주 마주치는 오류들과 해결 방법을 정리했습니다.

• AccessDeniedException: IAM 정책에 bedrock:ListFoundationModels 권한이 없는 경우입니다. AWS 콘솔에서 IAM 정책을 확인하고 필요한 권한을 추가하세요.

• EndpointResolutionError: 선택한 리전에서 Bedrock이 지원되지 않는 경우입니다. us-east-1, us-west-2, ap-northeast-1 등 Bedrock 지원 리전을 사용하세요.

• NoCredentialsError: AWS 자격증명이 설정되지 않은 경우입니다. aws configure 명령어로 자격증명을 설정하거나 환경 변수를 활용하세요.

• bedrock-runtime vs bedrock 혼동: 모델 목록 조회는 반드시 bedrock 클라이언트를 사용해야 합니다. bedrock-runtime은 실제 모델 호출에만 사용됩니다.

자주 묻는 질문 (FAQ)

Q1. list_foundation_models()로 조회한 모델을 모두 바로 사용할 수 있나요?

아니요, 반드시 그런 것은 아닙니다. 일부 모델은 AWS 콘솔의 Bedrock 서비스 내 Model Access 메뉴에서 별도로 접근 권한을 요청해야 합니다. 특히 Anthropic Claude, Meta Llama 등 서드파티 모델은 약관 동의 후 활성화가 필요합니다. API로 목록에는 나타나지만 실제 호출 시 `AccessDeniedException`이 발생하는 경우가 이에 해당합니다.

Q2. 특정 모델의 버전 정보는 어떻게 확인하나요?

현재 `list_foundation_models()` API는 모델 버전을 별도로 나열하지 않으며, 각 버전이 독립적인 모델 ID로 관리됩니다. 예를 들어 `anthropic.claude-3-sonnet-20240229-v1:0`처럼 모델 ID 자체에 버전 정보가 포함되어 있습니다. 따라서 반환된 모델 ID 목록을 분석하면 사용 가능한 모든 버전을 파악할 수 있습니다. 또한 `get_foundation_model(modelIdentifier='모델ID')` API를 통해 특정 모델의 상세 정보를 조회할 수도 있습니다.

Q3. 리전마다 사용 가능한 모델이 다른가요?

네, AWS 리전에 따라 지원되는 Bedrock 모델이 다를 수 있습니다. 일반적으로 us-east-1(버지니아 북부)이 가장 많은 모델을 지원하며, 새로운 모델은 보통 이 리전에 먼저 출시됩니다. 글로벌 서비스를 운영한다면 각 리전별로 `list_foundation_models()`를 호출하여 사용 가능한 모델을 확인하고, 리전 간 모델 가용성 차이를 고려한 폴백(fallback) 로직을 구현하는 것이 좋습니다.