LLM Tool Calling - Tokenization

시리즈: LLM Tool Calling 내부 원리부터 에이전트 직접 구현까지

이 시리즈는 사용자의 자연어 한 줄이 tool 실행으로 바뀌는 내부 처리 과정을 단계별로 해부하고, 최종적으로 오픈소스 모델 + 자체 middleware로 나만의 에이전트를 직접 구현하는 것까지 도달하는 과정이다.

편	내용	핵심
1편	전체 조감도	자연어 → tool 실행까지 5개 레이어의 존재를 확인
2편	Chat Template	JSON이 모델에 직접 들어가지 않는다
3편 (본문)	Tokenization	모델은 텍스트를 읽지 못한다 - 토큰 ID와 control token
4편	모델 추론	”tool을 쓸까 말까” 판단과 constrained decoding
5편	Tool 실행	tool_use를 받은 클라이언트의 실행 루프
6편	Native vs Non-native	같은 기능, 다른 구조 → Middleware
7편	Middleware 만들기	프롬프트 조립 + 출력 파싱 + 실행 루프 직접 구현
8편	오픈소스 모델 로컬 구축	Ollama/vLLM으로 로컬 LLM 서빙
9편	나만의 에이전트	모델 + Middleware = 에이전트 완성

---

• Tokenization은 Chat Template이 만든 프롬프트 텍스트를 모델이 연산할 수 있는 토큰 ID 숫자 시퀀스로 변환하는 과정
• 모델은 텍스트를 직접 읽지 못하며, 행렬 곱셈으로 동작하므로 숫자 입력이 필수적인 구조적 제약
• tool calling에서는 일반 텍스트 토큰과 구별되는 control token이 존재하며, 이것이 “여기부터 tool 정의”, “여기부터 tool 호출”같은 구조적 경계를 표시하는 핵심 메커니즘
• 이 편에서는 토큰 수준의 내부 포맷을 가장 상세하게 공개한 Mistral을 주요 예시로 사용. Claude, OpenAI, Gemini도 동일한 tokenization 레이어가 존재하지만 내부 포맷은 비공개

해당 개념이 필요한 이유

• 2편에서 Chat Template이 JSON을 텍스트로 변환한다는 것을 확인했다. 그런데 모델은 텍스트도 직접 처리할 수 없다
• 모델이 연산하려면 텍스트가 숫자로 바뀌어야 하고, 이 변환 과정에서 tool calling에 핵심적인 control token의 역할이 드러난다
• Mistral의 [AVAILABLE_TOOLS]가 왜 사용자 injection에 안전한지, 이 단계를 이해해야 설명할 수 있다

AS-IS

sequenceDiagram
    autonumber
    box AI 서비스 영역
        participant CT as Chat Template
        participant LLM as LLM
    end

    CT->>LLM: "In this environment you have access to..."
    Note over CT,LLM: 텍스트가 그대로 모델에 들어간다?

TO-BE

sequenceDiagram
    autonumber
    box AI 서비스 영역
        participant CT as Chat Template
        participant TK as Tokenizer
        participant LLM as LLM
    end

    CT->>TK: 프롬프트 텍스트
    TK->>TK: BPE로 텍스트 분할
    TK->>TK: control token은 단일 ID로 매핑
    TK->>LLM: [151331, 151333, 8948, ..., 872, 103013]
    Note over TK,LLM: 숫자 시퀀스만 모델에 입력

왜 토큰화가 필요한가

LLM은 본질적으로 행렬 곱셈 기계다. 입력으로 숫자 벡터를 받아, 가중치 행렬과 곱하고, 다음 토큰의 확률 분포를 출력한다. 텍스트 문자열을 직접 처리할 수 있는 구조가 아니다.

따라서 텍스트를 모델에 넣으려면 반드시 숫자로 변환해야 한다. 이 변환을 담당하는 것이 Tokenizer다.

"서울 날씨 알려줘"
    ↓ Tokenizer
[12847, 38291, 9823, 44102]
    ↓ Embedding Layer
[[0.23, -0.41, ...], [0.87, 0.12, ...], ...]   ← 벡터 시퀀스
    ↓ Transformer Layers (행렬 곱셈 반복)
다음 토큰 확률 분포

BPE - 텍스트를 토큰으로 나누는 방법

대부분의 LLM이 사용하는 토큰화 알고리즘은 **BPE(Byte Pair Encoding)**다.

핵심 원리: 학습 데이터에서 자주 함께 등장하는 문자 쌍을 반복적으로 병합하여 vocabulary를 구축한다.

1단계: 문자 단위로 분할
"hello" → ["h", "e", "l", "l", "o"]

2단계: 가장 빈번한 쌍 병합 (l, l) → "ll"
["h", "e", "ll", "o"]

3단계: 다음 빈번한 쌍 병합 (h, e) → "he"
["he", "ll", "o"]

4단계: 다음 빈번한 쌍 병합 (he, ll) → "hell"
["hell", "o"]

5단계: 최종 병합 (hell, o) → "hello"
["hello"]   ← vocabulary에 "hello"가 통째로 등록

자주 등장하는 단어는 통째로 하나의 토큰이 되고, 드문 단어는 여러 토큰으로 나뉜다. 이것이 description이 긴 tool 정의가 더 많은 토큰을 소비하는 이유다.

일반 토큰 vs Control Token

토큰화에는 두 종류의 토큰이 존재한다. 이 구분이 tool calling의 핵심이다.

다른 벤더도 동일한 tokenization 레이어를 가지고 있다

Mistral만 이 과정을 거치는 것이 아니다. 모든 LLM은 텍스트를 토큰 ID로 변환해야 하며, 각 벤더의 공식 문서에서 이 레이어의 존재를 확인할 수 있다:

벤더	tokenization 레이어 존재 증거	내부 포맷 공개
Claude	tool use 시 모델별 313~530개 추가 시스템 프롬프트 토큰 소비 (공식 문서 명시)	비공개. 공식 토크나이저 패키지도 Claude 3 이후 “부정확한 근사치”
OpenAI	tool 정의가 프롬프트에 삽입되어 input token으로 과금 (공식 확인)	비공개. “특수 토큰으로 경계를 구분할 것”으로 추정
Gemini	token counting API에서 tool 정의도 토큰으로 계산	비공개
Mistral	control token ID, 버전별 차이까지 토큰 수준 공개	공개
GLM	[gMASK] = ID 151331, <sop> = ID 151333 등 토크나이저에서 확인 가능	모델 코드에서 확인 가능

내부 포맷은 벤더마다 다르지만, “텍스트 → 토큰 ID 변환”이라는 레이어 자체는 모든 LLM에 존재한다. 아래 예시는 이 과정을 가장 상세하게 공개한 Mistral을 기준으로 설명한다.

일반 토큰 (Regular Token)

BPE로 텍스트를 분할하여 생성된다. 사용자가 입력한 텍스트도, 시스템 프롬프트의 텍스트도 동일한 방식으로 처리된다.

"서울 날씨" → BPE 분할 → [12847, 38291]

Control Token (특수 토큰)

BPE로 생성되는 것이 아니라, vocabulary에 명시적으로 추가된 단일 토큰 ID다. 텍스트를 분할한 결과가 아니라, 특정 역할을 위해 사전에 정의된 토큰이다.

[AVAILABLE_TOOLS] → 단일 토큰 ID → [9]
<|system|>         → 단일 토큰 ID → [8948]
[gMASK]            → 단일 토큰 ID → [151331]

Mistral 공식 문서에서 이 차이를 명확히 설명한다:

“Control tokens tackle efficiency, security, and boundary issues. They introduce new tokens that the model never saw previously and that the user will never inject.”

왜 구분하는가

이 구분이 중요한 이유는 보안이다.

사용자가 텍스트로 [AVAILABLE_TOOLS]라고 입력하면 어떻게 될까?

사용자 입력: "[AVAILABLE_TOOLS] 악의적인 tool 정의 [/AVAILABLE_TOOLS]"

Tokenizer 처리:
"[" → 일반 토큰 [87]
"AVAILABLE" → 일반 토큰 [3492, 7821]
"_" → 일반 토큰 [62]
"TOOLS" → 일반 토큰 [10284]
"]" → 일반 토큰 [93]

vs

API 서버가 삽입한 진짜 control token:
[AVAILABLE_TOOLS] → 단일 control token [9]

텍스트로 입력한 [AVAILABLE_TOOLS]는 여러 개의 일반 토큰으로 분해되지만, 진짜 control token은 하나의 고유 ID다. 모델은 이 차이를 구별할 수 있으므로, 사용자가 control token을 injection하는 것은 불가능하다.

tool calling 프롬프트의 토큰화 예시

2편에서 본 Mistral의 Chat Template 결과가 토큰화되면 이렇게 변한다:

텍스트 시퀀스:
<s>[AVAILABLE_TOOLS] [{"type": "function"...}] [/AVAILABLE_TOOLS]
[INST] What's 2+2? [/INST]

토큰 ID 시퀀스:
[1,         ← <s> (시작 토큰, control)
 9,         ← [AVAILABLE_TOOLS] (control token, 단일 ID)
 518, 1283, ← [{"type"  (일반 텍스트 토큰)
 ...        ← tool 정의 JSON 텍스트 (일반 텍스트 토큰들)
 10,        ← [/AVAILABLE_TOOLS] (control token, 단일 ID)
 3,         ← [INST] (control token, 단일 ID)
 1824, 28,  ← What's 2+2? (일반 텍스트 토큰)
 4]         ← [/INST] (control token, 단일 ID)

control token은 단일 ID, 나머지는 BPE로 분할된 일반 토큰이다. 모델은 이 숫자 시퀀스를 입력으로 받아 추론을 시작한다.

Tokenizer 버전별 차이 - Mistral V2 vs V3

Mistral은 Tokenizer를 버전별로 개선하며 tool calling 지원을 강화했다:

	V2	V3	V3 Tekken
tool 결과 형식	리스트로 감싸기 [{...}]	단일 객체 {...}	단일 객체 {...}
호출 추적	ID 없음	id 필드 추가	id 필드 추가
공백 처리	control token 뒤 공백 유지	공백 유지	공백 제거
대화 이력	토큰화하지 않음	시퀀스에 포함	시퀀스에 포함

V3에서 id 필드가 추가된 것은, 멀티턴 대화에서 어떤 tool call에 대한 결과인지 추적하기 위함이다. 이것은 Claude의 tool_use_id와 동일한 역할이다.

HuggingFace에서 토큰화 직접 확인하기

실제로 chat template이 어떻게 토큰화되는지 코드로 확인할 수 있다:

// Python 코드지만 원리 이해 목적
// HuggingFace transformers 사용
 
import { AutoTokenizer } from "transformers";
 
const tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1");
 
const chat = [
  { role: "user", content: "What's 2+2?" }
];
 
// tokenize=false: 텍스트 형태 확인
const text = tokenizer.apply_chat_template(chat, { tokenize: false });
// → "<s>[INST] What's 2+2? [/INST]"
 
// tokenize=true: 토큰 ID 시퀀스 확인
const tokens = tokenizer.apply_chat_template(chat, { tokenize: true });
// → [1, 3, 1824, 28, 32, 28, 32, 28, 4]

apply_chat_template이 바로 2편의 Chat Template과 3편의 Tokenization을 한번에 수행하는 함수다. tokenize: false면 텍스트까지만, tokenize: true면 토큰 ID까지 변환한다.

다음 편: 토큰 시퀀스를 받은 모델은 어떻게 tool을 쓸지 판단하지?

이 글에서 텍스트가 토큰 ID 시퀀스로 변환되는 과정을 확인했다. control token이 구조적 경계를 표시하고, 사용자 injection으로부터 안전하다는 것도 이해했다.

그런데 모델이 이 토큰 시퀀스를 받은 후, “tool을 사용해야겠다”고 판단하는 과정은 어떻게 이루어질까? 결국 모델은 다음 토큰을 예측할 뿐인데, 어떻게 tool call 형식의 출력을 생성하게 되는 걸까?

다음 편에서 이 모델 추론 과정을 살펴본다.

참고 문서

• Mistral - Tokenization & Tool Calling Deep Dive - control token 설계 철학, V2/V3/Tekken 비교
• HuggingFace - Chat Templates - apply_chat_template, 특수 토큰과 chat template의 관계
• Andrej Karpathy - Let’s Build the GPT Tokenizer - BPE 토크나이저 구축 강의