기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 빌드
Amazon Bedrock을 사용하여 모델 구축을 시작하려면 먼저 사용 사례부터 시작합니다. 그런 다음 API, 엔드포인트를 선택한 다음 모델을 프로그래밍 방식으로 사용하기 시작합니다.
**사용 사례에 따라 API 선택**
Amazon Bedrock은 Amazon Bedrock에서 추론을 수행하기 위한 네 가지 주요 API 패턴을 제공합니다. [응답](bedrock-mantle.md), [채팅 완료](bedrock-mantle.md), [간접 호출](inference-invoke.md) 및 [대화](conversation-inference.md). 지원되는 APIs에 대해 자세히 알아보세요.
| **시나리오** | **권장 API** |
| --- | --- |
| OpenAI API 호환 엔드포인트에서 마이그레이션 | OpenAI 호환 APIs 사용: [응답 API](https://platform.openai.com/docs/api-reference/responses) 또는 [채팅 완료 API](https://platform.openai.com/docs/api-reference/chat) |
| OpenAI 호환 엔드포인트와 호환되지 않는 모델 사용 | 기본 Amazon Bedrock APIs 사용: [Converse](conversation-inference.md) 및 [Invoke](inference-invoke.md). 사용 사례에 적합한 APIs를 선택하는 방법에 대해 자세히 알아보세요. |
**Amazon Bedrock의 엔드포인트 선택**
사용할 API를 식별한 후에는 Amazon Bedrock과 프로그래밍 방식으로 상호 작용하는 데 사용할 엔드포인트를 식별할 수 있습니다. 지원되는 APIs에 대해 자세히 알아보세요.
| **Endpoint** | **지원되는 APIs** |
| --- | --- |
| bedrock-mantle.\$1 | [응답 API](bedrock-mantle.md), [채팅 완료 API](bedrock-mantle.md) |
| bedrock-runtime.\$1 | [API 호출](inference-invoke.md), [Converse API](conversation-inference.md), [Chat Completions API](inference-chat-completions.md) |
**모델 선택**
사용 중인 엔드포인트를 기반으로 Amazon Bedrock이 지원하는 모델 목록을 볼 수 있습니다.
| **Endpoint** | **API** | **설명** |
| --- | --- | --- |
| bedrock-runtime.\$1 | ListFoundationModels | Bedrock에서 사용 가능한 모든 파운데이션 모델의 목록을 반환합니다. 모델 IDs, 공급자 이름, 지원되는 양식(텍스트, 이미지, 임베딩), 입력/출력 형식, 스트리밍 또는 사용자 지정 지원 여부 등 여러 모델에 대한 요약 정보를 제공합니다. GetFoundationModel API를 사용하여 모델 ID를 사용하여 특정 파운데이션 모델에 대한 세부 정보를 검색합니다. |
| bedrock-mantle.\$1 | client.models.list | OpenAI 호환 API를 사용하여 사용 가능한 모델을 검색합니다. 응답 API 및 채팅 완료 API와 함께 사용할 수 있는 모델 목록을 검색합니다. |
# Amazon Bedrock에서 지원하는 APIs
**지원되는 추론 APIs **
Amazon Bedrock은 Amazon Bedrock에서 [추론](inference.md)을 수행하기 위한 네 가지 주요 API 패턴을 제공합니다.
| **API 방식** | **서비스 엔드포인트** | **에 가장 적합한 사용 사례** | **주요 기능** |
| --- | --- | --- | --- |
| [응답 API](bedrock-mantle.md)(권장) | bedrock-mantle. | 상태 저장 대화 | 내장된 도구 사용(검색, 코드 인터프리터), 멀티모달 입력 및 상태 저장 대화가 필요한 최신 에이전트 애플리케이션에 응답 API 사용 |
| [채팅 완료](bedrock-mantle.md) | bedrock-mantle. (권장) 및 bedrock-runtime. | 상태 비저장 멀티턴 채팅 | [채팅 기록 관리를 완전히 제어하고 지연 시간을 줄여야 하는 경량의 상태 비저장 텍스트 중심 작업에 Chat Completions API](inference-chat-completions.md)를 사용합니다. |
| [역방향 메서드](conversation-inference.md) | bedrock-runtime. | 멀티턴 채팅/표준화 | [Converse API](conversation-inference.md)는 Amazon Bedrock의 모든 모델과 상호 작용하기 위한 통합 인터페이스를 제공합니다. |
| [메서드 호출](inference-invoke.md) | bedrock-runtime. | 단일 트랜잭션/대형 페이로드 | 간접 호출 API는 요청 및 응답 형식을 제어할 수 있는 더 많은 기능을 갖춘 모델에 대한 직접 액세스를 제공합니다. |
참고: 접미사는 입니다. `{region}.amazonaws.com`
[Amazon Bedrock에서 지원하는 APIs](inference-api.md)에 대해 자세히 알아보세요.
**APIs 간 결정**
사용하는 API는 사용 사례에 따라 다릅니다.
| **사용 사례** | **권장 API** |
| --- | --- |
| OpenAI API 호환 엔드포인트에서 마이그레이션 | OpenAI 호환 APIs [응답 API](https://platform.openai.com/docs/api-reference/responses) 또는 [채팅 완료 API를](inference-chat-completions.md) 사용합니다. OpenAI에 따르면 [권장되는](https://platform.openai.com/docs/guides/migrate-to-responses) API 장기는 응답 API입니다. |
| OpenAI 호환 엔드포인트와 호환되지 않는 모델 사용 | 기본 Amazon Bedrock APIs 사용: [Converse](conversation-inference.md) 및 [Invoke](inference-invoke.md). 자세한 내용은 [API를 사용하여 프롬프트 제출 및 응답 생성](inference-api.md) 단원을 참조하십시오. |
| 모든 모델에서 일관된 인터페이스 | [Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) - 메시지를 지원하는 모든 모델과 함께 작동합니다. 코드를 한 번 작성하고 다른 모델과 함께 사용합니다. 예제 코드는 [Converse API 예제](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html#message-inference-examples)를 참조하세요. |
| 전체 제어를 통한 직접 모델 액세스 | [API 호출](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) - 요청 및 응답 형식을 더 잘 제어할 수 있는 모델에 대한 직접 액세스를 제공합니다. 텍스트, 이미지 및 임베딩을 생성하는 데 사용합니다. 예제 코드는 [모델 코드 예제 호출을](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-invoke.html#inference-example-invoke) 참조하세요. |
| Amazon Bedrock 신규 | [응답 API](bedrock-mantle.md)로 시작 |
**각 API 및 엔드포인트에서 지원하는 모델**
먼저 [모델을](models.md) 탐색하여 사용하려는 모델을 결정합니다. 사용하려는 모델을 결정하면 사용할 엔드포인트를 선택한 것을 기반으로 및에서 지원하는 APIs를 볼 수 있습니다. 는 응답 및 채팅 완료 API를 `bedrock-mantle` 지원합니다. 는 Invoke 및 Converse API를 `bedrock-runtime` 지원합니다.
# Amazon Bedrock에서 지원하는 엔드포인트
Amazon Bedrock은 컨트롤 플레인 연산자 또는 [추론](inference.md) 작업을 수행할지 여부에 따라 다양한 엔드포인트를 지원합니다.
**컨트롤 플레인 작업**
Amazon Bedrock 컨트롤 플레인 작업은 엔드포인트와 함께 사용할 수 있습니다. `bedrock.{region}.amazonaws.com.` 사용 가능한 [모델](models.md) 나열, [사용자 지정 모델](custom-models.md) 작업 생성, [프로비저닝된 처리량](prov-throughput.md) 관리와 같은 리소스를 관리하는 데 사용할 수 있습니다. [여기에서](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) 컨트롤 플레인 API에 대해 자세히 알아보세요.
**추론 작업**
Amazon Bedrock은 프로그래밍 방식으로 추론을 수행하기 위해 다음과 같은 두 가지 기본 엔드포인트를 지원합니다.
| **Endpoint** | **지원되는 APIs** | **설명** |
| --- | --- | --- |
| bedrock-mantle.\$1region\$1.api.aws | [응답 API](bedrock-mantle.md)/[채팅 완료 API](bedrock-mantle.md) | OpenAI 호환 엔드포인트를 사용하여 Amazon Bedrock에서 호스팅되는 모델에 대한 추론 요청을 수행하기 위한 리전별 엔드포인트입니다. |
| bedrock-runtime.\$1region\$1.amazonaws.com | [InvokeModel](inference-invoke.md) / [Converse](conversation-inference.md) / [Chat Completions](inference-chat-completions.md) | InvokeModel/Converse/Chat Completions APIs. Amazon Bedrock 런타임 APIs에 대한 자세한 내용은 [여기에서](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html) 확인하세요. |
**추론에 사용해야 하는 서비스 엔드포인트는 무엇입니까?**
사용하는 엔드포인트는 사용 사례에 따라 다릅니다.
| **Endpoint** | **기능 및 사용 사례** |
| --- | --- |
| bedrock-mantle | OpenAI 호환 APIs([응답 API](bedrock-mantle.md), [채팅 완료 API)를](bedrock-mantle.md) 지원합니다. **용도:** OpenAI 호환 APIs. **기능:** Lambda 함수에서 클라이언트 및 서버 측 도구 사용을 모두 지원하며 애플리케이션에서 ready-to-use 가능한 도구로 구성됩니다. **권장 대상:** Amazon Bedrock의 신규 사용자. |
| bedrock-runtime | Amazon Bedrock 네이티브 APIs([API 호출](inference-invoke.md), [Converse API](conversation-inference.md))를 지원합니다. 또한 OpenAI 호환 [채팅 완료 API를](inference-chat-completions.md) 지원합니다. **용도:** Amazon Bedrock에서 지원하는 모든 모델 실행. [Converse API](conversation-inference.md)는 Amazon Bedrock의 모든 모델과 상호 작용하기 위한 통합 인터페이스를 제공하고 [Invoke API](inference-invoke.md)는 요청 및 응답 형식을 제어할 수 있는 더 많은 기능을 갖춘 모델에 대한 직접 액세스를 제공합니다. [Chat Completions API](inference-chat-completions.md)를 사용하여 모델과 상호 작용할 수도 있습니다. **기능:** Lambda 함수에서 클라이언트 측 도구 사용만 지원하며 ready-to-use 있는 도구로 미리 구성되지 않습니다. 모델을 호출할 때 사용량과 비용을 추적할 수 있습니다. |
Amazon Bedrock을 처음 사용하는 경우 `bedrock-mantle` 엔드포인트로 시작하는 것이 좋습니다.
# 프로젝트 API
Amazon Bedrock Projects API는 [OpenAI 호환 APIs](bedrock-mantle.md). 프로젝트를 사용하면 조직 전체에서 향상된 액세스 제어, 비용 추적 및 관찰성을 통해 AI 애플리케이션을 구성하고 관리할 수 있습니다.
**참고**
프로젝트는 [bedrock-mantle 엔드포인트](bedrock-mantle.md)에 대해 OpenAI 호환 APIs를 사용하는 모델에서만 사용할 수 있습니다. bedrock-runtime 엔드포인트를 사용하는 경우 태그 지정 및 관찰성 대신 추론 프로파일을 사용하세요.
## 프로젝트란 무엇입니까?
프로젝트는 Amazon Bedrock 내에서 애플리케이션, 환경 또는 실험과 같은 워크로드를 격리하는 데 사용되는 논리적 경계입니다. 프로젝트에서는 다음을 제공합니다.
+ **액세스 격리**: [AWS Identity and Access Management(IAM) 정책을](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) 사용하여 특정 프로젝트 리소스에 액세스할 수 있는 사용자 제어
+ **비용 모니터링**: [AWS 태그](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html) 및 [AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html)를 사용하여 프로젝트 수준에서 지출 추적
프로젝트를 사용하면 별도의 AWS 계정 또는 조직을 생성하지 않고도 프로덕션 환경에서 여러 생성형 AI 워크로드를 관리할 수 있으므로 보안 및 거버넌스를 유지하면서 운영 복잡성을 줄일 수 있습니다.
각 AWS 계정에는 모든 추론 요청이 연결된 기본 프로젝트가 있습니다. 프로젝트 API를 사용하여 계정에 더 많은 프로젝트를 생성할 수 있습니다.
## 프로젝트를 사용해야 하는 경우
다음과 같은 경우 프로젝트 API를 사용해야 합니다.
+ **비즈니스 구조별 구성**: 사업부, 팀, 애플리케이션 또는 비용 센터와 같은 조직 분류를 기반으로 Bedrock 사용량 관리
+ **민감한 데이터 격리**: 한 애플리케이션의 프롬프트, 응답 및 컨텍스트 데이터에 다른 애플리케이션이 액세스할 수 없도록 합니다.
+ **비용을 정확하게 추적**: AI 지출을 모니터링하고 특정 팀, 프로젝트 또는 환경에 할당
+ **액세스 정책 적용**: 세분화된 IAM 권한을 적용하여 특정 AI 워크로드에 액세스할 수 있는 사용자를 제어합니다.
+ **프로덕션 워크로드 규모 조정**: 명확한 운영 경계 및 모니터링으로 여러 프로덕션 애플리케이션 실행
## 프로젝트와 추론 프로파일 비교
프로젝트 API와 [추론 프로파일](inference-profiles-create.md) 모두 Amazon Bedrock에서 격리, 태그 지정 및 액세스 제어 기능을 제공하지만 사용하는 API에 따라 다릅니다. Mantle 추론 엔진을 사용하는 [bedrock-mantle](endpoints.md) 엔드포인트와 함께 OpenAI 호환 APIs를 사용하는 경우 프로젝트 API를 사용합니다. [bedrock-runtime](endpoints.md) 엔드포인트와 함께 Invoke 또는 Converse APIs를 사용하는 경우 추론 프로파일을 사용합니다. 채팅 완료 API를 bedrock-mantle 또는 bedrock-runtime 엔드포인트와 함께 사용할 수 있지만 Mantle 엔드포인트를 사용하는 것이 좋습니다.
| 기능 | 프로젝트 API | 추론 프로파일 |
| --- | --- | --- |
| 지원되는 API | OpenAI 호환 APIs(응답, 채팅 완료) | 네이티브 Bedrock APIs(Invoke, Converse), OpenAI 호환 API(챗 완료) |
| 엔드포인트 | bedrock-mantle.\$1region\$1.api.aws | bedrock-runtime.\$1region\$1.amazonaws.com |
| 사용 사례 | OpenAI 호환 엔드포인트를 사용하는 애플리케이션 | 네이티브 Bedrock APIs 사용하는 애플리케이션 |
| 액세스 통제 | IAM 정책의 리소스로 프로젝트 | 추론 프로필 ARN에 대한 IAM 정책 |
| 비용 추적 | 프로젝트의 AWS 태그 | 추론 프로필의 AWS 태그 |
## 프로젝트와 AWS 계정 비교
[AWS 계정](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html) 및 [AWS Organizations](https://docs.aws.amazon.com/controltower/latest/userguide/organizations.html) 인프라 수준에서 결제 및 소유권 경계를 나타냅니다. 프로젝트는 단일 계정 내의 워크로드 및 애플리케이션 경계를 나타냅니다.
별도의 AWS 계정 대신 프로젝트를 사용하면 다음과 같은 이점이 있습니다.
+ **더 빠른 설정**: API 직접 호출을 통해 몇 초 만에 프로젝트 생성
+ **복잡성 감소**: 계정 확장 없이 여러 워크로드 관리
+ **간소화된 작업**: 단일 계정 내의 중앙 집중식 관리
+ **오버헤드 감소**: 교차 계정 IAM 역할 또는 리소스 공유 필요 없음
## 프로젝트 시작하기
이 페이지에서는 첫 번째 프로젝트를 생성하고, 추론 요청과 연결하고, 프로젝트 리소스를 관리하는 방법을 안내합니다.
### 사전 조건
시작하기 전에 다음을 갖추었는지 확인하세요.
+ Amazon Bedrock 액세스 권한이 있는 AWS 계정
+ Bedrock 프로젝트를 생성하고 관리할 수 있는 IAM 권한
+ Python 3.7 이상 설치됨
+ OpenAI Python SDK가 설치되었습니다. `pip install openai boto3`
+ Amazon Bedrock 인증을 위한 [API 키](api-keys.md)
### 1단계: 환경 설정
Amazon Bedrock 자격 증명을 사용하여 환경 변수를 구성합니다.
```
export OPENAI_API_KEY=""
export OPENAI_BASE_URL="https://bedrock-mantle..api.aws/v1"
```
를 AWS 리전(예: us-east-1, us-west-2)``으로 바꿉니다.
**참고**
Amazon Bedrock은 단기 및 장기[라는 두 가지 유형의 키를](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-how.html) 제공합니다. Amazon Bedrock 탐색에 장기 API 키를 사용할 수 있지만 보안 요구 사항이 더 높은 애플리케이션에는 단기 키를 사용하는 것이 좋습니다. 장기 키를 프로젝트와 함께 사용하는 경우 장기 키에 연결된 기본 정책은 프로젝트를 가져오고 나열할 뿐 create/update/archive할 수는 없다는 점에 유의하세요. 장기 키를 사용하여 프로젝트를 관리하려면 키에 추가 IAM 정책을 할당하여 이러한 작업을 활성화해야 합니다.
### 2단계: 사용 가능한 모델 검색
`list()` API를 사용하여 프로젝트 API와 호환되는 모델 목록을 검색합니다.
```
curl -X GET $OPENAI_BASE_URL/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### 3단계: 첫 번째 프로젝트 생성
비용 모니터링 및 관찰성을 위한 태그가 있는 프로젝트 생성 API를 사용하여 프로젝트를 생성합니다. 현재 SDK에서는 cURL만 지원됩니다.
```
curl -X POST $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Project ABC",
"tags": {
"Project": "CustomerChatbot",
"Environment": "Production",
"Owner": "TeamAlpha",
"CostCenter": "21524"
}
}' -v
```
응답:
```
{
"arn": "arn:aws:bedrock-mantle:ap-northeast-1:673693429514:project/proj_5d5ykleja6cwpirysbb7",
"created_at": 1772135628,
"id": "proj_5d5ykleja6cwpirysbb7",
"name": "Project ABC",
"object": "organization.project",
"status": "active",
"tags": {
"Owner": "TeamAlpha",
"Project": "CustomerChatbot",
"Environment": "Production",
"CostCenter": "21524"
}
}
```
**중요 참고 사항:**
+ OpenAI API 사양의 지리 파라미터는 Amazon Bedrock에서 무시됩니다.
+ 리전은 엔드포인트 구성에 따라 결정됩니다.
+ ARN 필드는 Amazon Bedrock에 고유하며 IAM 정책 연결을 위한 ARN을 제공합니다.
+ 태그는 프로젝트 생성 중에 지정할 수 있으며 모든 프로젝트 응답에 반환됩니다.
### 4단계: 추론 요청을 프로젝트와 연결
프로젝트를 추론 요청에 연결하려면 클라이언트를 생성할 때 프로젝트 ID를 제공합니다.
------
#### [ cURL ]
```
curl -X POST $OPENAI_BASE_URL/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Project: proj_5d5ykleja6cwpirysbb7" \
-d '{
"model": "openai.gpt-oss-120b",
"input": "Explain the benefits of using projects in Amazon Bedrock"
}'
```
------
#### [ Python ]
```
from openai import OpenAI
client = OpenAI(project="proj_5d5ykleja6cwpirysbb7")
```
------
이 클라이언트로 이루어진 모든 추론 요청은 지정된 프로젝트와 연결되어 적절한 격리, 비용 추적 및 액세스 제어를 보장합니다.
### 5단계: 프로젝트 설정 확인
모든 프로젝트를 나열하여 프로젝트가 성공적으로 생성되었는지 확인합니다.
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
응답:
```
{
"data": [
{
"arn": "arn:aws:bedrock-mantle:ap-northeast-1:673693429514:project/default",
"created_at": 1764460800,
"id": "default",
"name": "default",
"object": "organization.project",
"status": "active",
"tags": {}
},
{
"arn": "arn:aws:bedrock-mantle:ap-northeast-1:673693429514:project/proj_2z766pfxmkij5vwubv75",
"created_at": 1771823259,
"id": "proj_2z766pfxmkij5vwubv75",
"name": "Project ABC",
"object": "organization.project",
"status": "active",
"tags": {}
}
],
"first_id": "default",
"has_more": false,
"last_id": "proj_znaruqn723npmjqnxqfd",
"object": "list"
}
```
### 다음 단계
이제 첫 번째 프로젝트를 생성했으므로 다음을 수행할 수 있습니다.
+ **액세스 제어 구성**: IAM 정책을 연결하여 프로젝트 액세스 제한
+ **비용 추적 설정**: 비용 할당을 위한 AWS 태그 추가
+ **모니터링 활성화**: CloudWatch 지표 및 경보 구성
+ **추가 프로젝트 생성**: 팀, 환경 또는 애플리케이션별로 워크로드 구성
## 프로젝트 작업
이 페이지에서는 수명 주기 동안 프로젝트 관리에 대한 자세한 정보를 제공합니다.
### 프로젝트 생성
#### 기본 프로젝트 생성
이름, 설명 및 태그를 사용하여 프로젝트를 생성합니다.
```
curl -X POST $OPENAI_BASE_URL/v1/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Development Environment",
"tags": {
"Project": "InternalTools",
"Environment": "Development",
"Owner": "TeamAlpha",
"CostCenter": "30156"
}
}'
```
계정당 최대 1,000개의 프로젝트를 보유할 수 있습니다.
#### 권장 이름 지정 규칙
조직 구조를 반영하는 명확하고 설명적인 이름을 사용합니다.
+ **애플리케이션별**: CustomerChatbot-Prod, InternalSearch-Dev
+ **팀별**: TeamAlpha-Production, DataScience-Experiments
+ **환경별**: Production-WebApp, Staging-MobileApp
+ **비용 센터별**: CostCenter-2152-Production
### 프로젝트 나열
#### 모든 프로젝트 나열
계정의 모든 프로젝트를 검색합니다.
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### 프로젝트 세부 정보 검색
특정 프로젝트에 대한 자세한 정보를 가져옵니다.
```
curl -X GET $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### 프로젝트 업데이트
다음과 같은 프로젝트 속성을 수정합니다.
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Chatbot v2"
}'
```
### 프로젝트 태그 관리
새 태그를 추가하거나 기존 태그 값을 업데이트합니다.
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"add_tags": {
"Application": "WebApp",
"Version": "2.0",
"Team": "Engineering"
}
}'
```
키로 특정 태그를 제거합니다.
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"remove_tag_keys": ["Version", "OldTagKey"]
}'
```
**중요 정보**
**전체 교체 없음**: 전체 태그 세트를 한 번에 교체하는 작업이 없습니다. 추가할 태그와 제거할 태그를 명시적으로 지정해야 합니다.
**오류 처리**: 적절한 오류 처리 및 확인 구현
### 프로젝트 아카이빙
더 이상 사용되지 않는 프로젝트를 아카이브합니다.
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_abc123/archive \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json"
```
**중요**
보관된 프로젝트는 새 추론 요청에 사용할 수 없지만 기록 데이터 및 지표는 최대 30일 동안 액세스할 수 있습니다.
### 다른 APIs에서 프로젝트 사용
------
#### [ Responses API ]
```
from openai import OpenAI
client = OpenAI(project="proj_abc123")
response = client.responses.create(
model="openai.gpt-oss-120b",
input="What are the key features of Amazon Bedrock?"
)
print(response)
```
------
#### [ Chat Completions API ]
```
from openai import OpenAI
client = OpenAI(project="proj_abc123")
response = client.chat.completions.create(
model="openai.gpt-oss-120b",
messages=[
{"role": "user", "content": "Explain how projects improve security"}
]
)
print(response.choices[0].message.content)
```
------
### 모범 사례
#### 권장 프로젝트 구조
**애플리케이션당 프로젝트 1**개: 각 개별 애플리케이션 또는 서비스에 대해 별도의 프로젝트를 생성합니다.
```
├── CustomerChatbot-Production
├── CustomerChatbot-Staging
├── CustomerChatbot-Development
├── InternalSearch-Production
└── InternalSearch-Development
```
+ **별도의 환경**: 개발, 스테이징 및 프로덕션 환경에 다른 프로젝트를 사용합니다.
+ **실험 격리**: 실험 및 proof-of-concepts 위한 전용 프로젝트를 생성합니다.
#### 프로젝트 수명 주기 관리
+ **프로젝트 조기 생성**: 애플리케이션을 배포하기 전에 프로젝트 설정
+ **일관된 이름 지정 사용**: 조직 이름 지정 규칙 준수
+ **문서 프로젝트 목적**: 명확한 설명 포함
+ **정기 감사**: 사용하지 않는 프로젝트를 정기적으로 검토 및 보관
+ **사용량 모니터링**: 프로젝트 지표를 추적하여 최적화 기회 식별
# API 키
Amazon Bedrock API 키를 생성하고 이를 사용하여 Amazon Bedrock API에 요청 시 자격 증명을 인증함으로써 Amazon Bedrock API를 쉽게 직접 호출할 수 있습니다.
**참고**
감사 및 규정 준수를 위해 모든 API 호출이 로그인됩니다 AWS CloudTrail. Amazon Bedrock API 키는 API 요청에 권한 부여 헤더로 전달되며 로깅되지 않습니다.
Amazon Bedrock API 키는 [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock.html) 및 [Amazon Bedrock 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html) 작업으로 제한됩니다. 다음 API 작업에서는 해당 기능을 사용할 수 없습니다.
[InvokeModelWithBidirectionalStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithBidirectionalStream.html)
[Amazon Bedrock Agents](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html) 또는 [Amazon Bedrock Agents 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html) API 작업
[Amazon Bedrock용 데이터 자동화](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Data_Automation_for_Amazon_Bedrock.html) 또는 [Amazon Bedrock Data Automation용 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Runtime_for_Amazon_Bedrock_Data_Automation) API 작업
Amazon Bedrock을 사용하면 다음과 같은 종류의 Amazon Bedrock API 키를 생성할 수 있습니다.
+ **단기** - 세션 동안(12시간 이내) 지속되는 Amazon Bedrock API 키를 생성합니다. Amazon Bedrock을 사용할 수 있는 적절한 권한을 가진 [IAM 보안 주체](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html#intro-structure-terms)가 이미 설정되어 있어야 합니다. 이 옵션은 보안을 강화하기 위해 자격 증명을 정기적으로 변경해야 하는 프로덕션 환경에서 장기 키보다 선호됩니다.
단기 키의 속성은 다음과 같습니다.
+ 다음 값 중 더 짧은 값에 대해 유효합니다.
+ 12시간
+ 키를 생성하는 데 사용되는 IAM 보안 주체가 생성한 세션의 기간
+ 키를 생성하는 데 사용되는 보안 주체에 연결된 권한을 상속합니다.
+ 생성한 AWS 리전에서만 사용할 수 있습니다.
+ **장기** - Amazon Bedrock에서 기본 API 요청을 수행할 수 있는 권한이 있는 Amazon Bedrock API 키를 생성합니다. 이 간편한 원클릭 옵션을 사용하면 기본 보안 인프라를 이해하거나 AWS Identity and Access Management 권한을 수동으로 구성하지 않고도 Amazon Bedrock API 탐색을 빠르게 시작할 수 있습니다. Amazon Bedrock을 처음 사용해 보는 경우 손쉬운 자습서의 [Amazon Bedrock API 키 시작하기: 30일 키를 생성하고 첫 API 직접 호출 수행](getting-started-api-keys.md)에서 예제를 통해 장기 키를 생성하고 Amazon Bedrock을 쉽게 시작할 수 있습니다.
**주의**
Amazon Bedrock 탐색을 위해 Amazon Bedrock API 키 사용을 제한하는 것이 좋습니다. 보안 요구 사항이 더 큰 애플리케이션에 Amazon Bedrock을 통합할 준비가 되면 단기 자격 증명으로 전환해야 합니다. 자세한 내용은 IAM 사용 설명서의 [장기 액세스 키의 대안](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html#security-creds-alternatives-to-long-term-access-keys)을 참조하세요.
주제를 선택하여 Amazon Bedrock API 키에 대해 자세히 알아보세요. 다양한 유형의 Amazon Bedrock 키에 대한 여러 옵션과 이를 사용자 지정하는 방법이 있습니다. 장기 Amazon Bedrock API 키를 생성하고 탐색 목적으로 사용하는 방법에 대한 빠른 시작 자습서를 살펴보려면 [Amazon Bedrock API 키 시작하기: 30일 키를 생성하고 첫 API 직접 호출 수행](getting-started-api-keys.md) 섹션을 참조하세요.
**Topics**
+ [Amazon Bedrock API 키의 작동 방식](api-keys-how.md)
+ [Amazon Bedrock API 키에 지원되는 리전 및 AWS 소프트웨어 개발 키트(SDKs)](api-keys-supported.md)
+ [Amazon Bedrock API 키 생성](api-keys-generate.md)
+ [Amazon Bedrock API 키 사용](api-keys-use.md)
+ [장기 및 단기 Amazon Bedrock API 키에 대한 권한 수정](api-keys-modify.md)
+ [손상된 장기 및 단기 Amazon Bedrock API 키 처리](api-keys-revoke.md)
+ [Amazon Bedrock API 키 생성 및 사용에 대한 권한 제어](api-keys-permissions.md)
# Amazon Bedrock API 키의 작동 방식
다음 이미지는 자격 증명을 가져오는 기본 프로세스를 Amazon Bedrock API 키 사용과 비교합니다.
![\[Amazon Bedrock API 키를 사용한 API 설정 프로세스와 비교한 기본 API 설정 프로세스\]](http://docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/images/setup/setup-api.png)
다이어그램의 맨 왼쪽 흐름은 AWS IAM Identity Center 또는 IAM에서 자격 증명을 생성하는 기본 프로세스를 보여줍니다. 이 프로세스를 통해 해당 자격 증명에 IAM 정책을 연결하여 API 작업을 수행할 수 있는 권한을 제공한 다음 해당 자격 증명에 대한 일반 AWS 자격 증명을 생성합니다. 그런 다음 자격 증명을 사용하여 AWS에서 API를 직접 호출할 수 있습니다.
블루 노드는 특히 Amazon Bedrock에 인증할 2개의 추가 흐름을 나타냅니다. 두 흐름 모두에 Amazon Bedrock 작업을 사용하여 인증할 수 있는 Amazon Bedrock API 키를 생성하는 작업이 포함됩니다. 다음과 같은 유형의 키를 생성할 수 있습니다.
+ **단기 키** - Amazon Bedrock을 사용하여 임시 액세스를 허용하는 보안 옵션입니다.
단기 키의 속성은 다음과 같습니다.
+ 다음 값 중 더 짧은 값에 대해 유효합니다.
+ 12시간
+ 키를 생성하는 데 사용되는 IAM 보안 주체가 생성한 세션의 기간
+ 키를 생성하는 데 사용되는 보안 주체에 연결된 권한을 상속합니다.
+ 생성한 AWS 리전에서만 사용할 수 있습니다.
+ **장기 키** - Amazon Bedrock 탐색에만 권장됩니다. 키가 만료되는 시간을 설정할 수 있습니다. 장기 키를 생성하면 기본적으로 사용자를 대신하여 IAM 사용자를 생성하고, 사용자가 선택한 IAM 정책을 연결하고, 키를 사용자와 연결합니다. 키를 생성한 후 IAM 서비스를 사용하여 [IAM 사용자에 대한 권한을 수정](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)할 수 있습니다.
**주의**
Amazon Bedrock 탐색을 위해 Amazon Bedrock API 키 사용을 제한하는 것이 좋습니다. 보안 요구 사항이 더 큰 애플리케이션에 Amazon Bedrock을 통합할 준비가 되면 단기 자격 증명으로 전환해야 합니다. 자세한 내용은 IAM 사용 설명서의 [장기 액세스 키의 대안](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html#security-creds-alternatives-to-long-term-access-keys)을 참조하세요.
# Amazon Bedrock API 키에 지원되는 리전 및 AWS 소프트웨어 개발 키트(SDKs)
다음 목록은 API 키를 AWS 리전 지원하는를 보여줍니다.
+ ap-northeast-1
+ ap-northeast-2
+ ap-northeast-3
+ ap-south-1
+ ap-south-2
+ ap-southeast-1
+ ap-southeast-2
+ ca-central-1
+ eu-central-1
+ eu-central-2
+ eu-north-1
+ eu-south-1
+ eu-south-2
+ eu-west-1
+ eu-west-2
+ eu-west-3
+ sa-east-1
+ us-east-1
+ us-gov-east-1
+ us-gov-west-1
+ us-west-2
**참고**
Amazon Bedrock API 키는 [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock.html) 및 [Amazon Bedrock 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html) 작업으로 제한됩니다. 다음 API 작업에서는 해당 기능을 사용할 수 없습니다.
[InvokeModelWithBidirectionalStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithBidirectionalStream.html)
[Amazon Bedrock Agents](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html) 또는 [Amazon Bedrock Agents 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html) API 작업
[Amazon Bedrock용 데이터 자동화](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Data_Automation_for_Amazon_Bedrock.html) 또는 [Amazon Bedrock Data Automation용 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Runtime_for_Amazon_Bedrock_Data_Automation) API 작업
Amazon Bedrock API 키는 다음 AWS SDKs
+ Python
+ Javascript
+ Java
# Amazon Bedrock API 키 생성
AWS Management Console 또는 AWS API를 사용하여 Amazon Bedrock API 키를 생성할 수 있습니다. 몇 단계만으로 Amazon Bedrock API 키를 쉽게 생성할 수 있는 AWS Management Console을 사용하는 것이 좋습니다.
**주의**
Amazon Bedrock 탐색을 위해 Amazon Bedrock API 키 사용을 제한하는 것이 좋습니다. 보안 요구 사항이 더 큰 애플리케이션에 Amazon Bedrock을 통합할 준비가 되면 단기 자격 증명으로 전환해야 합니다. 자세한 내용은 IAM 사용 설명서의 [장기 액세스 키의 대안](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html#security-creds-alternatives-to-long-term-access-keys)을 참조하세요.
**Topics**
+ [콘솔을 사용하여 Amazon Bedrock API 키 생성](#api-keys-generate-console)
+ [API를 사용하여 장기 Amazon Bedrock API 키 생성](#api-keys-generate-api-long-term)
+ [클라이언트 라이브러리를 사용하여 단기 Amazon Bedrock API 키 생성](#api-keys-generate-short-term)
+ [단기 Amazon Bedrock API 키의 자동 새로 고침 설정](#api-keys-refresh-short-term)
## 콘솔을 사용하여 Amazon Bedrock API 키 생성
콘솔을 사용하여 Amazon Bedrock API 키를 생성하려면 다음을 수행합니다.
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명으로 AWS Management Console에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 왼쪽 탐색 창에서 **API 키**를 선택합니다.
1. 다음 유형의 키 중 하나를 생성합니다.
+ **단기 API 키** - **단기 API 키** 탭에서 **단기 API 키 생성**을 선택합니다. 키는 콘솔 세션이 만료되면 만료되고(12시간 이내) 키를 생성한 AWS 리전에 직접 호출할 수 있도록 지원합니다. 생성된 키에서 직접 리전을 수정할 수 있습니다.
+ **장기 API 키** - **장기 API 키** 탭에서 **장기 API 키 생성**을 선택합니다.
1. **API 키 만료** 섹션에서 키가 만료될 시간을 선택합니다.
1. (선택 사항) 기본적으로 핵심 Amazon Bedrock API 작업에 대한 액세스 권한을 부여하는 [AmazonBedrockLimitedAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockLimitedAccess) AWS 관리형 정책은 키와 연결된 IAM 사용자에게 연결됩니다. 사용자에게 연결할 정책을 더 선택하려면 **고급 권한** 섹션을 확장하고 추가하려는 정책을 선택합니다.
1. **생성**을 선택합니다.
**주의**
Amazon Bedrock 탐색을 위해 Amazon Bedrock API 키 사용을 제한하는 것이 좋습니다. 보안 요구 사항이 더 큰 애플리케이션에 Amazon Bedrock을 통합할 준비가 되면 단기 자격 증명으로 전환해야 합니다. 자세한 내용은 IAM 사용 설명서의 [장기 액세스 키의 대안](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html#security-creds-alternatives-to-long-term-access-keys)을 참조하세요.
## API를 사용하여 장기 Amazon Bedrock API 키 생성
API에서 장기 Amazon Bedrock API 키를 생성하는 일반적인 단계는 다음과 같습니다.
1. [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)로 [CreateUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateUser.html) 요청을 전송하여 IAM 사용자를 생성합니다.
1. [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)로 [AttachUserPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachUserPolicy.html) 요청을 전송하여 [AmazonBedrockLimitedAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockLimitedAccess)를 IAM 사용자에게 연결합니다. 이 단계를 반복하여 필요에 따라 다른 관리형 또는 사용자 지정 정책을 사용자에게 연결할 수 있습니다.
**참고**
보안 모범 사례로 IAM 정책을 IAM 사용자에게 연결하여 Amazon Bedrock API 키 사용을 제한하는 것이 좋습니다. 시간 제한 정책 및 키를 사용할 수 있는 IP 주소 제한의 예제는 [IAM 사용자에게 인라인 정책을 연결하여 액세스 키 사용 제어](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys_inline-policy.html)를 참조하세요.
1. [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)로 [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html.html) 요청을 보내고 `bedrock.amazonaws.com`을 `ServiceName`으로 지정하여 장기 Amazon Bedrock API 키를 생성합니다.
+ 응답에 반환된 `ServiceApiKeyValue`는 장기 Amazon Bedrock API 키입니다.
+ 응답에 반환된 `ServiceSpecificCredentialId`를 사용하여 키와 관련된 API 작업을 수행할 수 있습니다.
장기 Amazon Bedrock API 키를 생성하는 방법을 알아보려면 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
장기 Amazon Bedrock API 키를 생성하려면 AWS Identity and Access Management API 작업을 사용합니다. 먼저 사전 조건을 충족했는지 확인합니다.
**전제 조건**
설정에서 AWS CLI가 AWS 자격 증명을 자동으로 인식하도록 허용하는지 확인합니다. 자세한 내용은 [AWS CLI 설정 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)을 참조하세요.
터미널을 열고 다음 명령을 실행합니다.
1. IAM 사용자를 생성합니다. 이름을 원하는 이름으로 바꿀 수 있습니다.
```
aws iam create-user --user-name bedrock-api-user
```
1. [AmazonBedrockLimitedAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockLimitedAccess)를 사용자에게 연결합니다. API 키에 추가하려는 다른 AWS 관리형 또는 사용자 지정 정책의 ARN을 사용하여 이 단계를 반복할 수 있습니다.
```
aws iam attach-user-policy --user-name bedrock-api-user --policy-arn arn:aws:iam::aws:policy/AmazonBedrockLimitedAccess
```
1. 장기 Amazon Bedrock API 키를 생성하여 *\$1\$1NUMBER-OF-DAYS\$1*를 키를 유지할 일수로 바꿉니다.
```
aws iam create-service-specific-credential \
--user-name bedrock-api-user \
--service-name bedrock.amazonaws.com \
--credential-age-days ${NUMBER-OF-DAYS}
```
------
#### [ Python ]
장기 Amazon Bedrock API 키를 생성하려면 AWS Identity and Access Management API 작업을 사용합니다. 먼저 사전 조건을 충족했는지 확인합니다.
**전제 조건**
설정을 통해 Python이 AWS 자격 증명을 자동으로 인식할 수 있는지 확인합니다. 자세한 내용은 [AWS CLI 설정 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)을 참조하세요.
다음 스크립트를 실행하여 IAM 사용자를 생성하고, Amazon Bedrock 작업을 수행할 권한을 연결하고, 사용자와 연결할 장기 Amazon Bedrock API 키를 생성합니다.
```
import boto3
from datetime import datetime, timedelta
# Replace with name for your IAM user
username = "bedrock-api-user"
# Add any AWS-managed or custom policies that you want to the user
bedrock_policies = [
"arn:aws:iam::aws:policy/AmazonBedrockLimitedAccess", # Limited access
# "arn:aws:iam::aws:policy/AmazonBedrockMarketplaceAccess", # Optional: Access to Amazon Bedrock Marketplace actions
]
# Set the key expiration time to a number of your choice
expiration_time_in_days = 30
iam_client = boto3.client("iam")
# Create IAM user
user = iam_client.create_iam_user(username)
# Attach policies to user
for policy_arn in bedrock_policies:
iam_client.attach_managed_policy(username, policy_arn)
# Create long-term Amazon Bedrock API key and return it
service_credentials = iam_client.create_service_specific_credential(
user_name=username,
service_name="bedrock",
credential_age_days=expiration_time_in_days
)
api_key = service_credentials["ServiceApiKeyValue"]
print(api_key)
```
------
## 클라이언트 라이브러리를 사용하여 단기 Amazon Bedrock API 키 생성
단기 키의 속성은 다음과 같습니다.
+ 다음 값 중 더 짧은 값에 대해 유효합니다.
+ 12시간
+ 키를 생성하는 데 사용되는 IAM 보안 주체가 생성한 세션의 기간
+ 키를 생성하는 데 사용되는 보안 주체에 연결된 권한을 상속합니다.
+ 생성한 AWS 리전에서만 사용할 수 있습니다.
장기 실행 애플리케이션의 경우 [aws-bedrock-token-generator](https://github.com/aws/aws-bedrock-token-generator-js/blob/main/README.md) 클라이언트 라이브러리는 자격 증명을 새로 고칠 때 필요에 따라 새 Amazon Bedrock 단기 API 키를 생성할 수 있습니다. 자세한 내용은 [단기 Amazon Bedrock API 키의 자동 새로 고침 설정](#api-keys-refresh-short-term) 섹션을 참조하세요.
**사전 조건**
+ 키를 생성하는 데 사용하는 IAM 보안 주체가 Amazon Bedrock을 사용할 수 있는 적절한 권한으로 설정되어 있는지 확인합니다. 실험을 위해 AWS 관리형 [AmazonBedrockLimitedAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockLimitedAccess) 정책을 보안 주체에 연결할 수 있습니다. 자격 증명을 보호하기 위해 [IAM의 보안 모범 사례](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)를 참조할 수 있습니다.
+ 설정을 통해 Python이 AWS 자격 증명을 자동으로 인식할 수 있는지 확인합니다. 자격 증명을 검색하는 기본 방법은 정의된 계층 구조를 따릅니다. 특정 SDK 또는 [AWS SDK 및 도구의 표준화된 자격 증명 공급자](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)의 도구에 대한 계층 구조를 볼 수 있습니다.
+ Amazon Bedrock 토큰 생성기를 설치합니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ Python ]
터미널을 열고 다음 명령을 실행합니다.
```
pip install aws-bedrock-token-generator
```
------
#### [ Javascript ]
터미널을 열고 다음 명령을 실행합니다.
```
npm install @aws/bedrock-token-generator
```
------
#### [ Java ]
Maven을 사용한다면 `pom.xml`에 다음 종속성을 추가합니다.
```
software.amazon.bedrock
aws-bedrock-token-generator
1.1.0
```
Gradle을 사용하는 경우 `build.gradle`에 다음을 추가합니다.
```
implementation 'software.amazon.bedrock:aws-bedrock-token-generator:1.1.0'
```
------
**예시**
토큰 생성기를 사용하여 다양한 언어로 된 기본 자격 증명으로 단기 Amazon Bedrock API 키를 생성하는 예제를 보려면 선호하는 방법의 탭을 선택한 다음 단계를 따릅니다.
------
#### [ Python ]
```
from aws_bedrock_token_generator import provide_token
token = provide_token()
print(f"Token: {token}")
```
------
#### [ Javascript ]
```
import { getTokenProvider } from "@aws/bedrock-token-generator";
// Create a token provider that uses default credentials and region providers.
// You can configure it to use other credential providers.
const provideToken = getTokenProvider();
async function example() {
const token = await provideToken();
// Use the token for API calls. The token has a default expiration of 12 hour.
// If the expiresInSeconds parameter is specified during token creation, the
// expiration can be configured up to a maximum of 12 hours. However, the actual
// token validity period will always be the minimum of the requested expiration
// time and the AWS credentials' expiry time
console.log(`Bearer Token: ${token}`);
}
```
------
#### [ Java ]
```
import software.amazon.bedrock.token.BedrockTokenGenerator;
// Credentials and region will be picked up from the default provider chain
BedrockTokenGenerator tokenGenerator = BedrockTokenGenerator.builder().build();
tokenGenerator.getToken();
```
------
토큰을 생성할 때 다양한 사용 사례에 대한 추가 예제를 보려면 다음 링크를 참조하세요.
+ [ Python](https://github.com/aws/aws-bedrock-token-generator-python/blob/main/README.md)
+ [Javascript](https://github.com/aws/aws-bedrock-token-generator-js/blob/main/README.md)
+ [ Java](https://github.com/aws/aws-bedrock-token-generator-java/blob/main/README.md)
## 단기 Amazon Bedrock API 키의 자동 새로 고침 설정
`aws-bedrock-token-generator` 패키지의 도움을 받아 스크립트를 생성하여 현재 키가 만료될 때마다 새 단기 키를 프로그래밍 방식으로 재생성할 수 있습니다. 먼저 [클라이언트 라이브러리를 사용하여 단기 Amazon Bedrock API 키 생성](#api-keys-generate-short-term)에서 사전 조건을 충족했는지 확인합니다. 토큰을 검색하고 Converse 요청을 하는 예제 스크립트를 보려면 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ Python ]
```
from aws_bedrock_token_generator import provide_token
import requests
def get_new_token():
url = "https://bedrock-runtime.us-west-2.amazonaws.com/model/us.anthropic.claude-3-5-haiku-20241022-v1:0/converse"
payload = {
"messages": [
{
"role": "user",
"content": [{"text": "Hello"}]
}
]
}
# Create a token provider that uses default credentials and region providers.
# You can configure it to use other credential providers.
# https://github.com/aws/aws-bedrock-token-generator-python/blob/main/README.md
# It can be used for each API call as it is inexpensive.
token = provide_token()
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {token}"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
if __name__ == "__main__":
get_new_token()
```
------
#### [ Javascript ]
```
import { getTokenProvider } from "@aws/bedrock-token-generator";
// Create a token provider that uses default credentials and region providers.
// You can configure it to use other credential providers.
// https://github.com/aws/aws-bedrock-token-generator-js/blob/main/README.md
// This can be created just once. Use await provideToken() to fetch the token
const provideToken = getTokenProvider();
async function example() {
const url = "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-3-5-haiku-20241022-v1:0/converse";
const payload = {
messages: [
{
role: "user",
content: [{ text: "Hello" }]
}
]
};
const headers = {
"Content-Type": "application/json",
// provideToken retrieves a valid token. It can be used for each API call as it is inexpensive.
"Authorization": `Bearer ${await provideToken()}`
};
await fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(payload)
})
}
```
------
#### [ Java ]
```
package com.amazon.bedrocktoken;
import software.amazon.bedrock.token.BedrockTokenGenerator;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class GetNewToken {
public static void main(String[] args) throws Exception {
// Use default credentials and region from environment/profile chain
// Create a token generator that uses default credentials and region providers.
// You can configure it to use other credential providers.
// https://github.com/aws/aws-bedrock-token-generator-java/blob/main/README.md
BedrockTokenGenerator tokenGenerator = BedrockTokenGenerator.builder().build();
// getToken() retrieves a valid token. It can be used for each API call as it is inexpensive.
String token = tokenGenerator.getToken();
String url = "https://bedrock-runtime.us-west-2.amazonaws.com/model/us.anthropic.claude-3-5-haiku-20241022-v1:0/converse";
String payload = "{\n" +
" \"messages\": [\n" +
" {\n" +
" \"role\": \"user\",\n" +
" \"content\": [{ \"text\": \"Hello\" }]\n" +
" }\n" +
" ]\n" +
"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + token)
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
------
# Amazon Bedrock API 키 사용
다음과 같은 방법으로 Amazon Bedrock API 키를 사용할 수 있습니다.
+ **환경 변수로 설정** - Amazon Bedrock 서비스는 `AWS_BEARER_TOKEN_BEDROCK` 환경 변수를 인식합니다. 키를 설정하는 옵션은 다음과 같습니다.
+ 터미널을 열어 설정합니다.
+ **MacOS/Linux**
```
export AWS_BEARER_TOKEN_BEDROCK=${api-key}
```
+ **(Windows**):
```
setx AWS_BEARER_TOKEN_BEDROCK "${api-key}"
```
+ API 요청을 하기 전에 코드에서 환경 변수로 설정합니다. 예를 들어, 요청을 하기 전에 다음 줄을 포함할 수 있습니다.
+ ** Python**
```
import os
os.environ['AWS_BEARER_TOKEN_BEDROCK'] = "${api-key}"
```
+ **요청에 지정** - 다음과 같은 방법으로 권한 부여 헤더에 Amazon Bedrock API 키를 포함할 수 있습니다(*\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*을 실제 값으로 대체).
+ **직접 HTTP 요청에서** - 다음을 권한 부여 헤더로 포함합니다.
```
Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK
```
+ **지원되는 SDK의 파라미터로** - 클라이언트를 설정할 때 파라미터에 값을 지정합니다. 예를 들어, [OpenAI Python SDK](https://github.com/openai/openai-python?tab=readme-ov-file#usage)로 클라이언트를 설정할 때 `api_key` 필드에서 지정할 수 있습니다.
**참고**
Amazon Bedrock API 키는 [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock.html) 및 [Amazon Bedrock 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html) 작업으로 제한됩니다. 다음 API 작업에서는 해당 기능을 사용할 수 없습니다.
[InvokeModelWithBidirectionalStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithBidirectionalStream.html)
[Amazon Bedrock Agents](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html) 또는 [Amazon Bedrock Agents 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html) API 작업
[Amazon Bedrock용 데이터 자동화](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Data_Automation_for_Amazon_Bedrock.html) 또는 [Amazon Bedrock Data Automation용 런타임](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Runtime_for_Amazon_Bedrock_Data_Automation) API 작업
API 키를 사용하여 응답을 생성하는 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 요청을 보내는 예제를 보려면 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ Python ]
다음 예제에서는 AWS SDK for Python (Boto3)을 사용하여 API 요청을 보내는 방법을 보여줍니다. API 키를 `AWS_BEARER_TOKEN_BEDROCK` 환경 변수로 아직 설정하지 않은 경우 다음 코드에서 *\$1\$1api-key\$1* 대신 지정합니다.
```
import os
import boto3
# If you already set the API key as an environment variable, you can comment this line out
os.environ['AWS_BEARER_TOKEN_BEDROCK'] = "${api-key}"
# Create an Amazon Bedrock client
client = boto3.client(
service_name="bedrock-runtime",
region_name="us-east-1" # If you've configured a default region, you can omit this line
)
# Define the model and message
model_id = "us.anthropic.claude-3-5-haiku-20241022-v1:0"
messages = [{"role": "user", "content": [{"text": "Hello"}]}]
response = client.converse(
modelId=model_id,
messages=messages,
)
```
------
#### [ HTTP Client (requests package in Python) ]
**사전 조건:** 터미널을 열고 다음 명령을 실행하여 `requests` 패키지를 설치합니다.
```
python3 -m pip install requests
```
다음 예제에서는 HTTP 클라이언트를 사용하여 API 요청을 직접 보내는 방법을 보여줍니다. 헤더에 *\$1\$1api-key\$1*를 지정합니다.
```
import requests
url = "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-3-5-haiku-20241022-v1:0/converse"
payload = {
"messages": [
{
"role": "user",
"content": [{"text": "Hello"}]
}
]
}
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer ${api-key}"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
```
------
#### [ HTTP request using cURL ]
다음 예제에서는 cURL을 사용하여 API 요청을 직접 보내는 방법을 보여줍니다. API 키를 AWS\$1BEARER\$1TOKEN\$1BEDROCK 환경 변수로 설정하지 않은 경우 예제에서 `$AWS_BEARER_TOKEN_BEDROCK`을 키의 리터럴 값으로 바꿔야 합니다.
```
curl -X POST "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-3-5-haiku-20241022-v1:0/converse" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
-d '{
"messages": [
{
"role": "user",
"content": [{"text": "Hello"}]
}
]
}'
```
------
# 장기 및 단기 Amazon Bedrock API 키에 대한 권한 수정
장기 Amazon Bedrock API 키를 생성할 때 키와 연결된 IAM 사용자를 생성합니다. 키와 연결된 권한을 변경하려면 IAM 서비스를 통해 IAM 사용자의 권한을 수정합니다. 자세한 내용은 IAM 사용 설명서의 [IAM 자격 증명 권한 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)를 참조하세요.
**참고**
에서 장기 키를 생성한 경우 AWS Management Console[AmazonBedrockLimitedAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockLimitedAccess)가 기본적으로 여기에 연결됩니다. 권한을 수정하려는 경우 사용자 지정 권한을 설정하기 전에 먼저 이 정책을 제거합니다.
## API 키에 대한 권한 수정 예제
다음 절차에서는 [AmazonBedrockLimitedAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockLimitedAccess)를 더 제한적으로 교체하는 방법을 보여줍니다.
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명 AWS Management Console 으로에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 왼쪽 탐색 창에서 **API 키**를 선택합니다.
1. **장기 API 키** 탭을 선택합니다.
1. API 키를 선택하고 **IAM 콘솔에서 관리**를 선택합니다.
1. **권한** 탭을 선택하고 **AmazonBedrockLimitedAccess** 정책을 선택한 다음 **제거**를 선택합니다.
**참고**
현재 API 키에서 모든 권한을 제거했으며 해당 키로 아무 작업도 수행할 수 없습니다.
1. **권한 정책** 섹션의 **권한 추가** 드롭다운에서 **인라인 정책 생성**을 선택합니다.
1. **정책 편집기**에서 **JSON**을 선택합니다. 다음 정책을 편집기에 붙여넣습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock:CallWithBearerToken"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel*"
],
"Resource": [
"arn:aws:bedrock:us-west-2:111122223333:inference-profile/us.anthropic.claude-3-haiku-20240307-v1:0"
]
},
{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel*"
],
"Resource": [
"arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-haiku-20240307-v1:0",
"arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
],
"Condition": {
"StringLike": {
"bedrock:InferenceProfileArn": "arn:aws:bedrock:us-west-2:111122223333:inference-profile/us.anthropic.claude-3-haiku-20240307-v1:0"
}
}
}
]
}
```
------
1. **다음**을 선택하고 **정책 이름**을 입력한 후 **정책 생성**을 선택합니다.
1. 이제 사용자는 이 API 키를 사용하여 미국 서부(오리건)의 미국 Anthropic Claude 3 Haiku 추론 프로파일로만 추론을 실행할 수 있습니다.
# 손상된 장기 및 단기 Amazon Bedrock API 키 처리
API 키가 손상되면 API 키 사용 권한을 취소해야 합니다. 다양한 방법으로 Amazon Bedrock API 키에 대한 권한을 취소할 수 있습니다.
+ 장기 Amazon Bedrock API 키의 경우 [UpdateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateServiceSpecificCredential.html.html), [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html.html) 또는 [DeleteServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteServiceSpecificCredential.html.html)을 사용하여 다음과 같은 방법으로 권한을 취소할 수 있습니다.
+ 키의 상태를 비활성으로 설정합니다. 나중에 키를 다시 활성화할 수 있습니다.
+ 키를 재설정합니다. 이 작업은 키에 대한 새 암호를 생성합니다.
+ 키를 영구적으로 삭제합니다.
**참고**
API를 통해 이러한 작업을 수행하려면 Amazon Bedrock API 키가 아닌 AWS 자격 증명으로 인증해야 합니다.
+ 장기 및 단기 Amazon Bedrock API 키 모두에 대해 IAM 정책을 연결하여 권한을 취소할 수 있습니다.
**Topics**
+ [장기 Amazon Bedrock API 키의 상태 변경](#api-keys-change-status)
+ [장기 Amazon Bedrock API 키 재설정](#api-keys-reset)
+ [장기 Amazon Bedrock API 키 삭제](#api-keys-delete)
+ [IAM 정책을 연결하여 Amazon Bedrock API 키 사용 권한 제거](#api-keys-iam-policies)
## 장기 Amazon Bedrock API 키의 상태 변경
키가 일시적으로 사용되지 않도록 해야 하는 경우 비활성화합니다. 다시 사용할 준비가 되면 재활성화합니다.
원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ Console ]
**키를 비활성화하려면**
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명 AWS Management Console 으로에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 왼쪽 탐색 창에서 **API 키**를 선택합니다.
1. **장기 API 키** 섹션에서 **상태**가 **비활성**인 키를 선택합니다.
1. **작업**을 선택합니다.
1. **Deactivate**(비활성화)를 선택합니다.
1. 확인하려면 **API 키 비활성화**를 선택합니다. 키의 **상태**가 **비활성**이 됩니다.
**키를 다시 활성화하려면**
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명 AWS Management Console 으로에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 왼쪽 탐색 창에서 **API 키**를 선택합니다.
1. **장기 API 키** 섹션에서 **상태**가 **비활성**인 키를 선택합니다.
1. **작업**을 선택합니다.
1. **활성화**를 선택합니다.
1. 확인하려면 **API 키 활성화**를 선택합니다. 키의 **상태**가 **활성**이 됩니다.
------
#### [ Python ]
API를 사용하여 키를 비활성화하려면 [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)를 사용하여 [UpdateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateServiceSpecificCredential.html.html) 요청을 보내고 `Status`를 `Inactive`로 지정합니다. 다음 코드 조각을 통해 *\$1\$1ServiceSpecificCredentialId\$1*를 키 생성 시 반환된 값으로 바꾸어 키를 비활성화할 수 있습니다.
```
import boto3
iam_client = boto3.client("iam")
iam_client.update_service_specific_credential(
service_specific_credential_id=${ServiceSpecificCredentialId},
status="Inactive"
)
```
API를 사용하여 키를 재활성화하려면 [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)를 사용하여 [UpdateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateServiceSpecificCredential.html.html) 요청을 보내고 `Status`를 `Active`로 지정합니다. 다음 코드 조각을 통해 *\$1\$1ServiceSpecificCredentialId\$1*를 키 생성 시 반환된 값으로 바꾸어 키를 다시 활성화할 수 있습니다.
```
import boto3
iam_client = boto3.client("iam")
iam_client.update_service_specific_credential(
service_specific_credential_id=${ServiceSpecificCredentialId},
status="Active"
)
```
------
## 장기 Amazon Bedrock API 키 재설정
키 값이 손상되었거나 키 값이 더 이상 없는 경우 재설정합니다. 키가 아직 만료되지 않았어야 합니다. 이미 만료된 경우 키를 삭제하고 새 키를 생성합니다.
원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ Console ]
**키를 재설정하려면**
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명 AWS Management Console 으로에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 왼쪽 탐색 창에서 **API 키**를 선택합니다.
1. **장기 API 키** 섹션에서 키를 선택합니다.
1. **작업**을 선택합니다.
1. **키 재설정**을 선택합니다.
1. **다음**을 선택합니다.
------
#### [ Python ]
API를 사용하여 키를 재설정하려면 [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)를 사용하여 [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html.html) 요청을 전송합니다. 다음 코드 조각을 통해 *\$1\$1ServiceSpecificCredentialId\$1*를 키 생성 시 반환된 값으로 바꾸어 키를 재설정할 수 있습니다.
```
import boto3
iam_client = boto3.client("iam")
iam_client.reset_service_specific_credential(
service_specific_credential_id=${ServiceSpecificCredentialId}
)
```
------
## 장기 Amazon Bedrock API 키 삭제
키가 더 이상 필요하지 않거나 만료된 경우 삭제합니다.
원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ Console ]
**키 삭제**
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명 AWS Management Console 으로에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 왼쪽 탐색 창에서 **API 키**를 선택합니다.
1. **장기 API 키** 섹션에서 키를 선택합니다.
1. **작업**을 선택합니다.
1. **삭제**를 선택합니다.
1. 삭제를 확인합니다.
**API 키가 IAM 사용자와 연결됨**
이 API 키를 삭제해도이 키를 소유자로 사용하여 생성된 IAM 사용자는 삭제되지 않습니다. 다음 단계에서 IAM 콘솔에서 IAM 사용자를 삭제할 수 있습니다.
------
#### [ Python ]
API를 사용하여 키를 삭제하려면 [IAM 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/iam-service.html)를 사용하여 [DeleteServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteServiceSpecificCredential.html.html) 요청을 보냅니다. 다음 코드 조각을 통해 *\$1\$1ServiceSpecificCredentialId\$1*를 키 생성 시 반환된 값으로 바꾸어 키를 삭제할 수 있습니다.
```
import boto3
iam_client = boto3.client("iam")
iam_client.delete_service_specific_credential(
service_specific_credential_id=${ServiceSpecificCredentialId}
)
```
------
## IAM 정책을 연결하여 Amazon Bedrock API 키 사용 권한 제거
이 섹션에서는 Amazon Bedrock API 키에 대한 액세스를 제한하는 데 사용할 수 있는 몇 가지 IAM 정책을 제공합니다.
### 자격 증명의 Amazon Bedrock API 키를 사용한 직접 호출 기능 거부
자격 증명이 Amazon Bedrock API 키를 사용하여 직접 호출할 수 있도록 허용하는 작업은 `bedrock:CallWithBearerToken`입니다. 자격 증명이 Amazon Bedrock API 키를 사용하여 직접 호출하지 못하도록 하려면 키 유형에 따라 자격 증명에 IAM 정책을 연결할 수 있습니다.
+ **장기 키** - 정책을 키와 연결된 IAM 사용자에게 연결합니다.
+ **단기 키** - 키를 생성하는 데 사용된 IAM 역할에 정책을 연결합니다.
IAM 자격 증명에 연결할 수 있는 IAM 정책은 다음과 같습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "bedrock:CallWithBearerToken",
"Resource": "*"
}
}
```
------
### IAM 역할 세션 무효화
단기 키가 손상되면 키를 생성하는 데 사용된 역할 세션을 무효화하여 사용을 방지할 수 있습니다. 역할 세션을 무효화하려면 키를 생성한 IAM 자격 증명에 다음 정책을 연결합니다. *2014-05-07T23:47:00Z*를 세션을 무효화하려는 시간으로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {
"DateLessThan": {"aws:TokenIssueTime": "2014-05-07T23:47:00Z"}
}
}
}
```
------
# Amazon Bedrock API 키 생성 및 사용에 대한 권한 제어
Amazon Bedrock API 키의 생성 및 사용은 Amazon Bedrock 및 IAM 서비스 모두에서 작업 및 조건 키로 제어됩니다.
**Amazon Bedrock API 키 생성 제어**
[iam:CreateServiceSpecificCredential](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) 작업은 서비스별 키(예: 장기 Amazon Bedrock API 키)의 생성을 제어합니다. 이 작업의 범위를 리소스인 IAM 사용자로 지정하여 키를 생성할 수 있는 사용자를 제한할 수 있습니다.
다음 조건 키를 사용하여 `iam:CreateServiceSpecificCredential` 작업에 대한 권한에 조건을 적용할 수 있습니다.
+ [iam:ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) - 조건에서 키의 만료 시간을 일 단위로 지정할 수 있습니다. 예를 들어, 이 조건 키를 사용하여 90일 이내에 만료되는 API 키의 생성만 허용할 수 있습니다.
+ [iam:ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) - 조건에서 서비스 이름을 지정할 수 있습니다. 예를 들어, 이 조건 키를 사용하여 다른 서비스가 아닌 Amazon Bedrock에 대한 API 키 생성만 허용할 수 있습니다.
**Amazon Bedrock API 키 사용 제어**
[bedrock:CallWithBearerToken](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-actions-as-permissions) 작업은 단기 또는 장기 Amazon Bedrock API 키의 사용을 제어합니다.
`bedrock:bearerTokenType` 조건 키를 [문자열 조건 연산자](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String)와 함께 사용하여 `bedrock:CallWithBearerToken`에 대한 권한을 적용할 보유자 토큰 유형을 지정할 수 있습니다. 다음 값 중 하나를 지정할 수 있습니다.
+ `SHORT_TERM` - 조건에 단기 Amazon Bedrock API 키를 지정합니다.
+ `LONG_TERM` - 조건에 장기 Amazon Bedrock API 키를 지정합니다.
다음 표에는 자격 증명이 Amazon Bedrock API 키를 생성하거나 사용하지 못하도록 하는 방법이 요약되어 있습니다.
****
| 용도 | 장기 키 | 단기 키 |
| --- | --- | --- |
| 키 생성 방지 | iam:CreateServiceSpecificCredential 작업을 거부하는 정책을 IAM 자격 증명에 연결합니다. | 해당 사항 없음 |
| 키 사용 방지 | 키와 연결된 IAM 사용자에게 bedrock:CallWithBearerToken 작업을 거부하는 정책을 연결합니다. | 키를 사용하지 않으려는 IAM 자격 증명에 bedrock:CallWithBearerToken 작업을 거부하는 정책을 연결합니다. |
**주의**
단기 Amazon Bedrock API 키는 세션의 기존 자격 증명을 사용하므로, 키를 생성한 자격 증명에 대한 `bedrock:CallWithBearerToken` 작업을 거부하여 사용을 방지할 수 있습니다. 그러나 단기 키의 생성을 방지할 수는 없습니다.
## API 키의 생성 및 사용을 제어하는 정책 예제
가령 API 키의 생성 및 사용을 제어하는 IAM 정책의 경우 다음 주제 중에서 선택하면 됩니다.
**Topics**
+ [자격 증명이 장기 키를 생성하고 Amazon Bedrock API 키를 사용하지 못하도록 방지](#api-keys-permissions-examples-prevent-generation-and-use)
+ [자격 증명이 단기 API 키를 사용하지 못하도록 방지](#api-keys-permissions-examples-prevent-use-short-term)
+ [자격 증명이 장기 API 키를 사용하지 못하도록 방지](#api-keys-permissions-examples-prevent-use-long-term)
+ [자격 증명이 단기 API 키를 사용하지 않도록 명시적으로 방지](#api-keys-permissions-examples-deny-use-short-term-explicitly)
+ [자격 증명이 장기 API 키를 사용하지 않도록 명시적으로 방지](#api-keys-permissions-examples-deny-use-long-term-explicitly)
+ [90일 이내에 만료되는 경우에만 Amazon Bedrock 키 생성 허용](#api-keys-permissions-examples-allow-bedrock-keys-expire-within-90-days)
### 자격 증명이 장기 키를 생성하고 Amazon Bedrock API 키를 사용하지 못하도록 방지
IAM 자격 증명이 장기 Amazon Bedrock API 키를 생성하고 Amazon Bedrock API 키를 사용하지 못하도록 하려면 자격 증명에 다음 정책을 연결합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid":"DenyBedrockShortAndLongTermAPIKeys",
"Effect": "Deny",
"Action": [
"iam:CreateServiceSpecificCredential",
"bedrock:CallWithBearerToken"
],
"Resource": [
"*"
]
}
]
}
```
------
**주의**
단기 키의 생성을 방지할 수는 없습니다.
이 정책은 AWS 서비스별 자격 증명 생성을 지원하는 모든 서비스에 대한 자격 증명 생성을 방지합니다. 자세한 내용은 [IAM 사용자를 위한 서비스별 자격 증명](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html)을 참조하세요.
### 자격 증명이 단기 API 키를 사용하지 못하도록 방지
IAM 자격 증명이 단기 Amazon Bedrock API 키를 사용하지 못하도록 하려면 다음 정책을 자격 증명에 연결합니다.
### 자격 증명이 장기 API 키를 사용하지 못하도록 방지
IAM 자격 증명이 장기 Amazon Bedrock API 키를 사용하지 못하도록 하려면 다음 정책을 자격 증명에 연결합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "bedrock:CallWithBearerToken",
"Resource": "*",
"Condition": {
"StringEquals": {
"bedrock:bearerTokenType": "LONG_TERM"
}
}
}
]
}
```
------
### 자격 증명이 단기 API 키를 사용하지 않도록 명시적으로 방지
IAM 자격 증명이 단기 Amazon Bedrock API 키를 사용하지 못하도록 명시적으로 방지하되, 다른 API 키 사용을 허용하려면 다음 정책을 자격 증명에 연결합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "bedrock:CallWithBearerToken",
"Resource": "*",
"Condition": {
"StringEquals": {
"bedrock:bearerTokenType": "SHORT_TERM"
}
}
},
{
"Effect": "Allow",
"Action": "bedrock:CallWithBearerToken",
"Resource": "*"
}
]
}
```
------
### 자격 증명이 장기 API 키를 사용하지 않도록 명시적으로 방지
IAM 자격 증명이 장기 Amazon Bedrock API 키를 사용하지 못하도록 명시적으로 방지하되, 다른 API 키 사용을 허용하려면 다음 정책을 자격 증명에 연결합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "bedrock:CallWithBearerToken",
"Resource": "*",
"Condition": {
"StringEquals": {
"bedrock:bearerTokenType": "LONG_TERM"
}
}
},
{
"Effect": "Allow",
"Action": "bedrock:CallWithBearerToken",
"Resource": "*"
}
]
}
```
------
### 90일 이내에 만료되는 경우에만 Amazon Bedrock 키 생성 허용
Amazon Bedrock용이고 만료 시간이 90일 이하인 경우에만 IAM 자격 증명이 장기 API 키를 생성하도록 허용하려면 자격 증명에 다음 정책을 연결합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceSpecificCredential",
"Resource": "arn:aws:iam::123456789012:user/username",
"Condition": {
"StringEquals": {
"iam:ServiceSpecificCredentialServiceName": "bedrock.amazonaws.com"
},
"NumericLessThanEquals": {
"iam:ServiceSpecificCredentialAgeDays": "90"
}
}
}
]
}
```
------
# 모델 추론을 사용하여 프롬프트 제출 및 응답 생성
추론은 모델에 제공된 입력에서 출력을 생성하는 프로세스를 말합니다.
Amazon Bedrock은 다음 양식의 출력을 생성하는 데 사용할 수 있는 일련의 파운데이션 모델을 제공합니다. 파운데이션 모델별 양식 지원을 확인하려면 [Amazon Bedrock에서 지원되는 파운데이션 모델](models-supported.md) 섹션을 참조하세요.
****
| 출력 양식 | 설명 | 사용 사례 예제 |
| --- | --- | --- |
| 텍스트 | 텍스트 입력을 제공하고 다양한 유형의 텍스트를 생성합니다. | 채팅, 질문과 답변, 브레인스토밍, 요약, 코드 생성, 테이블 생성, 데이터 형식 지정, 재작성 |
| 이미지 | 텍스트 또는 입력 이미지를 제공하고 이미지를 생성 또는 수정합니다. | 이미지 생성, 이미지 편집, 이미지 변형 |
| 비디오 | 텍스트 또는 참조 이미지 제공 및 비디오 생성 | 비디오 생성, 비디오로 이미지 변환 |
| 임베딩 | 텍스트, 이미지 또는 텍스트와 이미지를 모두 제공하고 입력을 나타내는 숫자 값의 벡터를 생성합니다. 출력 벡터를 다른 임베딩 벡터와 비교하여 시맨틱 유사성(텍스트) 또는 시각적 유사성(이미지)을 확인할 수 있습니다. | 텍스트 및 이미지 검색, 쿼리, 분류, 추천, 개인화, [지식 기반 생성](knowledge-base.md) |
**Topics**
+ [다양한 모델 추론 방법의 사용 사례에 대해 알아봅니다.](inference-methods.md)
+ [Amazon Bedrock에서 추론이 작동하는 방식](inference-how.md)
+ [추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법](inference-parameters.md)
+ [모델 추론에 지원되는 리전 및 모델](inference-supported.md)
+ [모델 추론 실행을 위한 사전 조건](inference-prereq.md)
+ [플레이그라운드를 사용하여 콘솔에서 응답 생성](playgrounds.md)
+ [모델 추론을 사용하여 모델 응답 향상](inference-reasoning.md)
+ [지연 시간에 대한 모델 추론 최적화](latency-optimized-inference.md)
+ [OpenAI APIs 사용하여 응답 생성](bedrock-mantle.md)
+ [API를 사용하여 프롬프트 제출 및 응답 생성](inference-api.md)
+ [모델에서 검증된 JSON 결과 가져오기](structured-output.md)
+ [컴퓨터 사용 도구를 사용하여 Amazon Bedrock 모델 응답 완료](computer-use.md)
# 다양한 모델 추론 방법의 사용 사례에 대해 알아봅니다.
다음과 같은 방법으로 모델 추론을 직접 실행할 수 있습니다.
****
| 방법 | 사용 사례: |
| --- | --- |
| [Amazon Bedrock 콘솔 플레이그라운드](playgrounds.md) | 사용자 친화적인 그래픽 인터페이스에서 추론을 실행합니다. 탐색에 편리합니다. |
| [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 또는 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) | 모델 입력을 위한 통합 API를 사용하여 대화형 애플리케이션을 구현합니다. |
| [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 또는 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) | 단일 프롬프트를 제출하고 응답을 동기적으로 생성합니다. 실시간 응답 생성이나 검색 쿼리에 유용합니다. |
| [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html) | 단일 프롬프트를 제출하고 응답을 비동기적으로 생성합니다. 대규모로 응답을 생성하는 데 유용합니다. |
| [CreateModelInvocationJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_CreateModelInvocationJob.html) | 프롬프트 데이터세트를 준비하고 배치로 응답을 생성합니다. |
| [응답 API](https://platform.openai.com/docs/api-reference/responses) | 내장된 도구 사용(검색, 코드 인터프리터), 멀티모달 입력 및 상태 저장 대화가 필요한 최신 에이전트 애플리케이션에 응답 API를 사용합니다. |
| [채팅 완료](https://platform.openai.com/docs/api-reference/chat) | 채팅 기록 관리를 완전히 제어하고 지연 시간을 줄여야 하는 경량의 상태 비저장 텍스트 중심 작업에 Chat Completions API를 사용합니다. |
다음 Amazon Bedrock 기능 또한 모델 추론을 더 큰 워크플로의 한 단계로 사용합니다.
+ [모델 평가](evaluation.md)는 사용자가 [CreateEvaluationJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_CreateEvaluationJob.html) 요청을 제출한 후 모델 간접 호출 프로세스를 사용하여 여러 모델의 성능을 평가합니다.
+ [지식 기반](knowledge-base.md)은 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) API를 사용하여 지식 기반에서 검색된 결과를 기반으로 응답을 생성할 때 모델 간접 호출을 사용합니다.
+ [에이전트](agents.md)는 모델 간접 호출을 사용하여 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 요청 과정의 다양한 단계에서 응답을 생성합니다.
+ [흐름](flows.md)에는 모델 간접 호출을 사용하는 프롬프트, 지식 기반 및 에이전트와 같은 Amazon Bedrock 리소스가 포함됩니다.
다양한 프롬프트와 추론 파라미터를 사용하여 다양한 파운데이션 모델을 테스트한 후 원하는 사양으로 이러한 API를 직접 호출하도록 애플리케이션을 구성할 수 있습니다.
# Amazon Bedrock에서 추론이 작동하는 방식
모델에 입력을 제출하면 모델이 뒤에 오는 토큰의 가능한 시퀀스를 예측하고 그 시퀀스를 출력으로 반환합니다. Amazon Bedrock은 선택한 파운데이션 모델로 추론을 실행할 수 있는 기능을 제공합니다. 추론을 실행할 때 다음 입력을 제공합니다.
+ **프롬프트** - 응답을 생성하기 위해 모델에 제공하는 입력입니다. 프롬프트를 작성하는 방법에 대한 자세한 내용은 [프롬프트 엔지니어링 개념](prompt-engineering-guidelines.md) 섹션을 참조하세요. 프롬프트 인젝션 공격을 방어하는 방법에 대한 자세한 내용은 [프롬프트 인젝션 보안](prompt-injection.md) 섹션을 참조하세요.
+ **모델** - 프롬프트에 대해 추론을 실행하도록 모델에 요청합니다. 선택한 모델은 사용자가 처리할 수 있는 입력 및 출력 토큰의 수와 속도를 정의하는 처리량 수준도 지정합니다. 다음 유형의 모델에 요청할 수 있습니다.
+ **기본 모델** - 추론을 실행할 파운데이션 모델입니다. 요청은 단일 AWS 리전으로 전송됩니다. 모델 ID에 대해서는 [Amazon Bedrock에서 지원되는 파운데이션 모델](models-supported.md) 섹션을 참조하세요. Amazon Bedrock에서 사용할 수 있는 파운데이션 모델에 대한 자세한 내용은 [Amazon Bedrock 파운데이션 모델 정보](foundation-models-reference.md) 섹션을 참조하세요.
+ **추론 프로파일** - 추론을 실행할 파운데이션 모델입니다. 여러 AWS 리전의 모델로 요청이 이루어집니다. 추론 프로파일 ID에 대해서는 [추론 프로파일에 지원되는 리전 및 모델](inference-profiles-support.md) 섹션을 참조하세요.
**참고**
모델은 리전 및 API 메서드별로 기본 모델 및 추론 프로파일 가용성이 다릅니다. 자세한 내용은 [파운데이션 모델 참조](foundation-models-reference.md)의 [Amazon Bedrock에서 지원되는 파운데이션 모델](models-supported.md) 및 개별 모델 페이지를 참조하세요.
+ **프로비저닝된 처리량** - 전용 처리량을 구매한 파운데이션 모델입니다. 자세한 내용은 [Amazon Bedrock에서 프로비저닝된 처리량으로 모델 간접 호출 용량 증대](prov-throughput.md) 섹션을 참조하세요.
+ **사용자 지정 모델** - 모델 사용자 지정을 통해 가중치가 수정된 파운데이션 모델입니다. 자세한 내용은 [모델을 사용자 지정하여 사용 사례에 맞게 성능 개선](custom-models.md) 섹션을 참조하세요.
+ **추론 파라미터** - 모델 응답을 제한하거나 영향을 미치도록 조정할 수 있는 값 집합입니다. 추론 파라미터에 대한 자세한 내용은 [추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법](inference-parameters.md) 및 [파운데이션 모델의 추론 요청 파라미터 및 응답 필드](model-parameters.md) 섹션을 참조하세요.
## 다양한 AWS 리전에서 모델 간접 호출
모델을 간접적으로 호출할 때 호출할 AWS 리전을 선택합니다. 수행할 수 있는 요청의 빈도와 크기에 대한 할당량은 리전에 따라 다릅니다. [Amazon Bedrock 서비스 할당량](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#limits_bedrock)에서 다음 할당량을 검색하여 이러한 할당량을 찾을 수 있습니다.
+ *\$1\$1Model\$1*에 대한 분당 온디맨드 모델 추론 요청
+ *\$1\$1Model\$1*에 대한 분당 온디맨드 InvokeModel 토큰 \$1
파운데이션 모델 자체 대신 추론 프로파일을 간접적으로 호출할 수도 있습니다. 추론 프로파일은 추론 프로파일이 모델 간접 호출 요청을 라우팅할 수 있는 하나 이상의 리전과 모델을 정의합니다. 여러 리전이 포함된 추론 프로파일을 간접적으로 호출하면 처리량을 늘릴 수 있습니다. 자세한 내용은 [교차 리전 추론을 통한 처리량 증대](cross-region-inference.md) 섹션을 참조하세요. 추론 프로파일로 수행할 수 있는 요청의 빈도 및 크기에 대한 할당량을 보려면 [Amazon Bedrock 서비스 할당량](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#limits_bedrock)에서 다음 할당량을 검색합니다.
+ *\$1\$1Model\$1*에 대한 분당 교차 리전 InvokeModel 요청
+ *\$1\$1Model\$1*에 대한 분당 교차 리전 InvokeModel 토큰
+ *\$1\$1Model\$1*에 대한 분당 글로벌 교차 리전 InvokeModel 요청
+ *\$1\$1Model\$1*에 대한 분당 글로벌 교차 리전 InvokeModel 토큰
리전에 대한 요청은 동일한 상위 리전을 공유하는 로컬 영역에서 처리될 수 있습니다. 예를 들어 미국 동부(버지니아 북부)(us-east-1)에 대한 요청은 미국 애틀랜타(us-east-1-atl-2a)와 같이 연결된 모든 로컬 영역에서 처리될 수 있습니다.
교차 리전 추론을 사용할 때도 동일한 원칙이 적용됩니다. 예를 들어 미국 Anthropic Claude 3 Haiku 추론 프로파일에 대한 요청은 미국 시애틀(us-west-2-sea-1a)과 같이 미국에 상위 리전이 있는 모든 로컬 영역에서 처리될 수 있습니다. 새 로컬 영역이 AWS에 추가되면 해당 교차 리전 추론의 엔드포인트에도 추가됩니다.
로컬 엔드포인트 및 연결된 상위 리전의 목록을 보려면 [AWS 로컬 영역 위치](https://aws.amazon.com/about-aws/global-infrastructure/localzones/locations/)를 참조하세요.
Amazon Bedrock에서 교차 리전 추론 프로파일을 간접적으로 호출하면 요청은 소스 리전에서 시작되고 해당 프로파일에 정의된 대상 리전 중 하나로 자동으로 라우팅되어 성능을 최적화합니다. 글로벌 교차 리전 추론 프로파일의 대상 리전에는 모든 상용 리전이 포함됩니다.
AWS가 사용자의 요청을 처리할 수 있는 상용 리전을 추가함에 따라 특정 모델에 대한 글로벌 교차 리전 추론 프로파일은 시간이 지나면서 변경될 수 있습니다. 그러나 추론 프로파일이 지리(예: 미국, EU 또는 APAC)에 연결된 경우 대상 리전 목록은 변경되지 않습니다. AWS는 새 리전을 통합하는 새 추론 프로파일을 생성할 수 있습니다. 설정의 ID를 새 ID로 변경하여 이러한 추론 프로파일을 사용하도록 시스템을 업데이트할 수 있습니다.
**참고**
교차 리전 추론 프로파일의 대상 리전에는 AWS 계정 또는 조직 수준에서 명시적으로 활성화해야 하는 리전인 **옵트인 리전**이 포함될 수 있습니다. 자세한 내용은 [계정에서 AWS 리전 활성화 또는 비활성화](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html)를 참조하세요. 교차 리전 추론 프로파일을 사용하는 경우 계정의 해당 리전에 옵트인하지 않은 경우에도 추론 요청을 프로파일의 대상 리전으로 라우팅할 수 있습니다.
서비스 제어 정책(SCP)과 AWS Identity and Access Management(IAM) 정책은 함께 작동하여 교차 리전 추론이 허용되는 위치를 제어합니다. SCP를 사용하면 Amazon Bedrock이 추론에 사용할 수 있는 리전을 제어할 수 있으며, IAM 정책을 사용하면 추론을 실행할 권한이 있는 사용자 또는 역할을 정의할 수 있습니다. 교차 리전 추론 프로파일의 대상 리전이 SCP에서 차단된 경우 다른 리전이 허용된 상태로 남아 있더라도 요청이 실패합니다. 교차 리전 추론을 통한 효율적인 작업을 보장하기 위해 SCP 및 IAM 정책을 업데이트하여 선택한 추론 프로파일에 포함된 모든 대상 리전에서 필요한 모든 Amazon Bedrock 추론 작업(예: `bedrock:InvokeModel*` 또는 `bedrock:CreateModelInvocationJob`)을 허용할 수 있습니다. 자세한 내용은 [https://aws.amazon.com/blogs/machine-learning/enable-amazon-bedrock-cross-region-inference-in-multi-account-environments/](https://aws.amazon.com/blogs/machine-learning/enable-amazon-bedrock-cross-region-inference-in-multi-account-environments/)다중 계정 환경에서 Amazon Bedrock 교차 리전 추론 활성화를 참조하세요.
# 추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법
모델 추론을 실행할 때 추론 파라미터를 조정하여 모델 응답에 영향을 미칠 수 있습니다. 추론 파라미터는 모델이 생성 과정에서 고려하는 가능한 출력 풀을 변경하거나 최종 응답을 제한할 수 있습니다.
추론 파라미터 기본값 및 범위는 모델에 따라 다릅니다. 여러 모델의 추론 파라미터에 대한 자세한 내용은 [파운데이션 모델의 추론 요청 파라미터 및 응답 필드](model-parameters.md) 섹션을 참조하세요.
다음과 같은 카테고리의 파라미터는 여러 모델에서 흔히 볼 수 있습니다.
**Topics**
+ [무작위성 및 다양성](#inference-randomness)
+ [길이](#inference-length)
## 무작위성 및 다양성
주어진 모든 시퀀스의 경우 시퀀스의 다음 토큰에 대한 옵션의 확률 분포를 확인할 수 있습니다. 출력에 각 토큰을 생성하기 위해 모델은 이 분포에서 샘플링합니다. 무작위성과 다양성은 모델 응답의 변수량을 나타냅니다. 분포를 제한하거나 조정하여 이러한 요인을 제어할 수 있습니다. 파운데이션 모델은 일반적으로 다음과 같은 파라미터를 지원하여 응답의 무작위성과 다양성을 제어합니다.
+ **온도** - 예측 출력의 확률 분포 형태에 영향을 미치고 모델이 낮은 확률 출력을 선택할 가능성에 영향을 줍니다.
+ 모델이 더 높은 확률의 출력을 선택하도록 영향을 미치려면 더 낮은 값을 선택합니다.
+ 모델이 더 낮은 확률의 출력을 선택하도록 영향을 미치려면 더 높은 값을 선택합니다.
전문적 관점에서 온도는 다음 토큰의 확률 질량 함수를 조절합니다. 온도가 낮을수록 함수의 강도가 높아져 결정론적 응답이 나타나고, 온도가 높을수록 함수가 평면화되어 무작위 응답이 더 많아집니다.
+ **Top K** - 모델이 다음 토큰을 고려할 가능성이 가장 높은 후보의 수입니다.
+ 풀 크기를 줄이고 옵션을 더 가능성이 높은 출력으로 제한하려면 더 낮은 값을 선택합니다.
+ 풀 크기를 늘리고 모델에서 더 가능성이 낮은 출력을 고려하도록 하려면 더 높은 값을 선택합니다.
예를 들어 상위 K 값을 50으로 선택하면 모델은 시퀀스에서 다음 토큰이 될 가능성이 가장 높은 50개의 토큰 중에서 선택합니다.
+ **Top P** - 모델이 다음 토큰을 고려할 가능성이 가장 높은 후보의 비율입니다.
+ 풀 크기를 줄이고 옵션을 더 가능성이 높은 출력으로 제한하려면 더 낮은 값을 선택합니다.
+ 풀 크기를 늘리고 모델에서 더 가능성이 낮은 출력을 고려하도록 하려면 더 높은 값을 선택합니다.
전문적 관점에서 모델은 응답 집합에 대한 누적 확률 분포를 계산하고 분포의 상위 P%만 고려합니다.
예를 들어 상위 P 값을 0.8로 선택하면 모델은 시퀀스에서 다음 토큰 확률 분포가 될 가능성이 가장 높은 상위 80%에서 선택합니다.
다음 표에는 이 파라미터의 효과가 요약되어 있습니다.
****
| 파라미터 | 낮은 값에 따른 영향 | 높은 값에 따른 영향 |
| --- | --- | --- |
| Temperature | 높은 확률 토큰의 가능성 증가 낮은 확률 토큰의 가능성 감소 | 낮은 확률 토큰의 가능성 증가높은 확률 토큰의 가능성 감소 |
| Top K | 낮은 확률 토큰 삭제 | 낮은 확률 토큰 허용 |
| Top P | 낮은 확률 토큰 삭제 | 낮은 확률 토큰 허용 |
이러한 파라미터를 이해하기 위한 예제로 **I hear the hoof beats of "** 프롬프트를 참조하세요. 모델이 다음 토큰의 후보로 다음 세 단어를 결정한다고 가정해 보겠습니다. 또한 모델은 각 단어에 확률을 할당합니다.
```
{
"horses": 0.7,
"zebras": 0.2,
"unicorns": 0.1
}
```
+ **temperature**를 높게 설정하면 확률 분포가 평탄해지고 확률의 차이가 줄어들어 ‘unicorns’를 선택할 확률은 높아지고 ‘horses’를 선택할 확률은 낮아집니다.
+ **Top K**를 2로 설정하면 모델은 가장 가능성이 높은 상위 2개 후보인 ‘horses’와 ‘zebras’만 고려합니다.
+ **Top P**를 0.7로 설정하면 모델에서는 ‘horses’만 고려하는데, 이는 확률 분포의 상위 70% 에 속하는 유일한 후보이기 때문입니다. **Top P**를 0.9로 설정하면 모델은 확률 분포의 상위 90%에 속하는 ‘horses’와 ‘zebras’를 고려합니다.
## 길이
일반적으로 파운데이션 모델은 응답의 길이를 제어하는 파라미터를 지원합니다. 이러한 파라미터의 예제가 아래에 나와 있습니다.
+ **응답 길이** - 생성된 응답에서 반환할 최소 또는 최대 토큰 수를 지정하는 정확한 값입니다.
+ **페널티** - 응답의 출력에 페널티 수준을 지정합니다. 예는 다음과 같습니다.
+ 응답의 길이입니다.
+ 응답에서 토큰이 반복되었습니다.
+ 응답에 포함된 토큰의 빈도입니다.
+ 응답의 토큰 유형입니다.
+ **중지 시퀀스** - 모델이 더 이상 토큰을 생성하지 못하도록 하는 문자 시퀀스를 지정합니다. 모델에서 지정한 중지 시퀀스를 생성하는 경우 해당 시퀀스 이후에는 생성이 중지됩니다.
# 모델 추론에 지원되는 리전 및 모델
파운데이션 모델을 사용한 모델 추론은 모든 리전과 Amazon Bedrock에서 지원하는 모든 모델에서 지원됩니다. Amazon Bedrock에서 지원하는 리전 및 모델을 보려면 [Amazon Bedrock에서 지원되는 파운데이션 모델](models-supported.md) 섹션을 참조하세요.
파운데이션 모델 이외의 Amazon Bedrock 리소스를 사용하여 모델 추론을 실행할 수도 있습니다. 다양한 리소스의 리전 및 모델 가용성을 보려면 다음 페이지를 참조하세요.
+ [추론 프로파일에 지원되는 리전 및 모델](inference-profiles-support.md)
+ [프롬프트 관리에 지원되는 리전 및 모델](prompt-management-supported.md)
**참고**
[InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 및 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)은 구성이 Anthropic Claude 또는 Meta Llama 모델을 지정하는 프롬프트 관리의 프롬프트에서만 작동합니다.
+ [미세 조정에 지원되는 모델 및 리전](custom-model-fine-tuning.md#custom-model-supported)
+ [사용자 지정 모델 가져오기를 사용하여 사용자 지정 오픈 소스 모델을 Amazon Bedrock으로 가져오기](model-customization-import-model.md)
+ [Amazon Bedrock Guardrails에 지원되는 리전 및 모델](guardrails-supported.md)
# 모델 추론 실행을 위한 사전 조건
역할이 모델 추론을 실행하려면 모델 간접 호출 API 작업을 수행하도록 허용해야 합니다. 역할에 [AmazonBedrockFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockFullAccess)AWS 관리형 정책이 연결되어 있는 경우이 섹션을 건너뛸 수 있습니다. 그렇지 않으면 역할에 다음 권한을 연결하여 Amazon Bedrock에서 지원되는 모든 리소스와 함께 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html), [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html), [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 및 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) 작업을 사용할 수 있도록 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ModelInvocationPermissions",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream",
"bedrock:GetInferenceProfile",
"bedrock:ListInferenceProfiles",
"bedrock:RenderPrompt",
"bedrock:GetCustomModel",
"bedrock:ListCustomModels",
"bedrock:GetImportedModel",
"bedrock:ListImportedModels",
"bedrock:GetProvisionedModelThroughput",
"bedrock:ListProvisionedModelThroughputs",
"bedrock:GetGuardrail",
"bedrock:ListGuardrails",
"bedrock:ApplyGuardrail"
],
"Resource": "*"
}
]
}
```
------
권한을 더욱 제한하려면 작업을 생략하거나 리소스 및 조건 키를 지정하여 권한을 필터링할 수 있습니다. 작업, 리소스 및 조건 키에 대한 자세한 내용은 *서비스 권한 부여 참조*에서 다음 주제를 참조하세요.
+ [Amazon Bedrock에서 정의한 작업](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-actions-as-permissions) - 작업, `Resource` 필드에서 작업의 범위를 지정할 수 있는 리소스 유형, `Condition` 필드에서 권한을 필터링할 수 있는 조건 키에 대해 알아봅니다.
+ [Amazon Bedrock에서 정의한 리소스 유형](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-resources-for-iam-policies) - Amazon Bedrock의 리소스 유형에 대해 알아봅니다.
+ [Amazon Bedrock의 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-policy-keys) - Amazon Bedrock의 조건 키에 대해 알아봅니다.
다음 목록에는 사용 사례에 따라 작업이 필요한지 여부가 요약되어 있습니다.
+ `bedrock:InvokeModel` - 모델 간접 호출을 수행하는 데 필요합니다. 역할이 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 및 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) API 작업을 직접적으로 호출하도록 허용합니다.
+ `bedrock:InvokeModelWithResponseStream` - 모델 간접 호출을 수행하고 스트리밍 응답을 반환하는 데 필요합니다. 역할이 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) 및 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)Stream API 작업을 직접적으로 호출하도록 허용합니다.
+ 다음 작업을 통해 역할은 파운데이션 모델 외에 Amazon Bedrock 리소스로 추론을 실행할 수 있습니다.
+ `bedrock:GetInferenceProfile` - [추론 프로파일](inference-profiles.md)로 추론을 실행하는 데 필요합니다.
+ `bedrock:RenderPrompt` - [프롬프트 관리](prompt-management.md)에서 프롬프트를 간접적으로 호출하는 데 필요합니다.
+ `bedrock:GetCustomModel` - [사용자 지정 모델](custom-models.md)로 추론을 실행하는 데 필요합니다.
+ `bedrock:GetImportedModel` - [가져온 모델](model-customization-import-model.md)로 추론을 실행하는 데 필요합니다.
+ `bedrock:GetProvisionedModelThroughput` - [프로비저닝된 처리량](prov-throughput.md)으로 추론을 실행하는 데 필요합니다.
+ 다음 작업을 통해 역할은 Amazon Bedrock 콘솔에서 파운데이션 모델 외에 Amazon Bedrock 리소스를 보고 선택할 수 있습니다.
+ `bedrock:ListInferenceProfiles` - Amazon Bedrock 콘솔에서 [추론 프로파일](custom-models.md)을 선택하는 데 필요합니다.
+ `bedrock:ListCustomModels` - Amazon Bedrock 콘솔에서 [사용자 지정 모델](custom-models.md)을 선택하는 데 필요합니다.
+ `bedrock:ListImportedModels` - Amazon Bedrock 콘솔에서 [가져온 모델](model-customization-import-model.md)을 선택하는 데 필요합니다.
+ `bedrock:ListProvisionedModelThroughputs` - Amazon Bedrock 콘솔에서 [프로비저닝된 처리량](prov-throughput.md)을 선택하는 데 필요합니다.
+ 다음 작업을 통해 역할은 모델 간접 호출 중에 [Amazon Bedrock Guardrails](guardrails.md)에서 가드레일을 액세스 및 적용할 수 있습니다.
+ `bedrock:GetGuardrail` - 모델 간접 호출 중에 가드레일을 사용하는 데 필요합니다.
+ `bedrock:ApplyGuardrail` - 모델 간접 호출 중에 가드레일을 적용하는 데 필요합니다.
+ `bedrock:ListGuardrails` - Amazon Bedrock 콘솔에서 가드레일을 선택하는 데 필요합니다.
# 플레이그라운드를 사용하여 콘솔에서 응답 생성
Amazon Bedrock 플레이그라운드는 다양한 모델에서 추론을 실행하고 다양한 구성을 사용하여 실험할 수 있는 시각적 인터페이스를 AWS Management Console 제공하는의 도구입니다. 플레이그라운드를 사용하여 다양한 모델과 값을 애플리케이션에 통합하기 전에 먼저 테스트할 수 있습니다.
플레이그라운드에서 프롬프트를 실행하는 것은 API에서 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html), [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html), [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 또는 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) 요청을 수행하는 것과 동일합니다.
Amazon Bedrock은 실험할 수 있는 다음과 같은 플레이그라운드를 제공합니다.
+ **채팅/텍스트** - 텍스트 프롬프트를 제출하고 응답을 생성하거나 음성과 상호 작용합니다. 다음 모드 중 하나를 선택할 수 있습니다.
+ **채팅** - 텍스트 프롬프트를 제출하거나 음성과 상호 작용합니다. 텍스트 프롬프트의 경우 이미지 또는 문서를 포함하여 프롬프트를 보완할 수도 있습니다. 제출하는 후속 프롬프트에는 이전 프롬프트가 컨텍스트로 포함되므로 프롬프트 및 응답 시퀀스가 대화와 유사합니다.
+ **단일 프롬프트** - 단일 텍스트 프롬프트를 제출하고 그에 대한 응답을 생성합니다.
**참고**
Amazon Nova Sonic과 같은 Speech-to-speech 모델은 채팅 모드에서만 사용할 수 있습니다. speech-to-speech 모델에서는 비교 모드가 지원되지 않습니다.
+ **이미지** - 텍스트 프롬프트를 제출하여 이미지를 생성합니다. 이미지 프롬프트를 제출하고 이 프롬프트를 편집할지 아니면 변형을 생성할지 지정할 수도 있습니다.
+ **다중 모달(미리 보기)** - 텍스트 프롬프트를 제출하고 다중 모달 콘텐츠를 생성합니다. 채팅 및 단일 프롬프트 모드도 지원합니다.
다음 절차에서는 플레이그라운드에서 프롬프트를 제출하는 방법, 조정할 수 있는 옵션, 모델이 응답을 생성한 후 수행할 수 있는 작업에 대해 설명합니다.
**플레이그라운드를 사용하려면 다음을 수행하세요.**
1. 아직 요청하지 않은 경우 사용하려는 모델에 대한 액세스 권한을 요청하세요. 자세한 내용은 [Amazon Bedrock 파운데이션 모델 액세스](model-access.md) 단원을 참조하십시오.
1. Amazon Bedrock 콘솔을 사용할 권한이 있는 IAM 자격 증명 AWS Management Console 으로에 로그인합니다. 그 다음 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)에서 Amazon Bedrock 콘솔을 엽니다.
1. 탐색 창의 테스트에서 **플레이그라운드**를 선택합니다.
1. **채팅/텍스트** 플레이그라운드가 열려 있는 경우 **모드**를 선택합니다.
1. **모델 선택**을 선택하고 사용할 제공업체, 모델 및 처리량을 선택합니다. 처리량 증가에 대한 자세한 내용은 [교차 리전 추론을 통한 처리량 증대](cross-region-inference.md) 및 [Amazon Bedrock에서 프로비저닝된 처리량으로 모델 간접 호출 용량 증대](prov-throughput.md) 섹션을 참조하세요.
1. 응답을 생성하려면 다음 정보를 제출하세요.
+ 프롬프트 - 모델의 시나리오, 질문 또는 작업을 설정하는 하나 이상의 텍스트 문장입니다. 프롬프트 생성에 대한 자세한 내용은 [프롬프트 엔지니어링 개념](prompt-engineering-guidelines.md) 섹션을 참조하세요.
일부 모델( 참조[지원되는 모델 및 모델 기능](conversation-inference-supported-models-features.md))에서는 다음과 같은 방법으로 파일을 포함할 수 있습니다.
+ 첨부 파일 아이콘을 선택하고 업로드할 파일을 선택합니다.
+ 첨부 파일 아이콘을 선택하고 업로드할 Amazon S3 객체를 선택합니다.
+ 파일을 프롬프트로 드래그합니다.
프롬프트를 보완할 파일을 포함합니다. 프롬프트 텍스트에서 파일을 참조할 수 있습니다. 예를 들어 **Summarize this document for me** 또는 **Tell me what's in this image**를 작성할 수 있습니다. 다음과 같은 유형의 파일을 포함할 수 있습니다.
+ **문서** - 프롬프트를 보완할 문서를 추가합니다. 지원되는 파일 유형 목록은 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)의 `format` 필드를 참조하세요.
**주의**
모델이 실수로 문서 이름을 지침으로 해석할 수 있으므로 문서 이름은 프롬프트 인젝션에 취약합니다. 따라서 중립 이름을 지정하는 것이 좋습니다.
+ **이미지** - 모델이 멀티모달 이미지 및 텍스트 입력을 지원하는 경우 프롬프트를 보완할 이미지를 추가합니다. 지원되는 파일 유형 목록은 [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html)의 `format` 필드를 참조하세요.
+ **비디오** - 모델이 멀티모달 비디오 및 텍스트 입력을 지원하는 경우 프롬프트를 보완하는 비디오를 추가합니다. 지원되는 파일 유형 목록은 [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html)의 `format` 필드를 참조하세요.
**참고**
콘텐츠 제한은 기본 API 작업 및 모델에 따라 다릅니다. 자세한 내용은 [API 제한을](inference-api-restrictions.md) 참조하세요.
+ 구성 - 모델 응답을 수정하기 위해 조정하는 설정입니다. 구성에는 다음이 포함됩니다.
+ 추론 파라미터 - 모델이 응답을 생성하는 방식에 영향을 미치거나 제한하는 값입니다. 자세한 내용은 [추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법](inference-parameters.md) 섹션을 참조하세요. 특정 모델에 대한 추론 파라미터를 보려면 [파운데이션 모델의 추론 요청 파라미터 및 응답 필드](model-parameters.md) 섹션을 참조하세요.
+ 시스템 프롬프트 - 수행해야 하는 작업 또는 채택해야 하는 페르소나에 대한 지침 또는 컨텍스트를 모델에 제공하는 프롬프트입니다. 자세한 내용과 시스템 프롬프트를 지원하는 모델 목록은 [Converse API 작업과 대화 수행](conversation-inference.md) 섹션을 참조하세요.
+ 가드레일 - 프롬프트 및 모델 응답에서 유해하거나 원치 않는 콘텐츠를 필터링합니다. 자세한 내용은 [Amazon Bedrock Guardrails를 사용하여 유해한 콘텐츠 감지 및 필터링](guardrails.md) 단원을 참조하십시오.
1. (선택 사항) 모델이 스트리밍을 지원하는 경우 기본 동작은 응답을 스트리밍하는 것입니다. 옵션 아이콘(![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/images/icons/vertical-ellipsis.png))을 선택하고 **스트리밍 기본 설정** 옵션을 수정하여 스트리밍을 끌 수 있습니다.
1. (선택 사항) 일부 텍스트 생성 모델은 비교 평가를 지원하므로 다음을 수행하여 다양한 모델의 응답을 비교할 수 있습니다.
1. **비교 모드**를 켭니다.
1. **모델 선택**을 선택하고 사용할 제공업체, 모델 및 처리량을 선택합니다.
1. 구성 아이콘(![\[Three horizontal sliders with adjustable circular controls for settings or parameters.\]](http://docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/images/icons/configurations.png))을 선택하여 사용할 구성을 수정합니다.
1. 비교할 모델을 더 추가하려면 오른쪽의 \$1 아이콘을 선택하고 모델을 선택한 다음 필요에 따라 구성을 수정합니다.
1. (선택 사항) 모델이 프롬프트 캐싱을 지원하는 경우 **구성** 패널을 열고 **프롬프트 캐싱**을 켜서 비용 및 지연 시간을 줄이기 위해 입력 및 모델 응답 캐싱을 활성화할 수 있습니다. 자세한 내용은 [더 빠른 모델 추론을 위한 프롬프트 캐싱](prompt-caching.md) 단원을 참조하십시오.
1. 프롬프트를 실행하려면 **실행**을 선택합니다. Amazon Bedrock은 사용자가 제공하는 텍스트, 이미지 또는 문서를 저장하지 않습니다. 데이터는 응답을 생성하는 용도로만 사용됩니다.
**참고**
응답이 콘텐츠 조정 정책을 위반할 경우 Amazon Bedrock에서는 해당 응답을 표시하지 않습니다. 스트리밍을 활성화하면 정책을 위반하는 콘텐츠가 생성된 경우 Amazon Bedrock은 전체 응답을 지웁니다. 자세한 내용을 보려면 Amazon Bedrock 콘솔로 이동하여 **제공업체**를 선택하고 **콘텐츠 제한 사항** 섹션 아래의 텍스트를 참조하세요.
1. 모델은 응답을 반환합니다. 플레이그라운드의 채팅 모드를 사용하는 경우 응답에 회신하고 다른 응답을 생성하는 프롬프트를 제출할 수 있습니다.
1. 응답 생성을 마치면 다음과 같은 옵션을 선택할 수 있습니다.
+ 응답을 JSON 파일로 내보내려면 옵션 아이콘(![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/images/icons/vertical-ellipsis.png))을 선택하고 **JSON으로 내보내기**를 선택합니다.
+ 수행한 API 요청을 보려면 옵션 아이콘(![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/images/icons/vertical-ellipsis.png))을 선택하고 **API 요청 보기**를 선택합니다.
+ 플레이그라운드의 채팅 모드에서는 **모델 지표 섹션에서 지표**를 볼 수 있습니다. 다음과 같은 모델 지표를 사용할 수 있습니다.
+ **지연 시간** - Amazon Bedrock에서 요청을 수신한 시점과 응답이 반환된 시점(스트리밍되지 않는 응답의 경우) 또는 응답 스트림이 완료된 시점(스트리밍 응답의 경우) 사이에 걸리는 시간입니다.
+ **입력 토큰 수** - 추론 중에 입력으로 모델에 제공되는 토큰 수입니다.
+ **출력 토큰 수** - 프롬프트에 대한 응답으로 생성된 토큰 수입니다. 더 길고 대화가 많은 응답에는 더 많은 토큰이 필요합니다.
+ **비용** - 입력을 처리하고 출력 토큰을 생성하는 데 드는 비용입니다.
응답과 일치시키려는 지표 기준을 설정하려면 **지표 기준 정의**를 선택하고 모델이 일치할 조건을 정의합니다. 기준을 적용하면 **모델 지표** 섹션에 응답에서 충족된 기준의 종류와 개수가 표시됩니다.
기준이 충족되지 않으면 다른 모델을 선택하거나, 프롬프트를 다시 작성하거나, 구성을 수정하고 프롬프트를 다시 실행할 수 있습니다.
# 모델 추론을 사용하여 모델 응답 향상
일부 파운데이션 모델은 더 크고 복잡한 태스크를 수행하고 더 작고 간단한 단계로 나눌 수 있는 모델 추론을 수행할 수 있습니다. 이 프로세스를 생각의 사슬(CoT) 추론이라고 하는 경우가 많습니다. 생각의 사슬 추론은 모델에 응답하기 전에 생각할 수 있는 기회를 제공하여 모델 정확도를 개선할 수 있습니다. 모델 추론은 다단계 분석, 수학 문제, 복잡한 추론 태스크와 같은 태스크에 가장 유용합니다.
예를 들어 수학적 단어 문제를 해결할 때 모델은 먼저 관련 변수를 식별한 다음 지정된 정보를 기반으로 방정식을 구성하고 마지막으로 이러한 방정식을 해결하여 솔루션에 도달할 수 있습니다. 이 전략은 오류를 최소화할 뿐만 아니라 추론 프로세스를 더 투명하고 따르기 쉽게 만들어 파운데이션 모델의 출력 품질을 개선합니다.
모델 추론은 모든 태스크에 필요하지 않으며 지연 시간 증가 및 출력 토큰을 포함한 추가 오버헤드가 발생합니다. 추가 설명이 필요하지 않은 간단한 태스크는 CoT 추론에 적합하지 않습니다.
일부 모델은 모델 추론에 할당된 출력 토큰 수를 구성할 수 없습니다.
모델 추론은 다음 모델에 사용할 수 있습니다.
| 파운데이션 모델 | 모델 ID | 토큰 수 | 추론 구성 |
| --- | --- | --- | --- |
| Anthropic Claude Opus 4 | anthropic.claude-opus-4-20250514-v1:0 | 이 모델에는 출력 토큰과 추론 토큰을 모두 포함하는 32,768개의 토큰이 있습니다. | 구성 가능한 토큰 예산을 사용하여 이 모델에 대한 추론을 활성화하거나 비활성화할 수 있습니다. 기본적으로 추론은 비활성화되어 있습니다. |
| Anthropic Claude Sonnet 4 | anthropic.claude-sonnet-4-20250514-v1:0 | 이 모델에는 출력 토큰과 추론 토큰을 모두 포함하는 65,536개의 토큰이 있습니다. | 구성 가능한 토큰 예산을 사용하여 이 모델에 대한 추론을 활성화하거나 비활성화할 수 있습니다. 기본적으로 추론은 비활성화되어 있습니다. |
| Anthropic Claude 3.7 Sonnet | anthropic.claude-3-7-sonnet-20250219-v1:0 | 이 모델에는 출력 토큰과 추론 토큰을 모두 포함하는 65,536개의 토큰이 있습니다. | 구성 가능한 토큰 예산을 사용하여 이 모델에 대한 추론을 활성화하거나 비활성화할 수 있습니다. 기본적으로 추론은 비활성화되어 있습니다. |
| DeepSeek DeepSeek-R1 | deepseek.r1-v1:0 | 이 모델에는 출력 토큰과 추론 토큰을 모두 포함하는 8,192개의 토큰이 있습니다. 사고 토큰 수는 구성할 수 없으며 최대 출력 토큰 수는 8,192개보다 크지 않아야 합니다. | 추론은 이 모델에 대해 항상 활성화됩니다. 모델은 추론 기능 켜기 및 끄기를 지원하지 않습니다. |
# 지연 시간에 대한 모델 추론 최적화
**참고**
지연 시간 최적화 추론 기능은에 대한 미리 보기 릴리스이며 변경될 수 Amazon Bedrock 있습니다.
의 파운데이션 모델에 대한 지연 시간 최적화 추론은 AI 애플리케이션에 더 빠른 응답 시간과 향상된 응답성을 Amazon Bedrock 제공합니다. 최적화된 버전의 [https://docs.aws.amazon.com/nova/latest/userguide/what-is-nova.html](https://docs.aws.amazon.com/nova/latest/userguide/what-is-nova.html), [Anthropic의 Claude 3.5 Haiku 모델](https://aws.amazon.com/bedrock/claude/) 및 [Meta의 Llama 3.1 405B 및 70B 모델](https://aws.amazon.com/bedrock/llama/)은 정확도를 손상시키지 않고 지연 시간을 크게 단축합니다.
지연 시간 최적화 기능에 액세스하려면 추가 설정이나 모델 미세 조정이 필요하지 않으므로 응답 시간이 빨라진 기존 애플리케이션을 즉시 개선할 수 있습니다. Amazon Bedrock 런타임 API를 직접 호출하는 동안 “지연 시간” 파라미터를 “최적화됨”으로 설정할 수 있습니다. 간접 호출 옵션으로 "표준"을 선택하면 요청이 표준 추론으로 처리됩니다. 기본적으로 모든 요청은 "표준"을 통해 로 라우팅됩니다.
```
"performanceConfig" : {
"latency" : "standard | optimized"
}
```
모델의 지연 시간 최적화를 위한 사용량 할당량에 도달하면 표준 지연 시간으로 요청을 처리하려고 시도합니다. 이 경우 요청에 표준 지연 시간 요금이 부과됩니다. 제공된 요청에 대한 지연 시간 구성은 API 응답 및 AWS CloudTrail 로그에 표시됩니다. "model-id\$1latency-optimized"에서 Amazon CloudWatch 로그의 지연 시간 최적화 요청에 대한 지표를 볼 수도 있습니다.
지연 시간 최적화 추론은 [교차 리전](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) 추론을 통해 미국 동부(오하이오) 및 미국 서부(오리건) 리전에서 Meta의 Llama 3.1 70B 및 405B와 Anthropic의 Claude 3.5 Haiku에 사용할 수 있습니다.
지연 시간 최적화 추론은 [리전 간](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) 추론을 통해 미국 동부(버지니아 북부), 미국 동부(오하이오) 및 미국 서부(오리건) 리전의 Amazon Nova Pro에 대해 사용할 수 있습니다.
요금에 대한 자세한 내용은 [요금 세부 정보](https://aws.amazon.com/bedrock/pricing/) 페이지를 참조하세요.
**참고**
Llama 3.1 405B에 대한 지연 시간 최적화 추론은 현재 총 입력 및 출력 토큰 수가 최대 11K인 요청을 지원합니다. 더 큰 토큰 수 요청의 경우 표준 모드로 돌아갑니다.
다음 표에는 지연 시간 최적화를 지원하는 추론 프로파일이 나와 있습니다.
| 제공업체 | 모델 | 모델 ID | 교차 리전 추론 프로파일 지원 |
| --- | --- | --- | --- |
| Amazon | Nova Pro | amazon.nova-pro-v1:0 | us-east-1 us-east-2 |
| Anthropic | Claude 3.5 Haiku | anthropic.claude-3-5-haiku-20241022-v1:0 | us-east-2 us-west-2 |
| Meta | Llama 3.1 405B 지침 | meta.llama3-1-405b-instruct-v1:0 | us-east-2 |
| Meta | Llama 3.1 70B Instruct | meta.llama3-1-70b-instruct-v1:0 | us-east-2 us-west-2 |
추론 프로파일에 대한 자세한 내용은 [추론 프로파일에 지원되는 리전 및 모델](inference-profiles-support.md) 섹션을 참조하세요.
# OpenAI APIs 사용하여 응답 생성
Amazon Bedrock은 대규모 기계 학습 모델 제공을 위한 분산 추론 엔진인 Mantle로 구동되는 모델 추론을 위한 OpenAI 호환 가능한 API 엔드포인트를 제공합니다. 이러한 엔드포인트를 사용하면 Amazon Bedrock 모델과 함께 익숙한 OpenAI SDKs 및 도구를 사용할 수 있으므로 코드 변경을 최소화하면서 기존 애플리케이션을 마이그레이션할 수 있습니다. 기본 URL 및 API 키를 간단히 업데이트하면 됩니다.
주요 이점은 다음과 같습니다.
+ **비동기 추론** - 응답 API를 통해 장기 실행 추론 워크로드 지원
+ **상태 저장 대화 관리** - 각 요청과 함께 대화 기록을 수동으로 전달하지 않고 컨텍스트를 자동으로 재구축합니다.
+ **간소화된 도구 사용** - 에이전트 워크플로를 위한 간소화된 통합
+ **유연한 응답 모드** - 스트리밍 응답과 비스트리밍 응답 모두 지원
+ **간편한 마이그레이션** - 기존 OpenAI SDK 코드베이스와 호환
## 지원되는 리전 및 엔드포인트
Amazon Bedrock은 다음 AWS 리전에서 사용할 수 있습니다.
| 리전 이름 | 리전 | 엔드포인트 |
| --- | --- | --- |
| 미국 동부(오하이오) | us-east-2 | bedrock-mantle.us-east-2.api.aws |
| 미국 동부(버지니아 북부) | us-east-1 | bedrock-mantle.us-east-1.api.aws |
| 미국 서부(오리건) | us-west-2 | bedrock-mantle.us-west-2.api.aws |
| 아시아 태평양(자카르타) | ap-southeast-3 | bedrock-mantle.ap-southeast-3.api.aws |
| 아시아 태평양(뭄바이) | ap-south-1 | bedrock-mantle.ap-south-1.api.aws |
| 아시아 태평양(도쿄) | ap-northeast-1 | bedrock-mantle.ap-northeast-1.api.aws |
| 유럽(프랑크푸르트) | eu-central-1 | bedrock-mantle.eu-central-1.api.aws |
| 유럽(아일랜드) | eu-west-1 | bedrock-mantle.eu-west-1.api.aws |
| Europe (London) | eu-west-2 | bedrock-mantle.eu-west-2.api.aws |
| Europe (Milan) | eu-south-1 | bedrock-mantle.eu-south-1.api.aws |
| 유럽(스톡홀름) | eu-north-1 | bedrock-mantle.eu-north-1.api.aws |
| 남아메리카(상파울루) | sa-east-1 | bedrock-mantle.sa-east-1.api.aws |
## 사전 조건
OpenAI APIs 사용하기 전에 다음이 있는지 확인합니다.
+ **인증** - 다음을 사용하여 인증할 수 있습니다.
+ Amazon Bedrock API 키(OpenAISDK에 필요)
+ AWS 자격 증명(HTTP 요청에 지원됨)
+ **OpenAI SDK**(선택 사항) - SDK 기반 요청을 사용하는 경우 OpenAI Python SDK를 설치합니다.
+ **환경 변수** - 다음 환경 변수를 설정합니다.
+ `OPENAI_API_KEY` - Amazon Bedrock API 키로 설정
+ `OPENAI_BASE_URL` - 리전의 Amazon Bedrock 엔드포인트로 설정(예: ` https://bedrock-mantle.us-east-1.api.aws/v1`)
## 모델 API
모델 API를 사용하면 Mantle로 구동되는 Amazon Bedrock에서 사용 가능한 모델을 검색할 수 있습니다. 이 API를 사용하여 응답 API 및 채팅 완료 API와 함께 사용할 수 있는 모델 목록을 검색합니다. 전체 API 세부 정보는 [OpenAI 모델 설명서를 참조하세요](https://platform.openai.com/docs/api-reference/models).
### 사용 가능한 모델 나열
사용 가능한 모델을 나열하려면 원하는 방법의 탭을 선택한 다음 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
```
# List all available models using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
models = client.models.list()
for model in models.data:
print(model.id)
```
------
#### [ HTTP request ]
에 GET 요청`/v1/models`:
```
# List all available models
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X GET $OPENAI_BASE_URL/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
------
## 응답 API
응답 API는 스트리밍, 백그라운드 처리 및 멀티턴 상호 작용을 지원하여 상태 저장 대화 관리를 제공합니다. 전체 API 세부 정보는 [OpenAI 응답 설명서를 참조하세요](https://platform.openai.com/docs/api-reference/responses).
### 기본 요청
응답을 생성하려면 원하는 방법의 탭을 선택한 다음 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
```
# Create a basic response using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="openai.gpt-oss-120b",
input=[
{"role": "user", "content": "Hello! How can you help me today?"}
]
)
print(response)
```
------
#### [ HTTP request ]
에 POST를 요청합니다`/v1/responses`.
```
# Create a basic response
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"input": [
{"role": "user", "content": "Hello! How can you help me today?"}
]
}'
```
------
### 스트림 응답
응답 이벤트를 점진적으로 수신하려면 원하는 방법의 탭을 선택한 다음 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
```
# Stream response events incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
stream = client.responses.create(
model="openai.gpt-oss-120b",
input=[{"role": "user", "content": "Tell me a story"}],
stream=True
)
for event in stream:
print(event)
```
------
#### [ HTTP request ]
를 로 `stream` 설정`/v1/responses`하여에 POST 요청을 수행합니다`true`.
```
# Stream response events incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"input": [
{"role": "user", "content": "Tell me a story"}
],
"stream": true
}'
```
------
## 채팅 완료 API
채팅 완료 API는 대화 응답을 생성합니다. 전체 API 세부 정보는 [OpenAI 채팅 완료 설명서를 참조하세요](https://platform.openai.com/docs/api-reference/chat/create).
### Chat Completions 생성
채팅 완료를 생성하려면 원하는 방법의 탭을 선택한 다음 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
환경 변수를 사용하여 OpenAI 클라이언트를 구성합니다.
```
# Create a chat completion using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create(
model="openai.gpt-oss-120b",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
print(completion.choices[0].message)
```
------
#### [ HTTP request ]
에 POST 요청`/v1/chat/completions`:
```
# Create a chat completion
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
}'
```
------
### 스트리밍 활성화
응답을 점진적으로 수신하려면 원하는 방법의 탭을 선택한 다음 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
```
# Stream chat completion responses incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
stream = client.chat.completions.create(
model="openai.gpt-oss-120b",
messages=[{"role": "user", "content": "Tell me a story"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end="")
```
------
#### [ HTTP request ]
가 로 ` stream` 설정된 `/v1/chat/completions`에 POST 요청을 수행합니다. `true`
```
# Stream chat completion responses incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"messages": [
{"role": "user", "content": "Tell me a story"}
],
"stream": true
}'
```
------
# API를 사용하여 프롬프트 제출 및 응답 생성
Amazon Bedrock은 모델 추론을 수행하기 위해 다음 API 작업을 제공합니다.
+ [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) - 프롬프트를 제출하고 응답을 생성합니다. 요청 본문은 모델별로 다릅니다. 스트리밍 응답을 생성하려면 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)을 사용합니다.
+ [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) - 프롬프트를 제출하고 모든 모델에 통합된 구조로 응답을 생성합니다. 모델별 요청 필드는 `additionalModelRequestFields` 필드에서 지정할 수 있습니다. 컨텍스트를 위해 시스템 프롬프트와 이전 대화를 포함할 수도 있습니다. 스트리밍 응답을 생성하려면 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)을 사용합니다.
+ [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html) - 프롬프트를 제출하고 나중에 검색할 수 있는 응답을 비동기적으로 생성합니다. 비디오를 생성하는 데 사용됩니다.
+ [InvokeModelWithBidirectionalStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithBidirectionalStream.html) –
+ OpenAI Chat completions API - Amazon Bedrock에서 지원하는 모델과 함께 [OpenAI Chat completions API](https://platform.openai.com/docs/api-reference/chat/create)를 사용하여 응답을 생성합니다.
**참고**
제한 사항은 `InvokeModel`, `InvokeModelWithResponseStream`, 및 작업에 적용됩니다`Converse``ConverseStream`. 자세한 내용은 [API 제한을](inference-api-restrictions.md) 참조하세요.
모델 추론의 경우 다음 파라미터를 결정해야 합니다.
+ 모델 ID - 추론을 위해 `modelId` 필드에 사용할 모델 또는 추론 프로파일의 ID 또는 Amazon 리소스 이름(ARN)입니다. 다음 테이블에서는 다양한 유형의 리소스에 대한 ID를 찾는 방법을 설명합니다.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/inference-api.html)
+ 요청 본문 - 모델 및 기타 구성에 대한 추론 파라미터를 포함합니다. 각 기본 모델에는 자체 추론 파라미터가 있습니다. 사용자 지정 또는 프로비저닝된 모델의 추론 파라미터는 모델을 만든 기본 모델에 따라 달라집니다. 자세한 내용은 [파운데이션 모델의 추론 요청 파라미터 및 응답 필드](model-parameters.md) 섹션을 참조하세요.
다음 주제에서 모델 간접 호출 API를 사용하는 방법을 알아보세요.
**Topics**
+ [InvokeModel을 사용하여 단일 프롬프트 제출](inference-invoke.md)
+ [OpenAI Chat Completions API를 사용하여 모델 간접 호출](inference-chat-completions.md)
+ [Converse API 작업과 대화 수행](conversation-inference.md)
+ [API 제한](inference-api-restrictions.md)
# InvokeModel을 사용하여 단일 프롬프트 제출
[InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 및 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) API 작업을 사용하고 모델을 지정하여 단일 프롬프트에서 추론을 실행합니다. Amazon Bedrock 모델은 텍스트, 이미지 또는 비디오 입력을 수락하는지 여부와 텍스트, 이미지 또는 임베딩의 출력을 생성할 수 있는지 여부에 따라 다릅니다. 일부 모델은 스트림에 응답을 반환할 수 있습니다. 입력, 출력 및 스트리밍 지원에 대한 모델 지원을 확인하려면 다음 중 하나를 수행합니다.
+ [Amazon Bedrock에서 지원되는 파운데이션 모델](models-supported.md)에서 모델에 대해 **입력 양식**, **출력 양식** 또는 **스트리밍 지원** 열의 값을 확인합니다.
+ 모델 ID로 [GetFoundationModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GetFoundationModel.html) 요청을 보내고 `inputModalities`, `outputModalities` 및 `responseStreamingSupported` 필드의 값을 확인합니다.
[Amazon Bedrock 런타임 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)를 사용하여 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 또는 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) 요청을 전송하여 프롬프트에서 모델 추론을 실행합니다.
**참고**
제한 사항은 `InvokeModel`, `InvokeModelWithResponseStream`, `Converse`및 작업에 적용됩니다`ConverseStream`. 자세한 내용은 [API 제한을](inference-api-restrictions.md) 참조하세요.
필수 필드는 다음과 같습니다.
****
| Field | 사용 사례: |
| --- | --- |
| modelId | 사용할 프롬프트 관리의 모델, 추론 프로파일 또는 프롬프트를 지정합니다. 이 값을 찾는 방법을 알아보려면 [API를 사용하여 프롬프트 제출 및 응답 생성](inference-api.md) 섹션을 참조하세요. |
| 본문 | 모델의 추론 파라미터를 지정합니다. 여러 모델의 추론 파라미터를 확인하려면 [파운데이션 모델의 추론 요청 파라미터 및 응답 필드](model-parameters.md) 섹션을 참조하세요. modelId 필드의 프롬프트 관리에서 프롬프트를 지정하는 경우 이 필드를 생략합니다(포함하면 무시됨). |
다음 필드는 선택 사항입니다.
****
| Field | 사용 사례: |
| --- | --- |
| accept | 요청 본문의 미디어 유형을 지정합니다. 자세한 내용은 [Swagger 웹사이트](https://swagger.io/specification/)의 Media Types를 참조하세요. |
| contentType | 응답 본문의 미디어 유형을 지정합니다. 자세한 내용은 [Swagger 웹사이트](https://swagger.io/specification/)의 미디어 유형을 참조하세요. |
| performanceConfigLatency | 지연 시간에 맞게 모델을 최적화할지 여부를 지정합니다. 자세한 내용은 [지연 시간에 대한 모델 추론 최적화](latency-optimized-inference.md) 단원을 참조하십시오. |
| guardrailIdentifier | 프롬프트 및 응답에 적용할 가드레일을 지정합니다. 자세한 내용은 [가드레일 테스트](guardrails-test.md) 섹션을 참조하세요. |
| guardrailVersion | 프롬프트 및 응답에 적용할 가드레일을 지정합니다. 자세한 내용은 [가드레일 테스트](guardrails-test.md) 섹션을 참조하세요. |
| trace | 지정한 가드레일에 대한 추적을 반환할지 여부를 지정합니다. 자세한 내용은 [가드레일 테스트](guardrails-test.md) 단원을 참조하십시오. |
| serviceTier | 요청에 대한 서비스 티어를 지정합니다. 자세한 내용은 [성능 및 비용 최적화를 위한 서비스 티어](service-tiers-inference.md) 단원을 참조하십시오. |
## 모델 코드 간접 호출 예제
이 주제에서는 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API와 함께 단일 프롬프트를 사용하여 추론을 실행하는 몇 가지 기본 예제를 제공합니다. 다른 모델을 사용한 더 많은 예제를 보려면 다음 리소스를 참조하세요.
+ [AWS SDKs를 사용한 Amazon Bedrock 런타임의 코드 예제](service_code_examples_bedrock-runtime.md) 주제에서 예제를 선택합니다.
+ [파운데이션 모델의 추론 요청 파라미터 및 응답 필드](model-parameters.md)에서 원하는 모델에 대한 추론 파라미터 참조를 방문하세요.
다음 예제에서는 이러한 예제를 실행할 AWS 리전 때 기본값으로 AWS CLI 및 SDK for Python(Boto3)에 자동으로 인증하도록 프로그래밍 방식 액세스를 설정했다고 가정합니다. 프로그래밍 방식 액세스를 설정하는 방법에 대한 자세한 내용은 [API 시작하기](getting-started-api.md) 섹션을 참조하세요.
**참고**
예제를 시도하기 전에 다음 사항을 검토합니다.
예제에 사용된 모든 모델을 지원하는 미국 동부(버지니아 북부)(us-east-1)에서 이러한 예제를 테스트해야 합니다.
`body` 파라미터는 클 수 있으므로 일부 CLI 예제의 경우 명령줄에 지정하는 대신 JSON 파일을 생성하고 해당 파일을 `--body` 인수에 제공하라는 메시지가 표시됩니다.
이미지 및 비디오 예제의 경우 자체 이미지와 비디오를 사용하라는 메시지가 표시됩니다. 이 예제에서는 이미지 파일의 이름이 *image.png*이고 비디오 파일의 이름이 *video.mp4*라고 가정합니다.
이미지 또는 비디오를 base64로 인코딩된 문자열로 변환하거나 Amazon S3 위치에 업로드해야 할 수 있습니다. 이 예제에서 자리표시자를 실제 base64로 인코딩된 문자열 또는 S3 위치로 바꿔야 합니다.
섹션을 확장하여 몇 가지 기본 코드 예제를 시도해 보세요.
### 텍스트 프롬프트를 사용하여 텍스트 생성
다음 예제에서는 Amazon Titan Text Premier 모델을 사용하여 텍스트 프롬프트에 대한 텍스트 응답을 생성합니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
터미널에서 다음 명령을 실행하고 *invoke-model-output.txt*라는 파일에서 생성된 응답을 찾습니다.
```
aws bedrock-runtime invoke-model \
--model-id amazon.titan-text-premier-v1:0 \
--body '{
"inputText": "Describe the purpose of a 'hello world' program in one line.",
"textGenerationConfig": {
"maxTokenCount": 512,
"temperature": 0.5
}
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
------
#### [ Python ]
다음 Python 코드 예제를 실행하여 텍스트 응답을 생성합니다.
```
# Use the native inference API to send a text message to Amazon Titan Text.
import boto3
import json
from botocore.exceptions import ClientError
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client("bedrock-runtime", region_name="us-east-1")
# Set the model ID, e.g., Titan Text Premier.
model_id = "amazon.titan-text-premier-v1:0"
# Define the prompt for the model.
prompt = "Describe the purpose of a 'hello world' program in one line."
# Format the request payload using the model's native structure.
native_request = {
"inputText": prompt,
"textGenerationConfig": {
"maxTokenCount": 512,
"temperature": 0.5,
},
}
# Convert the native request to JSON.
request = json.dumps(native_request)
try:
# Invoke the model with the request.
response = client.invoke_model(modelId=model_id, body=request)
except (ClientError, Exception) as e:
print(f"ERROR: Can't invoke '{model_id}'. Reason: {e}")
exit(1)
# Decode the response body.
model_response = json.loads(response["body"].read())
# Extract and print the response text.
response_text = model_response["results"][0]["outputText"]
print(response_text)
```
------
### 서비스 계층을 사용하여 텍스트 프롬프트로 텍스트 생성
다음 예제에서는 서비스 계층이 있는 OpenAI GPT 모델을 사용하여 텍스트 프롬프트에 대한 텍스트 응답을 생성하여 요청의 우선순위를 지정합니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
터미널에서 다음 명령을 실행하고 응답에서 서비스 계층을 검증합니다.
```
aws bedrock-runtime invoke-model \
--model-id openai.gpt-oss-120b-1:0 \
--body '{
"messages": [
{
"role": "user",
"content": "Describe the purpose of a '\''hello world'\'' program in one line."
}
],
"max_tokens": 512,
"temperature": 0.7
}' \
--content-type application/json \
--accept application/json \
--service-tier priority \
--cli-binary-format raw-in-base64-out
```
------
#### [ Python ]
다음 Python 코드 예제를 실행하여 서비스 계층으로 텍스트 응답을 생성합니다.
```
import boto3
import json
# Create a Bedrock Runtime client
bedrock_runtime = boto3.client(
service_name="bedrock-runtime",
region_name="us-east-1"
)
# Define the model ID and request body
model_id = "openai.gpt-oss-120b-1:0"
body = json.dumps({
"messages": [
{
"role": "user",
"content": "Describe the purpose of a 'hello world' program in one line."
}
],
"max_tokens": 512,
"temperature": 0.7
})
# Make the request with service tier
response = bedrock_runtime.invoke_model(
modelId=model_id,
body=body,
contentType="application/json",
accept="application/json",
serviceTier="priority"
)
# Parse and print the response
response_body = json.loads(response["body"])
print(response_body)
```
------
### 텍스트 프롬프트를 사용하여 이미지 생성
다음 코드 예제에서는 Stable Diffusion XL 1.0 모델에서 텍스트 프롬프트를 사용하여 이미지를 생성합니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
터미널에서 다음 명령을 실행하고 *invoke-model-output.txt*라는 파일에서 생성된 응답을 찾습니다. 이미지를 나타내는 바이트는 응답의 `base64` 필드에서 찾을 수 있습니다.
```
aws bedrock-runtime invoke-model \
--model-id stability.stable-diffusion-xl-v1 \
--body '{
"text_prompts": [{"text": "A stylized picture of a cute old steampunk robot."}],
"style_preset": "photographic",
"seed": 0,
"cfg_scale": 10,
"steps": 30
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
------
#### [ Python ]
다음 Python 코드 예제를 실행하여 이미지를 생성하고 *output*이라는 폴더에서 결과 *stability\$11.png* 이미지 파일을 찾습니다.
```
# Use the native inference API to create an image with Amazon Titan Image Generator
import base64
import boto3
import json
import os
import random
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client("bedrock-runtime", region_name="us-east-1")
# Set the model ID, e.g., Titan Image Generator G1.
model_id = "amazon.titan-image-generator-v2:0"
# Define the image generation prompt for the model.
prompt = "A stylized picture of a cute old steampunk robot."
# Generate a random seed.
seed = random.randint(0, 2147483647)
# Format the request payload using the model's native structure.
native_request = {
"taskType": "TEXT_IMAGE",
"textToImageParams": {"text": prompt},
"imageGenerationConfig": {
"numberOfImages": 1,
"quality": "standard",
"cfgScale": 8.0,
"height": 512,
"width": 512,
"seed": seed,
},
}
# Convert the native request to JSON.
request = json.dumps(native_request)
# Invoke the model with the request.
response = client.invoke_model(modelId=model_id, body=request)
# Decode the response body.
model_response = json.loads(response["body"].read())
# Extract the image data.
base64_image_data = model_response["images"][0]
# Save the generated image to a local folder.
i, output_dir = 1, "output"
if not os.path.exists(output_dir):
os.makedirs(output_dir)
while os.path.exists(os.path.join(output_dir, f"titan_{i}.png")):
i += 1
image_data = base64.b64decode(base64_image_data)
image_path = os.path.join(output_dir, f"titan_{i}.png")
with open(image_path, "wb") as file:
file.write(image_data)
print(f"The generated image has been saved to {image_path}")
```
------
### 텍스트에서 임베딩 생성
다음 예제에서는 Amazon Titan Text Embeddings V2 모델을 사용하여 텍스트 입력에 대한 바이너리 임베딩을 생성합니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
터미널에서 다음 명령을 실행하고 *invoke-model-output.txt*라는 파일에서 생성된 응답을 찾습니다. 결과 임베딩은 `binary` 필드에 있습니다.
```
aws bedrock-runtime invoke-model \
--model-id amazon.titan-embed-text-v2:0 \
--body '{
"inputText": "What are the different services that you offer?",
"embeddingTypes": ["binary"]
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
------
#### [ Python ]
다음 Python 코드 예제를 실행하여 제공된 텍스트에 대한 임베딩을 생성합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to generate an embedding with the Amazon Titan Text Embeddings V2 Model
"""
import json
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_embedding(model_id, body):
"""
Generate an embedding with the vector representation of a text input using Amazon Titan Text Embeddings G1 on demand.
Args:
model_id (str): The model ID to use.
body (str) : The request body to use.
Returns:
response (JSON): The embedding created by the model and the number of input tokens.
"""
logger.info("Generating an embedding with Amazon Titan Text Embeddings V2 model %s", model_id)
bedrock = boto3.client(service_name='bedrock-runtime')
accept = "application/json"
content_type = "application/json"
response = bedrock.invoke_model(
body=body, modelId=model_id, accept=accept, contentType=content_type
)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Amazon Titan Embeddings V2 - Text example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "amazon.titan-embed-text-v2:0"
input_text = "What are the different services that you offer?"
# Create request body.
body = json.dumps({
"inputText": input_text,
"embeddingTypes": ["binary"]
})
try:
response = generate_embedding(model_id, body)
print(f"Generated an embedding: {response['embeddingsByType']['binary']}") # returns binary embedding
print(f"Input text: {input_text}")
print(f"Input Token count: {response['inputTextTokenCount']}")
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
else:
print(f"Finished generating an embedding with Amazon Titan Text Embeddings V2 model {model_id}.")
if __name__ == "__main__":
main()
```
------
### 이미지에서 임베딩 생성
다음 예제에서는 Amazon Titan Multimodal Embeddings G1 모델을 사용하여 이미지 입력에 대한 임베딩을 생성합니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
터미널을 열고 다음을 수행합니다.
1. 다음 명령을 실행하여 현재 폴더의 *image.png*라는 이미지를 base64 인코딩 문자열로 변환하고 *image.txt*라는 파일에 씁니다.
```
base64 -i image.png -o image.txt
```
1. *image-input-embeddings-output.json*이라는 JSON 파일을 생성하고 다음 JSON을 붙여 넣어 *\$1\$1image-base64\$1*를 *image.txt* 파일의 콘텐츠로 바꿉니다(문자열 끝에 새 줄이 없는지 확인).
```
{
"inputImage": "${image-base64}",
"embeddingConfig": {
"outputEmbeddingLength": 256
}
}
```
1. *image-input-embeddings-output.json* 파일을 본문으로 지정하여 다음 명령을 실행합니다.
```
aws bedrock-runtime invoke-model \
--model-id amazon.titan-embed-image-v1 \
--body file://image-input-embeddings-output.json \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
1. *invoke-model-output.txt* 파일에서 결과 임베딩을 찾습니다.
------
#### [ Python ]
다음 Python 스크립트에서 */path/to/image*를 실제 이미지의 경로로 바꿉니다. 그런 다음 스크립트를 실행하여 임베딩을 생성합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to generate embeddings from an image with the Amazon Titan Multimodal Embeddings G1 model (on demand).
"""
import base64
import json
import logging
import boto3
from botocore.exceptions import ClientError
class EmbedError(Exception):
"Custom exception for errors returned by Amazon Titan Multimodal Embeddings G1"
def __init__(self, message):
self.message = message
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_embeddings(model_id, body):
"""
Generate a vector of embeddings for an image input using Amazon Titan Multimodal Embeddings G1 on demand.
Args:
model_id (str): The model ID to use.
body (str) : The request body to use.
Returns:
response (JSON): The embeddings that the model generated, token information, and the
reason the model stopped generating embeddings.
"""
logger.info("Generating embeddings with Amazon Titan Multimodal Embeddings G1 model %s", model_id)
bedrock = boto3.client(service_name='bedrock-runtime')
accept = "application/json"
content_type = "application/json"
response = bedrock.invoke_model(
body=body, modelId=model_id, accept=accept, contentType=content_type
)
response_body = json.loads(response.get('body').read())
finish_reason = response_body.get("message")
if finish_reason is not None:
raise EmbedError(f"Embeddings generation error: {finish_reason}")
return response_body
def main():
"""
Entrypoint for Amazon Titan Multimodal Embeddings G1 example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
# Read image from file and encode it as base64 string.
with open("/path/to/image", "rb") as image_file:
input_image = base64.b64encode(image_file.read()).decode('utf8')
model_id = 'amazon.titan-embed-image-v1'
output_embedding_length = 256
# Create request body.
body = json.dumps({
"inputImage": input_image,
"embeddingConfig": {
"outputEmbeddingLength": output_embedding_length
}
})
try:
response = generate_embeddings(model_id, body)
print(f"Generated image embeddings of length {output_embedding_length}: {response['embedding']}")
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
except EmbedError as err:
logger.error(err.message)
print(err.message)
else:
print(f"Finished generating image embeddings with Amazon Titan Multimodal Embeddings G1 model {model_id}.")
if __name__ == "__main__":
main()
```
------
### 이미지와 그와 함께 제공되는 텍스트 프롬프트에 대한 텍스트 응답 생성
원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
다음 예제에서는 Anthropic Claude 3 Haiku 모델을 사용하여 주어진 이미지와 이미지의 내용을 묻는 텍스트 프롬프트로 응답을 생성합니다. 터미널을 열고 다음을 수행합니다.
1. 다음 명령을 실행하여 현재 폴더의 *image.png*라는 이미지를 base64 인코딩 문자열로 변환하고 *image.txt*라는 파일에 씁니다.
```
base64 -i image.png -o image.txt
```
1. *image-text-input.json*이라는 JSON 파일을 생성하고 다음 JSON을 붙여 넣어 *\$1\$1image-base64\$1*를 *image.txt* 파일의 콘텐츠로 바꿉니다(문자열 끝에 새 줄이 없는지 확인).
```
{
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "${image-base64}"
}
},
{
"type": "text",
"text": "What's in this image?"
}
]
}
]
}
```
1. 다음 명령을 실행하여 이미지와 그와 함께 제공되는 텍스트 프롬프트를 기반으로 *invoke-model-output.txt*라는 파일에 대한 텍스트 출력을 생성합니다.
```
aws bedrock-runtime invoke-model \
--model-id anthropic.claude-3-haiku-20240307-v1:0 \
--body file://image-text-input.json \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
1. 현재 폴더의 *invoke-model-output.txt* 파일에서 출력을 찾습니다.
------
#### [ Python ]
다음 Python 스크립트에서 스크립트를 실행하기 전에 */path/to/image.png*를 실제 이미지 경로로 바꿉니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to run a multimodal prompt with Anthropic Claude (on demand) and InvokeModel.
"""
import json
import logging
import base64
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def run_multi_modal_prompt(bedrock_runtime, model_id, messages, max_tokens):
"""
Invokes a model with a multimodal prompt.
Args:
bedrock_runtime: The Amazon Bedrock boto3 client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
max_tokens (int) : The maximum number of tokens to generate.
Returns:
None.
"""
body = json.dumps(
{
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": max_tokens,
"messages": messages
}
)
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Anthropic Claude multimodal prompt example.
"""
try:
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
model_id = 'anthropic.claude-3-sonnet-20240229-v1:0'
max_tokens = 1000
input_text = "What's in this image?"
input_image = "/path/to/image" # Replace with actual path to image file
# Read reference image from file and encode as base64 strings.
image_ext = input_image.split(".")[-1]
with open(input_image, "rb") as image_file:
content_image = base64.b64encode(image_file.read()).decode('utf8')
message = {
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": f"image/{image_ext}",
"data": content_image
}
},
{
"type": "text",
"text": input_text
}
]
}
messages = [message]
response = run_multi_modal_prompt(
bedrock_runtime, model_id, messages, max_tokens)
print(json.dumps(response, indent=4))
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occurred: " +
format(message))
if __name__ == "__main__":
main()
```
------
### Amazon S3에 업로드된 비디오와 그와 함께 제공되는 텍스트 프롬프트에 대한 텍스트 응답 생성
다음 예제에서는 S3 버킷에 업로드하는 비디오와 그와 함께 제공되는 텍스트 프롬프트를 사용하여 Amazon Nova Lite 모델로 응답을 생성하는 방법을 보여줍니다.
**사전 조건:** Amazon Simple Storage Service 사용자 안내서에서 [객체 업로드](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html#upload-objects-procedure)에 나온 단계에 따라 *video.mp4*라는 비디오를 계정의 Amazon S3 버킷에 업로드합니다. 비디오의 S3 URI를 기록해 둡니다.
원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
터미널을 열고 다음 명령을 실행하여 *s3://amzn-s3-demo-bucket/video.mp4*를 비디오의 실제 S3 위치로 바꿉니다.
```
aws bedrock-runtime invoke-model \
--model-id amazon.nova-lite-v1:0 \
--body '{
"messages": [
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/video.mp4"
}
}
}
},
{
"text": "What happens in this video?"
}
]
}
]
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
현재 폴더의 *invoke-model-output.txt* 파일에서 출력을 찾습니다.
------
#### [ Python ]
다음 Python 스크립트에서 *s3://amzn-s3-demo-bucket/video.mp4*를 비디오의 실제 S3 위치로 바꿉니다. 그런 다음 이 스크립트를 실행합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to run a multimodal prompt with Nova Lite (on demand) and InvokeModel.
"""
import json
import logging
import base64
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def run_multi_modal_prompt(bedrock_runtime, model_id, messages, max_tokens):
"""
Invokes a model with a multimodal prompt.
Args:
bedrock_runtime: The Amazon Bedrock boto3 client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
max_tokens (int) : The maximum number of tokens to generate.
Returns:
None.
"""
body = json.dumps(
{
"messages": messages,
"inferenceConfig": {
"maxTokens": max_tokens
}
}
)
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Nova Lite video prompt example.
"""
try:
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
model_id = "amazon.nova-lite-v1:0"
max_tokens = 1000
input_video_s3_uri = "s3://amzn-s3-demo-bucket/video.mp4" # Replace with real S3 URI
video_ext = input_video_s3_uri.split(".")[-1]
input_text = "What happens in this video?"
message = {
"role": "user",
"content": [
{
"video": {
"format": video_ext,
"source": {
"s3Location": {
"uri": input_video_s3_uri
}
}
}
},
{
"text": input_text
}
]
}
messages = [message]
response = run_multi_modal_prompt(
bedrock_runtime, model_id, messages, max_tokens)
print(json.dumps(response, indent=4))
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
if __name__ == "__main__":
main()
```
------
### base64 인코딩 문자열로 변환된 비디오와 그와 함께 제공되는 텍스트 프롬프트에 대한 텍스트 응답 생성
다음 예제에서는 base64 인코딩 문자열로 변환된 비디오와 그와 함께 제공되는 텍스트 프롬프트를 사용하여 Amazon Nova Lite 모델로 응답을 생성하는 방법을 보여줍니다. 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ CLI ]
해결 방법:
1. 다음 명령을 실행하여 현재 폴더의 *video.mp4*라는 비디오를 base64로 변환합니다.
```
base64 -i video.mp4 -o video.txt
```
1. *video-text-input.json*이라는 JSON 파일을 생성하고 다음 JSON을 붙여 넣어 *\$1\$1video-base64\$1*를 `video.txt` 파일의 콘텐츠로 바꿉니다(끝에 새 줄이 없는지 확인).
```
{
"messages": [
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": ${video-base64}
}
}
},
{
"text": "What happens in this video?"
}
]
}
]
}
```
1. 다음 명령을 실행하여 비디오와 그와 함께 제공되는 텍스트 프롬프트를 기반으로 *invoke-model-output.txt*라는 파일에 대한 텍스트 출력을 생성합니다.
```
aws bedrock-runtime invoke-model \
--model-id amazon.nova-lite-v1:0 \
--body file://video-text-input.json \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
1. 현재 폴더의 *invoke-model-output.txt* 파일에서 출력을 찾습니다.
------
#### [ Python ]
다음 Python 스크립트에서 */path/to/video.mp4*를 실제 비디오 경로로 바꿉니다. 그런 다음 이 스크립트를 실행합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to run a multimodal prompt with Nova Lite (on demand) and InvokeModel.
"""
import json
import logging
import base64
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def run_multi_modal_prompt(bedrock_runtime, model_id, messages, max_tokens):
"""
Invokes a model with a multimodal prompt.
Args:
bedrock_runtime: The Amazon Bedrock boto3 client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
max_tokens (int) : The maximum number of tokens to generate.
Returns:
None.
"""
body = json.dumps(
{
"messages": messages,
"inferenceConfig": {
"maxTokens": max_tokens
}
}
)
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Nova Lite video prompt example.
"""
try:
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
model_id = "amazon.nova-lite-v1:0"
max_tokens = 1000
input_video = "/path/to/video.mp4" # Replace with real path to video
video_ext = input_video.split(".")[-1]
input_text = "What happens in this video?"
# Read reference video from file and encode as base64 string.
with open(input_video, "rb") as video_file:
content_video = base64.b64encode(video_file.read()).decode('utf8')\
message = {
"role": "user",
"content": [
{
"video": {
"format": video_ext,
"source": {
"bytes": content_video
}
}
},
{
"text": input_text
}
]
}
messages = [message]
response = run_multi_modal_prompt(
bedrock_runtime, model_id, messages, max_tokens)
print(json.dumps(response, indent=4))
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
if __name__ == "__main__":
main()
```
------
## 스트리밍 코드가 포함된 모델 간접 호출 예제
**참고**
AWS CLI 는 스트리밍을 지원하지 않습니다.
다음 예제는 *화성에서 살기에 대한 1,000단어 에세이 쓰기* 프롬프트를 사용하여 Python으로 스트리밍 텍스트를 생성하는 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) API의 사용 방법을 보여줍니다.
```
import boto3
import json
brt = boto3.client(service_name='bedrock-runtime')
body = json.dumps({
'prompt': '\n\nHuman: write an essay for living on mars in 1000 words\n\nAssistant:',
'max_tokens_to_sample': 4000
})
response = brt.invoke_model_with_response_stream(
modelId='anthropic.claude-v2',
body=body
)
stream = response.get('body')
if stream:
for event in stream:
chunk = event.get('chunk')
if chunk:
print(json.loads(chunk.get('bytes').decode()))
```
# OpenAI Chat Completions API를 사용하여 모델 간접 호출
Amazon Bedrock 모델로 [OpenAI Create chat completion API](https://platform.openai.com/docs/api-reference/chat/create)를 사용하여 모델 추론을 실행할 수 있습니다.
다음과 같은 방식으로 Chat Completions API를 호출할 수 있습니다.
+ Amazon Bedrock 런타임 엔드포인트를 사용하여 HTTP 요청을 수행합니다.
+ Amazon Bedrock 런타임 엔드포인트를 사용하여 OpenAI SDK 요청을 사용합니다.
주제 영역을 선택하여 자세히 알아보세요.
**Topics**
+ [OpenAI Chat Completions API에 지원되는 모델 및 리전](#inference-chat-completions-supported)
+ [Chat Completions API를 사용하기 위한 사전 조건](#inference-chat-completions-prereq)
+ [Chat Completions 생성](#inference-chat-completions-create)
+ [채팅 완성에 가드레일 포함](#inference-chat-completions-guardrails)
## OpenAI Chat Completions API에 지원되는 모델 및 리전
채팅 완료 생성 API는 Amazon Bedrock 및 이러한 OpenAI 모델을 지원하는 AWS 리전에서 지원되는 모든 모델에 사용할 수 있습니다. 지원되는 모델 및 리전에 대한 자세한 내용은 [Amazon Bedrock에서 지원되는 파운데이션 모델](models-supported.md) 섹션을 참조하세요.
## Chat Completions API를 사용하기 위한 사전 조건
Chat Completions API를 사용하기 위한 사전 조건을 보려면 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ OpenAI SDK ]
+ **인증** - OpenAI SDK는 Amazon Bedrock API 키를 사용한 인증만 지원합니다. Amazon Bedrock API 키를 생성하여 요청을 인증합니다. Amazon Bedrock API 키 및 생성 방법에 대해 알아보려면 빌드 장의 API 키 섹션을 참조하세요.
+ **엔드포인트** - Amazon Bedrock 런타임 엔드포인트 및 할당량에 사용할 AWS 리전에 해당하는 엔드포인트를 찾습니다. [https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt) AWS SDK를 사용하는 경우 클라이언트를 설정할 때 전체 엔드포인트가 아닌 리전 코드만 지정하면 될 수 있습니다.
+ **OpenAI SDK 설치** - 자세한 내용은 OpenAI 설명서의 [라이브러리](https://platform.openai.com/docs/libraries)를 참조하세요.
------
#### [ HTTP request ]
+ **인증** - 자격 AWS 증명 또는 Amazon Bedrock API 키로 인증할 수 있습니다.
자격 AWS 증명을 설정하거나 Amazon Bedrock API 키를 생성하여 요청을 인증합니다.
+ 자격 AWS 증명 설정에 대한 자세한 내용은 [AWS 보안 자격 증명을 사용한 프로그래밍 방식 액세스를](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html) 참조하세요.
+ Amazon Bedrock API 키 및 생성 방법에 대해 알아보려면 빌드 장의 API 키 섹션을 참조하세요.
+ **엔드포인트** - Amazon Bedrock 런타임 엔드포인트 및 할당량에 사용할 AWS 리전에 해당하는 엔드포인트를 찾습니다. [https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt) AWS SDK를 사용하는 경우 클라이언트를 설정할 때 전체 엔드포인트가 아닌 리전 코드만 지정하면 될 수 있습니다.
------
## Chat Completions 생성
Create chat completion API에 대한 자세한 내용은 OpenAI 설명서의 다음 리소스를 참조하세요.
+ [요청 본문 파라미터](https://platform.openai.com/docs/api-reference/chat/create)
+ [응답 본문 파라미터](https://platform.openai.com/docs/api-reference/chat/object)
**참고**
Amazon Bedrock은 현재 다른 OpenAI Chat completion API 작업을 지원하지 않습니다.
OpenAI Create chat completion API를 사용하는 방법을 알아보려면 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
OpenAI SDK로 채팅 완성을 생성하려면 다음을 수행합니다.
1. OpenAI SDK를 가져오고 다음 필드를 사용하여 클라이언트를 설정합니다.
+ `base_url` - 다음 형식과 같이 Amazon Bedrock 런타임 엔드포인트를 `/openai/v1`에 접두사로 추가합니다.
```
https://${bedrock-runtime-endpoint}/openai/v1
```
+ `api_key` - Amazon Bedrock API 키를 지정합니다.
+ `default_headers` - 헤더를 포함해야 하는 경우 이 객체에 헤더를 키-값 페어로 포함할 수 있습니다. 또는 특정 API 직접 호출을 수행할 때 `extra_headers`에서 헤더를 지정할 수 있습니다.
1. `chat.completions.create()` 메서드를 클라이언트와 함께 사용하고 요청 본문에 `model` 및 `messages`를 최소한으로 지정합니다.
다음 예제에서는 `us-west-2`에서 채팅 완성 생성 API를 직접적으로 호출합니다. *\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*을 실제 API 키로 바꿉니다.
```
from openai import OpenAI
client = OpenAI(
base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1",
api_key="$AWS_BEARER_TOKEN_BEDROCK" # Replace with actual API key
)
completion = client.chat.completions.create(
model="openai.gpt-oss-20b-1:0",
messages=[
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
)
print(completion.choices[0].message)
```
------
#### [ HTTP request ]
직접 HTTTP 요청으로 채팅 완성을 생성하려면 다음을 수행합니다.
1. 다음 형식과 같이 Amazon Bedrock 런타임 엔드포인트를 `/openai/v1/chat/completions`에 접두사로 지정하여 URL을 지정합니다.
```
https://${bedrock-runtime-endpoint}/openai/v1/chat/completions
```
1. `Authorization` 헤더에서 AWS 자격 증명 또는 Amazon Bedrock API 키를 지정합니다.
1. 요청 본문에서 요청 본문에 최소한 `model` 및 `messages`를 지정합니다.
다음 예제에서는 curl을 사용하여 `us-west-2`에서 Create chat completion API를 호출합니다. *\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*을 실제 API 키로 바꿉니다.
```
curl -X POST https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
-d '{
"model": "openai.gpt-oss-20b-1:0",
"messages": [
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
}'
```
------
## 채팅 완성에 가드레일 포함
모델 입력 및 응답에 보호 장치를 포함하려면 다음 [추가 파라미터](https://github.com/openai/openai-python#undocumented-request-params)를 요청 본문의 필드로 포함하여 모델 간접 호출을 실행할 때 [가드레일](guardrails.md)을 적용합니다.
+ `extra_headers` - 요청에 추가 헤더를 지정하는 다음 필드가 포함된 객체에 매핑됩니다.
+ `X-Amzn-Bedrock-GuardrailIdentifier`(필수) - 가드레일의 ID입니다.
+ `X-Amzn-Bedrock-GuardrailVersion`(필수) - 가드레일의 버전입니다.
+ `X-Amzn-Bedrock-Trace`(선택 사항) - 가드레일 추적을 활성화할지 여부입니다.
+ `extra_body` - 객체에 매핑됩니다. 해당 객체에 다음 `amazon-bedrock-guardrailConfig` 필드가 포함된 객체에 매핑되는 필드를 포함할 수 있습니다.
+ `tagSuffix`(선택 사항) - [입력 태그 지정](guardrails-tagging.md)을 위해 이 필드를 포함합니다.
Amazon Bedrock Guardrails의 이러한 파라미터에 대한 자세한 내용은 [가드레일 테스트](guardrails-test.md) 섹션을 참조하세요.
OpenAI Chat completion을 통한 가드레일을 사용하는 예를 보려면 원하는 방법의 탭을 선택한 후 다음 단계를 따릅니다.
------
#### [ OpenAI SDK (Python) ]
```
import openai
from openai import OpenAIError
# Endpoint for Amazon Bedrock Runtime
bedrock_endpoint = "https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"
# Model ID
model_id = "openai.gpt-oss-20b-1:0"
# Replace with actual values
bedrock_api_key = "$AWS_BEARER_TOKEN_BEDROCK"
guardrail_id = "GR12345"
guardrail_version = "DRAFT"
client = openai.OpenAI(
api_key=bedrock_api_key,
base_url=bedrock_endpoint,
)
try:
response = client.chat.completions.create(
model=model_id,
# Specify guardrail information in the header
extra_headers={
"X-Amzn-Bedrock-GuardrailIdentifier": guardrail_id,
"X-Amzn-Bedrock-GuardrailVersion": guardrail_version,
"X-Amzn-Bedrock-Trace": "ENABLED",
},
# Additional guardrail information can be specified in the body
extra_body={
"amazon-bedrock-guardrailConfig": {
"tagSuffix": "xyz" # Used for input tagging
}
},
messages=[
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "assistant",
"content": "Hello! How can I help you today?"
},
{
"role": "user",
"content": "What is the weather like today?"
}
]
)
request_id = response._request_id
print(f"Request ID: {request_id}")
print(response)
except OpenAIError as e:
print(f"An error occurred: {e}")
if hasattr(e, 'response') and e.response is not None:
request_id = e.response.headers.get("x-request-id")
print(f"Request ID: {request_id}")
```
------
#### [ OpenAI SDK (Java) ]
```
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponseFor;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
// Endpoint for Amazon Bedrock Runtime
String bedrockEndpoint = "http://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"
// Model ID
String modelId = "openai.gpt-oss-20b-1:0"
// Replace with actual values
String bedrockApiKey = "$AWS_BEARER_TOKEN_BEDROCK"
String guardrailId = "GR12345"
String guardrailVersion = "DRAFT"
OpenAIClient client = OpenAIOkHttpClient.builder()
.apiKey(bedrockApiKey)
.baseUrl(bedrockEndpoint)
.build()
ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
.addUserMessage("What is the temperature in Seattle?")
.model(modelId)
// Specify additional headers for the guardrail
.putAdditionalHeader("X-Amzn-Bedrock-GuardrailIdentifier", guardrailId)
.putAdditionalHeader("X-Amzn-Bedrock-GuardrailVersion", guardrailVersion)
// Specify additional body parameters for the guardrail
.putAdditionalBodyProperty(
"amazon-bedrock-guardrailConfig",
JsonValue.from(Map.of("tagSuffix", JsonValue.of("xyz"))) // Allows input tagging
)
.build();
HttpResponseFor rawChatCompletionResponse =
client.chat().completions().withRawResponse().create(request);
final ChatCompletion chatCompletion = rawChatCompletionResponse.parse();
System.out.println(chatCompletion);
```
------
# Converse API 작업과 대화 수행
Amazon Bedrock Converse API를 사용하여 Amazon Bedrock 모델과 메시지를 주고받는 대화형 애플리케이션을 생성할 수 있습니다. 예를 들어, 여러 턴의 대화를 유지하고, 유용한 기술 지원 도우미와 같이 사용자의 요구 사항에 맞는 페르소나를 사용하거나 톤을 사용자 지정하는 챗봇을 생성할 수 있습니다.
Converse API를 사용하려면 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 또는 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(응답 스트리밍용) 작업을 사용하여 모델에 메시지를 보냅니다. 대화 애플리케이션에 기존의 기본 추론 작업([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 또는 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html))을 사용하는 것도 가능합니다. 그러나 Converse API는 메시지를 지원하는 모든 Amazon Bedrock 모델과 호환되는 일관된 API를 제공하므로 이를 사용하는 것이 좋습니다. 즉, 코드를 한 번만 작성하면 다른 모델에서도 사용할 수 있습니다. 모델에 고유한 추론 파라미터가 있는 경우, Converse API를 사용하면 모델별 구조에 이러한 고유한 파라미터를 전달할 수도 있습니다.
Converse API를 사용하여 애플리케이션에서 [도구 사용](tool-use.md) 및 [가드레일](guardrails-use-converse-api.md)을 구현할 수 있습니다.
**참고**
Mistral AI 및 Meta 모델을 사용하면 Converse API가 대화를 활성화하는 모델별 프롬프트 템플릿에 사용자의 입력을 포함합니다.
제한 사항은 `InvokeModel`, `InvokeModelWithResponseStream`, 및 작업에 적용됩니다`Converse``ConverseStream`. 자세한 내용은 [API 제한을](inference-api-restrictions.md) 참조하세요.
코드 예제는 다음을 참조하세요.
+ 이 주제의 Python 예제 - [Converse API 예제](conversation-inference-examples.md)
+ 다양한 언어 및 모델 - [AWS SDKs를 사용한 Amazon Bedrock 런타임의 코드 예제](service_code_examples_bedrock-runtime.md)
+ Java 자습서 - [Bedrock의 새로운 Converse API에 대한 Java 개발자 안내서](https://community.aws/content/2hUiEkO83hpoGF5nm3FWrdfYvPt/amazon-bedrock-converse-api-java-developer-guide)
+ JavaScript 자습서 - [Bedrock의 새로운 Converse API에 대한 개발자 안내서](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide)
**Topics**
+ [지원되는 모델 및 모델 기능](conversation-inference-supported-models-features.md)
+ [Converse API 사용](conversation-inference-call.md)
+ [Converse API 예제](conversation-inference-examples.md)
# 지원되는 모델 및 모델 기능
Converse API는 다음과 같은 Amazon Bedrock 모델 및 모델 기능을 지원합니다. Converse API는 임베딩 또는 이미지 생성 모델을 지원하지 않습니다.
| 모델 | Converse | ConverseStream | 시스템 프롬프트 | 문서 채팅 | 비전 | 도구 사용 | 스트리밍 도구 사용 | 가드레일 | 멀티미디어용 Amazon S3 링크 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| AI21 Jamba-Instruct | 예 | 예 | 예 | 아니요 | 아니요 | 아니요 | 아니요 | 아니요 | 아니요 |
| AI21 Labs Jurassic-2 (텍스트) | 제한. 채팅 미지원. | 아니요 | 아니요 | 아니요 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| AI21 Labs Jamba 1.5 Large | 예 | 예 | 예 | 예 | 아니요 | 예 | 예 | 예 | 아니요 |
| AI21 Labs Jamba 1.5 Mini | 예 | 예 | 예 | 예 | 아니요 | 예 | 예 | 예 | 아니요 |
| Amazon Nova Premier | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 |
| Amazon Nova Pro | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 |
| Amazon Nova Lite | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 |
| Amazon Nova Micro | 예 | 예 | 예 | 아니요 | 아니요 | 예 | 예 | 예 | 아니요 |
| Amazon Titan 모델 | 예 | 예 | 아니요 | 예(Titan Text Premier 제외) | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Anthropic Claude 2.x 이하 모델 | 예 | 예 | 예 | 예 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Anthropic Claude 3 모델 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 |
| Anthropic Claude 3.5 Sonnet | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 |
| Anthropic Claude 3.5 Sonnet v2 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 |
| Anthropic Claude 3.7 Sonnet | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 |
| Anthropic Claude 3.5 Haiku | 예 | 예 | 예 | 예 | 아니요 | 예 | 예 | 아니요 | 아니요 |
| Anthropic Claude Sonnet 4 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 아니요 |
| Anthropic Claude Opus 4 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 아니요 |
| Anthropic Claude Sonnet 4.5 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 아니요 |
| Anthropic Claude Haiku 4.5 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 아니요 |
| Anthropic Claude Opus 4.1 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 아니요 |
| Claude Opus 4.5 | 예 | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 아니요 |
| Cohere Command | 제한. 채팅 미지원. | 제한. 채팅 미지원. | 아니요 | 예 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Cohere Command Light | 제한. 채팅 미지원. | 제한. 채팅 미지원. | 아니요 | 아니요 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Cohere 및 Command RCommand R\$1 | 예 | 예 | 예 | 예 | 아니요 | 예 | 예 | 아니요 | 아니요 |
| DeepSeek-R1 | 예 | 예 | 예 | 예 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Meta 및 Llama 2Llama 3 | 예 | 예 | 예 | 예 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Meta Llama 3.1 | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 | 예 | 아니요 |
| Meta Llama 3.2 1b and Llama 3.2 3b | 예 | 예 | 예 | 예 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Meta Llama 3.2 11b and Llama 3.2 90b | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 |
| Meta Llama 4 Maverick 17B and Llama 4.0 Scout 17B | 예 | 예 | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 |
| Mistral AI Instruct | 예 | 예 | 아니요 | 예 | 아니요 | 아니요 | 아니요 | 예 | 아니요 |
| Mistral Large | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 | 예 | 아니요 |
| Mistral Large 2 (24.07) | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 | 예 | 아니요 |
| Mistral Small | 예 | 예 | 예 | 아니요 | 아니요 | 예 | 아니요 | 예 | 아니요 |
| Pixtral Large (25.02) | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 | 예 | 아니요 |
| Writer Palmyra X4 | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 | 예 | 아니요 |
| Writer Palmyra X5 | 예 | 예 | 예 | 예 | 아니요 | 예 | 아니요 | 예 | 아니요 |
각 모델을 지원하는 리전의 표는 [Amazon Bedrock AWS 리전 에서의 모델 지원](models-regions.md) 섹션을 참조하세요.
**참고**
Cohere Command(텍스트) 및 AI21 Labs Jurassic-2(텍스트)는 Converse API와의 채팅을 지원하지 않습니다. 모델은 한 번에 하나의 사용자 메시지만 처리할 수 있으며 대화 기록을 유지할 수 없습니다. 메시지를 두 개 이상 전달하려고 하면 오류가 발생합니다.
# Converse API 사용
Converse API를 사용하려면 `Converse` 또는 `ConverseStream` 작업을 직접적으로 호출하여 모델에 메시지를 보냅니다. `Converse`를 직접적으로 호출하려면 `bedrock:InvokeModel` 작업에 대한 권한이 필요합니다. `ConverseStream`을 직접적으로 호출하려면 `bedrock:InvokeModelWithResponseStream` 작업에 대한 권한이 필요합니다.
**Topics**
+ [요청](#conversation-inference-call-request)
+ [응답](#conversation-inference-call-response)
**참고**
제한 사항은 InvokeModel, InvokeModelWithResponseStream, Converse 및 ConverseStream 작업에 적용됩니다. 자세한 내용은 [API 제한을](inference-api-restrictions.md) 참조하세요.
## 요청
[Amazon Bedrock 런타임 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)로 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 요청을 할 때 다음 필드를 포함할 수 있습니다.
+ **modelId** - 추론에 사용할 리소스를 지정할 수 있는 헤더의 필수 파라미터입니다.
+ 다음 필드를 사용하면 프롬프트를 사용자 지정할 수 있습니다.
+ **messages** - 프롬프트의 콘텐츠와 역할을 지정하는 데 사용합니다.
+ **system** - 모델의 지침 또는 컨텍스트를 정의하는 시스템 프롬프트를 지정하는 데 사용합니다.
+ **inferenceConfig** - 모든 모델에 공통적인 추론 파라미터를 지정하는 데 사용합니다. 추론 파라미터는 응답 생성에 영향을 미칩니다.
+ **additionalModelRequestFields** - 추론을 실행하는 모델과 관련된 추론 파라미터를 지정하는 데 사용합니다.
+ **promptVariables** – (프롬프트 관리의 프롬프트를 사용하는 경우)이 필드를 사용하여 프롬프트에서 입력할 변수와 이를 채울 값을 정의합니다.
+ 다음 필드를 사용하면 응답이 반환되는 방식을 사용자 지정할 수 있습니다.
+ **guardrailConfig** -이 필드를 사용하여 전체 프롬프트에 적용할 가드레일을 포함합니다.
+ **toolConfig** - 이 필드를 사용하여 모델이 응답을 생성하는 데 도움이 되는 도구를 포함합니다.
+ **additionalModelResponseFieldPaths** - 이 필드를 사용하여 JSON 포인터 객체로 반환할 필드를 지정합니다.
+ **serviceTier** -이 필드를 사용하여 특정 요청에 대한 서비스 계층을 지정합니다.
+ **requestMetadata** - 간접 호출 로그를 사용할 때 필터링할 수 있는 메타데이터를 포함하려면 이 필드를 사용합니다.
**참고**
`Converse` 또는 `ConverseStream`에서 프롬프트 관리 프롬프트를 사용하는 경우 다음 제한 사항이 적용됩니다.
`additionalModelRequestFields`, `inferenceConfig`, `system` 또는 `toolConfig` 필드는 포함할 수 없습니다.
`messages` 필드를 포함하면 프롬프트에 정의된 메시지 뒤에 메시지가 추가됩니다.
`guardrailConfig` 필드를 포함하면 가드레일이 전체 프롬프트에 적용됩니다. [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 필드에 `guardContent` 블록을 포함하는 경우 가드레일은 해당 블록에만 적용됩니다.
섹션을 확장하여 `Converse` 요청 본문의 필드에 대해 자세히 알아봅니다.
### messages
`messages` 필드는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체의 배열로, 각 객체는 사용자와 모델 간의 메시지를 정의합니다. `Message` 객체는 다음 필드를 포함합니다.
+ **role** - 메시지가 `user`(모델로 전송된 프롬프트) 또는 `assistant`(모델 응답)에서 왔는지 정의합니다.
+ **content** - 프롬프트의 콘텐츠를 정의합니다.
**참고**
Amazon Bedrock은 사용자가 내용으로 제공하는 텍스트, 이미지 또는 문서를 저장하지 않습니다. 데이터는 응답을 생성하는 용도로만 사용됩니다.
후속 `Converse` 요청에서 대화에 모든 메시지를 포함시키고 `role` 필드를 사용하여 메시지가 사용자 또는 모델의 메시지인지 지정하여 대화 컨텍스트를 유지할 수 있습니다.
`content` 필드는 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 객체의 배열에 매핑됩니다. 각 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 내에서 다음 필드 중 하나를 지정할 수 있습니다(모델별로 지원하는 블록을 알아보려면 [지원되는 모델 및 모델 기능](conversation-inference-supported-models-features.md) 참조).
------
#### [ text ]
`text` 필드는 프롬프트를 지정하는 문자열에 매핑됩니다. `text` 필드는 동일한 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)에 지정된 다른 필드와 함께 해석됩니다.
다음은 텍스트 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"text": "string"
}
]
}
```
------
#### [ image ]
`image` 필드는 [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html)에 매핑됩니다. `bytes` 필드의 이미지에 대해 base64로 인코딩된 원시 바이트를 전달합니다. AWS SDK를 사용하는 경우 base64에서 바이트를 인코딩할 필요가 없습니다.
`text` 필드를 제외하면 모델이 이미지를 설명합니다.
다음은 이미지 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 예제 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"bytes": "image in bytes"
}
}
}
]
}
```
요청 본문에 바이트를 직접 전달하는 대신 Amazon S3 URI를 지정할 수도 있습니다. 다음은 Amazon S3 URI를 통해 전달된 소스를 포함하는 콘텐츠 배열이 있는 샘플 `Message` 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myImage",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ document ]
`document` 필드는 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)에 매핑됩니다. `DocumentBlock`을 포함할 경우 요청이 다음 제한 사항을 준수하는지 확인합니다.
+ [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체의 `content` 필드에는 문서와 관련된 프롬프트가 있는 `text` 필드도 포함해야 합니다.
+ `bytes` 필드의 문서에 대해 base64로 인코딩된 원시 바이트를 전달합니다. AWS SDK를 사용하는 경우 base64로 문서 바이트를 인코딩할 필요가 없습니다.
+ `name` 필드에는 다음 문자만 포함할 수 있습니다.
+ 영숫자
+ 공백 문자(한 줄에 1개 이하)
+ 하이픈
+ 괄호
+ 대괄호
**참고**
`name` 필드는 모델이 지침으로 잘못 해석할 여지가 있어 프롬프트 인젝션에 취약합니다. 따라서 중립 이름을 지정하는 것이 좋습니다.
문서를 사용할 때 `citations` 태그를 활성화하면 API 직접 호출의 응답으로 문서별 인용을 제공할 수 있습니다. 자세한 내용은 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html) API를 참조하세요.
다음은 문서 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 및 필수 텍스트 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 샘플 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"text": "string"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"bytes": "document in bytes"
}
}
}
]
}
```
요청 본문에 바이트를 직접 전달하는 대신 Amazon S3 URI를 지정할 수도 있습니다. 다음은 Amazon S3 URI를 통해 전달된 소스를 포함하는 콘텐츠 배열이 있는 샘플 `Message` 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"text": "string"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myDocument",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ video ]
`video` 필드는 [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html) 객체에 매핑됩니다. `bytes` 필드에 base64로 인코딩된 원시 바이트를 전달합니다. AWS SDK를 사용하는 경우 base64에서 바이트를 인코딩할 필요가 없습니다.
`text` 필드를 포함하지 않으면 모델이 비디오를 설명합니다.
다음은 비디오 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)만 포함된 `content` 배열이 있는 샘플 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": "video in bytes"
}
}
}
]
}
```
요청 본문에 바이트를 직접 전달하는 대신 Amazon S3 URI를 지정할 수도 있습니다. 다음은 Amazon S3 URI를 통해 전달된 소스를 포함하는 콘텐츠 배열이 있는 샘플 `Message` 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myVideo",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
**참고**
수임된 역할에는 Amazon S3 URI에 대한 `s3:GetObject` 권한이 있어야 합니다. `bucketOwner` 필드는 선택 사항이지만 요청을 하는 계정이 Amazon S3 URI가 있는 버킷을 소유하지 않은 경우 지정해야 합니다. 자세한 내용은 [Amazon S3 버킷에 액세스 구성](s3-bucket-access.md) 단원을 참조하십시오.
------
#### [ cachePoint ]
`cachePoint` 필드를 사용하여 프롬프트 캐싱을 활용하여 캐시 체크포인트를 함께 제공되는 프롬프트와 함께 메시지에 블록으로 추가할 수 있습니다. 프롬프트 캐싱은 대화 컨텍스트 캐싱을 시작하여 비용 및 지연 시간을 절감할 수 있는 기능입니다. 자세한 내용은 [더 빠른 모델 추론을 위한 프롬프트 캐싱](prompt-caching.md) 단원을 참조하십시오.
다음은 문서 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)과 함께 제공되는 필수 텍스트 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)이 포함된 `content` 배열과 문서 및 텍스트 콘텐츠를 모두 캐시에 추가하는 **cachePoint**가 있는 샘플 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"text": "string"
},
{
"document": {
"format": "pdf",
"name": "string",
"source": {
"bytes": "document in bytes"
}
}
},
{
"cachePoint": {
"type": "default"
}
}
]
}
```
------
#### [ guardContent ]
`guardContent` 필드는 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 객체에 매핑됩니다. 이 필드를 사용하여 `guardrailConfig` 필드에 정의된 가드레일이 평가할 입력을 대상으로 지정할 수 있습니다. 이 필드를 지정하지 않으면 가드레일은 요청 본문의 모든 메시지를 평가합니다. `GuardBlock`에서 다음 유형의 콘텐츠를 전달할 수 있습니다.
+ **text** – 다음은 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 텍스트만 포함하는 `content` 배열이 있는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체의 예를 보여줍니다.
```
{
"role": "user",
"content": [
{
"text": "Tell me what stocks to buy.",
"qualifiers": [
"guard_content"
]
}
]
}
```
평가할 텍스트를 정의하고 [컨텍스트 근거](guardrails-contextual-grounding-check.md)에 사용할 한정자를 포함합니다.
+ **image** – 다음은 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 이미지만 포함하는 `content` 배열이 있는 [메시지](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"format": "png",
"source": {
"bytes": "image in bytes"
}
}
]
}
```
이미지의 형식을 지정하고 이미지를 바이트 단위로 정의합니다.
가드레일 사용에 대한 자세한 내용은 [Amazon Bedrock Guardrails를 사용하여 유해한 콘텐츠 감지 및 필터링](guardrails.md) 섹션을 참조하세요.
------
#### [ reasoningContent ]
`reasoningContent` 필드는 [ReasoningContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ReasoningContentBlock.html)에 매핑됩니다. 이 블록에는 함께 제공되는 `ContentBlock`에서 응답을 생성하기 위해 모델이 수행한 추론에 대한 콘텐츠가 포함되어 있습니다.
다음은 `ReasoningContentBlock` 및 함께 제공되는 텍스트 `ContentBlock`만 포함하는 `content` 배열이 있는 `Message` 객체를 보여줍니다.
```
{
"role": "user",
"content": [
{
"text": "string"
},
{
"reasoningContent": {
"reasoningText": {
"text": "string",
"signature": "string"
}
"redactedContent": "base64-encoded binary data object"
}
}
]
}
```
`ReasoningContentBlock`에는 `redactedContent` 필드의 신뢰 및 안전상의 이유로 모델 공급자가 암호화한 추론의 콘텐츠 외에도 `reasoningText` 필드에 함께 제공되는 콘텐츠를 생성하는 데 사용되는 추론이 포함되어 있습니다.
`reasoningText` 필드 내에서 `text` 필드는 추론을 설명합니다. `signature` 필드는 대화에 있는 모든 메시지의 해시이며 모델에서 사용하는 추론의 변조를 방지합니다. 후속 `Converse` 요청에 서명과 모든 이전 메시지를 포함해야 합니다. 메시지가 변경되면 응답에 오류가 발생합니다.
------
#### [ toolUse ]
모델이 사용할 도구에 대한 정보를 포함합니다. 자세한 내용은 [도구를 사용하여 Amazon Bedrock 모델 응답 완성](tool-use.md) 단원을 참조하십시오.
------
#### [ toolResult ]
도구를 사용하여 모델의 결과에 대한 정보를 포함합니다. 자세한 내용은 [도구를 사용하여 Amazon Bedrock 모델 응답 완성](tool-use.md) 단원을 참조하십시오.
------
다음 `messages` 예제에서 사용자는 세 개의 가요 목록을 요청하고 모델은 노래의 목록을 생성합니다.
```
[
{
"role": "user",
"content": [
{
"text": "Create a list of 3 pop songs."
}
]
},
{
"role": "assistant",
"content": [
{
"text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"As It Was\" by Harry Styles\n2. \"Easy On Me\" by Adele\n3. \"Unholy\" by Sam Smith and Kim Petras"
}
]
}
]
```
### 시스템
시스템 프롬프트는 모델이 수행해야 하는 작업 또는 대화 중에 채택해야 하는 페르소나에 대한 지침이나 컨텍스트를 제공하는 프롬프트의 한 유형입니다. 다음 예제와 같이 `system`([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 필드에서 요청에 대한 시스템 프롬프트 목록을 지정할 수 있습니다.
```
[
{
"text": "You are an app that creates play lists for a radio station that plays rock and pop music. Only return song names and the artist. "
}
]
```
### inferenceConfig
Converse API는 `inferenceConfig` 필드([InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html))에 설정한 추론 파라미터의 기본 세트를 지원합니다. 추론 파라미터의 기본 세트는 다음과 같습니다.
+ **maxTokens** - 생성된 응답에서 허용할 최대 토큰 수입니다.
+ **stopSequences** - 중지 시퀀스 목록입니다. 중지 시퀀스는 모델이 응답 생성을 중지하게 하는 문자 시퀀스입니다.
+ **temperature** - 응답을 생성하는 동안 모델이 더 높은 확률 옵션을 선택할 가능성입니다.
+ **topP** - 모델이 다음 토큰으로 고려할 가능성이 가장 높은 후보의 비율입니다.
자세한 내용은 [추론 파라미터를 사용하여 응답 생성에 영향을 주는 방법](inference-parameters.md) 섹션을 참조하세요.
다음 예제 JSON은 `temperature` 추론 파라미터를 설정합니다.
```
{"temperature": 0.5}
```
### additionalModelRequestFields
사용 중인 모델에 추론 파라미터가 더 있는 경우 `additionalModelRequestFields` 필드에 JSON으로 지정하여 해당 파라미터를 설정할 수 있습니다. 다음 예제 JSON은 Anthropic Claude 모델에서 사용할 수 있지만 메시지 API의 기본 추론 파라미터는 아닌 `top_k`를 설정하는 방법을 보여줍니다.
```
{"top_k": 200}
```
### promptVariables
`modelId`의 [프롬프트 관리](prompt-management.md)에서 프롬프트를 추론 실행 대상으로 지정한 경우, 이 필드를 사용하여 프롬프트 변수에 실제 값을 입력합니다. `promptVariables` 필드는 변수를 대체할 프롬프트 및 값에 정의된 변수에 해당하는 키가 있는 JSON 객체에 매핑됩니다.
예를 들어 **Make me a *\$1\$1genre\$1\$1* playlist consisting of the following number of songs: *\$1\$1number\$1\$1*.**라는 프롬프트가 있다고 가정해 보겠습니다. 프롬프트의 ID는 `PROMPT12345`이고 해당 버전은 `1`입니다. 변수를 교체하기 위해 다음 `Converse` 요청을 보낼 수 있습니다.
```
POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1
Content-type: application/json
{
"promptVariables": {
"genre" : "pop",
"number": 3
}
}
```
### guardrailConfig
이 필드를 포함하여 [Amazon Bedrock Guardrails](guardrails.md)로 생성한 가드레일을 적용할 수 있습니다. 대화의 특정 메시지에 가드레일을 적용하려면 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)에 메시지를 포함합니다. 요청 본문에 `GuardrailConverseContentBlock`를 포함하지 않으면 `messages` 필드의 모든 메시지에 가드레일이 적용됩니다. 예제는 [Converse API에 가드레일 포함](guardrails-use-converse-api.md) 섹션을 참조하세요.
### toolConfig
이 필드를 사용하면 모델이 응답을 생성하는 데 사용할 도구를 정의할 수 있습니다. 자세한 내용은 [도구를 사용하여 Amazon Bedrock 모델 응답 완성](tool-use.md) 단원을 참조하십시오.
### additionalModelResponseFieldPaths
다음 예제와 같이 `additionalModelResponseFieldPaths` 필드에 추가 모델 파라미터의 경로를 지정할 수 있습니다.
```
[ "/stop_sequence" ]
```
API는 `additionalModelResponseFields` 필드에서 요청한 추가 필드를 반환합니다.
### requestMetadata
이 필드는 JSON 객체에 매핑됩니다. 이 객체 내에서 매핑되는 메타데이터 키와 값을 지정할 수 있습니다. 요청 메타데이터를 사용하여 모델 간접 호출 로그를 필터링할 수 있습니다.
### serviceTier
이 필드는 JSON 객체에 매핑됩니다. 특정 요청에 대한 서비스 계층을 지정할 수 있습니다.
다음 예제에서는 `serviceTier` 구조를 보여줍니다.
```
"serviceTier": {
"type": "reserved" | "priority" | "default" | "flex"
}
```
요금 및 성능 특성을 포함하여 서비스 티어에 대한 자세한 내용은 섹션을 참조하세요[성능 및 비용 최적화를 위한 서비스 티어](service-tiers-inference.md).
사용 중인 모델에 따라 `system` 또는 `tools` 필드에 선택적으로 캐시 체크포인트를 추가하여 프롬프트 캐싱을 사용할 수도 있습니다. 자세한 내용은 [더 빠른 모델 추론을 위한 프롬프트 캐싱](prompt-caching.md) 단원을 참조하십시오.
## 응답
Converse API로부터 받는 응답은 직접적으로 호출하는 작업(`Converse` 또는 `ConverseStream`)에 따라 달라집니다.
**Topics**
+ [Converse 응답](#conversation-inference-call-response-converse)
+ [ConverseStream 응답](#conversation-inference-call-response-converse-stream)
### Converse 응답
`Converse`의 응답에서 `output` 필드([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html))에는 모델이 생성하는 메시지([Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html))가 포함됩니다. 메시지 내용은 `content`([ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)) 필드에 있고 메시지에 해당하는 역할(`user` 또는 `assistant`)은 `role` 필드에 있습니다.
[프롬프트 캐싱](prompt-caching.md)을 사용한 경우, 사용 필드에서 `cacheReadInputTokensCount`와 `cacheWriteInputTokensCount`는 각각 캐시에서 읽은 총 토큰 수와 캐시에 쓴 총 토큰 수를 알려줍니다.
[서비스 티어를](#inference-service-tiers) 사용한 경우 응답 필드에서 `service tier`는 요청에 사용된 서비스 티어를 알려줍니다.
`metrics` 필드([ConverseMetrics](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseMetrics.html))에는 직접 호출에 대한 지표가 포함됩니다. 모델이 콘텐츠 생성을 중단한 이유를 알아보려면 `stopReason` 필드를 확인하세요. `usage` 필드([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html))를 확인하여 요청에서 모델에 전달된 토큰과 응답에서 생성된 토큰에 대한 정보를 얻을 수 있습니다. 요청에서 추가 응답 필드를 지정한 경우 API는 해당 필드를 `additionalModelResponseFields` 필드에 JSON으로 반환합니다.
다음 예제는 [요청](#conversation-inference-call-request)에서 설명한 프롬프트를 전달할 때 `Converse`의 응답을 보여줍니다.
```
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"Wannabe\" by Spice Girls\n2. \"Bitter Sweet Symphony\" by The Verve \n3. \"Don't Look Back in Anger\" by Oasis"
}
]
}
},
"stopReason": "end_turn",
"usage": {
"inputTokens": 125,
"outputTokens": 60,
"totalTokens": 185
},
"metrics": {
"latencyMs": 1175
}
}
```
### ConverseStream 응답
`ConverseStream`을 직접적으로 호출하여 모델에서 응답을 스트리밍하면 `stream` 응답 필드에 스트림이 반환됩니다. 스트림은 이벤트를 다음과 같은 순서로 내보냅니다.
1. `messageStart` ([MessageStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStartEvent.html)). 메시지의 시작 이벤트입니다. 메시지의 역할이 포함됩니다.
1. `contentBlockStart` ([ContentBlockStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStartEvent.html)). 콘텐츠 블록 시작 이벤트입니다. 도구 사용 전용.
1. `contentBlockDelta` ([ContentBlockDeltaEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDeltaEvent.html)). 콘텐츠 블록 델타 이벤트입니다. 다음 중 하나를 포함합니다.
+ `text` - 모델이 생성하는 부분 텍스트입니다.
+ `reasoningContent` - 모델이 응답을 생성하기 위해 수행하는 부분 추론입니다. 후속 `Converse` 요청의 모든 이전 메시지 외에도 반환된 `signature`를 제출해야 합니다. 메시지가 변경되면 응답에 오류가 발생합니다.
+ `toolUse` - 도구 사용을 위한 부분 입력 JSON 객체입니다.
1. `contentBlockStop` ([ContentBlockStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStopEvent.html)). 콘텐츠 블록 중지 이벤트입니다.
1. `messageStop` ([MessageStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStopEvent.html)). 메시지에 대한 중지 이벤트입니다. 모델이 출력 생성을 중단한 이유를 포함합니다.
1. `metadata` ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)). 요청에 대한 메타데이터입니다. 메타데이터에는 `usage`([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html))의 토큰 사용량과 `metrics`([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html))의 직접 호출에 대한 지표가 포함됩니다.
ConverseStream은 전체 콘텐츠 블록을 `ContentBlockStartEvent` 이벤트, 하나 이상의 `ContentBlockDeltaEvent` 이벤트 및 `ContentBlockStopEvent` 이벤트로 스트리밍합니다. `contentBlockIndex` 필드를 인덱스로 사용하여 콘텐츠 블록을 구성하는 이벤트를 상호 연관시킵니다.
다음 예제는 `ConverseStream`의 부분 응답입니다.
```
{'messageStart': {'role': 'assistant'}}
{'contentBlockDelta': {'delta': {'text': ''}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ' Title'}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ':'}, 'contentBlockIndex': 0}}
.
.
.
{'contentBlockDelta': {'delta': {'text': ' The'}, 'contentBlockIndex': 0}}
{'messageStop': {'stopReason': 'max_tokens'}}
{'metadata': {'usage': {'inputTokens': 47, 'outputTokens': 20, 'totalTokens': 67}, 'metrics': {'latencyMs': 100.0}}}
```
# Converse API 예제
다음 예제는 `Converse` 및 `ConverseStream` 작업을 사용하는 방법을 보여줍니다.
------
#### [ Text ]
이 예제에서는 *Anthropic Claude 3 Sonnet* 모델을 사용하여 `Converse` 작업을 직접적으로 호출하는 방법을 보여줍니다. 이 예제에서는 입력 텍스트, 추론 파라미터 및 모델에 고유한 추가 파라미터를 보내는 방법을 보여줍니다. 코드는 모델에 노래 목록을 생성하도록 요청하면서 대화를 시작합니다. 그런 다음 영국 아티스트의 노래를 요청하면서 대화를 계속합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API with Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
system_prompts,
messages):
"""
Sends messages to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
system_prompts (JSON) : The system prompts for the model to use.
messages (JSON) : The messages to send to the model.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters to use.
inference_config = {"temperature": temperature}
# Additional inference parameters to use.
additional_model_fields = {"top_k": top_k}
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
# Log token usage.
token_usage = response['usage']
logger.info("Input tokens: %s", token_usage['inputTokens'])
logger.info("Output tokens: %s", token_usage['outputTokens'])
logger.info("Total tokens: %s", token_usage['totalTokens'])
logger.info("Stop reason: %s", response['stopReason'])
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
# Setup the system prompts and messages to send to the model.
system_prompts = [{"text": "You are an app that creates playlists for a radio station that plays rock and pop music. Only return song names and the artist."}]
message_1 = {
"role": "user",
"content": [{"text": "Create a list of 3 pop songs."}]
}
message_2 = {
"role": "user",
"content": [{"text": "Make sure the songs are by artists from the United Kingdom."}]
}
messages = []
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
# Start the conversation with the 1st message.
messages.append(message_1)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
# Add the response message to the conversation.
output_message = response['output']['message']
messages.append(output_message)
# Continue the conversation with the 2nd message.
messages.append(message_2)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
output_message = response['output']['message']
messages.append(output_message)
# Show the complete conversation.
for message in messages:
print(f"Role: {message['role']}")
for content in message['content']:
print(f"Text: {content['text']}")
print()
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Image ]
이 예제에서는 메시지의 일부로 이미지를 보내는 방법과 모델에게 이미지를 설명하도록 요청하는 방법을 보여줍니다. 이 예제에서는 `Converse` 작업과 *Anthropic Claude 3 Sonnet* 모델을 사용합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an image with the Converse API with an accompanying text prompt to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_image):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The text prompt accompanying the image.
input_image : The path to the input image.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get image extension and read in image as bytes
image_ext = input_image.split(".")[-1]
with open(input_image, "rb") as f:
image = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"image": {
"format": image_ext,
"source": {
"bytes": image
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this image?"
input_image = "path/to/image"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_image)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Document ]
이 예제는 메시지의 일부로 문서를 보내는 방법과 모델에게 문서의 내용을 설명하도록 요청하는 방법을 보여줍니다. 이 예제에서는 `Converse` 작업과 *Anthropic Claude 3 Sonnet* 모델을 사용합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an document as part of a message to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_message(bedrock_client,
model_id,
input_text,
input_document_path):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_document_path : The path to the input document.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get format from path and read the path
input_document_format = input_document_path.split(".")[-1]
with open(input_document_path, 'rb') as input_document_file:
input_document = input_document_file.read()
# Message to send.
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"document": {
"name": "MyDocument",
"format": input_document_format,
"source": {
"bytes": input_document
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this document?"
input_document_path = "path/to/document"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_message(
bedrock_client, model_id, input_text, input_document_path)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Streaming ]
이 예제에서는 *Anthropic Claude 3 Sonnet* 모델을 사용하여 `ConverseStream` 작업을 직접적으로 호출하는 방법을 보여줍니다. 이 예제에서는 입력 텍스트, 추론 파라미터 및 모델에 고유한 추가 파라미터를 보내는 방법을 보여줍니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API to stream a response from Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def stream_conversation(bedrock_client,
model_id,
messages,
system_prompts,
inference_config,
additional_model_fields):
"""
Sends messages to a model and streams the response.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send.
system_prompts (JSON) : The system prompts to send.
inference_config (JSON) : The inference configuration to use.
additional_model_fields (JSON) : Additional model fields to use.
Returns:
Nothing.
"""
logger.info("Streaming messages with model %s", model_id)
response = bedrock_client.converse_stream(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
stream = response.get('stream')
if stream:
for event in stream:
if 'messageStart' in event:
print(f"\nRole: {event['messageStart']['role']}")
if 'contentBlockDelta' in event:
print(event['contentBlockDelta']['delta']['text'], end="")
if 'messageStop' in event:
print(f"\nStop reason: {event['messageStop']['stopReason']}")
if 'metadata' in event:
metadata = event['metadata']
if 'usage' in metadata:
print("\nToken usage")
print(f"Input tokens: {metadata['usage']['inputTokens']}")
print(
f":Output tokens: {metadata['usage']['outputTokens']}")
print(f":Total tokens: {metadata['usage']['totalTokens']}")
if 'metrics' in event['metadata']:
print(
f"Latency: {metadata['metrics']['latencyMs']} milliseconds")
def main():
"""
Entrypoint for streaming message API response example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
system_prompt = """You are an app that creates playlists for a radio station
that plays rock and pop music. Only return song names and the artist."""
# Message to send to the model.
input_text = "Create a list of 3 pop songs."
message = {
"role": "user",
"content": [{"text": input_text}]
}
messages = [message]
# System prompts.
system_prompts = [{"text" : system_prompt}]
# inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters.
inference_config = {
"temperature": temperature
}
# Additional model inference parameters.
additional_model_fields = {"top_k": top_k}
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
stream_conversation(bedrock_client, model_id, messages,
system_prompts, inference_config, additional_model_fields)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
else:
print(
f"Finished streaming messages with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Video ]
이 예제에서는 메시지의 일부로 비디오를 보내는 방법과 모델에게 비디오를 설명하도록 요청하는 방법을 보여줍니다. 이 예제에서는 `Converse` 작업과 Amazon Nova Pro 모델을 사용합니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send a video with the Converse API to Amazon Nova Pro (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_video):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_video : The input video.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Message to send.
with open(input_video, "rb") as f:
video = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"video": {
"format": 'mp4',
"source": {
"bytes": video
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Amazon Nova Pro example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "amazon.nova-pro-v1:0"
input_text = "What's in this video?"
input_video = "path/to/video"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_video)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
# API 제한
`InvokeModel`, `InvokeModelWithResponseStream`, `Converse`및 `ConverseStream` 작업에는 다음 제한이 적용됩니다. 일부 제한 사항은 아래와 같이 작업 또는 모델에 따라 다릅니다.
+ 이러한 작업을 사용할 때가 인 경우에만 이미지와 문서를 포함할 수 `role` 있습니다`user`.
+ **비디오 생성:** 비디오 생성은 `InvokeModel` 및에서 지원되지 않습니다`InvokeModelWithResponseStream`. 대신 [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html) 작업을 사용할 수 있습니다. 예제는 [Amazon Nova Reel을 사용하여 텍스트 프롬프트에서 비디오 생성](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_Scenario_AmazonNova_TextToVideo_section.html)을 참조하세요.
+ **요청 본문의 문서 지원:** `InvokeModel` 및 사용 시 요청 본문에 문서를 포함하는 것은 지원되지 않습니다`InvokeModelWithResponseStream`. 추론 중에 문서를 포함하려면에서 [채팅/텍스트 플레이그라운드](playgrounds.md)를 사용하거나 `Converse` 또는 `ConverseStream` 작업을 AWS Management Console 사용합니다.
+ **문서 수 및 크기:** 요청당 최대 5개의 문서를 포함할 수 있습니다. 각 문서의 크기는 4.5MB를 초과할 수 없습니다. Claude 4 및 후속 버전의 경우 4.5MB 문서 크기 제한이 `PDF` 형식에 적용되지 않습니다. Nova 모델의 경우 및 `PDF` `DOCX` 형식에는 4.5MB 문서 크기 제한이 적용되지 않습니다. 이러한 제한은 Bedrock 콘솔에서 계속 적용됩니다. 개별 모델에는 Amazon Bedrock에서 적용하는 것 이외의 추가 콘텐츠 제한이 있을 수 있습니다. 자세한 내용은 **타사 모델 공급자 요구 사항을** 참조하세요.
+ **이미지 수 및 크기**: Amazon Bedrock은 이미지 수 및 크기에 제한을 두지 않습니다. 그러나 개별 모델에는 특정 이미지 요구 사항이 있을 수 있습니다. 자세한 내용은 **타사 모델 공급자 요구 사항을** 참조하세요.
+ **타사 모델 공급자 요구 사항:** `InvokeModel`, , `InvokeModelWithResponseStream` `Converse`및 `ConverseStream` 작업을 사용할 때 타사 모델 공급자 요구 사항이 적용되며 충족되지 않으면 오류가 발생할 수 있습니다. Amazon Bedrock을 통해 타사 모델(예: Anthropic Claude)을 사용하는 경우 예상치 못한 오류를 방지하려면 공급자의 사용 설명서와 API 설명서를 검토하세요. 예를 들어 Anthropic Messages 표준 엔드포인트는 최대 요청 크기 32MB를 지원합니다. 또한 Claude에는 요청당 최대 100`PDF`페이지, 최대 이미지 크기 8000x8000픽셀과 같은 특정 콘텐츠 요구 사항이 있습니다. 요청 크기 및 콘텐츠 요구 사항을 포함하여 Anthropic Claude Messages 요청 및 응답에 대한 최신 정보는 Anthropic Claude 설명서: [Anthropic Claude API 개요](https://platform.claude.com/docs/en/api/overview), [Anthropic Claude Messages API 참조](https://docs.anthropic.com/claude/reference/messages_post), [Build with Claude: Vision](https://platform.claude.com/docs/en/build-with-claude/vision) 및 [Build with Claude: PDF Support](https://platform.claude.com/docs/en/build-with-claude/pdf-support)를 참조하세요.
**작은 정보**
Claude에서는 PDF 문서가 요청당 최대 100페이지여야 합니다. 더 큰 PDF 문서가 있는 경우 각각 100페이지 미만의 여러 PDFs로 분할하거나 더 많은 텍스트를 더 적은 페이지로 통합하는 것이 좋습니다.
# 모델에서 검증된 JSON 결과 가져오기
구조화된 출력은 모델 응답이 사용자 정의 JSON 스키마 및 도구 정의를 준수하도록 하여 프로덕션 AI 배포에서 사용자 지정 구문 분석 및 검증 메커니즘의 필요성을 줄이는 Amazon Bedrock의 기능입니다.
## 이점
구조화된 출력은 프로덕션 AI 애플리케이션의 중요한 문제를 해결합니다.
+ **스키마 규정 준수 보장 **- 프롬프트 기반 접근 방식에서 오류 발생률 및 재시도 루프 제거
+ **개발 복잡성 감소** - 사용자 지정 구문 분석 및 검증 로직이 필요하지 않음
+ **운영 비용 절감** - 실패한 요청 및 재시도를 줄입니다.
+ **프로덕션 신뢰성** - 예측 가능하고 기계 판독이 가능한 출력이 필요한 AI 애플리케이션을 자신 있게 배포할 수 있습니다.
## 작동 방식
구조화된 출력은 특정 스키마를 따르도록 모델 응답을 제한하여 다운스트림 처리를 위한 유효하고 구문 분석 가능한 출력을 보장합니다. 두 가지 보완 메커니즘을 통해 구조화된 출력을 사용할 수 있습니다.
### JSON 스키마 출력 형식
Anthropic Claude 모델이 포함된 InvokeModel API의 경우 `output_config.format` 요청 필드를 사용합니다. 개방형 가중치 모델의 경우 `response_format` 요청 필드를 사용합니다. Converse APIs의 경우 `outputConfig.textFormat` 요청 필드를 사용합니다. 모델의 응답은 지정된 JSON 스키마를 따릅니다.
### 엄격한 도구 사용
도구 정의에 `strict: true` 플래그를 추가하여 도구 이름 및 입력에 대한 스키마 검증을 활성화합니다. 그러면 모델의 도구 호출이 정의된 도구 입력 스키마를 따릅니다.
이러한 메커니즘은 동일한 요청에서 독립적으로 또는 함께 사용할 수 있습니다. 자세한 내용은 [Bedrock API 설명서를](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html) 참조하세요.
### 요청 워크플로
다음은 Amazon Bedrock이 구조화된 출력으로 요청을 처리하는 방법을 설명합니다.
1. **초기 요청** - `outputConfig.textFormat`, `output_config.format`또는 `response_format` 파라미터를 통한 JSON 스키마 또는 추론 요청에 `strict: true` 플래그가 있는 도구 정의를 포함합니다.
1. **스키마 검증** - Amazon Bedrock은 지원되는 JSON 스키마 초안 2020년 12월 하위 집합과 비교하여 JSON 스키마 형식을 검증합니다. 스키마에 지원되지 않는 기능이 포함된 경우 Amazon Bedrock은 즉시 400 오류를 반환합니다.
1. **최초 컴파일** - 새 스키마의 경우 Amazon Bedrock은 최대 몇 분 정도 걸릴 수 있는 문법을 컴파일합니다.
1. **캐싱** - 성공적으로 컴파일된 문법은 처음 액세스한 후 24시간 동안 캐싱됩니다. 캐시된 문법은 AWS 관리형 키로 암호화됩니다.
1. **후속 요청** - 동일한 계정의 동일한 스키마가 캐시된 문법을 사용하므로 오버헤드를 최소화하면서 표준 요청과 비슷한 추론 지연 시간이 발생합니다.
1. **응답** - 엄격한 스키마 규정 준수로 표준 추론 응답을 받습니다.
## 지원되는 APIs 또는 기능
다음 Amazon Bedrock 기능에서 구조화된 출력을 사용할 수 있습니다.
**Converse 및 ConverseStream APIs** - 대화 추론을 위해 Converse 및 ConverseStream APIs와 함께 구조화된 출력을 사용합니다.
**InvokeModel 및 InvokeModelWithResponseStream APIs**- 단일 턴 추론을 위해 InvokeModel 및 InvokeModelWithResponseStream APIs와 함께 구조화된 출력을 사용합니다.
**교차 리전 추론** - 추가 설정 없이 교차 리전 추론 내에서 구조화된 출력을 사용합니다.
**배치 추론** - 추가 설정 없이 배치 추론 내에서 구조화된 출력을 사용합니다.
**참고**
구조화된 출력은 Anthropic 모델의 인용과 호환되지 않습니다. 구조화된 출력을 사용하는 동안 인용을 활성화하면 모델이 400 오류를 반환합니다.
## 지원되는 모델
구조화된 출력은 일반적으로 일부 Amazon Bedrock 서버리스 모델의 모든 상용 AWS 리전에서 사용할 수 있습니다. 지원되는 모델 목록은 기능별 모델 지원을 참조하세요.
### 지원되는 모든 모델 보기
Anthropic
+ Claude Haiku 4.5(`anthropic.claude-haiku-4-5-20251001-v1:0`)
+ Claude Sonnet 4.5(`anthropic.claude-sonnet-4-5-20250929-v1:0`)
+ Claude Opus 4.5(`anthropic.claude-opus-4-5-20251101-v1:0`)
+ Claude Opus 4.6(`anthropic.claude-opus-4-6-v1`)
쿠엔
+ Qwen3 235B A22B 2507(`qwen.qwen3-235b-a22b-2507-v1:0`)
+ Qwen3 32B(집약적)(`qwen.qwen3-32b-v1:0`)
+ Qwen3-Coder-30B-A3B-Instruct(`qwen.qwen3-coder-30b-a3b-v1:0`)
+ Qwen3 Coder 480B A35B 지침(`qwen.qwen3-coder-480b-a35b-v1:0`)
+ Qwen3 다음 80B A3B(`qwen.qwen3-next-80b-a3b`)
+ Qwen3 VL 235B A22B(`qwen.qwen3-vl-235b-a22b`)
OpenAI
+ gpt-oss-120b(`openai.gpt-oss-120b-1:0`)
+ gpt-oss-20b(`openai.gpt-oss-20b-1:0`)
+ GPT OSS 보호 120B(`openai.gpt-oss-safeguard-120b`)
+ GPT OSS 보호 20B(`openai.gpt-oss-safeguard-20b`)
DeepSeek
+ DeepSeek-V3.1(`deepseek.v3-v1:0`)
Google
+ Gemma 3 12B IT(`google.gemma-3-12b-it`)
+ Gemma 3 27B PT(`google.gemma-3-27b-it`)
MiniMax
+ MiniMax M2(`minimax.minimax-m2`)
Mistral AI
+ Magistral Small 2509(`mistral.magistral-small-2509`)
+ 미니스트럴 3B(`mistral.ministral-3-3b-instruct`)
+ 미니스트럴 3 8B(`mistral.ministral-3-8b-instruct`)
+ 미니스트럴 14B 3.0(`mistral.ministral-3-14b-instruct`)
+ Mistral Large 3(`mistral.mistral-large-3-675b-instruct`)
+ Voxtral Mini 3B 2507(`mistral.voxtral-mini-3b-2507`)
+ Voxtral Small 24B 2507(`mistral.voxtral-small-24b-2507`)
달샷 AI
+ 키미 K2 Thinking(`moonshot.kimi-k2-thinking`)
NVIDIA
+ NVIDIA Nemotron Nano 12B v2 VL BF16(`nvidia.nemotron-nano-12b-v2`)
+ NVIDIA Nemotron Nano 9B v2(`nvidia.nemotron-nano-9b-v2`)
## 요청 예시
### JSON 스키마 출력 형식
다음 예제에서는 구조화된 출력과 함께 JSON 스키마 출력 형식을 사용하는 방법을 보여줍니다.
#### Converse API
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": [
{
"text": "Given the following unstructured data, extract it into the provided structure."
},
{
"text": "..."
}
]
}
],
"outputConfig": {
"textFormat": {
"type": "json_schema",
"structure": {
"jsonSchema": {
"schema": "{\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\", \"description\": \"title\"}, \"summary\": {\"type\": \"string\", \"description\": \"summary\"}, \"next_steps\": {\"type\": \"string\", \"description\": \"next steps\"}}, \"required\": [\"title\", \"summary\", \"next_steps\"], \"additionalProperties\": false}",
"name": "data_extraction",
"description": "Extract structured data from unstructured text"
}
}
}
}
}
```
#### InvokeModel(Anthropic Claude)
##### 예제 보기
```
{
"anthropic_version": "bedrock-2023-05-31",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Given the following unstructured data, extract it into the provided structure."
},
{
"type": "text",
"text": "..."
}
]
}
],
"max_tokens": 3000,
"temperature": 1.0,
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "title"
},
"summary": {
"type": "string",
"description": "summary"
},
"next_steps": {
"type": "string",
"description": "next steps"
}
},
"required": [
"title",
"summary",
"next_steps"
],
"additionalProperties": false
}
}
}
}
```
#### InvokeModel(Open-weight 모델)
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": "Given the following unstructured data, extract it into the provided structure."
},
{
"role": "user",
"content": "..."
}
],
"inferenceConfig": {
"maxTokens": 3000,
"temperature": 1.0
},
"response_format": {
"json_schema": {
"name": "summarizer",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "title"
},
"summary": {
"type": "string",
"description": "summary"
},
"next_steps": {
"type": "string",
"description": "next steps"
}
},
"required": [
"title",
"summary",
"next_steps"
],
"additionalProperties": false
}
},
"type": "json_schema"
}
}
```
### 엄격한 도구 사용
다음 예제에서는 도구 사용과 함께 엄격한 필드를 사용하는 방법을 보여줍니다.
#### Converse API
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": [
{
"text": "What's the weather like in New York?"
}
]
}
],
"toolConfig": {
"tools": [
{
"toolSpec": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"inputSchema": {
"json": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
]
}
}
}
}
]
}
}
```
#### InvokeModel(Anthropic Claude)
##### 예제 보기
```
{
"anthropic_version": "bedrock-2023-05-31",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's the weather like in San Francisco?"
}
]
}
],
"max_tokens": 3000,
"temperature": 1.0,
"tools": [
{
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
],
"additionalProperties": false
}
}
]
}
```
#### InvokeModel(Open-weight 모델)
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": "What's the weather like in San Francisco?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
]
}
}
}
],
"tool_choice": "auto",
"max_tokens": 2000,
"temperature": 1.0
}
```
# 컴퓨터 사용 도구를 사용하여 Amazon Bedrock 모델 응답 완료
컴퓨터 사용은 Anthropic Claude 3.7 Sonnet 및 Claude 3.5 Sonnet v2에서만 사용할 수 있는 Anthropic Claude 모델 기능(베타)입니다. 컴퓨터 사용 기능을 사용하면 Claude가 기본 GUI 작업을 통해 작업을 자동화하는 데 도움을 줍니다.
**주의**
컴퓨터 사용 기능은 서비스 약관에 정의된 대로 '베타 AWS 서비스'로 사용할 수 있습니다. 여기에는 및 AWS 서비스 약관 AWS 과의 계약과 해당 모델 EULA가 적용됩니다. Computer Use API는 표준 API 기능 또는 채팅 인터페이스와는 다른 고유한 위험을 초래한다는 점에 유의하세요. 이러한 위험은 Computer Use API를 사용하여 인터넷과 상호 작용할 때 더욱 커집니다. 위험을 최소화하려면 다음과 같은 예방 조치를 취하는 것이 좋습니다.
전용 가상 머신 또는 컨테이너에서 컴퓨터 사용 기능을 최소한의 권한으로 작동하여 직접 시스템 공격 또는 사고를 방지합니다.
정보 도난을 방지할 수 있도록 민감한 계정 또는 데이터에 대한 Computer Use API 액세스 권한을 부여하지 마세요.
Computer Use API의 인터넷 액세스를 필수 도메인으로 제한하여 악성 콘텐츠에 대한 노출을 줄입니다.
적절한 감독이 이루어질 수 있도록, 민감한 작업(예: 의미 있는 실제 결과로 이어질 수 있는 의사 결정)과 긍정적인 동의가 필요한 모든 작업(예: 쿠키 허용, 금융 거래 실행 또는 서비스 약관 동의)에 대해 사람을 루프에 관여시킵니다.
Claude가 확인하거나 액세스할 수 있도록 설정한 모든 콘텐츠로 인해 지침이 재정의되거나, Claude의 실수 또는 의도하지 않은 작업 수행이 발생할 수 있습니다. 프롬프트 인젝션과 관련된 위험을 방지하기 위해서는 민감한 표면에서 Claude를 격리하는 등 적절한 예방 조치를 취하는 것이 중요합니다. 자체 제품에서 컴퓨터 사용 기능을 설정하는 데 필요한 권한을 활성화하거나 요청하기 전에 최종 사용자에게 관련 위험을 알리고 필요한 경우 동의를 얻으시기 바랍니다.
Computer Use API는 사전 정의된 여러 컴퓨터 사용 도구(*computer\$120241022*, *bash\$120241022*, *text\$1editor\$120241022*)를 제공합니다. 그런 다음 “지난 회의의 메모가 포함된 이메일을 Ben에게 전송해 줘” 같은 프롬프트와 스크린샷(필요한 경우)과 같은 프롬프트를 작성할 수 있습니다. 응답에는 JSON 형식의 `tool_use` 작업 목록이 포함됩니다(예: scroll\$1down, left\$1button\$1press, screenshot). 코드는 컴퓨터 작업을 실행하고, Claude에 요청 시 출력을 보여주는 스크린샷을 제공합니다.
도구 파라미터가 다형성 도구 유형을 허용하도록 업데이트되었습니다. 이를 구분하기 위해 새 `tool.type` 속성이 추가됩니다. `type`은 선택 사항이며, 생략된 경우 도구는 사용자 지정 도구로 간주됩니다(이전에 유일하게 지원된 도구 유형). 또한 해당 열거형 값이 `computer-use-2024-10-22`인 새 파라미터 `anthropic_beta`가 추가되었습니다. 이 파라미터와 열거형으로 이루어진 요청만 새 컴퓨터 사용 도구를 사용할 수 있습니다. 이렇게 지정할 수 있습니다. `"anthropic_beta": ["computer-use-2024-10-22"] `
Anthropic Claude 3.5 Sonnet v2에서 컴퓨터 사용을 사용하려면 Converse API([Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 또는 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html))를 사용하면 됩니다. 컴퓨터가 `additionalModelRequestFields` 필드의 특정 필드를 사용하도록 지정하세요. Converse API 직접 호출에 대해 알아보려면 [Converse API 작업과 대화 수행](conversation-inference.md) 섹션을 참조하세요.
기본 추론 작업([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 또는 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html))과 함께 도구를 사용하는 것이 가능합니다. 요청 본문에서 전달하는 추론 파라미터를 찾는 방법은 [Anthropic Claude Messages API](model-parameters-anthropic-claude-messages.md) 섹션을 참조하세요.
자세한 내용은 Anthropic 설명서의 [컴퓨터 사용(베타)](https://docs.anthropic.com/en/docs/build-with-claude/computer-use)을 참조하세요.
**Topics**
+ [예제 코드](#computer-use-example-code)
+ [응답의 예](#example-response)
## 예제 코드
다음 코드는 Computer Use API를 호출하는 방법을 보여줍니다. 입력은 AWS 콘솔의 이미지입니다.
```
with open('test_images/console.png', 'rb') as f:
png = f.read()
response = bedrock.converse(
modelId='anthropic.claude-3-5-sonnet-20241022-v2:0',
messages=[
{
'role': 'user',
'content': [
{
'text': 'Go to the bedrock console'
},
{
'image': {
'format': 'png',
'source': {
'bytes': png
}
}
}
]
}
],
additionalModelRequestFields={
"tools": [
{
"type": "computer_20241022",
"name": "computer",
"display_height_px": 768,
"display_width_px": 1024,
"display_number": 0
},
{
"type": "bash_20241022",
"name": "bash",
},
{
"type": "text_editor_20241022",
"name": "str_replace_editor",
}
],
"anthropic_beta": ["computer-use-2024-10-22"]
},
toolConfig={
'tools': [
{
'toolSpec': {
'name': 'get_weather',
'inputSchema': {
'json': {
'type': 'object'
}
}
}
}
]
})
print(json.dumps(response, indent=4))
```
## 응답의 예
예제 코드는 다음과 비슷한 출력을 내보냅니다.
```
{
"id": "msg_bdrk_01Ch8g9MF3A9FTrmeywrwfMZ",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I can see from the screenshot that we're already in the AWS Console. To go to the Amazon Bedrock console specifically, I'll click on the Amazon Bedrock service from the \"Recently Visited\" section."
},
{
"type": "tool_use",
"id": "toolu_bdrk_013sAzs1gsda9wLrfD8bhYQ3",
"name": "computer",
"input": {
"action": "screenshot"
}
}
],
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 3710,
"output_tokens": 97
}
}
```
# 도구를 사용하여 Amazon Bedrock 모델 응답 완성
Amazon Bedrock API를 사용하여 모델에 전송하는 메시지에 대한 응답을 생성하는 데 도움이 되는 도구에 대한 액세스 권한을 모델에 제공할 수 있습니다. 예를 들어, 사용자가 라디오 방송국에서 재생되는 가장 인기 있는 노래를 찾을 수 있는 채팅 애플리케이션이 있을 수 있습니다. 가장 인기 있는 노래에 대한 요청에 답변하려면 모델에 노래 정보를 쿼리하고 반환할 수 있는 도구가 필요합니다.
**참고**
이제 도구 사용과 함께 구조화된 출력을 사용할 수 있습니다. 자세한 내용은 [모델에서 검증된 JSON 결과 가져오기](structured-output.md) 섹션을 참조하세요.
Amazon Bedrock에서는 모델이 도구를 직접 호출하지 않습니다. 대신 모델에 메시지를 전송할 때 모델이 응답을 생성하는 데 잠재적으로 도움이 될 수 있는 하나 이상의 도구에 대한 정의를 함께 제공합니다. 이 예제에서는 지정된 라디오 방송국에서 가장 인기 있는 노래를 반환하는 도구에 대한 정의를 제공합니다. 모델에 메시지에 대한 응답을 생성하는 데 도구가 필요하다고 판단되면 모델은 모델을 호출하는 데 사용되는 API에 따라 클라이언트 측 호출을 수행하거나 Bedrock에 서버 측 도구 호출을 사용하여 도구를 호출하도록 요청할 수 있습니다. 이 두 가지 옵션에 대해 자세히 살펴보겠습니다.
**클라이언트 측 도구 호출**
응답 API, 채팅 완료 API, Converse API 또는 InvokeModel API를 사용하여 요청을 보내는 경우 모델은 클라이언트 측 도구 호출을 사용합니다. 즉, 코드에서 모델을 대신하여 도구를 호출합니다. 이 시나리오에서는 도구 구현이 API라고 가정합니다. 이 도구는 데이터베이스, Lambda 함수 또는 기타 소프트웨어처럼 쉽게 사용할 수 있습니다. 도구를 구현할 방법을 결정합니다. 그런 다음 도구의 결과가 포함된 메시지를 제공하여 모델과의 대화를 계속합니다. 마지막으로 모델은 모델로 전송한 도구 결과가 포함된 원본 메시지에 대한 응답을 생성합니다.
도구 사용에 사용할 도구를 정의해 보겠습니다. 다음 Python 예제에서는 가상 라디오 방송국에서 가장 인기 있는 노래를 반환하는 도구를 사용하는 방법을 보여줍니다.
```
def get_most_popular_song(station_name: str) -> str:
stations = {
"Radio Free Mars": "Starman – David Bowie",
"Neo Tokyo FM": "Plastic Love – Mariya Takeuchi",
"Cloud Nine Radio": "Blinding Lights – The Weeknd",
}
return stations.get(station_name, "Unknown Station – No chart data available")
```
**클라이언트 측 도구에 응답 API 사용**
OpenAI에서 제공하는 [함수 호출](https://platform.openai.com/docs/guides/function-calling) 기능을 사용하여이 도구를 호출할 수 있습니다. 응답 API는 OpenAI의 기본 API입니다. 다음은 클라이언트 측 도구에 대한 응답 API의 Python 코드입니다.
```
from openai import OpenAI
import json
client = OpenAI()
response = client.responses.create(
model="oss-gpt-120b",
input="What is the most popular song on Radio Free Mars?",
tools=[
{
"type": "function",
"name": "get_most_popular_song",
"description": "Returns the most popular song on a radio station",
"parameters": {
"type": "object",
"properties": {
"station_name": {
"type": "string",
"description": "Name of the radio station"
}
},
"required": ["station_name"]
}
}
]
)
if response.output and response.output[0].content:
tool_call = response.output[0].content[0]
args = json.loads(tool_call["arguments"])
result = get_most_popular_song(args["station_name"])
final_response = client.responses.create(
model="oss-gpt-120b",
input=[
{
"role": "tool",
"tool_call_id": tool_call["id"],
"content": result
}
]
)
print(final_response.output_text)
```
**클라이언트 측 도구에 Chat Completions API 사용**
채팅 완료 API를 사용할 수도 있습니다. 다음은 채팅 완료를 사용하기 위한 Python 코드입니다.
```
from openai import OpenAI
import json
client = OpenAI()
completion = client.chat.completions.create(
model="oss-gpt-120b",
messages=[{"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"}],
tools=[{
"type": "function",
"function": {
"name": "get_most_popular_song",
"description": "Returns the most popular song on a radio station",
"parameters": {
"type": "object",
"properties": {
"station_name": {"type": "string", "description": "Name of the radio station"}
},
"required": ["station_name"]
}
}
}]
)
message = completion.choices[0].message
if message.tool_calls:
tool_call = message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = get_most_popular_song(args["station_name"])
followup = client.chat.completions.create(
model="oss-gpt-120b",
messages=[
{"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"},
message,
{"role": "tool", "tool_call_id": tool_call.id, "content": result}
]
)
print(followup.choices[0].message.content)
```
응답에서 함수 호출 API 및 채팅 완료 API를 사용하는 방법에 대한 자세한 내용은 OpenAI에서 [함수 호출을](https://platform.openai.com/docs/guides/function-calling) 참조하세요.
**클라이언트 측 도구에 Converse API 사용**
[Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html)를 사용하여 모델이 대화에서 도구를 사용하도록 할 수 있습니다. 다음 Python 예제에서는 가상 라디오 방송국에서 가장 인기 있는 노래를 반환하는 도구를 사용하는 방법을 보여줍니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""Shows how to use tools with the Converse API and the Cohere Command R model."""
import logging
import json
import boto3
from botocore.exceptions import ClientError
class StationNotFoundError(Exception):
"""Raised when a radio station isn't found."""
pass
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def get_top_song(call_sign):
"""Returns the most popular song for the requested station.
Args:
call_sign (str): The call sign for the station for which you want
the most popular song.
Returns:
response (json): The most popular song and artist.
"""
song = ""
artist = ""
if call_sign == 'WZPZ':
song = "Elemental Hotel"
artist = "8 Storey Hike"
else:
raise StationNotFoundError(f"Station {call_sign} not found.")
return song, artist
def generate_text(bedrock_client, model_id, tool_config, input_text):
"""Generates text using the supplied Amazon Bedrock model. If necessary,
the function handles tool use requests and sends the result to the model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The Amazon Bedrock model ID.
tool_config (dict): The tool configuration.
input_text (str): The input text.
Returns:
Nothing.
"""
logger.info("Generating text with model %s", model_id)
# Create the initial message from the user input.
messages = [{"role": "user",
"content": [{"text": input_text}]}]
response = bedrock_client.converse(modelId=model_id,
messages=messages,
toolConfig=tool_config)
output_message = response['output']['message']
messages.append(output_message)
stop_reason = response['stopReason']
if stop_reason == 'tool_use':
# Tool use requested. Call the tool and send the result to the model.
tool_requests = response['output']['message']['content']
for tool_request in tool_requests:
if 'toolUse' in tool_request:
tool = tool_request['toolUse']
logger.info("Requesting tool %s. Request: %s",
tool['name'], tool['toolUseId'])
if tool['name'] == 'top_song':
tool_result = {}
try:
song, artist = get_top_song(tool['input']['sign'])
tool_result = {"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}]}
except StationNotFoundError as err:
tool_result = {"toolUseId": tool['toolUseId'],
"content": [{"text": err.args[0]}],
"status": 'error'}
tool_result_message = {"role": "user",
"content": [{"toolResult": tool_result}]}
messages.append(tool_result_message)
# Send the tool result to the model.
response = bedrock_client.converse(modelId=model_id,
messages=messages,
toolConfig=tool_config)
output_message = response['output']['message']
# print the final response from the model.
for content in output_message['content']:
print(json.dumps(content, indent=4))
def main():
"""Entrypoint for tool use example."""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "cohere.command-r-v1:0"
input_text = "What is the most popular song on WZPZ?"
tool_config = {
"tools": [
{
"toolSpec": {
"name": "top_song",
"description": "Get the most popular song played on a radio station.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ, and WKRP."
}
},
"required": ["sign"]
}
}
}
}
]
}
bedrock_client = boto3.client(service_name='bedrock-runtime')
try:
print(f"Question: {input_text}")
generate_text(bedrock_client, model_id, tool_config, input_text)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
**클라이언트 측 도구 사용에 APIs 호출 사용**
기본 추론 작업([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 또는 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html))과 함께 도구를 사용하는 것이 가능합니다. 요청 본문에서 전달하는 추론 파라미터를 찾으려면 사용하려는 모델의 [추론 파라미터](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html)를 참조하세요.
**서버 측 도구 호출**
응답 API를 사용하여 모델을 호출하는 경우 이전에 설명한 클라이언트 측 도구 호출 외에도 서버 측 도구 호출을 사용할 수 있습니다. 서버 측 도구 호출은 도구(APIs, 함수, 워크플로)가 클라이언트가 아닌 신뢰할 수 있는 백엔드 환경에서 실행되는 메커니즘입니다. 이렇게 하면 애플리케이션의 보안, 신뢰성 및 거버넌스 태세가 향상됩니다. Amazon Bedrock은 도구 사용을 구현하는 Lambda 함수를 실행하기 전에 Lambda 함수가 이를 호출하는 애플리케이션과 동일한 IAM 정책을 갖도록 합니다. Amazon Bedrock이 도구 실행을 주도함에 따라 클라이언트는 도구 기능을 추가하는 대신 비즈니스 로직을 구현하는 데 집중할 수 있습니다. Amazon Bedrock은 ISO, SOC 및 HIPAA 적격과 같은 가장 높은 거버넌스 표준도 지원합니다. 고객은 자체 사용자 지정 Lambda 함수를 제출하여 도구를 실행하거나 메모 및 작업과 같은 기존 사전 정의된 도구를 사용할 수 있습니다. 응답 API를 사용하는 서버 측 도구는 OpenAI의 GPT OSS 20B/120B 모델부터 사용할 수 있으며 다른 모델에 대한 지원이 곧 제공될 예정입니다. 모델 API를 사용하여 응답 API와 함께 사용할 수 있는 사용 가능한 모델을 검색할 수 있습니다. 응답 API에 대한 자세한 내용은 [ OpenAI APIs](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html).
Amazon Bedrock과 함께 사용할 수 있는 도구에는 Lambda를 사용하는 사용자 지정 도구 또는 Bedrock에서 지원하는 사전 정의된 도구라는 두 가지 유형이 있습니다. 이 섹션에서는 응답 API를 사용하여 사용자 지정 Lambda 도구를 생성하는 방법을 검토합니다. 두 가지를 모두 자세히 살펴보겠습니다.
**응답 API에서 Lambda를 사용하는 사용자 지정 도구**
Bedrock에서 Lambda 함수를 사용자 지정 도구로 사용하면 사용자 지정 AWS Lambda 함수를 도구로 통합하여 에이전트의 기능을 확장할 수 있습니다. 이를 통해 모델 컨텍스트 프로토콜(MCP)을 통해 AI 어시스턴트 및 기타 애플리케이션에서 호출할 수 있는 확장 가능한 서버리스 도구를 생성할 수 있습니다. 이 기능의 장점은 다음과 같습니다.
+ 기능 확장: 사용자 지정 비즈니스 로직, API 통합 또는 데이터 처리 기능을 추가합니다.
+ 도구를 안전하게 실행: Lambda를 사용하면 도구가 전체 VPC 액세스 권한을 부여하지 않고도 VPC 내의 리소스에 액세스할 수 있습니다.
+ 서버리스 아키텍처: 인프라 관리가 없는 Lambda는 조정을 자동으로 처리합니다.
+ 비용 효율성: 유휴 리소스가 아닌 실행 시간에 대해서만 비용을 지불합니다.
+ 간편한 통합: Lambda 함수는 기본 제공 도구와 함께 원활하게 나타납니다.
Amazon Bedrock의 모델이 도구를 사용하여 메시지에 대한 응답을 완료하도록 하려면 메시지와 하나 이상의 도구에 대한 정의를 모델에 전송합니다. 애플리케이션의 프롬프트에 따라 모델이 도구 중 하나가 응답을 생성하는 데 도움이 될 수 있다고 판단하면 Bedrock이 도구를 사용하고 도구 결과를 모델로 다시 보내라는 요청을 반환합니다. 그런 다음 모델은 결과를 사용하여 원본 메시지에 대한 응답을 생성합니다.
다음 단계에서는 [응답 API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html)와 함께 도구를 사용하는 방법을 보여줍니다.
**작동 방식**
1. **Lambda 함수**: MCP 프로토콜을 구현하는 Lambda 함수 생성
1. **도구 검색**: Bedrock이 Lambda 함수를 호출하여 사용 가능한 도구를 검색합니다.
1. **도구 등록**: 도구가 Bedrock에 등록되어 있습니다.
1. **도구 실행**: 에이전트가 도구를 요청하면 Bedrock은 Lambda 함수를 호출합니다.
1. **응답 처리**: 표준 인터페이스를 통해 에이전트에 결과가 반환됩니다.
**1단계: 가장 인기 있는 노래를 가져오도록 Lambda 함수 정의**
MCP 프로토콜을 구현하는 Lambda 함수를 생성합니다. 다음은 간단한 Python 예제입니다.
```
import json
def lambda_handler(event, context):
# Parse JSON-RPC request
method = event.get('method')
params = event.get('params', {})
request_id = event.get('id')
if method == 'tools/list':
return {
"jsonrpc": "2.0",
"id": request_id,
"result": {
"tools": [
{
"name": "my_custom_tool",
"description": "My custom business logic tool",
"inputSchema": {
"type": "object",
"properties": {
"input": {
"type": "string",
"description": "Input text to process"
}
},
"required": ["input"]
}
}
]
}
}
elif method == 'tools/call':
tool_name = params.get('name')
arguments = params.get('arguments', {})
if tool_name == 'my_custom_tool':
# Your custom logic here
result = f"Processed: {arguments.get('input', '')}"
return {
"jsonrpc": "2.0",
"id": request_id,
"result": {
"content": [
{
"type": "text",
"text": result
}
]
}
}
# Error response for unsupported methods
return {
"jsonrpc": "2.0",
"id": request_id,
"error": {
"code": -32601,
"message": "Method not found"
}
}
```
**2단계: Lambda 함수 배포**
그런 다음 IAM 역할을 사용하여이 Lambda 함수를 배포하여 ARN을 가져옵니다. Lambda 함수 배포에 대한 자세한 내용은 여기에서 확인할 수 [있습니다](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html).
```
# Example using AWS CLI
aws lambda create-function \
--function-name my-custom-tool \
--runtime python3.14 \
--role arn:aws:iam::YOUR-ACCOUNT:role/lambda-execution-role \
--handler lambda_function.lambda_handler \
--zip-file fileb://function.zip
```
ARN이 다음과 같다고 가정해 보겠습니다. `arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool`
**3단계: 추론 요청에서 메시지 및 도구 정의 정의**
메시지 및 도구 정의를 보내려면 [응답 API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html) 작업을 사용합니다. Amazon Bedrock은 응답 API의 [커넥터 및 원격 MCP 서버 기능을](https://platform.openai.com/docs/guides/tools-connectors-mcp) 사용하여 도구 사용 기능을 제공합니다. 도구의 정의는 mcp 요청 파라미터에서 생성 작업에 전달하는 JSON 스키마입니다. 응답 커넥터 API의 `connector_id` 필드에서 이전 단계에서 생성한 Lambda ARN을 전달할 수 있습니다. Bedrock은 모델을 호출하는 애플리케이션에 사용되는 것과 동일한 IAM 역할 및 정책을 사용하므로 권한 부여 자격 증명을 제공할 필요가 없습니다. 다음은 라디오 방송국에서 재생되는 가장 인기 있는 노래를 가져오는 도구의 예제 스키마입니다.
```
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="oss-gpt-120b",
tools=[
{
"type": "mcp",
"server_label": "xamzn_arn",
"connector_id": "arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool",
"require_approval": "never",
},
],
input="My custom prompt.",
)
print(resp.output_text)
```
**4단계: Bedrock이 도구를 호출하고 응답을 모델에 다시 전달합니다.**
커넥터 도구 사용 기능은 [응답 API를 지원하는 모델에서 사용할 수 있습니다](https://platform.openai.com/docs/api-reference/responses/create). [여기에서](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html) 모델을 지원하는 도구를 확인하세요. 응답 API를 사용하여 도구를 사용하는 경우 도구 정의를 가져오거나 도구를 호출할 때 사용된 [토큰](https://platform.openai.com/docs/pricing)에 대해서만 비용을 지불합니다. 도구 호출당 추가 요금은 없습니다.
`tools` 파라미터에서 Lambda 함수를 지정하면 API는 서버에서 도구 목록을 가져오려고 시도합니다. 도구 목록을 성공적으로 검색하면 모델 응답 `mcp_list_tools` 출력에 새 출력 항목이 나타납니다. 이 객체의 `tools` 속성에는 성공적으로 가져온 도구가 표시됩니다. 모델이 이러한 도구 정의에 액세스할 수 있게 되면 모델 컨텍스트의 내용에 따라 이를 호출하도록 선택할 수 있습니다. 모델이 Lambda 도구를 호출하기로 결정하면 API는 Lambda 함수에 요청하여 도구를 호출하고 출력을 모델의 컨텍스트에 넣습니다. [OpenAI 설명서](https://platform.openai.com/docs/guides/tools-connectors-mcp?quickstart-panels=connector)의 목록 도구 및 호출 도구에 대해 자세히 알아볼 수 있습니다. Lambda 함수에는 Bedrock에서 모델을 호출하는 애플리케이션과 동일한 IAM 역할 및 정책이 연결되어 있어야 합니다. 그렇지 않으면 Lambda 함수가 실패합니다. 다음은 오류 정의입니다.
```
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32000,
"message": "Tool execution failed",
"data": "Additional error details"
}
}
```
**응답 API에서 AWS 제공 도구 사용**
Bedrock에는 메모 작성 기능(노트 도구)과 작업 관리(작업 도구)라는 두 가지 AWS 제공 도구가 있습니다. 둘 다 자세히 살펴보겠습니다.
**참고 도구 개요**
`notes` 도구를 사용하면 동일한 대화 세션 내에 키-값 페어를 저장하고 검색할 수 있습니다. 이는 여러 상호 작용에서 컨텍스트를 유지하기 위한 간단한 메모리 메커니즘을 제공합니다. 키는 대소문자를 구분하는 문자열이며 키 길이 또는 이름 지정 규칙에 제한이 없습니다. 시스템은 동일한 키의 이전 값을 덮어씁니다. 값은 문자열(JSON, URLs 등)로 저장되며 도구 수준에서 적용되는 크기 제한은 없습니다. 값은 전체 대화 세션을 통해 유지됩니다. 메모리는 현재 대화로만 범위가 지정됩니다.
**파라미터**
| 파라미터 | Type | 필수 | 설명 |
| --- | --- | --- | --- |
| operation | 문자열 | 예 | 수행할 작업: "store" 또는 "recall" |
| key | 문자열 | 예 | 메모리 항목의 키 식별자입니다. |
| value | 문자열 | 조건부 | 저장할 값("store"작업에만 필요) |
**유효한 작업**
+ **`store`**: 키-값 페어를 메모리에 저장
+ **`recall`**: 키로 값 검색
자연어(예: "좋아하는 색상이 파란색이라고 기억하세요", "좋아하는 색상에 대해 무엇을 말했나요?", "아침 회의를 선호한다는 사실을 저장하세요", "회의 기본 설정에 대해 말한 내용을 기억하세요")를 사용하거나 프롬프트에서 직접 도구 호출을 사용할 수 있습니다("메모 도구를 사용하여 내 이메일을 john@example.com으로 저장하세요", "이메일 주소에 대한 메모 확인").
**작업 도구 개요**
도구는 대화 세션 내에서 작업을 관리하기 위한 LIFO(Last-In-First-Out) 스택을 `tasks` 제공합니다. 이렇게 하면 태스크를 스택에 푸시하고 역순으로 팝업할 수 있으므로 중첩된 워크플로, 임시 알림 또는 계층적 태스크 관리를 관리하는 데 적합합니다. 작업은 전체 대화 세션 동안 지속됩니다. 스택 상태는 여러 상호 작용에서 유지됩니다. 메모리는 현재 대화로만 범위가 지정됩니다.
| 파라미터 | Type | 필수 | 설명 |
| --- | --- | --- | --- |
| operation | 문자열 | 예 | 수행할 작업: "push" 또는 "pop" |
| description | 문자열 | 조건부 | 작업 항목에 대한 설명("push"작업에만 필요) |
| summary | 문자열 | No | 작업 항목에 대한 선택적 요약("push"작업에만 해당) |
자연어(예: '예산을 검토하기 위해 작업 추가', '클라이언트를 호출하기 위해 미리 알림 푸시', '다음 작업은 해야 합니까?', '최신 작업 건너뛰기', ' 스택에서 최신 작업 가져오기')를 사용하여 작업 도구를 호출하거나 프롬프트에서 직접 도구를 호출할 수 있습니다('작업 도구를 사용하여 '완료 프레젠테이션' 푸시', '스택에서 작업 건너뛰기', '작업 목록에 회의 예약' 추가').
## AgentCore Gateway와의 서버 측 도구 사용 통합
Amazon Bedrock은 이제 통합 유형을 호출하는 서버 측 도구로 [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html)를 지원합니다. 이 기능을 사용하면 모델을 AgentCore Gateway 엔드포인트에 직접 연결하여 게이트웨이 인프라를 통해 관리되는 도구에 원활하게 액세스할 수 있습니다.
AgentCore Gateway 통합은 Lambda 함수 통합과 동일한 패턴을 따르며 한 가지 주요 차이점이 있습니다.
**Lambda 통합:**
+ Lambda 함수 ARNs 사용
+ AWS Lambda 함수를 직접 호출합니다.
**AgentCore 게이트웨이 통합:**
+ AgentCore 게이트웨이 ARNs 사용
+ AgentCore Gateway 인프라를 통해 도구 호출 라우팅
+ 중앙 집중식 도구 관리 및 검색 제공
### 구성
**요청 구조**
AgentCore Gateway를 도구 소스로 구성할 때는 응답 API 요청의 `tools` 배열에 다음 구조를 사용합니다.
```
{
"type":"mcp",
"server_label":"agentcore_tools",
"connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp",
"server_description":"AgentCore Gateway providing custom tools",
"require_approval":"never"
}
```
**파라미터**
| 파라미터 | Type | 필수 | 설명 |
| --- | --- | --- | --- |
| type | 문자열 | 예 | mcp로 설정해야 합니다. |
| server\$1label | 문자열 | 예 | 요청 내이 도구 커넥터의 고유 식별자 |
| connector\$1id | 문자열 | 예 | AgentCore 게이트웨이의 ARN |
| server\$1description | 문자열 | No | 이 게이트웨이에서 제공하는 도구에 대한 사람이 읽을 수 있는 설명 |
| require\$1approval | 문자열 | 예 | 필드는 여야 합니다. "never" |
**요청 완료 예제**
```
{
"model":"openai.gpt-oss-120b",
"stream":true,
"background":false,
"store":false,
"tools": [
{
"type":"mcp",
"server_label":"agentcore_tools",
"connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp",
"server_description":"AgentCore Gateway providing custom tools",
"require_approval":"never"
}
],
"input": [
{
"type":"message",
"role":"user",
"content": [
{
"type":"input_text",
"text":"What is the weather in Seattle?"
}
]
}
]
}
```
### 사전 조건
AgentCore Gateway 통합을 사용하기 전에 다음이 있는지 확인합니다.
1. 구성된 대상(Lambda 함수, API **Gateway 단계, OpenAPI 스키마 또는 MCP 서버)이 있는 AgentCore Gateway를 생성했습니다**. OpenAPI
1. Bedrock 서비스 역할이 게이트웨이를 호출할 수 있도록 **IAM 권한을 구성했습니다**. Bedrock은 IAM 인증을 사용하는 게이트웨이만 지원합니다.
1. 올바른 형식의 **게이트웨이 ARN**
### AgentCore Gateway 통합의 이점
+ **중앙 집중식 도구 관리**: 단일 게이트웨이 엔드포인트를 통해 모든 도구 관리
+ **도구 검색**: 에이전트는 게이트웨이를 통해 사용 가능한 도구를 동적으로 검색할 수 있습니다.
+ **보안**: IAM 및 게이트웨이 정책을 통한 기본 제공 인증 및 권한 부여
+ **관찰성**: 도구 호출의 포괄적인 모니터링 및 로깅
+ **유연성**: 여러 대상 유형(Lambda, API Gateway, OpenAPI, MCP 서버) 지원
### IAM 권한
Bedrock 실행 역할에는 AgentCore 게이트웨이를 호출할 수 있는 권한이 필요합니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeGateway"
],
"Resource": "arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp"
}
]
}
```
### 다음 단계
+ [AgentCore 게이트웨이 생성에](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-create.html) 대해 자세히 알아보기
+ [게이트웨이 대상 유형](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-targets.html) 탐색
+ [게이트웨이 보안 모범 사례](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-security.html) 검토