기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 사용자 지정 채팅 템플릿 및 토큰화기 처리
사용자 지정 채팅 템플릿과 토큰화기는 대화 입력을 올바르게 포맷하고 가져온 모델에서 토큰 생성을 관리하기 위한 필수 구성 요소입니다. 사용자 지정 모델 가져오기는 멀티턴 대화가 구조화되고 토큰화되는 방식을 정의하는 사용자 지정 채팅 템플릿으로 모델 가져오기를 지원합니다.
## 사용자 지정 채팅 템플릿을 사용하여 모델 가져오기
사용자 지정 채팅 템플릿으로 모델을 가져올 때는 모델 가중치를 안전한 텐서 형식으로 가져오고 필요한 모든 구성 파일을 제공하는 등 기본 사용자 지정 모델 가져오기 설명서에 설명된 모범 사례를 따라야 합니다.
### 채팅 템플릿 형식 요구 사항
모델이 사용자 지정 채팅 템플릿을 사용하고 Amazon Bedrock에서 해당 템플릿을 사용하려면 채팅 템플릿 파일을 다음 형식 중 하나로 포함해야 합니다.
+ **`chat_template.jinja`** - 메시지 형식 지정 방법을 정의하는 Jinja2-based 템플릿 파일입니다.
+ **`chat_template.json`** - 채팅 템플릿을 문자열 값으로 포함하는 JSON 파일입니다.
+ **`tokenizer_config.json` 채팅 템플릿 포함** - 또는 `tokenizer_config.json` 파일 내에 채팅 템플릿을 `chat_template` 필드로 직접 포함할 수 있습니다. 예를 들어 Hugging Face의 [Hermes-2-Pro tokenizer\$1config.json](https://huggingface.co/NousResearch/Hermes-2-Pro-Llama-3-8B/blob/main/tokenizer_config.json#L2059)을 참조하세요.
사용자 지정 모델 가져오기는 이러한 파일을 자동으로 처리하고 가져오기 프로세스 중에 올바른 디렉터리에 포함합니다.
#### 채팅 템플릿 우선 순위
여러 채팅 템플릿 소스를 제공하는 경우 Amazon Bedrock은 다음 우선 순위 규칙을 적용합니다.
1. **별도의 채팅 템플릿 파일이 우선합니다 **-에 별도의 채팅 템플릿 파일(`chat_template.jinja` 또는 `chat_template.json`)과 `chat_template` 필드를 모두 포함하면 `tokenizer_config.json`별도의 파일이 사용되고에 포함된 템플릿`tokenizer_config.json`은 무시됩니다.
1. **폴백으로 포함된 템플릿** - 별도의 채팅 템플릿 파일을 제공하지 않으면 Amazon Bedrock은 있는 `tokenizer_config.json` 경우의 `chat_template` 필드를 사용합니다.
**주의**
한 **가지 접근 방식 선택:** 혼동을 피하고 예측 가능한 동작을 보장하려면 다음 접근 방식 중 하나만 사용하는 것이 좋습니다.
**옵션 1:**에 `chat_template` 필드를 포함하지 않고 별도의 채팅 템플릿 파일(`chat_template.jinja` 또는 `chat_template.json`)을 제공합니다`tokenizer_config.json`.
**옵션 2:**에 직접 `chat_template` 필드를 포함하고 별도의 템플릿 파일을 제공하지 `tokenizer_config.json` 않습니다.
사용자 지정 도구 템플릿 또는 복잡한 채팅 템플릿 구성이 있는 경우 단일 구성 파일 내에서 여러 개의 명명된 템플릿(예: "default" 및 "tool\$1use"`tokenizer_config.json`)을 정의할 수 있으므로 옵션 2(에 템플릿 포함)를 사용하는 것이 좋습니다.
**참고**
채팅 템플릿 파일은 Hugging Face 형식 및 이름 지정 규칙을 따라야 합니다. 템플릿이 Transformers 라이브러리와 호환되는지 확인합니다.
#### 채팅 템플릿 형식 예제
다음은 지원되는 두 가지 채팅 템플릿 형식의 예입니다.
------
#### [ Jinja Format (chat\$1template.jinja) ]
Jinja2-based 채팅 템플릿의 간단한 예:
```
{% for message in messages %}
{% if loop.first and message['role'] != 'system' %}
<|im_start|>system
You are a helpful assistant.<|im_end|>
{% endif %}
<|im_start|>{{ message['role'] }}
{{ message['content'] }}<|im_end|>
{% endfor %}
{% if add_generation_prompt %}
<|im_start|>assistant
{% endif %}
```
전체 예제는 Hugging Face의 [GPT-OSS 채팅 템플릿을](https://huggingface.co/openai/gpt-oss-20b/blob/main/chat_template.jinja) 참조하세요.
------
#### [ JSON Format (chat\$1template.json) ]
비전 지원이 포함된 JSON 기반 채팅 템플릿의 간단한 예:
```
{
"chat_template": "{% for message in messages %}{% if loop.first and message['role'] != 'system' %}<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n{% endif %}<|im_start|>{{ message['role'] }}\n{% if message['content'] is string %}{{ message['content'] }}<|im_end|>\n{% else %}{% for content in message['content'] %}{% if content['type'] == 'image' %}<|vision_start|><|image_pad|><|vision_end|>{% elif 'text' in content %}{{ content['text'] }}{% endif %}{% endfor %}<|im_end|>\n{% endif %}{% endfor %}{% if add_generation_prompt %}<|im_start|>assistant\n{% endif %}"
}
```
멀티모달 지원이 포함된 전체 예제는 Hugging Face의 [Qwen2-VL 채팅 템플릿을](https://huggingface.co/Qwen/Qwen2-VL-72B-Instruct/blob/main/chat_template.json) 참조하세요.
------
**중요**
채팅 템플릿 파일이 위의 예제에 표시된 정확한 명명 규칙(`chat_template.jinja` 또는 `chat_template.json`) 및 형식을 따르는지 확인합니다. 템플릿을 잘못 포맷하면 가져오기 또는 추론에 실패할 수 있습니다.
## 사용자 지정 채팅 템플릿을 사용하여 모델 호출
사용자 지정 채팅 템플릿으로 모델을 가져온 후에는 적절한 형식의 대화형 입력으로 모델을 호출하는 두 가지 옵션이 있습니다.
### 메시지와 함께 OpenAI ChatCompletion API 사용
메시지 스키마 형식으로 입력을 제공하는 경우 **OpenAI ChatCompletion API**를 사용해야 합니다. 업로드된 채팅 템플릿(`chat_template.jinja` 또는 `chat_template.json`)이 있는 모델에서이 API 형식을 사용하는 경우 Amazon Bedrock은 채팅 템플릿을 사용하여 입력 메시지를 올바른 형식으로 자동 변환합니다.
이는 가장 원활한 통합을 제공하고 Amazon Bedrock이 채팅 템플릿 애플리케이션을 자동으로 처리할 수 있으므로 권장되는 접근 방식입니다.
**예: 사용자 지정 채팅 템플릿과 함께 OpenAI ChatCompletion API 사용 ChatCompletion **
```
import json
import boto3
# Initialize Bedrock Runtime client
client = boto3.client('bedrock-runtime', region_name='us-east-1')
# Define the model ARN for your imported model with custom chat template
model_id = 'arn:aws:bedrock:us-east-1:123456789012:imported-model/your-model-id'
# Prepare the request payload using messages format
payload = {
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello, how are you?"
}
],
"max_tokens": 150,
"temperature": 0.7
}
# Invoke the model
response = client.invoke_model(
modelId=model_id,
body=json.dumps(payload),
accept='application/json',
contentType='application/json'
)
# Parse and display the response
response_body = json.loads(response['body'].read())
print(json.dumps(response_body, indent=2))
```
이 예제에서 Amazon Bedrock은 메시지 배열에 사용자 지정 채팅 템플릿을 자동으로 적용하여 모델에 적합한 형식으로 변환합니다.
### 수동 토큰화 접근 방식
또는 채팅 템플릿 애플리케이션 및 토큰화 프로세스를 완전히 제어하려는 경우 채팅 템플릿을 대화에 수동으로 적용한 다음 사전 형식의 텍스트와 함께 **완료 API**(ChatCompletion 아님)를 사용할 수 있습니다.
이 접근 방식은 템플릿 애플리케이션 로직을 사용자 지정해야 하거나 특수 토큰화 요구 사항으로 작업할 때 유용합니다.
#### 1단계: 채팅 템플릿을 로컬로 적용
다음 코드 조각을 사용하여 사용자 지정 채팅 템플릿을 로드하고 로컬에서 대화에 적용합니다.
```
from transformers import AutoTokenizer
# Configuration paths - update these with your actual paths
TOKENIZER_PATH = "" # Path to tokenizer directory
# Load tokenizer with updated chat template
tokenizer = AutoTokenizer.from_pretrained(TOKENIZER_PATH)
# Test chat template with sample conversation
chat_history = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello, how are you?"},
]
# Apply chat template and display formatted output to make sure chat template works as expected
formatted_chat = tokenizer.apply_chat_template(chat_history, tokenize=False)
print(formatted_chat)
```
이 코드는 다음을 수행하는 방법을 보여줍니다.
1. 모델 파일에서 토큰화기 구성 로드
1. 사용자 지정 채팅 템플릿을 토큰화기 구성에 추가
1. 채팅 템플릿을 대화 기록에 적용
1. 모델로 전송할 수 있는 형식이 지정된 텍스트 생성
#### 2단계: 완료 API로 간접 호출
채팅 템플릿을 로컬에 적용한 후 완료 API와 함께 형식이 지정된 텍스트를 사용합니다.
```
import json
import boto3
# Initialize Bedrock Runtime client
client = boto3.client('bedrock-runtime', region_name='us-east-1')
# Define the model ARN for your imported model
model_id = 'arn:aws:bedrock:us-east-1:123456789012:imported-model/your-model-id'
# Use the formatted_chat output from Step 1 as the prompt
payload = {
"prompt": formatted_chat,
"max_tokens": 150,
"temperature": 0.7
}
# Invoke the model using Completion format (not ChatCompletion)
response = client.invoke_model(
modelId=model_id,
body=json.dumps(payload),
accept='application/json',
contentType='application/json'
)
# Parse and display the response
response_body = json.loads(response['body'].read())
print(json.dumps(response_body, indent=2))
```
**주의**
**항상 `max_tokens` 파라미터 사용:** 사용자 지정 모델 가져오기와 함께 완료 API를 사용하는 경우 항상 `max_tokens` 파라미터를 사용하여 OpenAI 완료 스키마 호환성을 보장합니다. 이렇게 하면 번역 혼동을 방지하고 다양한 SDK 구현에서 일관된 동작을 보장할 수 있습니다. `max_gen_len` 또는 유사한 변형과 같은 모델별 파라미터 이름을 사용하지 마십시오.
**중요**
수동 토큰화 접근 방식을 사용할 때는 ChatCompletion **API 형식(필드 포함)이 아닌 완료** API 형식(`messages`필드 포함)을 사용해야 합니다. `prompt` ChatCompletion API는 원시 메시지를 예상하고 채팅 템플릿을 다시 적용하려고 시도하므로 형식이 잘못되었습니다.
### 모범 사례
+ **가능한 경우 ChatCompletion API 사용** - 메시지 형식의 OpenAI ChatCompletion API는 가장 원활한 환경을 제공하고 Amazon Bedrock이 채팅 템플릿 애플리케이션을 자동으로 처리할 수 있도록 합니다.
+ **채팅 템플릿 검증** - 모델을 가져오기 전에 Transformers 라이브러리를 사용하여 채팅 템플릿을 로컬에서 테스트하여 예상 출력 형식을 생성하는지 확인합니다.
+ **모든 특수 토큰 포함** - 채팅 템플릿에 모델에 필요한 모든 특수 토큰(예: beginning-of-sequence, end-of-sequence 및 역할 마커)이 포함되어 있는지 확인합니다.
+ **멀티턴 대화로 테스트 -** 채팅 템플릿이 대체 사용자 및 어시스턴트 메시지와 함께 멀티턴 대화를 올바르게 처리하는지 확인합니다.
+ **비전 지원 고려** - 모델이 멀티모달 입력을 지원하는 경우 채팅 템플릿에 이미지 및 비디오 콘텐츠 마커를 처리하기 위한 로직이 포함되어 있는지 확인합니다.
**주의**
채팅 템플릿의 형식을 잘못 지정하면 모델 성능이 저하되거나 예상치 못한 출력 또는 추론 실패가 발생할 수 있습니다. 프로덕션에 배포하기 전에 항상 채팅 템플릿을 철저히 테스트하세요.