# Amazon Nova에 대한 멀티모달 지원
**참고**
이 설명서는 Amazon Nova 버전 1용입니다. Amazon Nova 2 멀티모달 설명서는 [멀티모달 이해](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-multimodal-models.html)를 참조하세요.
Amazon Nova 이해 모델은 멀티모달 이해 모델로, 이미지, 비디오, 문서 등의 멀티모달 입력을 지원하여 제공된 콘텐츠를 기반으로 질문을 추론하고 답할 수 있습니다. Amazon Nova 모델에는 모델이 이미지, 문서, 비디오를 이해하고 분석할 수 있는 새로운 비전 기능이 탑재되어 있어 멀티모달 이해 사용 사례를 실현할 수 있습니다.
다음 섹션에서는 Amazon Nova에서 이미지, 문서, 비디오 작업에 대한 지침을 간략하게 설명합니다. 여기에는 사용된 전처리 전략, 코드 예제, 고려해야 할 관련 제한 사항이 포함됩니다.
**Topics**
+ [모달별로 지원되는 콘텐츠 유형](#modalities-content)
+ [이미지 이해](modalities-image.md)
+ [비디오 이해](modalities-video.md)
+ [문서 이해](modalities-document.md)
+ [오류 처리](text-error-handing.md)
## 모달별로 지원되는 콘텐츠 유형
다음 정보는 미디어 파일에서 지원하는 파일 형식과 허용되는 입력 방법을 자세히 설명합니다.
| 미디어 파일 유형 | 지원되는 파일 형식 | **입력 방법** | 구문 분석 전략 |
| --- |--- |--- |--- |
| 이미지 | PNG, JPG, JPEG, GIF, WebP | Base64 Amazon S3 URI | 이미지 비전 이해 |
| 텍스트 문서 *(Converse API만 해당)* | CSV, XLS, XLSX, HTML, TXT, MD, DOC | 바이트 Amazon S3 URI | 문서의 텍스트 이해만 |
| 미디어 문서 *(Converse API만 해당)* | PDF, DOCX | 바이트 Amazon S3 URI | 텍스트와 인터리브 이미지 이해 |
| 비디오 | MP4, MOV, MKV, WebM, FLV, MPEG, MPG, WMV, 3GP | Base64 Amazon S3 URI | 비디오 비전 이해 |
**참고**
컴퓨터에서 파일 최대 5개 또는 Amazon S3에서 파일 1,000개를 포함할 수 있습니다. Amazon S3에서 업로드할 때 각 파일은 1GB 이하여야 합니다. 업로드된 파일의 총 크기는 컴퓨터에서 업로드할 때 25MB를, Amazon S3에서 업로드할 때 2GB를 초과할 수 없습니다.
전체 페이로드 한도가 25MB이므로 base64 오버헤드를 고려해야 합니다. 작업하는 동안 라이브러리와 프레임워크가 메모리를 유지 관리하며 전달된 미디어 콘텐츠가 빠르게 늘어날 수 있다는 점을 기억하세요. 비디오를 사용할 때 `s3Location`을 지정하면 많은 스토리지 문제가 해결됩니다.
**참고**
입력 방법에 관계없이 대용량 비디오와 문서를 처리하는 데는 시간이 걸립니다. Amazon Bedrock의 응답을 기다리는 동안 boto3 SDK가 시간 초과되는 경우 적절한 [read\$1timeout](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html) 값이 설정되고 boto3가 버전 1.38 이상으로 업그레이드되어 있는지 확인하세요.
# 이미지 이해
**참고**
이 설명서는 Amazon Nova 버전 1용입니다. Amazon Nova 2 이미지 이해 가이드는 [이미지 이해](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-multimodal-models.html#image-understanding)를 참조하세요.
Amazon Nova 모델을 사용하면 페이로드에 여러 이미지를 포함할 수 있으며 총 페이로드 크기는 25MB로 제한됩니다. 그러나 이미지 이해를 위해 이미지가 포함된 Amazon S3 URI를 지정할 수 있습니다. 이 접근 방식을 사용하면 25MB 페이로드 제한의 제약 없이 더 큰 이미지와 더 많은 이미지에 모델을 활용할 수 있습니다. Amazon Nova 모델은 전달된 이미지를 분석하고 질문에 답하고, 이미지를 분류하고, 제공된 지침에 따라 이미지를 요약할 수 있습니다.
## 이미지 크기 정보
최상의 결과를 제공하기 위해 Amazon Nova는 가로 세로 비율과 원래 해상도에 따라 입력 이미지를 다시 스케일 업하거나 스케일 다운할 수 있습니다. 각 이미지에 대해 Amazon Nova는 먼저 1:1, 1:2, 1:3, 1:4, 1:5, 1:6, 1:7, 1:8, 1:9 2:3, 2:4 중 가장 가까운 가로 세로 비율과 해당 전치를 식별합니다. 그런 다음 가장 가까운 가로 세로 비율을 유지하면서 이미지의 한 면 이상이 896px 또는 원본 이미지의 짧은 면의 길이보다 커지도록 이미지가 다시 스케일됩니다. 최대 해상도는 8,000x8,000픽셀입니다.
## 경계 상자 감지
Amazon Nova Lite 및 Amazon Nova Pro 모델은 이미지 내의 경계 상자를 정확하게 감지하도록 훈련되었습니다. 이 기능은 관심 있는 특정 객체의 좌표를 얻는 것이 목적일 때 유용할 수 있습니다. Amazon Nova 모델은 경계 상자 감지 기능 덕분에 이미지 근거 태스크에 적합하며 이를 통해 스크린샷에 대한 이해를 높일 수 있습니다. Amazon Nova 모델은 [0, 1000)의 스케일로 경계 상자를 출력하며, 이러한 좌표를 얻은 후에는 후처리 단계로 이미지 치수에 따라 크기를 조정할 수 있습니다.
## 이미지에서 토큰으로 변환
앞서 설명한 것처럼 이미지 크기는 가로 세로 비율을 유지하면서 정보 추출을 극대화하도록 조정됩니다. 다음은 샘플 이미지 치수와 근사 토큰 계산의 몇 가지 예제입니다.
| image\$1resolution(HxW 또는 WxH) | 900 x 450 | 900 x 900 | 1400 x 900 | 1800 x 900 | 1300 x 1300 |
| --- |--- |--- |--- |--- |--- |
| 예상 토큰 수 | \$1800 | \$11,300 | \$11,800 | \$12,400 | \$12,600 |
예를 들어, 크기가 800x400인 이미지가 있다고 가정하고, 이 이미지의 토큰 수를 추정해 보려고 합니다. 치수를 기준으로 가로 세로 비율을 1:2로 유지하기 위해 가장 가까운 해상도는 900x450입니다. 따라서 이 이미지의 대략적인 토큰 수는 약 800개입니다.
# 이미지 이해 제한 사항
Amazon Nova의 다음 제한 사항을 숙지하세요.
+ **다국어 이미지 이해:** 모델은 다국어 이미지 및 비디오 프레임에 대한 이해도가 제한적이며, 유사한 태스크에서 어려움을 겪거나 할루시네이션이 발생할 수 있습니다.
+ **사람 식별**: Amazon Nova 모델은 이미지, 문서 또는 비디오에서 개인을 식별하거나 이름을 지정하는 기능을 지원하지 않습니다. 모델은 이러한 태스크 수행을 거부합니다.
+ **공간 추론**: Amazon Nova 모델은 공간 추론 기능이 제한적입니다. 따라서 정밀한 현지화 또는 레이아웃 분석이 필요한 태스크에서 어려움을 겪을 수 있습니다.
+ **이미지/비디오의 작은 텍스트**: 이미지 또는 비디오의 텍스트가 너무 작은 경우, 필요한 맥락을 유지하면서 관련 섹션으로 잘라내어 이미지의 텍스트 상대 크기를 늘리는 것을 고려하세요.
+ **수 계산**: Amazon Nova 모델은 이미지 내 객체의 대략적인 개수를 제공할 수 있지만, 특히 작은 개체가 많은 경우 정확하지 않을 수 있습니다.
+ **부적절한 콘텐츠**: Amazon Nova 모델은 이용 정책을 위반하는 부적절하거나 노골적인 이미지는 처리하지 않습니다.
+ **의료 애플리케이션**: 이러한 아티팩트의 민감한 특성으로 인해 Amazon Nova 모델은 의료 이미지 또는 비디오에 대한 일반적인 분석을 제공할 수 있지만, 복잡한 진단 스캔을 해석하는 것은 권장하지 않습니다. Amazon Nova 응답을 전문적인 의학적 조언을 대체하는 것으로 간주해서는 안 됩니다.
# 이미지 이해 예제
다음 예제에서는 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)을 사용하여 Amazon Nova 모델에 이미지 프롬프트를 전송하는 방법을 보여줍니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
import base64
import boto3
import json
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client(
"bedrock-runtime",
region_name="us-east-1",
)
MODEL_ID = "us.amazon.nova-lite-v1:0"
# Open the image you'd like to use and encode it as a Base64 string.
with open("media/sunset.png", "rb") as image_file:
binary_data = image_file.read()
base_64_encoded_data = base64.b64encode(binary_data)
base64_string = base_64_encoded_data.decode("utf-8")
# Define your system prompt(s).
system_list = [ {
"text": "You are an expert artist. When the user provides you with an image, provide 3 potential art titles"
}
]
# Define a "user" message including both the image and a text prompt.
message_list = [
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
},
}
},
{
"text": "Provide art titles for this image."
}
],
}
]
# Configure the inference parameters.
inf_params = {"maxTokens": 300, "topP": 0.1, "topK": 20, "temperature": 0.3}
native_request = {
"schemaVersion": "messages-v1",
"messages": message_list,
"system": system_list,
"inferenceConfig": inf_params,
}
# Invoke the model and extract the response body.
response = client.invoke_model(modelId=MODEL_ID, body=json.dumps(native_request))
model_response = json.loads(response["body"].read())
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(model_response, indent=2))
# Print the text content for easy readability.
content_text = model_response["output"]["message"]["content"][0]["text"]
print("\n[Response Content Text]")
print(content_text)
```
전체 페이로드가 25MB를 초과하는 대용량 이미지 파일 또는 여러 이미지 파일을 전달하기 위해 Amazon S3를 사용할 수 있습니다. 다음 예제에서는 Amazon S3를 사용하여 Amazon Nova에 이미지를 업로드하는 방법을 보여줍니다.
```
import boto3
import json
import base64
# Create a Bedrock Runtime client
client = boto3.client("bedrock-runtime",
region_name="us-east-1",
)
PRO_MODEL_ID = "us.amazon.nova-pro-v1:0"
LITE_MODEL_ID = "us.amazon.nova-lite-v1:0"
MICRO_MODEL_ID = "us.amazon.nova-micro-v1:0"
PREMIER_MODEL_ID = "us.amazon.nova-premier-v1:0"
messages = [
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"s3Location": {
#Replace the s3 bucket URI
"uri": "s3://demo-bucket/cat.png"
"bucketOwner" : "123456789012"
}
},
}
},
{"text": "Describe the following image"},
],
}
]
inf_params = {"maxTokens": 300, "topP": 0.1, "temperature": 0.3}
model_response = client.converse(
modelId=LITE_MODEL_ID, messages=messages, inferenceConfig=inf_params
)
print("\n[Full Response]")
print(json.dumps(model_response, indent=2))
print("\n[Response Content Text]")
print(model_response["output"]["message"]["content"][0]["text"])
```
# 비디오 이해
**참고**
이 설명서는 Amazon Nova 버전 1용입니다. Amazon Nova 2 동영상 이해 가이드는 [동영상 이해](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-multimodal-models.html#video-understanding)를 참조하세요.
Amazon Nova 모델을 사용하면 base64 형식 또는 Amazon S3 URI를 통해 제공될 수 있는 페이로드에 단일 비디오를 포함할 수 있습니다. base64 메서드를 사용하는 경우 전체 페이로드 크기는 25MB 이내로 유지되어야 합니다. 그러나 비디오 이해를 위해 Amazon S3 URI를 지정할 수 있습니다. 이 접근 방식을 사용하면 전체 페이로드 크기 제한에 구애받지 않고 더 긴 비디오(최대 1GB 크기)에 이 모델을 활용할 수 있습니다. Amazon Nova 모델은 전달된 비디오를 분석하고 질문에 답변하고, 비디오를 분류하고, 제공된 지침에 따라 비디오의 정보를 요약할 수 있습니다.
| 미디어 파일 유형 | 지원되는 파일 형식 | **입력 방법** |
| --- |--- |--- |
| 비디오 | MP4, MOV, MKV, WebM, FLV, MPEG, MPG, WMV, 3GP | Base64 *25MB 미만의 페이로드 크기에 권장됨* |
| | | Amazon S3 URI *25MB 이상, 최대 2GB의 페이로드에 권장됨. 개별 파일은 1GB 이하여야 합니다.* |
비디오가 base64로 전달되는지(크기 제약 조건에 맞는 한) Amazon S3 로케이션을 통해 전달되는지에 관계없이 비디오 입력 토큰 수에는 차이가 없습니다.
3GP 파일 형식의 경우 API 요청에 전달된 ‘형식’ 필드는 ‘three\$1gp’ 형식이어야 합니다.
Amazon S3를 사용할 때 ‘Content-Type’ 메타데이터를 비디오에 대한 올바른 MIME 유형으로 설정해야 합니다.
## 비디오 크기 정보
Amazon Nova 비디오 이해 기능은 다중 가로 세로 비율을 지원합니다. 모든 비디오는 모델에 공급되기 전에 **672\$1672 정사각형** 치수로 왜곡(입력에 따라 위 또는 아래로)을 적용하여 크기가 조정됩니다. 모델은 비디오 길이를 기반으로 하는 동적 샘플링 전략을 활용합니다. Amazon Nova Lite 및 Amazon Nova Pro에서 길이가 16분 이하인 비디오의 경우 1FPS(초당 프레임 수) 샘플링 속도가 사용됩니다. 그러나 길이가 16분을 초과하는 비디오의 경우 샘플링된 프레임 수를 일관되게 960개로 유지하기 위해 샘플링 속도가 감소하며 프레임 샘플링 속도도 그에 따라 달라집니다. 이 접근 방식은 긴 비디오 콘텐츠에 비해 짧은 비디오에 대해 보다 정확한 장면 수준의 비디오 이해를 제공하도록 설계되었습니다. 움직임이 적은 비디오는 1시간 이내로, 움직임이 많은 비디오는 16분 이내로 비디오 길이를 유지하는 것이 좋습니다. Amazon Nova Premier의 경우 1FPS 샘플링 속도가 최대 3,200프레임 한도까지 적용됩니다.
4k 버전의 비디오와 Full HD 버전을 분석할 때 차이가 없어야 합니다. 마찬가지로 샘플링 속도는 최대 1FPS이므로 60FPS 비디오도 30FPS 비디오와 동일한 성능을 발휘해야 합니다. 비디오 크기가 1GB로 제한되므로 필요보다 높은 해상도와 FPS를 사용해도 유익한 효과가 없으며 해당 크기 제한에 맞게 비디오 길이가 제한됩니다. 1GB보다 긴 비디오를 사전 처리할 수 있습니다.
# 비디오 이해 제한 사항
Amazon Nova의 다음 제한 사항을 숙지하세요.
+ **다국어 이미지 이해:** 모델은 다국어 이미지 및 비디오 프레임에 대한 이해도가 제한적이며, 유사한 태스크에서 어려움을 겪거나 할루시네이션이 발생할 수 있습니다.
+ **사람 식별**: Amazon Nova 모델은 이미지, 문서 또는 비디오에서 개인을 식별하거나 이름을 지정하는 기능을 지원하지 않습니다. 모델은 이러한 태스크 수행을 거부합니다.
+ **공간 추론**: Amazon Nova 모델은 공간 추론 기능이 제한적입니다. 따라서 정밀한 현지화 또는 레이아웃 분석이 필요한 태스크에서 어려움을 겪을 수 있습니다.
+ **이미지/비디오의 작은 텍스트**: 이미지 또는 비디오의 텍스트가 너무 작은 경우, 필요한 맥락을 유지하면서 관련 섹션으로 잘라내어 이미지의 텍스트 상대 크기를 늘리는 것을 고려하세요.
+ **수 계산**: Amazon Nova 모델은 이미지 내 객체의 대략적인 개수를 제공할 수 있지만, 특히 작은 개체가 많은 경우 정확하지 않을 수 있습니다.
+ **부적절한 콘텐츠**: Amazon Nova 모델은 이용 정책을 위반하는 부적절하거나 노골적인 이미지는 처리하지 않습니다.
+ **의료 애플리케이션**: 이러한 아티팩트의 민감한 특성으로 인해 Amazon Nova 모델은 의료 이미지 또는 비디오에 대한 일반적인 분석을 제공할 수 있지만, 복잡한 진단 스캔을 해석하는 것은 권장하지 않습니다. Amazon Nova 응답을 전문적인 의학적 조언을 대체하는 것으로 간주해서는 안 됩니다.
## 비디오 토큰
비디오 길이는 생성되는 토큰 수에 영향을 미치는 주요 요인입니다. 대략적인 비용을 계산하려면 예상 비디오 토큰 수에 사용 중인 특정 모델의 토큰당 가격을 곱해야 합니다.
다음 표에는 Amazon Nova Pro, Lite 및 Micro의 비디오 길이당 프레임 샘플링과 토큰 사용률에 대한 몇 가지 근사치가 나와 있습니다.
| video\$1duration | 10초 | 30초 | 16분 | 20분 | 30분 | 45분 | 1시간 | 1시간 30분 |
| --- |--- |--- |--- |--- |--- |--- |--- |--- |
| frames\$1to\$1sample | 10 | 30 | 960 | 960 | 960 | 960 | 960 | 960 |
| sample\$1rate\$1fps | 1 | 1 | 1 | 0.755 | 0.5 | 0.35556 | 0.14 | 0.096 |
| 예상 토큰 수 | 2,880 | 8,640 | 276,480 | 276,480 | 276,480 | 276,480 | 276,480 | 276,480 |
다음 표에는 Amazon Nova Premier의 비디오 길이당 프레임 샘플링과 토큰 사용률에 대한 몇 가지 근사치가 나와 있습니다.
| video\$1duration | 10초 | 30초 | 16분 | 20분 | 30분 | 45분 | 1시간 | 1시간 30분 |
| --- |--- |--- |--- |--- |--- |--- |--- |--- |
| frames\$1to\$1sample | 10 | 30 | 960 | 1200 | 1800 | 2700 | | |
| sample\$1rate\$1fps | 1 | 1 | 1 | 1 | 1 | 1 | | |
| 예상 토큰 수 | 2,880 | 8,640 | 276,480 | 345,600 | 518,400 | 777,600 | | |
다음 표에는 Amazon Nova Lite 1.5의 비디오 길이당 프레임 샘플링과 토큰 사용률에 대한 몇 가지 근사치가 나와 있습니다.
| video\$1duration | 10초 | 30초 | 16분 | 20분 | 30분 | 45분 | 1시간 | 1시간 30분 |
| --- |--- |--- |--- |--- |--- |--- |--- |--- |
| frames\$1to\$1sample | 10 | 30 | 960 | 1200 | 1800 | 2700 | | |
| sample\$1rate\$1fps | 1 | 1 | 1 | 1 | 1 | 1 | | |
| 예상 토큰 수 | 2,880 | 8,640 | 276,480 | 345,600 | 518,400 | 777,600 | | |
# 비디오 이해 제한 사항
다음은 모델 정확도와 성능이 보장되지 않을 수 있는 주요 모델 제한 사항입니다.
+ **요청당 비디오 1개:** 현재 모델은 요청당 비디오 1개만 지원합니다. 일부 프레임워크 및 라이브러리는 메모리를 사용하여 이전 상호 작용을 추적합니다. 이전 컨텍스트에 추가된 비디오가 있을 수 있습니다.
+ **오디오 지원 없음:** 모델은 현재 비디오의 시각적 정보만을 기반으로 비디오 콘텐츠를 처리하고 이해하도록 훈련되어 있습니다. 비디오에 있는 오디오 구성 요소를 분석하거나 이해할 수 있는 기능은 없습니다.
+ **시간적 인과 관계:** 모델은 비디오 진행 과정에서 이벤트 인과 관계에 대한 이해가 제한적입니다. 특정 시점을 가리키는 질문에는 잘 답변하지만 일련의 이벤트를 이해하는 데 의존하는 답변에는 잘 작동하지 않습니다.
+ **다국어 이미지 이해:** 모델은 다국어 이미지와 비디오 프레임에 대한 이해가 제한적입니다. 유사한 태스크에서 어려움을 겪거나 할루시네이션이 발생할 수 있습니다.
+ **사람 식별**: Amazon Nova 모델은 이미지, 문서 또는 비디오에서 개인을 식별하거나 이름을 지정하는 기능을 지원하지 않습니다. 모델은 이러한 태스크 수행을 거부합니다.
+ **공간 추론**: Amazon Nova 모델은 공간 추론 기능이 제한적입니다. 따라서 정밀한 현지화 또는 레이아웃 분석이 필요한 태스크에서 어려움을 겪을 수 있습니다.
+ **이미지 또는 비디오의 작은 텍스트**: 이미지 또는 비디오의 텍스트가 너무 작은 경우, 필요한 컨텍스트를 유지하면서 관련 섹션으로 잘라내어 이미지의 텍스트 상대 크기를 늘리는 것을 고려하세요.
+ **수 계산**: Amazon Nova 모델은 이미지 내 객체의 대략적인 개수를 제공할 수 있지만, 특히 작은 개체가 많은 경우 정확하지 않을 수 있습니다.
+ **부적절한 콘텐츠**: Amazon Nova 모델은 이용 정책을 위반하는 부적절하거나 노골적인 이미지는 처리하지 않습니다.
+ **의료 애플리케이션**: 이러한 아티팩트의 민감한 특성으로 인해 Amazon Nova 모델은 의료 이미지 또는 비디오에 대한 일반적인 분석을 제공할 수 있지만, 복잡한 진단 스캔을 해석하는 것은 권장하지 않습니다. Amazon Nova의 응답은 전문적인 의학적 조언을 대체하는 것으로 간주해서는 안 됩니다.
# 비디오 이해 예제
다음 예제에서는 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)을 통해 Amazon Nova 모델에 비디오 프롬프트를 전송하는 방법을 보여줍니다.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
import base64
import boto3
import json
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client(
"bedrock-runtime",
region_name="us-east-1",
)
MODEL_ID = "us.amazon.nova-lite-v1:0"
# Open the image you'd like to use and encode it as a Base64 string.
with open("media/cooking-quesadilla.mp4", "rb") as video_file:
binary_data = video_file.read()
base_64_encoded_data = base64.b64encode(binary_data)
base64_string = base_64_encoded_data.decode("utf-8")
# Define your system prompt(s).
system_list= [
{
"text": "You are an expert media analyst. When the user provides you with a video, provide 3 potential video titles"
}
]
# Define a "user" message including both the image and a text prompt.
message_list = [
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": video // Binary array (Converse API) or Base64-encoded string (Invoke API)
},
}
},
{
"text": "Provide video titles for this clip."
},
],
}
]
# Configure the inference parameters.
inf_params = {"maxTokens": 300, "topP": 0.1, "topK": 20, "temperature": 0.3}
native_request = {
"schemaVersion": "messages-v1",
"messages": message_list,
"system": system_list,
"inferenceConfig": inf_params,
}
# Invoke the model and extract the response body.
response = client.invoke_model(modelId=MODEL_ID, body=json.dumps(native_request))
model_response = json.loads(response["body"].read())
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(model_response, indent=2))
# Print the text content for easy readability.
content_text = model_response["output"]["message"]["content"][0]["text"]
print("\n[Response Content Text]")
print(content_text)
```
다음 예제에서는 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)을 통해 Amazon S3 로케이션을 사용하여 Amazon Nova에 비디오를 전송하는 방법을 보여줍니다.
```
import base64
import boto3
import json
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client(
"bedrock-runtime",
region_name="us-east-1",
)
MODEL_ID = "us.amazon.nova-lite-v1:0"
# Define your system prompt(s).
system_list = [
{
"text": "You are an expert media analyst. When the user provides you with a video, provide 3 potential video titles"
}
]
# Define a "user" message including both the image and a text prompt.
message_list = [
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://my_bucket/my_video.mp4",
"bucketOwner": "111122223333"
}
}
}
},
{
"text": "Provide video titles for this clip."
}
]
}
]
# Configure the inference parameters.
inf_params = {"maxTokens": 300, "topP": 0.1, "topK": 20, "temperature": 0.3}
native_request = {
"schemaVersion": "messages-v1",
"messages": message_list,
"system": system_list,
"inferenceConfig": inf_params,
}
# Invoke the model and extract the response body.
response = client.invoke_model(modelId=MODEL_ID, body=json.dumps(native_request))
model_response = json.loads(response["body"].read())
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(model_response, indent=2))
# Print the text content for easy readability.
content_text = model_response["output"]["message"]["content"][0]["text"]
print("\n[Response Content Text]")
print(content_text)
```
# 문서 이해
**참고**
이 설명서는 Amazon Nova 버전 1용입니다. Amazon Nova 2 문서 이해 가이드는 [문서 이해](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-multimodal-models.html#document-understanding)를 참조하세요.
Amazon Nova의 문서 이해 기능을 사용하면 프롬프트에 전체 문서(PDF, Word 파일, 스프레드시트 등)를 포함하고 콘텐츠에 대해 질문하거나 요청할 수 있습니다. Nova의 멀티모달 이해 모델(Lite, Pro, Premier)은 이러한 문서 내의 텍스트 및 시각적 요소(예: 차트 또는 테이블)를 모두 해석할 수 있습니다. 이를 통해 질문 답변, 요약, 긴 보고서 또는 스캔 문서 분석과 같은 사용 사례를 지원할 수 있습니다. 주요 기능에는 긴 문서를 위한 초대형 컨텍스트 창(1\$12M 토큰)과 단일 쿼리에서 여러 문서를 처리할 수 있는 기능이 포함됩니다.
Amazon Nova는 문서 입력을 두 가지 유형으로 구분합니다.
+ **텍스트 기반 문서 유형**(예: TXT, CSV, 마크다운, HTML, DOC): 주로 텍스트 콘텐츠에 대해 처리됩니다. Nova는 이러한 문서의 텍스트에서 정보를 이해하고 추출하는 데 중점을 둡니다.
+ **미디어 기반 문서 유형**(예: PDF, DOCX): 이러한 파일에는 복잡한 레이아웃, 이미지, 차트 또는 임베디드 그래픽이 포함될 수 있습니다. 미디어 기반 문서의 경우 Nova는 시각적 요소와 텍스트 요소를 모두 처리합니다. Nova는 비전 기반 이해를 활용하여 문서 텍스트와 함께 차트, 테이블, 다이어그램 또는 스크린샷과 같은 시각적 콘텐츠를 해석합니다.
JPEG2000 및 JBIG2는 Amazon Nova의 PDF 파일에서 지원되지 않습니다.
지원되는 파일 형식에는 일반 텍스트 및 구조화된 텍스트 파일(CSV, TXT), 스프레드시트(XLS/XLSX), HTML/마크다운, Word 문서(DOC/DOCX), PDF 파일과 같은 일반적인 문서 유형이 포함됩니다. 문서 내 이미지의 경우 표준 이미지 형식(PNG, JPG, GIF, WebP)은 처리되지만 특정 이미지 인코딩(CYMK, SVG)이 포함된 PDF는 지원되지 않습니다.
**문서 크기 제한 및 사용 지침**
| 제약 조건 | Limit |
| --- | --- |
| 최대 문서 수 | 요청당 최대 5개의 문서(직접 업로드와 Amazon S3 모두에 적용됨) |
| 텍스트 기반 문서 크기 | 각 텍스트 문서(예: .txt, .csv, .md, .html, .doc)는 ≤ 4.5MB여야 합니다. |
| 미디어 기반 문서 크기 | .pdf 및 .docx 파일의 경우 개별 파일 크기 제한은 없지만 다음과 같습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/nova/latest/userguide/modalities-document.html) |
| 지원되지 않는 PDF 콘텐츠 | CMYK 색상 프로필 또는 SVG 이미지가 포함된 PDF는 지원되지 않습니다. |
# API를 통한 Nova의 문서 이해 사용
문서 QA(질문 답변) 또는 분석에 Amazon Nova를 사용하는 방법을 설명하기 위해 Python의 간단한 예제를 소개합니다. AWS Bedrock API(Boto3 SDK를 통해)를 사용해 PDF 문서를 모델이 답변할 질문과 함께 보냅니다.
```
import base64
import base64
import json
import boto3
# Initialize Bedrock runtime client (adjust region as needed)
client = boto3.client("bedrock-runtime", region_name="us-east-1")
MODEL_ID = "us.amazon.nova-lite-v1:5" # using Nova Lite model in this example
# Read the document file (PDF) in binary mode
with open("my_document.pdf", "rb") as file:
doc_bytes = file.read()
# Construct the conversation messages with document + question
messages = [
{
"role": "user",
"content": [
{
"document": {
"format": "pdf",
"name": "Document1", # neutral name for the document
"source": {
"bytes": doc_bytes # embedding the PDF content directly
}
}
},
{
"text": "Here is a question about the document: ... (your question) ... ?"
}
]
}
]
# Set inference parameters (optional)
inf_params = {"maxTokens": 4000, "topP": 0.1, "temperature": 0.3}
# Invoke the model
response = client.converse(modelId=MODEL_ID, messages=messages, inferenceConfig=inf_params)
# Extract and print the answer
answer_text = response["output"]["message"]["content"][0]["text"]
print(answer_text)
```
입력 파일이 크거나(직접 업로드 한도인 25MB 초과) 파일이 많은 경우 Amazon S3에 저장하고 참조할 수 있습니다. 이렇게 하면 요청을 통해 원시 바이트가 전송되지 않습니다. S3를 사용하는 경우 Bedrock 서비스에 버킷/객체에 액세스할 수 있는 권한이 있는지 확인합니다. 예를 들어 S3의 PDF를 참조하기 위해 문서 소스는 다음과 같이 ‘바이트’ 대신 ‘s3Location’을 사용합니다.
```
messages = [
{
"role": "user",
"content": [
{
"document": {
"format": "pdf",
"name": "Report2023",
"source": {
"s3Location": {
"uri": "s3://your-bucket/path/to/document1.pdf",
"bucketOwner": "123456789012"
}
}
}
},
{
"text": "Summarize the key findings from the Q3 2023 report."
}
]
}
]
```
**참고**
문서 이름에는 영숫자, 하이픈, 괄호, 대괄호만 포함할 수 있습니다.
`name` 필드는 모델이 지침으로 잘못 해석할 여지가 있어 프롬프트 인젝션에 취약합니다. 따라서 중립 이름을 지정하는 것이 좋습니다.
# 오류 처리
오류가 클라이언트에 다시 전달되는 방법은 발생하는 오류 유형에 따라 달라집니다. 이 섹션에서는 Amazon Nova 모델에 고유한 오류 조건에만 중점을 둡니다. 애플리케이션 코드에서 처리하려는 세 가지 주요 유형의 오류는 **입력 검증** 오류, **책임 있는 AI(RAI) 입력 편향** 오류, **RAI 출력 편향** 오류입니다.
**입력 검증:** 입력 파라미터에 지원되지 않는 값을 사용하면 입력 검증 오류가 발생합니다. 온도 값이 범위를 벗어나거나 입력 `image`의 형식이 올바르지 않은 경우를 예로 들 수 있습니다. 모든 입력 검증 오류는 문제의 원인을 설명하는 메시지 문자열이 포함된 **ValidationException**으로 표현됩니다.
**RAI 입력 편향** 오류는 입력 텍스트 값 또는 이미지가 AWS 책임 있는 AI 정책을 위반하는 것으로 판단될 때 발생합니다. 이러한 오류는 다음 메시지 중 하나와 함께 **ValidationException**으로 표시됩니다.
+ **입력 텍스트** 검증 메시지: ‘이 요청은 콘텐츠 필터에 의해 차단되었습니다. 새 요청을 제출하려면 텍스트 프롬프트를 조정하세요.’
+ **입력 이미지** 검증 메시지: ‘이 요청은 콘텐츠 필터에 의해 차단되었습니다. 새 요청을 제출하려면 입력 이미지를 조정하세요.’
+ **입력 비디오** 검증 메시지: ‘이 요청은 콘텐츠 필터에 의해 차단되었습니다. 새 요청을 제출하려면 입력 비디오를 조정하세요.’
RAI 출력 편향 오류는 출력이 생성되었지만 AWS 책임 있는 AI 정책에 부합하지 않는 것으로 판단될 때 발생합니다. 이 경우 예외가 사용되지 않습니다. 대신 성공적인 응답이 반환되며, 그 구조에는 다음 값 중 하나를 갖는 문자열인 `error` 필드가 포함됩니다.
+ **출력 텍스트** 검증 메시지: ‘생성된 텍스트가 콘텐츠 필터에 의해 차단되었습니다.’