# 전체 요청 스키마
요청 스키마는 Invoke API(스트리밍 및 비스트리밍)와 Converse API 간에 거의 동일합니다. 이미지 및 비디오 페이로드 인코딩과 관련된 미묘한 차이가 있습니다. Amazon Nova Micro는 이미지 또는 비디오를 입력으로 지원하지 않으므로 요청 스키마의 해당 부분은 Amazon Nova Micro에 적용되지 않습니다. 그렇지 않으면 요청 스키마는 모든 Amazon Nova 이해 모델에 대해 동일합니다.
**중요**
Amazon Nova에 대한 추론 직접 호출의 제한 시간은 60분입니다. 기본적으로 AWS SDK 클라이언트는 1분 후에 시간 초과됩니다. AWS SDK 클라이언트의 읽기 제한 시간을 최소 60분으로 늘리는 것이 좋습니다. 예를 들어 AWS Python botocore SDK에서 [botocore.config](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#)의 `read_timeout`필드 값을 3600 이상으로 변경합니다.
```
client = boto3.client(
"bedrock-runtime",
region_name="us-east-1",
config=Config(
connect_timeout=3600, # 60 minutes
read_timeout=3600, # 60 minutes
retries={'max_attempts': 1}
)
)
```
```
{
"system": [
{
"text": "string"
}
],
"messages": [
{
"role": "user", //first turn should always be the user turn
"content": [
{
"text": "string"
},
{
"image": {
"format": "jpeg" | "png" | "gif" | "webp",
"source": {
"bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
}
}
},
{
"video": {
"format": "mkv" | "mov" | "mp4" | "webm" | "three_gp" | "flv" | "mpeg" | "mpg" | "wmv",
"source": {
// Option 1: Sending a S3 location
"s3Location": {
"uri": "string", // example: s3://my-bucket/object-key
"bucketOwner": "string" // (Optional) example: "123456789012"
},
// Option 2: Sending file bytes
"bytes": video // Binary array (Converse API) or Base64-encoded string (Invoke API)
}
}
},
{
"audio": {
"format": "mp3" | "opus" | "wav" | "aac" | "flac" | "mp4" | "ogg" | "mkv",
"source": {
// Option 1: Sending a S3 location
"s3Location": {
"uri": "string", // example: s3://my-bucket/object-key
"bucketOwner": "string" // (Optional) example: "123456789012"
},
// Option 2: Sending file bytes
"bytes": audio // Binary array (Converse API) or Base64-encoded string (Invoke API)
}
}
}
]
},
{
"role": "assistant",
"content": [
{
"text": "string" //prefilling assistant turn
}
]
}
],
"inferenceConfig":{ // all Optional, Invoke parameter names used in this example
"maxTokens": int, // greater than 0, equal or less than 5k (default: dynamic*)
"temperature": float, // greater than 0 and less than 1.0 (default: 0.7)
"topP": float, // greater than 0, equal or less than 1.0 (default: 0.9)
"topK": int, // 0 or greater (default: 50)
"stopSequences": ["string"],
"reasoningConfig": {
"type": "string", //"enabled"/"disabled" (default: "disabled")
"maxReasoningEffort": "string" // "low", "medium", "high"
}
},
"toolConfig": { // all Optional
"tools": [
{
"toolSpec": {
"name": "string", //meaningful tool name (Max char: 64)
"description": "string", //meaningful description of the tool
"inputSchema": {
"json": { // The JSON schema for the tool. For more information, see JSON Schema Reference
"type": "object",
"properties": {
"arg1": { //arguments
"type": "string", //argument data type
"description": "string" //meaningful description
}
},
"required": [
"string" //args
]
}
}
}
}
],
},
"toolChoice": { //can select one of three options
"auto": {},
"any": {},
"tool": {
"name": "string" //name of tool
}
}
}
```
다음은 필수 파라미터입니다.
+ `system` – (선택 사항) 요청에 대한 시스템 프롬프트입니다.
시스템 프롬프트는 특정 목표 또는 역할을 지정하는 것과 같이 Amazon Nova에 컨텍스트와 지침을 제공하는 방법입니다.
+ `messages` – (필수) 입력 메시지입니다.
+ `role` - 대화 턴의 역할입니다. 유효 값은 `user` 및 `assistant`입니다.
+ `content` – (필수) 대화 내용을 포함하는 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 객체의 목록입니다. 각 객체에는 콘텐츠 유형(`text`, `image`, `video` 또는 `audio`)을 지정하는 키가 포함되어 있습니다. 해당 객체의 값은 키 유형에 따라 달라집니다. 다음 키 유형이 지원됩니다.
+ `text` - 단일 필드 `text`를 포함하는 객체로 매핑되며, 이 필드의 값은 대화의 해당 턴에서 사용할 텍스트 프롬프트입니다. 대화 턴에 `image` 또는 `video` 객체가 포함된 경우, `text` 객체는 이미지 또는 비디오에 동반되는 텍스트 프롬프트로 해석됩니다.
+ `image` – (Amazon Nova Micro에서는 지원되지 않음) 이미지 콘텐츠를 나타내는 객체로 매핑되며, 다음 필드를 포함합니다.
+ `format` – (필수) 이미지 형식입니다. 다음 이미지 형식을 지정할 수 있습니다.
+ `jpeg`
+ `png`
+ `webp`
+ `gif`
+ `source` – (필수) 이미지 데이터입니다. Invoke API의 경우 Base64로 인코딩된 이미지 문자열이어야 합니다. Converse API의 경우 바이트 배열이어야 합니다.
+ `bytes` – (필수) 이미지 데이터입니다. Invoke API의 경우 Base64로 인코딩된 이미지 문자열이어야 합니다. Converse API의 경우 바이트 배열이어야 합니다.
+ `video` – (Amazon Nova Micro에서는 지원되지 않음) 비디오 콘텐츠를 나타내는 객체로 매핑되며, 다음 필드를 포함합니다.
+ `format` – (필수) 비디오 형식입니다. 다음 값을 지정할 수 있습니다.
+ `mkv`
+ `mov`
+ `mp4`
+ `webm`
+ `three_gp`
+ `flv`
+ `mpeg`
+ `mpg`
+ `wmv`
+ `source` – (필수) 비디오 데이터의 소스입니다. 요청에서 Amazon S3 URI 또는 비디오 파일 바이트를 지정할 수 있습니다.
+ `uri` – (필수) 비디오 파일의 Amazon S3 URI입니다. 예: `“s3://my-bucket/object-key”`
+ `bucketOwner` - (선택 사항) 버킷을 소유한 계정 ID입니다. 별도의 계정에서 모델을 간접적으로 호출하는 경우 사용합니다.
+ `bytes` – (필수) 비디오 데이터입니다. Invoke API의 경우 Base64로 인코딩된 비디오 문자열이어야 합니다. Converse API의 경우 바이트 배열이어야 합니다.
+ `audio` – (전용) 오디오 콘텐츠를 나타내고 다음 필드를 포함하는 객체에 매핑합니다.
+ `format` – (필수) 오디오 형식입니다. 다음 값을 지정할 수 있습니다.
+ `aac`
+ `flac`
+ `mkv`
+ `mp3`
+ `mp4`
+ `ogg`
+ `opus`
+ `wav`
+ `source` – (필수) 오디오 데이터의 소스입니다. 요청에서 Amazon S3 URI 또는 오디오 파일 바이트를 지정할 수 있습니다.
+ `uri` – (필수) 오디오 파일의 Amazon S3 URI입니다. 예: `"s3://my-bucket/object-key"`
+ `bucketOwner` - (선택 사항) 버킷을 소유한 계정 ID입니다. 별도의 계정에서 모델을 간접적으로 호출하는 경우 사용합니다.
+ `bytes` – (필수) 오디오 데이터입니다. Invoke API의 경우 Base64로 인코딩된 오디오 문자열이어야 합니다. Converse API의 경우 바이트 배열이어야 합니다.
+ `inferenceConfig:` 추론에 전달될 수 있는 추론 구성 값입니다.
+ `maxTokens` – (선택 사항) 중지하기 전에 생성할 최대 토큰 수입니다.
참고로 Amazon Nova 모델은 `maxTokens` 값에 도달하기 전에 토큰 생성을 중지할 수 있습니다. 허용되는 최대 새 토큰 값은 5,000입니다.
+ `temperature` – (선택 사항) 응답에 주입되는 무작위성의 양입니다. 유효한 값은 0.00001에서 1 사이입니다. 기본 값은 0.7입니다.
+ `topP` – (선택 사항) nucleus 샘플링을 사용합니다.
Amazon Nova는 각 후속 토큰의 모든 옵션에 대한 누적 분포를 확률 내림차순으로 계산하고 `topP`에서 지정한 특정 확률에 도달하면 이를 차단합니다. `temperature` 또는 `topP`를 변경해야 하지만, 둘 다 변경해서는 안 됩니다. 유효한 값은 0에서 1 사이입니다. 기본값은 0.9입니다.
+ `topK` – (선택 사항) 각 후속 토큰에 대해 상위 K개 옵션에서만 샘플을 추출합니다.
`topK` 파라미터를 사용하여 롱 테일 낮은 확률 응답을 제거합니다. 유효한 값은 0에서 128 사이입니다. 기본값은 이 파라미터가 사용되지 않는 것입니다.
**참고**
`topK` 파라미터와 함께 Converse API를 사용하는 경우 `additionalModelRequestFields` 필드에 추가 `inferenceConfig` 파라미터를 포함해야 합니다. 이러한 파라미터가 전달되는 방법의 예제는 [Converse API 사용](using-converse-api.md) 섹션을 참조하세요.
+ `stopSequences` – (선택 사항) 중지 시퀀스가 포함된 문자열의 배열입니다. 모델이 이러한 문자열을 생성하면 생성이 중지되고 해당 시점까지 응답이 반환됩니다.
+ `reasoningConfig` – (Amazon Nova Pro 및 Amazon Nova Lite만 해당) 추론에서 전달할 수 있는 추론 구성 값입니다.
+ `type` - (선택 사항) 추론을 활성화할지 또는 비활성화할지 여부입니다. 유효한 옵션은 `enabled` 또는 `disabled`입니다. 기본값은 `disabled`입니다.
+ `maxReasoningEffort` - 추론 프로세스에 사용되는 계산 작업입니다. 유효한 옵션은 `low`, `medium`, `high`입니다. 스트리밍에서 `low` 및 `medium` 설정을 사용하는 경우, `ConverseStream` 사용 시 각 토큰이 생성될 때 추론 콘텐츠가 스트리밍되지만, `high`는 다르게 작동하여 품질을 개선하기 위한 다양한 접근 방식을 적용해 모든 추론 콘텐츠를 최종 청크에 출력합니다.
**참고**
`reasoningConfig` 파라미터와 함께 Converse API를 사용하는 경우 파라미터를 `additionalModelRequestFields` 필드에 배치해야 합니다. 이러한 파라미터가 전달되는 방법의 예제는 [Converse API 사용](using-converse-api.md) 섹션을 참조하세요.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/nova/latest/userguide/complete-request-schema.html)
+ `toolConfig` – (선택 사항) 도구 사양과 도구 선택을 포함하는 [ToolConfig 스키마](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html)를 따르는 JSON 객체입니다. 이 스키마는 [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)에서 따르는 것과 동일합니다.
+ `toolChoice` – (선택 사항) 모델이 사용할 수 있는 도구를 지정합니다. 다음 세 가지 옵션 중 하나를 선택할 수 있습니다.
+ `auto` - 모델은 도구를 사용할지 여부 및 사용할 도구를 자동으로 결정합니다.
+ `any` - 모델은 제공된 도구 중 하나 이상을 사용해야 합니다.
+ `tool` - 모델은 이름으로 식별되는 특정 도구를 사용해야 합니다.
# 응답 구조 하이라이트
다음은 비스트리밍 `Converse` 및 `InvokeModel` 함수에서 반환되는 응답 구조의 주요 요소를 보여줍니다. 전체 응답 구조와 스트리밍 함수의 요청 및 응답 구조에 대한 자세한 내용은 API 설명서를 참조하세요.
```
{
"ResponseMetadata": {
"RequestId": string,
"HTTPStatusCode": int,
"HTTPHeaders": {
"date": string,
"content-type": "application/json",
"content-length": string,
"connection": "keep-alive",
"x-amzn-requestid": string
},
"RetryAttempts": 0
},
"output": {
"message": {
"role": "assistant",
"content": [
{ // Optional
"reasoningContent": {
"reasoningText": {
"text": string
}
}
},
{ // Optional
"toolUse": {
"toolUseId": string,
"name": string,
"input": object
}
},
{ // Optional
"text": string
},
{ // Optional
"image": {
"format": "png",
"source": {
"bytes": {
"bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
}
}
}
}
]
}
},
"stopReason": string, // "end_turn" | "content_filtered" | "max_tokens" | "malformed_model_output" | "malformed_tool_use" | etc.
"usage": {
"inputTokens": int,
"outputTokens": int,
"totalTokens": int
},
"metrics": {
"latencyMs": int
}
}
```
다음은 핵심 응답 요소입니다.
+ `output` – (필수) 모델의 응답 메시지를 포함합니다.
+ `message` – (필수) 어시스턴트의 응답 메시지입니다.
+ `content` – (필수) 다음을 포함할 수 있는 하나 이상의 콘텐츠 블록 배열입니다.
+ `reasoningContent` – (선택 사항) 추론이 활성화된 경우 반환됩니다. 항상 응답에서 `[REDACTED]`인 추론 텍스트를 포함합니다.
+ `toolUse` – (선택 사항) 도구가 호출된 경우 반환됩니다. 도구 사용 ID, 이름 및 입력 인수를 포함합니다.
+ `text` – (선택 사항) 모델이 텍스트 콘텐츠로 응답한 경우 반환됩니다.
+ `image` – (선택 사항, 전용) 모델이 이미지를 생성한 경우 반환됩니다. 형식은 다음에서 생성된 이미지의 경우 항상 PNG입니다.
+ `stopReason` – (필수) 모델이 출력 생성을 중지한 이유를 나타내는 열거형 값입니다. 지원되는 값에는 다음이 포함됩니다.
+ `end_turn` - 턴의 논리적 종료에 도달했습니다.
+ `max_tokens` - 출력이 사용자가 설정한 `maxTokens` 제한 또는 모델의 자체 최대 출력 토큰 제한에 도달했습니다.
+ `content_filtered` - 모델의 출력이 AWS 책임 있는 AI 정책을 위반했습니다.
+ `malformed_model_output` - 모델이 잘못된 출력을 생성했습니다.
+ `malformed_tool_use` - 모델이 잘못된 `toolUse` 출력을 생성했습니다.
+ `service_unavailable` - 기본 제공 도구 서비스 중 하나가 연결되지 않습니다.
+ `invalid_query` - 모델이 기본 제공 Web Grounding 도구로 전송한 쿼리가 잘못되었습니다.
+ `max_tool_invocations` - 기본 제공 도구가 호출되었지만 여러 번의 재시도 후에도 유효한 결과를 생성하지 않았음을 나타냅니다.
+ `usage` - (필수) 입력 토큰, 출력 토큰 및 총 토큰을 포함한 토큰 사용 정보입니다.
+ `metrics` - (필수) 밀리초 단위의 총 추론 지연 시간을 포함한 성능 지표입니다.