# 추론 컨테이너 기능
Amazon Nova SageMaker 추론 컨테이너에는 추론 중에 모델 동작을 사용자 지정할 수 있는 기능 세트가 포함되어 있습니다. 각 기능은 특정 컨테이너 버전에 도입되고 활성화하려면 환경 변수, 요청 파라미터 또는 두 가지 모두 필요할 수 있습니다.
이 페이지에서는 추론 컨테이너에서 사용할 수 있는 기능이 나열되고, 각 기능을 활성화하는 방법이 설명되어, 기능이 도입된 컨테이너 버전이 나와 있습니다. 이 참고 자료를 사용하여 배포에 사용할 수 있는 기능과 이를 구성하는 방법을 결정하세요.
환경 변수를 통해 활성화된 기능은 SageMaker 모델 또는 엔드포인트 구성을 생성할 때 설정됩니다. [CreateModel](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_CreateModel.html) API 직접 호출의 `Environment` 파라미터에 포함합니다. 요청 파라미터를 통해 활성화된 기능은 요청 본문의 간접 호출별로 설정됩니다.
**참고**
항상 최신 컨테이너 이미지를 사용하여 사용 가능한 모든 기능에 액세스할 수 있습니다. `SM-Inference-latest` 태그는 현재 `v1.4`를 가리킵니다.
## 변수 요약
다음 표에서는 Amazon Nova SageMaker 추론 컨테이너에서 지원되는 모든 기능을 빠르게 참조할 수 있습니다.
**추론 컨테이너 기능 요약**
| 기능 | 활성화 방법 | 기본값 | 지원되는 모델 | 소개 |
| --- | --- | --- | --- | --- |
| [기본 온도](#nova-sagemaker-inference-container-feature-default-temperature) | 환경 변수 | 1.0 | 모든 Amazon Nova 모델 | v1.0 |
| [기본 top-p](#nova-sagemaker-inference-container-feature-default-top-p) | 환경 변수 | 1.0 | 모든 Amazon Nova 모델 | v1.0 |
| [기본 top-k](#nova-sagemaker-inference-container-feature-default-top-k) | 환경 변수 | -1(비활성) | 모든 Amazon Nova 모델 | v1.0 |
| [기본 최대 새 토큰](#nova-sagemaker-inference-container-feature-default-max-new-tokens) | 환경 변수 | 모델의 최대 컨텍스트 길이 | 모든 Amazon Nova 모델 | v1.0 |
| [기본 logprobs](#nova-sagemaker-inference-container-feature-default-logprobs) | 환경 변수 | 비활성화됨 | 모든 Amazon Nova 모델 | v1.0 |
| [Eagle3 추측적 디코딩](#nova-sagemaker-inference-container-feature-speculative-decoding) | 기본적으로 사용됩니다. | 활성화됨 | 모든 Amazon Nova 모델 | v1.0 |
| [KV 캐시 데이터 유형](#nova-sagemaker-inference-container-feature-kv-cache-dtype) | 환경 변수 | 모델 데이터 유형과 동일 | 모든 Amazon Nova 모델 | v1.3 |
| [양자화](#nova-sagemaker-inference-container-feature-quantization) | 환경 변수 | 비활성화\* | 모든 Amazon Nova 모델 | v1.3 |
| [추측적 토큰 수](#nova-sagemaker-inference-container-feature-num-speculative-tokens) | 환경 변수 | 3 | 모든 Amazon Nova 모델 | v1.4 |
| [접미사 디코딩](#nova-sagemaker-inference-container-feature-suffix-decoding) | 환경 변수 | 비활성화됨 | 모든 Amazon Nova 모델 | v1.4 |
**중요**
\* FP8 양자화는 다음 모델 및 인스턴스 유형 조합에 대해 자동으로 활성화되며 비활성화할 수 없습니다.
`ml.g6.12xlarge` 또는 `ml.g6.24xlarge`의 Amazon Nova Lite
`ml.g6.48xlarge`의 Nova 2 Lite
이러한 구성의 경우 `QUANTIZATION_DTYPE`을 설정할 필요가 없습니다. 세부 정보는 [양자화](#nova-sagemaker-inference-container-feature-quantization) 섹션을 참조하세요.
## 기본 온도
엔드포인트로 전송되는 모든 추론 요청에 대한 기본 샘플링 온도를 설정합니다. 온도는 모델의 출력이 얼마나 무작위적이거나 예측 가능한지 제어합니다. 값이 `0`이면 모델이 항상 가장 가능성이 높은 다음 단어를 선택하여 일관적이고 반복 가능한 출력을 생성합니다. 값이 높을수록(최대 `2`) 모델이 가능성이 낮은 단어를 더 쉽게 선택하여 더 창의적이면서 다양한 응답을 생성합니다.
**사용 시기:** 분류 또는 데이터 추출과 같이 사실적이고 일관적인 답변이 필요한 태스크의 온도를 낮춥니다(예: `0.1`\~`0.3`). 스토리 작성 또는 브레인스토밍과 같은 창의적인 태스크의 경우 온도를 높입니다(예: `0.7`\~`1.0`). 온도는 top-p 및 top-k와 함께 작동합니다. 세 가지 모두 모델이 토큰을 선택하는 방식을 제어하며 이를 결합하여 출력 동작을 미세 조정할 수 있습니다.
소개
`v1.0`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `DEFAULT_TEMPERATURE` 환경 변수를 설정합니다.
기본값
`1.0`
유효값
`0`\~`2` 사이의 부동 소수점(포함)
**환경 변수**
```
"Environment": {
"DEFAULT_TEMPERATURE": "0.7"
}
```
**참고**
요청 본문에 `temperature` 파라미터를 포함하여 요청별로 이 기본값을 재정의할 수 있습니다.
## 기본 top-p
모든 추론 요청에 대한 기본 top-p 값을 설정합니다. top-p는 모델의 선택을 가장 가능성이 높은 단어의 하위 집합으로 제한하여 출력 다양성을 제어합니다. 특히 모델은 확률을 기준으로 모든 가능한 다음 단어를 정렬하고 결합 확률이 top-p 값에 도달한 가장 작은 그룹만 고려합니다. 예를 들어, top-p가 `0.9`이면 모델에서 확률이 90%가 되는 단어만 고려하고 나머지 가능성이 낮은 옵션은 무시합니다.
**사용 방법:** 더 낮은 top-p 값(예: `0.5`)을 사용하여 모델이 신뢰도가 높은 단어만을 선택하도록 하여 더 집중적인 출력을 생성합니다. 더 다양한 값을 허용하려면 더 높은 값(예: `0.95`)을 사용합니다. top-p는 온도의 대안으로 사용되는 경우가 많습니다. 둘 다 출력 다양성을 제어하지만, top-p는 각 단계에서 모델의 신뢰도에 따라 동적으로 조정됩니다. 둘 다 함께 사용할 수 있으며, 이 경우 모델은 각 단계에서 더 제한적인 제약을 적용합니다.
소개
`v1.0`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `DEFAULT_TOP_P` 환경 변수를 설정합니다.
기본값
`1.0`
유효값
`1e-10`\~`1` 사이의 부동 소수점(포함)
**환경 변수**
```
"Environment": {
"DEFAULT_TOP_P": "0.9"
}
```
**참고**
요청 본문에 `top_p` 파라미터를 포함하여 요청별로 이 기본값을 재정의할 수 있습니다.
## 기본 top-k
모든 추론 요청에 대한 기본 top-k 값을 설정합니다. top-k는 모델의 선택을 고정된 수만큼의 가능성이 가장 높은 다음 단어로 제한합니다. 예를 들어, top-k 값이 `50`이면 모델은 개별 확률과 무관하게 각 단계에서 가장 가능성이 높은 단어 50개만 고려합니다. 값이 `-1`이면 이 제한이 비활성화되어 모델이 가능한 모든 단어를 고려할 수 있습니다.
**사용 방법:** 모델이 고려하는 단어 선택 수에 하드 캡을 적용하려는 경우 top-k를 사용합니다. 값이 낮을수록(예: `10`) 예측 가능한 출력이 생성되는 반면 값이 높을수록 더 다양한 출력이 가능합니다. top-k는 온도 및 top-p와 함께 사용할 수 있습니다. 여러 샘플링 컨트롤이 활성화되면 모델은 각 단계에서 가장 제한적인 컨트롤을 사용하여 모든 컨트롤을 적용합니다.
소개
`v1.0`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `DEFAULT_TOP_K` 환경 변수를 설정합니다.
기본값
`-1`(비활성)
유효값
정수(`-1` 이상). `-1`을 사용하면 모든 토큰을 고려합니다.
**환경 변수**
```
"Environment": {
"DEFAULT_TOP_K": "50"
}
```
**참고**
요청 본문에 `top_k` 파라미터를 포함하여 요청별로 이 기본값을 재정의할 수 있습니다.
## 기본 최대 새 토큰
모델이 응답에서 생성하는 기본 최대 토큰 수(단어 또는 단어 조각)를 설정합니다. 이 값은 재정의되지 않는 한 모든 요청에 적용됩니다. 이를 사용하여 응답 길이를 제어하고 엔드포인트 전반의 비용을 관리할 수 있습니다.
**사용 시기:** 모든 요청에서 일관적인 최대 응답 길이를 적용하려는 경우 이 값을 설정합니다. 예를 들어, 짧은 응답 태스크의 경우 `256`으로 설정하고 더 긴 콘텐츠 생성의 경우 `2048`로 설정합니다. 최대 허용 값은 엔드포인트에 대해 구성된 `CONTEXT_LENGTH`에 따라 달라집니다. 입력 토큰과 출력 토큰이 컨텍스트 길이를 초과할 수 없기 때문입니다.
소개
`v1.0`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `DEFAULT_MAX_NEW_TOKENS` 환경 변수를 설정합니다.
기본값
모델의 최대 컨텍스트 길이
유효값
정수(`1` 이상)
**환경 변수**
```
"Environment": {
"DEFAULT_MAX_NEW_TOKENS": "512"
}
```
**참고**
요청 본문에 `max_tokens` 또는 `max_completion_tokens` 파라미터를 포함하여 요청별로 이 기본값을 재정의할 수 있습니다. 허용되는 최대값은 엔드포인트에 대해 구성된 `CONTEXT_LENGTH`에 따라 다릅니다.
## 기본 logprobs
생성된 각 토큰에 대해 반환할 로그 확률의 기본 수를 설정합니다. 로그 확률은 각 단어를 선택하는 데 있어 모델의 신뢰도를 나타내는 숫자 점수입니다. 활성화되면 응답에 각 출력 토큰에 대한 이러한 점수가 포함되며, 이는 모델 신뢰도를 평가하고, 대체 단어 선택을 비교하고, 생성 동작을 디버깅하는 데 유용합니다.
**사용 시기:** 예를 들어, 인적 검토를 위해 신뢰도가 낮은 응답에 플래그를 지정하거나 서로 다른 완료 확률을 비교하는 등 모델 출력의 신뢰도를 평가해야 하는 경우 logprobs를 활성화합니다. logprobs를 활성화하면 응답 지연 시간과 응답 페이로드 크기가 약간 증가할 수 있습니다.
소개
`v1.0`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `DEFAULT_LOGPROBS` 환경 변수를 설정합니다.
기본값
비활성화됨
유효값
`1`\~`20` 사이의 정수(포함)
**환경 변수**
```
"Environment": {
"DEFAULT_LOGPROBS": "5"
}
```
**참고**
요청 본문에 `logprobs` 및 `top_logprobs` 파라미터를 포함하여 요청별로 이 기본값을 재정의할 수 있습니다. logprobs를 활성화하면 응답 지연 시간이 약간 증가할 수 있습니다.
## Eagle3 추측적 디코딩
Eagle3 추측적 디코딩은 텍스트 생성 속도를 높이는 최적화 기술입니다. 더 작고 빠른 초안 모델을 사용하여 여러 토큰을 미리 예측한 다음 한 단계에서 기본 모델과 비교하여 이러한 예측을 확인하는 방식으로 작동합니다. 예측이 정확하면 모델은 일반적으로 토큰을 생성하는 데 걸리는 시간 내에 여러 토큰을 효과적으로 생성합니다. 기본 모델은 항상 초안 토큰을 확인하므로 최종 출력은 기본 모델이 자체적으로 생성하는 것과 동일하며 품질이 아니라 속도만 변경됩니다.
**사용 시기:** Eagle3 추측적 디코딩은 기본적으로 활성화되고 대부분의 워크로드에 유용합니다. 예기치 않은 동작이 관찰되거나 디버깅 중에 성능 특성을 격리해야 하는 경우에만 비활성화하는 것이 좋습니다.
소개
`v1.0`. Eagle3 추측적 디코딩을 사용한 FP8 양자화에 대한 지원이 `v1.4`에 추가되었습니다.
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
Eagle3 추측적 디코딩은 구성 없이 기본적으로 활성화됩니다. `DISABLE_SPECULATIVE_DECODING`을 사용하면 비활성화됩니다.
기본값
`false`(Eagle3 추측적 디코딩 활성화됨)
유효값
`true`, `false`
**환경 변수**
다음 예제에서는 Eagle3 추측적 디코딩을 비활성화합니다.
```
"Environment": {
"DISABLE_SPECULATIVE_DECODING": "true"
}
```
## KV 캐시 데이터 유형
추론 중에 사용되는 키-값(KV) 캐시의 데이터 유형을 설정합니다. KV 캐시는 이전 토큰의 모델 메모리를 대화에 저장하므로 전체 입력을 재처리하지 않고도 각 새 토큰을 생성할 수 있습니다. 긴 시퀀스의 경우 이 캐시는 상당량의 GPU 메모리를 소비할 수 있습니다. KV 캐시를 FP8과 같은 정밀도가 낮은 데이터 유형으로 설정하면 메모리 사용량이 감소하고 처리량이 향상되어 출력의 수치적 차이가 약간 발생합니다.
**사용 시기:** 인스턴스에서 더 긴 컨텍스트 길이 또는 더 높은 동시성을 지원해야 하는 경우 FP8 KV 캐시를 활성화합니다. 메모리가 제한된 GPU 인스턴스에서 특히 유용합니다. 정밀도가 낮을수록 결과가 약간 다를 수 있으므로 사용 사례를 테스트하여 출력 품질이 요구 사항을 충족하는지 확인합니다.
소개
`v1.3`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `KV_CACHE_DTYPE` 환경 변수를 설정합니다.
기본값
모델의 데이터 유형과 동일
유효값
`fp8`
**환경 변수**
```
"Environment": {
"KV_CACHE_DTYPE": "fp8"
}
```
**참고**
KV 캐시 데이터 유형을 변경하면 기본 정밀도와 약간 다른 출력이 생성될 수 있습니다. 사용 사례를 테스트하여 출력 품질이 요구 사항을 충족하는지 확인합니다.
## 양자화
모델 가중치에 대한 양자화 데이터 유형을 설정합니다. 양자화는 모델의 가중치를 더 낮은 정밀도 형식(기본적으로 더 높은 정밀도 대신 FP8)으로 압축하여 모델에 필요한 GPU 메모리의 양을 줄입니다. 이를 통해 추론 처리량이 개선되고 출력 품질에 미치는 영향을 최소화하면서 더 큰 모델을 더 작은 인스턴스 유형에 맞출 수 있습니다.
**사용 시기:** 더 높은 동시성을 지원하거나 더 작은 인스턴스 유형에 모델을 맞추기 위해 메모리 사용량을 줄이려는 경우 FP8 양자화를 사용합니다. 일부 모델 및 인스턴스 유형 조합에는 FP8 양자화가 자동으로 필요합니다. 아래의 경고를 참조하세요.
소개
`v1.3`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `QUANTIZATION_DTYPE` 환경 변수를 설정합니다.
기본값
비활성화됩니다. 하지만 FP8 양자화는 특정 모델 및 인스턴스 유형 조합에 대해 자동으로 활성화됩니다. 아래 참고 사항을 참조하세요.
유효값
`fp8`
**환경 변수**
```
"Environment": {
"QUANTIZATION_DTYPE": "fp8"
}
```
**중요**
다음 모델 및 인스턴스 유형 조합에는 FP8 양자화가 필요합니다. 이러한 구성의 경우 양자화가 자동으로 활성화되고 비활성화하거나 재정의할 수 없습니다.
`ml.g6.12xlarge` 또는 `ml.g6.24xlarge`의 Amazon Nova Lite
`ml.g6.48xlarge`의 Nova 2 Lite
다른 모든 구성의 경우 [지원되는 모델 및 인스턴스](nova-model-sagemaker-inference.md#nova-sagemaker-inference-supported)에서 자세한 내용을 참조하세요.
## 추측적 토큰 수
각 Eagle3 추측적 디코딩 단계에서 초안 모델이 예측하는 토큰 수를 제어합니다. 값이 높을수록 초안 모델이 한 번에 더 많은 토큰을 예측하려고 시도하므로 예측이 정확할 때 처리량이 향상될 수 있습니다. 초안 모델의 예측이 기본 모델과 다른 경우가 잦으면 더 낮은 값이 더 효율적일 수 있습니다.
**사용 시기:** 워크로드가 초안 모델을 올바르게 추측할 가능성이 있는 예측 가능한 출력 패턴(예: 정형 데이터 또는 템플릿 형식 텍스트)을 생성할 때 값을 늘립니다. 예측의 신뢰도가 낮은 창의적이거나 매우 가변적인 출력의 경우 이 값을 줄입니다.
소개
`v1.4`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `NUM_SPECULATIVE_TOKENS` 환경 변수를 설정합니다.
기본값
`3`
유효값
`1`\~`10` 사이의 정수(포함)
**환경 변수**
```
"Environment": {
"NUM_SPECULATIVE_TOKENS": "5"
}
```
**참고**
이 설정은 Eagle3 추측적 디코딩이 활성화된 경우에만 적용됩니다(`DISABLE_SPECULATIVE_DECODING`이 `false`). 추측적 디코딩이 비활성화되거나 접미사 디코딩을 사용할 때는 효과가 없습니다.
## 접미사 디코딩
접미사 디코딩은 텍스트 생성 속도를 높이기 위한 또 다른 방법입니다. (Eagle3와 마찬가지로) 별도의 초안 모델을 사용하는 대신 접미사 디코딩은 이미 생성된 텍스트 또는 입력 프롬프트에서 반복되는 패턴을 찾고, 이러한 패턴을 재사용하여 향후 토큰을 예측합니다. 이 접근 방식은 반복되는 문구, 구조화된 형식 입력을 거의 유사하게 미러링하는 콘텐츠가 포함될 가능성이 높을 때 효과적입니다.
**사용 시기:** 출력에 정형 데이터 생성, 템플릿 채우기, 소스의 문구를 재사용하는 콘텐츠 요약과 같은 반복적인 패턴이 포함된 태스크에 접미사 디코딩을 사용합니다. 출력이 매우 다양한 범용 생성의 경우 기본 Eagle3 방법이 더 높은 처리량을 제공합니다.
소개
`v1.4`
지원되는 모델
모든 Amazon Nova 모델
활성화 방법
SageMaker 모델을 생성할 때 `SPECULATIVE_DECODING_METHOD` 환경 변수를 `suffix`로 설정합니다.
기본값
`eagle3`
유효값
`eagle3`, `suffix`
**환경 변수**
```
"Environment": {
"SPECULATIVE_DECODING_METHOD": "suffix"
}
```
**참고**
접미사 디코딩을 사용하려면 `DISABLE_SPECULATIVE_DECODING`을 `false`(기본값)로 설정해야 합니다. `DISABLE_SPECULATIVE_DECODING`을 `true`로 설정하면 접미사 디코딩을 포함한 모든 추측적 디코딩 방법이 비활성화됩니다.