---
language:
- tr
tags:
- chat-template
- jinja2
- tool-calling
- multimodal
- transformers
- gemma
---

# Advanced Custom Chat Template — Jinja2

Bu proje, Hugging Face Transformers kütüphanesiyle kullanılmak üzere
hazırlanmış gelişmiş bir **Custom Chat Template** çalışmasıdır.

Şablon; kullanıcı, sistem, geliştirici, asistan ve araç mesajlarını
birbirinden ayırarak sohbet verisini dil modelinin işleyebileceği tek bir
metin veya token dizisine dönüştürür.

Proje, Custom Chat Template hazırlama ödevi kapsamında geliştirilmiştir.

## Projenin Amacı

Dil modellerine verilen sohbetler çoğunlukla aşağıdaki gibi bir mesaj
listesiyle temsil edilir:

```python
messages = [
    {
        "role": "system",
        "content": "Sen Türkçe cevap veren yardımcı bir asistansın.",
    },
    {
        "role": "user",
        "content": "Türkiye'nin başkenti neresidir?",
    },
]
```

Dil modeli bu Python sözlüklerini doğrudan işlemez. Chat template,
mesaj listesini aşağıdakine benzer tek bir metin hâline getirir:

```text
<|begin_of_chat|>
<|system|>
Sen Türkçe cevap veren yardımcı bir asistansın.
<|end_message|>
<|user|>
Türkiye'nin başkenti neresidir?
<|end_message|>
<|assistant|>
```

Sondaki `<|assistant|>` etiketi, sıradaki cevabın model tarafından
üretilmesi gerektiğini belirtir.

## Desteklenen Roller

Şablon aşağıdaki rolleri destekler:

| Rol | Açıklama |
|---|---|
| `system` | Modelin genel davranışını belirleyen sistem talimatı |
| `developer` | Uygulama geliştiricisine ait ek talimatlar |
| `user` | Kullanıcı tarafından gönderilen mesaj |
| `assistant` | Dil modeli veya asistan tarafından oluşturulan mesaj |
| `tool` | Bir araç çağrısından dönen sonuç |

Desteklenmeyen bir rol kullanıldığında şablon açıklayıcı bir hata üretir.

## Temel Özellikler

- System, developer, user, assistant ve tool rolleri
- BOS ve EOS token desteği
- Token bulunmadığında yedek kontrol tokenları
- `add_generation_prompt` desteği
- Tool tanımlarının modele aktarılması
- Assistant tool çağrılarının biçimlendirilmesi
- Tool sonuçlarının biçimlendirilmesi
- Çoklu tool çağrısı desteği
- Metin, görsel, ses ve video içerikleri
- Mesaj sırası doğrulaması
- Hatalı ve desteklenmeyen rollerin reddedilmesi
- Hugging Face `apply_chat_template()` uyumluluğu
- Tokenizasyon ve dışa aktarma testi

## Proje Yapısı

```text
custom-chat-template/
├── chat_template.jinja
├── test_template.py
├── test_huggingface.py
├── requirements.txt
├── README.md
└── .gitignore
```

### `chat_template.jinja`

Custom Jinja2 sohbet şablonudur. Mesaj rollerini, içerikleri, tool
çağrılarını ve özel kontrol tokenlarını işler.

### `test_template.py`

Template'i doğrudan Jinja2 ortamında test eder. Başarılı ve hatalı
senaryolardan oluşan toplam sekiz otomatik test içerir.

### `test_huggingface.py`

Şablonu Hugging Face Transformers kütüphanesinin gerçek
`apply_chat_template()` fonksiyonuyla test eder.

Ayrıca:

- Template'i düz metne dönüştürür.
- Sohbeti gerçek token ID'lerine dönüştürür.
- Tokenizer ile birlikte template'i dışa aktarır.
- Kaydedilen template ile kaynak template'i karşılaştırır.

## Kurulum

Projeyi indirdikten sonra proje klasörüne girin:

```bash
cd custom-chat-template
```

Bir sanal ortam oluşturun:

```bash
python3 -m venv .venv
```

macOS veya Linux üzerinde sanal ortamı etkinleştirin:

```bash
source .venv/bin/activate
```

Gerekli paketleri yükleyin:

```bash
pip install -r requirements.txt
```

## Jinja2 Testlerinin Çalıştırılması

```bash
python test_template.py
```

Başarılı bir çalıştırmanın sonunda aşağıdaki sonuç görülür:

```text
######################################################################
TEST ÖZETİ
######################################################################
Başarılı test: 8/8
🎉 Bütün testler başarıyla tamamlandı.
```

Test edilen senaryolar:

1. Normal sohbet
2. Developer mesajı
3. Tool calling
4. Çok modlu içerik
5. Özel BOS ve EOS tokenları
6. Art arda iki user mesajı
7. Desteklenmeyen rol
8. Konuşma başladıktan sonra gelen system mesajı

## Hugging Face Uyumluluk Testi

```bash
python test_huggingface.py
```

Bu testte `google/gemma-2-9b-it` modelinin yalnızca tokenizer dosyaları
kullanılır. Model ağırlıkları indirilmez ve model inference işlemi
yapılmaz.

Başarılı test çıktısı:

```text
######################################################################
✅ CUSTOM TEMPLATE HUGGING FACE İLE BAŞARIYLA ÇALIŞTI
######################################################################
```

Gerçekleştirilen kontroller:

- Custom template'in tokenizer'a atanması
- `apply_chat_template()` ile metin oluşturulması
- Tool calling mesajlarının işlenmesi
- Mesajların token ID'lerine dönüştürülmesi
- Template'in tokenizer ile birlikte kaydedilmesi
- Kaydedilen template'in kaynak dosyayla karşılaştırılması

## Tool Calling Formatı

Araçlar template'e `tools` parametresi aracılığıyla verilir:

```python
tools = [
    {
        "type": "function",
        "function": {
            "name": "multiply",
            "description": "Verilen iki sayıyı çarpar.",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"},
                },
                "required": ["a", "b"],
            },
        },
    }
]
```

Template bu tanımı aşağıdaki kontrol tokenlarıyla sarar:

```text
<|available_tools|>
...
<|end_available_tools|>
```

Assistant tarafından yapılan bir araç çağrısı:

```text
<|tool_call|>
{
    "id": "call_001",
    "type": "function",
    "function": {
        "name": "multiply",
        "arguments": {
            "a": 12,
            "b": 8
        }
    }
}
<|end_tool_call|>
```

Araçtan dönen sonuç:

```text
<|tool_result|>
{
    "role": "tool",
    "name": "multiply",
    "content": "96"
}
<|end_tool_result|>
```

## Çok Modlu İçerik Desteği

Mesaj içeriği yalnızca düz metin olmak zorunda değildir.

Örnek:

```python
{
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Bu görseli ve sesi incele:",
        },
        {
            "type": "image",
        },
        {
            "type": "audio",
        },
        {
            "type": "video",
        },
    ],
}
```

Bu içerik aşağıdaki özel tokenlara dönüştürülür:

```text
<|image|>
<|audio|>
<|video|>
```

## Mesaj Doğrulama Kuralları

Template aşağıdaki hatalı durumları kontrol eder:

- Art arda iki `user` mesajı gönderilmesi
- Geçersiz bir mesaj rolünün kullanılması
- Konuşma başladıktan sonra `system` veya `developer` mesajı gelmesi
- Bekleyen tool çağrısı olmadan tool sonucu gönderilmesi
- Tool sonucundan sonra doğrudan yeni user mesajı gönderilmesi
- Assistant mesajının geçersiz bir rolden sonra gelmesi
- Desteklenmeyen çok modlu içerik türü kullanılması
- Mesajda `role` veya gerekli `content` alanının bulunmaması

## BOS ve EOS Tokenları

Tokenizer bir başlangıç veya bitiş tokenı sağlıyorsa bu tokenlar
otomatik olarak kullanılır.

Gemma 2 tokenizer örneği:

```text
<bos>
...
<eos>
```

Tokenizer özel token sağlamazsa aşağıdaki yedek tokenlar kullanılır:

```text
<|begin_of_chat|>
<|end_message|>
```

## Generation Prompt

`add_generation_prompt=True` kullanıldığında sohbetin sonuna:

```text
<|assistant|>
```

eklenir.

Bu ifade, konuşmadaki sıradaki mesajın assistant tarafından
oluşturulacağını belirtir.

## Kullanım Örneği

```python
from pathlib import Path

from transformers import AutoTokenizer


tokenizer = AutoTokenizer.from_pretrained(
    "google/gemma-2-9b-it"
)

template = Path(
    "chat_template.jinja"
).read_text(encoding="utf-8")

tokenizer.chat_template = template

messages = [
    {
        "role": "system",
        "content": "Sorulara Türkçe cevap ver.",
    },
    {
        "role": "user",
        "content": "Merhaba!",
    },
]

rendered_chat = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)

print(rendered_chat)
```

## Önemli Uyumluluk Notu

Bu proje, chat template mekanizmasını göstermek amacıyla hazırlanmış
genel amaçlı ve eğitim odaklı bir şablondur.

Template, Gemma 2 tokenizer ile teknik olarak test edilmiştir. Ancak
gerçek bir dil modelinden en iyi üretim performansını almak için kontrol
tokenlarının ve konuşma formatının modelin eğitim sırasında kullandığı
doğal chat formatıyla eşleşmesi gerekir.

Yeni özel tokenlar kullanılarak model eğitilecekse ilgili tokenların
tokenizer sözlüğüne özel token olarak eklenmesi gerekebilir.

## Test Sonuçları

| Test | Sonuç |
|---|---|
| Doğrudan Jinja2 testi | Başarılı |
| Normal sohbet | Başarılı |
| Developer rolü | Başarılı |
| Tool calling | Başarılı |
| Çok modlu içerik | Başarılı |
| BOS/EOS tokenları | Başarılı |
| Hatalı rol kontrolleri | Başarılı |
| Hugging Face render testi | Başarılı |
| Hugging Face tokenizasyon testi | Başarılı |
| Template dışa aktarma testi | Başarılı |
| Gemma 2 9B tokenizer testi | Başarılı |


## Proje Durumu

```text
Jinja2 otomatik testleri: 8/8 başarılı
Hugging Face uyumluluk testi: Başarılı
Gemma 2 9B tokenizer testi: Başarılı
Tool calling testi: Başarılı
Multimodal içerik testi: Başarılı
```