Transformers documentation
토크나이저
토크나이저
토크나이저는 텍스트를 모델의 입력인 텐서로 변환합니다. 텍스트를 정규화하고 분할하며, 토크나이제이션 알고리즘을 적용하고, 특수 토큰을 추가하며, 출력 ID를 다시 텍스트로 디코딩합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
'input_ids': tensor([[ 2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]]),
'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}이 가이드에서는 로딩, 인코딩, 디코딩, 배치 처리 및 사용 가능한 토크나이저 백엔드를 다룹니다.
토크나이저 로드
AutoTokenizer 클래스 또는 모델별 토크나이저 클래스로 토크나이저를 로드합니다.
AutoTokenizer.from_pretrained() reads the model config, resolves the correct tokenizer class, and returns an instance of it. You don’t need to know the tokenizer class beforehand. Most tokenizers resolve to a subclass of TokenizersBackend, a fast Rust-based tokenizer from the Tokenizers library.
AutoTokenizer를 사용하여 로딩하는 것이 권장되는 방법입니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")모델별 토큰화 클래스는 모델이 학습될 때 사용된 정확한 토큰화 구성(노멀라이저, 프리토크나이저, 특수 토큰 규칙 등)을 사용하는 사전 구성된 TokenizersBackend입니다.
모델별 클래스를 사용하여 학습을 위한 빈 토크나이저를 초기화하거나 vocab 또는 merges와 같은 모델별 인수를 전달합니다(방법은 토크나이저 커스터마이징 가이드를 참고하세요). 빈 토크나이저는 최소한의 구성으로, <pad>, <eos>, <bos>와 같은 모델의 특수 토큰만 포함합니다.
from transformers import GemmaTokenizer
tokenizer = GemmaTokenizer()
corpus = [
["Sphinx of black quartz, judge my vow."],
["Pack my box with five dozen liquor jugs."],
["How vexingly quick daft zebras jump!"],
]
new_tokenizer = tokenizer.train_new_from_iterator(corpus, vocab_size=1000)인코딩 및 디코딩
TokenizersBackend.call() 메서드는 텍스트 또는 텍스트 배치로 input_ids, attention_mask 및 기타 모델 입력을 인코딩합니다. 또한 패딩, 잘라내기, 특수 토큰 삽입을 제어합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
'input_ids': tensor([[ 2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]]),
'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}TokenizersBackend.encode()는 이와 유사하지만 input_ids만 반환합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]TokenizersBackend.decode()는 토큰화된 input_ids 단일 시퀀스 또는 배치의 텍스트를 복원합니다.
tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'TokenizersBackend.decode()는 토큰화 간격을 정확히 유지합니다. 구두점 앞의 공백을 제거하려면 clean_up_tokenization_spaces를, 출력에서 특수 토큰을 제거하려면 skip_special_tokens를 설정하세요.
tokenizer.decode(input_ids, skip_special_tokens=True)
'Sphinx of black quartz, judge my vow.'특수 토큰
Special tokens은 시퀀스 내의 구조적 경계, 예를 들어 시퀀스 시작 위치나 패딩 위치를 표시합니다. 각 모델은 자체적인 special tokens 집합을 정의합니다. 토크나이저를 호출할 때 토크나이저가 이 토큰들을 추가합니다.
input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]
tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'extra_special_tokens 인수를 사용하여 추가의 이름이 지정된 특수 토큰을 등록합니다. 멀티모달 모델은 이를 이미지, 비디오 또는 오디오의 플레이스홀더로 사용합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained(
"google/gemma-3-4b-pt",
extra_special_tokens={"image_token": "<image>"}
)배치 처리
Batch processing은 단일 호출로 여러 시퀀스를 토큰화합니다. TokenizersBackend는 Rust 기반 백엔드가 작업을 여러 스레드에 걸쳐 병렬화하므로 큰 배치 처리가 더 빠릅니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
[
"Sphinx of black quartz, judge my vow.",
"Pack my box with five dozen liquor jugs.",
"How vexingly quick daft zebras jump!"
],
return_tensors="pt"
)Batch processing은 모든 시퀀스가 동일한 길이를 공유해야 합니다. 패딩(padding)과 잘라내기(truncation)는 길이가 다른 시퀀스를 처리하기 위한 전략입니다.
패딩
Padding은 배치 내 가장 긴 시퀀스와 길이를 맞추기 위해 짧은 시퀀스에 특수 토큰을 추가합니다. Attention mask는 패딩 위치를 0으로 표시하여 모델이 해당 위치를 무시하도록 합니다. padding=True를 설정하면 가장 긴 시퀀스 길이에 맞게 패딩을 수행하고, max_length를 전달하면 고정된 크기에 맞게 패딩을 수행합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
[
"Sphinx of black quartz, judge my vow.",
"Pack my box with five dozen liquor jugs.",
"How vexingly quick daft zebras jump!"
],
return_tensors="pt",
padding=True,
)
{
'input_ids': tensor([
[ 2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265],
[ 0, 2, 6519, 970, 3741, 675, 4105, 25955, 42184, 225789, 235265],
[ 0, 2, 2299, 73378, 17844, 4320, 224463, 4949, 48977, 9902, 235341]
]),
'attention_mask': tensor([
[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
[0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
[0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
])
}대형 언어 모델은 오른쪽에서 다음 토큰을 예측하는 생성 과정을 방해하지 않도록 왼쪽으로 패딩을 수행합니다.
단축
Truncation은 시퀀스가 최대 길이에 맞도록 토큰을 잘라냅니다. 활성화하려면 truncation=True를 설정하고 max_length를 지정하세요.
Padding과 truncation은 함께 작동합니다. 짧은 시퀀스는 padding 토큰을 추가하고 긴 시퀀스는 끝부분의 토큰을 제거합니다. 이를 통해 패킹된 직사각형 텐서를 생성합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
[
"Sphinx of black quartz, judge my vow.",
"Pack my box with five dozen liquor jugs.",
"How vexingly quick daft zebras jump!"
],
return_tensors="pt",
padding=True,
truncation=True,
max_length=5
)
{
'input_ids': tensor([
[ 2, 235277, 82913, 576, 2656],
[ 2, 6519, 970, 3741, 675],
[ 2, 2299, 73378, 17844, 4320]
]),
'attention_mask': tensor([
[1, 1, 1, 1, 1],
[1, 1, 1, 1, 1],
[1, 1, 1, 1, 1]
])
}백엔드
각 모델의 토크나이저는 단일 파일로 정의되며 네 가지 토크나이제이션 백엔드를 지원합니다.
| 백엔드 | 구현 | 설명 |
|---|---|---|
| TokenizersBackend | 토크나이저 | 대부분의 모델의 기본값 |
| SentencePieceBackend | SentencePiece | SentencePiece가 필요한 모델 |
| PythonBackend | Python | 특수한 커스텀 토크나이저가 필요한 모델 |
| MistralCommonBackend | mistral-common | Mistral 및 Pixtral 모델 |
모든 백엔드는 PreTrainedTokenizerBase를 상속하며, 인코딩, 디코딩, 패딩, 잘라내기, 저장 및 로딩을 위한 동일한 API를 공유합니다. 차이점은 아래에서 실행되는 토큰화 파이프라인이 무엇인지입니다.
AutoTokenizer는 from_pretrained()를 호출할 때 사용할 수 있는 최적의 백엔드를 선택합니다.
tokenizer_class필드를 위해tokenizer_config.json파일을 읽습니다.- 레지스트리는
tokenizer_class를 클래스 이름과 일치시킵니다. 해석된 클래스는 네 가지 백엔드 중 하나를 상속합니다. 예를 들어, GemmaTokenizer은 TokenizersBackend를 상속하고, SiglipTokenizer는 SentencePieceBackend를 상속합니다. GLM과 같은 일부 모델은tokenizer.json파일이 파이프라인을 완전히 설명하기 때문에 TokenizersBackend에 직접 매핑됩니다. GemmaTokenizer는tokenizer.json에 포함되지 않는 추가적인 모델별 설정을 Python으로 정의하기 때문에 서브클래스로 존재합니다. mistral-common과 같은 백엔드가 설치되지 않은 경우, AutoTokenizer는 TokenizersBackend로 폴백됩니다.
TokenizersBackend로 폴백
일부 모델에는 전용 토크나이저 클래스가 없으며, 일부 체크포인트에는 실제 tokenizer.json 파일과 일치하지 않는 tokenizer_class가 포함되어 있습니다. AutoTokenizer는 범용 TokenizersBackend를 통해 tokenizer.json에서 파이프라인을 로드하여 이 두 가지 경우를 모두 처리합니다. Hub의 클래스 이름보다 직렬화된 토크나이저를 우선적으로 사용하므로, 일치하지 않는 tokenizer_class가 잘못된 토큰 ID를 생성하는 문제와 같은 문제를 해결합니다.
체크포인트가 세 가지 이유 중 하나로 범용 TokenizersBackend로 해석됩니다.
| 이유 | 동작 | 예시 |
|---|---|---|
| 전용 토크나이저 클래스 없음 | 모델 유형은 tokenizer.json이 파이프라인을 완전히 설명하기 때문에 TokenizersBackend으로 바로 매핑됩니다. | GLM, Granite, OLMo 2, GPT BigCode |
| 잘못된 것으로 알려진 Hub 토크나이저 클래스 | Hub에 기록된 tokenizer_class가 모델 유형과 일치하지 않아 AutoTokenizer는 이를 무시하고 대신 tokenizer.json를 로드합니다. | DeepSeek V3, LLaVA, Qwen2, ModernBERT |
| 특정 체크포인트 오버라이드 | Hub 설정이 여전히 수정이 필요한 체크포인트는 모델 ID로 매칭되어 백엔드로 강제됩니다. | deepseek-ai/DeepSeek-R1-Distill-*, Salesforce/blip2-*, google/umt5-small |
설정값이 Hub에서 수정됨에 따라 영향을 받는 모델 유형 및 체크포인트가 증가합니다. 현재 대상은 tokenization_auto.py의 MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS 및 MODEL_IDS_TO_TOKENIZERS_BACKEND 정의를 참고하세요.
fallback은 자동으로 이루어지며 from_pretrained()를 호출하는 방식은 변경되지 않습니다. 생성된 tokenizer는 tokenizer.json에 명시된 대로 정확히 인코딩 및 디코딩합니다.
backend 속성을 사용하여 토크나이저가 어떤 백엔드를 사용하는지 확인할 수 있습니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer.backend
'tokenizers'토크나이저 구조 검사
_tokenizer 속성을 사용하여 토크나이저의 내부 구성 요소(노멀라이저, 프리-토크나이저, 모델, 디코더)를 검사합니다.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
print(tokenizer._tokenizer.normalizer)
print(tokenizer._tokenizer.pre_tokenizer)
print(tokenizer._tokenizer.model)
print(tokenizer._tokenizer.decoder)리소스
- Transformers v5의 토큰화 포스트는 새로운 토큰화 백엔드 도입의 동기를 다룹니다.
- 토큰화 변경 사항의 개요를 확인하려면 마이그레이션 가이드를 검토하세요.