1. InvokeModel API란?
InvokeModel은 애플리케이션에서 Amazon Bedrock의 Foundation Model에 입력 데이터를 직접 전달하고 모델의 추론 결과를 받아오는 Bedrock Runtime API입니다. 텍스트뿐 아니라 모델에 따라 이미지 생성이나 임베딩 같은 작업에도 사용할 수 있습니다.
여기서 잠깐 boto3에 대해서도 알아봅시다.
Boto3는 Python 프로그램에서 AWS 서비스를 제어하고 호출하기 위한 공식 AWS SDK(Software Development Kit)입니다.
쉽게 말하면,
Python 코드
Boto3
AWS 서비스 를 연결해 주는 라이브러리 입니다.
Boto3
AWS 서비스 를 연결해 주는 라이브러리 입니다.예를 들어 Amazon Bedrock을 Python에서 호출할 때 다음처럼 사용합니다.
import boto3
# Amazon Bedrock Runtime 클라이언트 생성
bedrock = boto3.client(
"bedrock-runtime",
region_name="us-east-1"
)
Plain Text
복사
여기서 boto3.client()는 특정 AWS 서비스를 사용할 수 있는 Python 객체를 만드는 명령어입니다.
Boto3로 할 수 있는 일
AWS 서비스 | Boto3 사용 예 |
Amazon Bedrock | 생성형 AI 모델 호출 |
Amazon S3 | 파일 업로드/다운로드 |
AWS Lambda | Lambda 함수 호출 |
Amazon EC2 | 인스턴스 조회/시작/중지 |
Amazon DynamoDB | 데이터 저장/조회 |
Amazon SQS | 메시지 전송/수신 |
Amazon SNS | 알림 전송 |
Amazon CloudWatch | 로그/메트릭 조회 |
Bedrock Converse API도 Boto3를 통해 호출합니다.
import boto3
bedrock = boto3.client(
"bedrock-runtime",
region_name="us-east-1"
)
response = bedrock.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=[
{
"role": "user",
"content": [
{"text": "AWS Bedrock이 무엇인가요?"}
]
}
]
)
print(response["output"]["message"]["content"][0]["text"])
Plain Text
복사
•
설치되어 있지 않다면 Windows PowerShell에서 다음처럼 설치합니다.
python -m pip install boto3
Plain Text
복사
정상 설치 확인은:
python -c "import boto3; print(boto3.__version__)"
Plain Text
복사
정리하면 AWS CLI가 명령어로 AWS를 관리하는 도구라면, Boto3는 Python 코드로 AWS를 다루기 위한 도구라고 이해하시면 가장 쉽다.
사용자
↓
Python 프로그램
↓
Boto3
↓
AWS API
↓
Amazon Bedrock / S3 / Lambda / EC2 ...
Plain Text
복사
특히 Bedrock에서는 boto3 → client() → bedrock-runtime → converse() 또는 invoke_model()이라는 흐름을 이해해 두시면 좋습니다
기본 흐름은 다음과 같습니다.
Python 프로그램
│
│ boto3
▼
Bedrock Runtime Client
│
│ invoke_model()
▼
Amazon Bedrock
│
▼
Foundation Model
│
▼
AI 추론 결과
│
▼
response["body"]
│
▼
Python에서 JSON 변환
│
▼
화면에 답변 출력
Plain Text
복사
특히 중요한 점은 InvokeModel의 JSON 요청 형식이 모델에 따라 달라질 수 있다는 것입니다. AWS도 InvokeModel의 request body가 모델별 형식이라고 명시하고 있습니다. 반대로 Converse는 여러 모델에 공통된 인터페이스를 제공하는 것이 장점입니다.
2. 가장 간단한 Python 실행 코드
첨부하신 슬라이드와 같은 목적의 코드를 Amazon Nova Lite 기준으로 작성하면 다음과 같습니다.
파일 이름을 예를 들어
invoke_model.py
Plain Text
복사
# ============================================================
# Amazon Bedrock InvokeModel API 실습
# Amazon Nova Lite 모델 호출
# ============================================================
import json
import boto3
from botocore.exceptions import ClientError
# ------------------------------------------------------------
# 1. Bedrock Runtime Client 생성
# ------------------------------------------------------------
# 실제 AI 모델을 호출할 때는
# "bedrock-runtime" 서비스를 사용합니다.
#
# region_name:
# Bedrock 모델을 호출할 AWS Region
# ------------------------------------------------------------
bedrock = boto3.client(
service_name="bedrock-runtime",
region_name="us-east-1"
)
# ------------------------------------------------------------
# 2. 사용할 Bedrock 모델 ID
# ------------------------------------------------------------
MODEL_ID = "amazon.nova-lite-v1:0"
# ------------------------------------------------------------
# 3. 사용자 질문
# ------------------------------------------------------------
user_prompt = "Amazon Bedrock이 무엇인지 초보자에게 쉽게 설명해주세요."
# ------------------------------------------------------------
# 4. 모델에게 전달할 Request Body 생성
# ------------------------------------------------------------
# Nova 모델에서는 messages 형식으로 질문을 전달합니다.
#
# inferenceConfig
# maxTokens : 최대 출력 토큰
# temperature : 답변의 다양성
# topP : 생성 후보 범위 제어
# ------------------------------------------------------------
request_body = {
"messages": [
{
"role": "user",
"content": [
{
"text": user_prompt
}
]
}
],
"inferenceConfig": {
"maxTokens": 512,
"temperature": 0.7,
"topP": 0.9
}
}
# ------------------------------------------------------------
# 5. Bedrock InvokeModel API 호출
# ------------------------------------------------------------
try:
response = bedrock.invoke_model(
# 사용할 Foundation Model
modelId=MODEL_ID,
# Python Dictionary -> JSON 문자열
body=json.dumps(request_body),
# 보내는 데이터 형식
contentType="application/json",
# 응답 데이터 형식
accept="application/json"
)
# --------------------------------------------------------
# 6. Bedrock 응답 읽기
# --------------------------------------------------------
response_body = json.loads(
response["body"].read()
)
# --------------------------------------------------------
# 7. Nova 응답에서 AI 답변 추출
# --------------------------------------------------------
answer = response_body[
"output"
][
"message"
][
"content"
][0][
"text"
]
# --------------------------------------------------------
# 8. 결과 출력
# --------------------------------------------------------
print("\n========== 사용자 질문 ==========\n")
print(user_prompt)
print("\n========== Bedrock 답변 ==========\n")
print(answer)
# ------------------------------------------------------------
# AWS API 호출 오류 처리
# ------------------------------------------------------------
except ClientError as error:
print("\nBedrock API 호출 오류가 발생했습니다.")
print(error)
# ------------------------------------------------------------
# 기타 Python 오류 처리
# ------------------------------------------------------------
except Exception as error:
print("\n프로그램 실행 중 오류가 발생했습니다.")
print(error)
Plain Text
복사
이 구조는 현재 AWS Nova Invoke API 문서의 messages → inferenceConfig 요청 및 output.message.content 응답 구조와 일치합니다.
3. Windows에서 실행 준비
PowerShell을 열고 프로젝트 폴더를 하나 만들겠습니다.
mkdir C:\bedrock-invoke
cd C:\bedrock-invoke
Plain Text
복사
가상환경을 만듭니다.
python -m venv .venv
Plain Text
복사
활성화합니다.
.\.venv\Scripts\Activate.ps1
Plain Text
복사
정상적으로 활성화되면 대략 다음과 같이 표시됩니다.
(.venv) PS C:\bedrock-invoke>
Plain Text
복사
필요한 Python 패키지를 설치합니다.
python -m pip install --upgrade pip
pip install boto3
Plain Text
복사
이번 코드는 .env를 사용하지 않으므로 python-dotenv는 필요하지 않습니다.
4. AWS 인증 설정
AWS CLI 인증이 아직 없다면 먼저 다음을 실행합니다.
aws configure
Plain Text
복사
예:
AWS Access Key ID: ********
AWS Secret Access Key: ********
Default region name: us-east-1
Default output format: json
Plain Text
복사
설정 확인:
aws sts get-caller-identity
Plain Text
복사
정상이라면 계정/ARN 등의 정보가 JSON으로 나타납니다.
5. Python 프로그램 실행
앞의 코드를
C:\bedrock-invoke\invoke_model.py
Plain Text
복사
에 저장하고 실행합니다.
python invoke_model.py
Plain Text
복사
정상적으로 호출되면 형태는 다음과 비슷합니다.
========== 사용자 질문 ==========
Amazon Bedrock이 무엇인지 초보자에게 쉽게 설명해주세요.
========== Bedrock 답변 ==========
Amazon Bedrock은 AWS에서 제공하는 생성형 AI 서비스입니다.
여러 Foundation Model을 API를 통해 사용할 수 있도록...
Plain Text
복사
6. 코드에서 가장 중요한 부분
실제로 핵심은 이 부분입니다.
response = bedrock.invoke_model(
modelId=MODEL_ID,
body=json.dumps(request_body),
contentType="application/json",
accept="application/json"
)
Plain Text
복사
각 항목의 의미는 다음과 같습니다.
항목 | 의미 |
bedrock | Bedrock Runtime Client |
invoke_model() | AI 모델을 직접 호출하는 API |
modelId | 호출할 모델 또는 추론 프로파일 ID/ARN |
body | 모델에 전달할 입력 JSON |
contentType | 입력 데이터 형식 |
accept | 받고 싶은 응답 데이터 형식 |
response | Bedrock이 반환한 결과 |
contentType은 application/json으로 지정해야 하며, modelId에는 기본 모델 ID뿐 아니라 상황에 따라 inference profile ID/ARN 등도 사용할 수 있습니다.
7. json.dumps()를 사용하는 이유
Python에서는 먼저 이렇게 Dictionary를 만듭니다.
request_body = {
"messages": [
{
"role": "user",
"content": [
{"text": "안녕하세요"}
]
}
]
}
Plain Text
복사
하지만 Bedrock에 보낼 때는 JSON 형태가 필요합니다.
그래서
json.dumps(request_body)
Plain Text
복사
를 사용합니다.
개념적으로는
Python Dictionary
↓
json.dumps()
↓
JSON
↓
InvokeModel
↓
Bedrock
Plain Text
복사
입니다.
반대로 응답을 받을 때는
response["body"].read()
Plain Text
복사
로 body를 읽고,
json.loads(...)
Plain Text
복사
로 Python에서 다루기 쉬운 구조로 변환합니다.
Bedrock
↓
StreamingBody
↓
.read()
↓
JSON 데이터
↓
json.loads()
↓
Python Dictionary
Plain Text
복사
8. InvokeModel의 주요 특징
특징 | 설명 |
직접 모델 호출 | Foundation Model을 직접 지정하여 추론 |
Bedrock Runtime 사용 | boto3.client("bedrock-runtime") 사용 |
modelId 필요 | 어떤 모델을 사용할지 지정 |
JSON Body 사용 | 입력 데이터와 추론 파라미터 전달 |
모델별 Body 차이 | 모델에 따라 request/response 구조가 달라질 수 있음 |
동기 방식 | 일반 InvokeModel은 요청 후 하나의 응답을 받음 |
스트리밍 별도 지원 | 실시간 출력은 InvokeModelWithResponseStream 계열 사용 |
IAM 권한 필요 | bedrock:InvokeModel 필요 |
다양한 추론 가능 | 지원 모델에 따라 텍스트·이미지·임베딩 등 가능 |
AWS는 현재 Invoke 계열에서 일반 동기 호출인 InvokeModel 외에도 스트리밍 및 비동기 호출 방식을 제공하고 있습니다.
9. 첨부 이미지에서 가장 중요한 부분
첨부하신 슬라이드에서는 이런 차이를 보여주고 있습니다.
Anthropic Claude
↓
Claude 전용 JSON 형식
Amazon Titan
↓
Titan 전용 JSON 형식
Meta Llama
↓
Llama 전용 JSON 형식
Plain Text
복사
이것이 InvokeModel을 공부할 때 가장 중요한 개념 중 하나입니다.
즉,
bedrock.invoke_model(...)
Plain Text
복사
이라는 호출 방법은 비슷해도
body=...
Plain Text
복사
안에 들어가는 내용은 모델에 따라 달라질 수 있습니다. AWS 역시 Invoke API가 모델의 native request/response 구조에 직접 접근하는 방식이라고 설명합니다.
10. Converse API와 차이
최근 Bedrock을 공부하신다면 이 차이를 함께 이해하는 것이 좋습니다.
구분 | InvokeModel | Converse |
목적 | 모델 직접 호출 | 대화형 모델 호출 |
Request 형식 | 모델별 차이 존재 | 비교적 통일 |
Response 형식 | 모델별 차이 존재 | 비교적 통일 |
모델 고유 기능 제어 | 유리 | 일부는 별도 필드 필요 |
여러 모델 교체 | 상대적으로 번거로움 | 상대적으로 편리 |
기본 실습 | 좋음 | 좋음 |
챗봇 개발 | 가능 | 특히 편리 |
AWS 문서에서도 지원되는 모델이라면 Converse가 모델 간 요청 형식을 통일하여 멀티턴 대화를 관리하기 쉽다는 이유로 Converse 사용을 권장하고 있습니다. 반면 Invoke API는 모델 고유의 요청/응답 구조와 기능을 직접 다룰 때 유용합니다.
따라서 학습 순서는 이렇게 잡으면 이해하기 쉽습니다.
STEP 01
boto3 이해
↓
STEP 02
bedrock-runtime Client 생성
↓
STEP 03
InvokeModel API 이해
↓
STEP 04
Nova Lite 호출
↓
STEP 05
Request Body 구조 이해
↓
STEP 06
Response Body 구조 이해
↓
STEP 07
InvokeModelWithResponseStream
↓
STEP 08
Converse API
↓
STEP 09
ConverseStream
↓
STEP 10
Streamlit 챗봇 연결
Plain Text
복사
특히 InvokeModel → Converse → Streamlit 챗봇 순서로 실습하면 Bedrock API의 기본 원리와 실제 챗봇 개발의 차이를 함께 이해하기 좋습니다.




