README_template.md

Özel Chat Template (Jinja2)

Bir dil modelinin system, user, assistant ve tool rollerini ayırt edebilmesi ve tool calling (function calling) yapabilmesi için hazırlanmış Jinja2 sohbet şablonu.

Chat template nedir?

Dil modelleri mesaj listesi göremez; yalnızca düz metin (token dizisi) işler. Kod tarafında şöyle bir yapı kullanılır:

[
  {"role": "user", "content": "Merhaba"},
  {"role": "assistant", "content": "Selam!"}
]

Chat template bu yapıyı modelin anlayacağı düz metne çevirir:

<|im_start|>mustafa
Merhaba<|im_end|>
<|im_start|>AI
Selam!<|im_end|>

Her model eğitim sırasında belirli bir biçim görür; çıkarımda da aynı biçimi bekler. Biçim uyuşmazsa model beklenmedik davranır.

Bu şablonun özellikleri

Özellik	Açıklama
Rol dönüşümü	user → mustafa, assistant → AI
Araç tanımları	tools listesi sistem bloğuna JSON olarak gömülür
Araç çağrısı	Assistant mesajındaki tool_calls alanı <tool_call> etiketleriyle sarmalanır
Çoklu çağrı	Model aynı turda birden fazla araç çağırabilir
Araç sonucu	tool rolü <tool_response> etiketleriyle sarmalanır
Üretim istemi	add_generation_prompt ile son satır açık bırakılır
Doğrulama	Bilinmeyen rol gelirse hata fırlatılır

Rol eşlemesi

Şablon, standart rol adlarını kendi adlarına çevirir:

Standart (kodda kullanılan)	Şablonda üretilen
system	system
user	mustafa
assistant	AI
tool	tool

Bu sayede kod tarafında OpenAI/Hugging Face standardı korunur; dönüşümü şablon yapar. Model değiştirildiğinde uygulama kodunu değiştirmek gerekmez.

Örnek çıktı

Girdi:

messages = [
    {"role": "system", "content": "Sen yardımcı bir asistansın."},
    {"role": "user", "content": "Ankara'da hava nasıl?"},
    {"role": "assistant", "content": None, "tool_calls": [
        {"function": {"name": "get_weather", "arguments": {"city": "Ankara"}}}
    ]},
    {"role": "tool", "content": '{"sehir": "Ankara", "sicaklik_c": 27}'},
    {"role": "assistant", "content": "Ankara'da hava 27°C."},
]

Çıktı:

<|im_start|>system
Sen yardımcı bir asistansın.

Kullanabileceğin araçlar:
<tools>
{"name": "get_weather", "description": "Bir şehrin güncel hava durumunu döndürür.", "parameters": {...}}
</tools>

Bir aracı çağırmak için şu biçimi kullan:
<tool_call>
{"name": "araç_adı", "arguments": {...}}
</tool_call><|im_end|>
<|im_start|>mustafa
Ankara'da hava nasıl?<|im_end|>
<|im_start|>AI
<tool_call>
{"name": "get_weather", "arguments": {"city": "Ankara"}}
</tool_call><|im_end|>
<|im_start|>tool
<tool_response>
{"sehir": "Ankara", "sicaklik_c": 27}
</tool_response><|im_end|>
<|im_start|>AI
Ankara'da hava 27°C.<|im_end|>

Kullanım

Hugging Face tokenizer ile

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("model-adi")
tokenizer.chat_template = open("chat_template.jinja", encoding="utf-8").read()

metin = tokenizer.apply_chat_template(
    messages,
    tools=tools,
    add_generation_prompt=True,   # çıkarımda True, eğitimde False
    tokenize=False,
)

Şablonu modelle birlikte yayınlamak için chat_template.jinja dosyasını model deposuna eklemek yeterlidir.

Doğrudan Jinja2 ile

from jinja2 import Environment

env = Environment()
env.globals["raise_exception"] = lambda m: (_ for _ in ()).throw(ValueError(m))
env.policies["json.dumps_kwargs"] = {"ensure_ascii": False, "sort_keys": False}

sablon = env.from_string(open("chat_template.jinja", encoding="utf-8").read())
print(sablon.render(messages=messages, tools=tools, add_generation_prompt=True))

ensure_ascii=False ayarı önemlidir: Türkçe karakterlerin \u015f gibi kaçış dizilerine dönüşmesini engeller ve gereksiz token harcanmasını önler.

add_generation_prompt nedir?

Aynı şablon iki farklı amaçla kullanılır:

Eğitimde (False) — konuşma tamamlanmıştır, model bunu öğrenecektir:

<|im_start|>mustafa
Nasılsın?<|im_end|>
<|im_start|>AI
İyiyim!<|im_end|>

Çıkarımda (True) — son satır açık bırakılır, model buradan devam eder:

<|im_start|>mustafa
Nasılsın?<|im_end|>
<|im_start|>AI

Bu açık satır olmazsa model ne yapacağını bilemez; kendi kullanıcı mesajı uydurabilir veya konuşmayı sonlandırabilir.

Test

pip install jinja2
python test_template.py

Test scripti beş senaryoyu kontrol eder:

1. Basit konuşma (araçsız)
2. Üretim istemi davranışı
3. Tam tool calling akışı (çok turlu, çoklu çağrı)
4. Sistem mesajı olmadan araç kullanımı
5. Geçersiz rol reddi

Ayrıca sekiz doğrulama yapar: HTML kaçışı olmaması, Türkçe karakterlerin korunması, rol dönüşümleri, etiket sarmalama ve üretilen JSON'ların ayrıştırılabilir olması.

Dosyalar

Dosya	İçerik
chat_template.jinja	Şablonun kendisi
test_template.py	Test ve doğrulama scripti
README.md	Bu dosya

Lisans

MIT