BroadRouter
시작하기

채팅 템플릿(chat template)

업데이트

채팅 템플릿은 역할이 붙은 채팅 메시지 목록을 모델이 기대하는 단일 토큰 시퀀스로 바꾸는 서식 규칙으로, 모델 고유의 특수 제어 토큰까지 포함합니다. 보통 Jinja로 작성되어 모델의 토크나이저와 함께 배포됩니다. 잘못된 템플릿을 쓰면 모델의 답변 품질이 크게 떨어질 수 있습니다.

다른 이름: 챗 템플릿, 대화 템플릿, Jinja 채팅 템플릿, 토크나이저 채팅 템플릿, chat_template, Jinja chat template, tokenizer chat template

채팅 모델은 메시지 목록을 보지 않습니다. 하나로 길게 이어진 토큰열을 봅니다. 그 토큰열의 모양을 정하는 것이 채팅 템플릿입니다.

작동 방식

Hugging Face 가이드는 핵심을 이렇게 설명합니다. 모든 인과적 언어 모델은 “continue a sequence of tokens”(번역: 토큰 시퀀스를 이어 간다)이며, 전달하는 역할과 내용의 딕셔너리는 “get converted to a token sequence, often with control tokens”(번역: 대개 제어 토큰과 함께 토큰 시퀀스로 변환된다). 모델마다 형식이 다르며, “even if they were fine-tuned from the same base model”(번역: 같은 기본 모델에서 파인튜닝되었더라도) 그렇습니다.

가이드에 나오는, 같은 짧은 대화를 두 템플릿으로 렌더링한 결과입니다.

Mistral-7B-Instruct:
<s>[INST] Hello, how are you? [/INST]I'm doing great. How can I help you today?</s>

Zephyr-7B:
<|user|>
Hello, how are you?</s>
<|assistant|>
I'm doing great. How can I help you today?</s>

Transformers에서는 tokenizer.apply_chat_template(messages, add_generation_prompt=True)로 대화를 렌더링합니다. add_generation_prompt 플래그는 어시스턴트 턴을 여는 토큰을 추가합니다. 가이드는 이 토큰이 없으면 모델이 답하는 대신 사용자의 메시지를 이어 쓸 수 있다고 경고합니다.

템플릿에는 모델 기능도 담길 수 있습니다. Google의 Gemma 4 카드에 따르면 시스템 프롬프트 맨 앞에 <|think|> 토큰을 넣으면 사고(thinking) 기능이 켜지며, “many libraries like Transformers and llama.cpp handle the complexities of the chat template for you.”(번역: Transformers나 llama.cpp 같은 많은 라이브러리가 채팅 템플릿의 복잡한 부분을 대신 처리한다)라고 합니다.

왜 중요한가

  • 품질. 가이드는 “with the wrong control tokens, these models would have drastically worse performance.”(번역: 제어 토큰이 잘못되면 이 모델들의 성능은 크게 나빠진다)라고 말합니다.
  • 셀프 호스팅. 서빙 엔진이 채팅 요청을 받으려면 템플릿이 필요합니다. vLLM 문서는 템플릿이 없으면 “all chat requests will error”(번역: 모든 채팅 요청이 오류가 난다)라고 하며, --chat-template로 템플릿을 지정할 수 있게 합니다. vLLM을 참고하세요.
  • 토큰 수. 제어 토큰도 입력 토큰으로 셉니다. 로컬에서 센 값과 과금된 값이 다른 이유는 보내기 전에 토큰 세기 글에서 다룹니다.
  • 특수 토큰 중복. 가이드는 템플릿 적용 후 <bos>나 <eos>를 또 붙이는 것은 “is often incorrect or duplicated, hurting model performance”(번역: 잘못되었거나 중복된 경우가 많아 모델 성능을 해친다)라고 경고합니다.
  • 시스템 프롬프트도 템플릿의 일부입니다. 시스템 메시지가 어디에 들어가는지, 모델에 시스템 역할이 아예 있는지도 템플릿이 정합니다.

BroadNet Inference에서는

BroadNet API는 OpenAI 호환 Chat Completions 엔드포인트이므로, messages를 보내면 BroadNet이 템플릿을 적용합니다. 원시 템플릿 텍스트를 보낼 일은 없습니다. BroadNet은 Gemma 4 VL 26B를 대화형 워크플로에 맞게 조정한 “BroadNet conversational chat template”(번역: BroadNet 대화형 채팅 템플릿)으로 서빙한다고 보고합니다. BroadNet의 Gemma와 같은 가중치를 로컬에서 돌린 결과를 비교하면 답이 다를 수 있으니, 직접 쓰는 프롬프트로 테스트하세요. BroadNet은 다른 모델의 템플릿 세부 사항은 공개하지 않습니다. GPU 플릿과 서빙 글에 Gemma의 다른 서빙 설정이 나와 있습니다.

자주 묻는 질문

API를 호출할 때 채팅 템플릿을 직접 적용해야 하나요?

아니요. Chat Completions API에서는 messages 목록을 보내면 제공업체가 자기 쪽에서 템플릿을 적용합니다. 템플릿을 직접 다루는 것은 모델을 로컬에서 실행하거나 원시 텍스트 완성 엔드포인트를 호출할 때뿐입니다.

내가 센 토큰 수가 왜 제공업체와 다른가요?

템플릿이 메시지마다 앞뒤로 제어 토큰을 붙이기 때문입니다. 메시지 텍스트만 세면 이 토큰이 빠지므로, 과금되는 프롬프트는 보통 조금 더 큽니다.

add_generation_prompt는 무슨 역할을 하나요?

어시스턴트 턴을 시작하는 토큰을 끝에 붙여, 모델이 내 메시지를 이어 쓰지 않고 답하게 합니다. Hugging Face 문서는 ChatML 계열 템플릿에서 이를 끝에 붙는 <|im_start|>assistant로 보여 줍니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기