| # Ö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: |
|
|
| ```python |
| [ |
| {"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:** |
|
|
| ```python |
| 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 |
|
|
| ```python |
| 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 |
|
|
| ```python |
| 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 |
|
|
| ```bash |
| 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 |
|
|
