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:

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:

<|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ı

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:

cd custom-chat-template

Bir sanal ortam oluşturun:

python3 -m venv .venv

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

source .venv/bin/activate

Gerekli paketleri yükleyin:

pip install -r requirements.txt

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

python test_template.py

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

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

Test edilen senaryolar:

Normal sohbet
Developer mesajı
Tool calling
Çok modlu içerik
Özel BOS ve EOS tokenları
Art arda iki user mesajı
Desteklenmeyen rol
Konuşma başladıktan sonra gelen system mesajı

Hugging Face Uyumluluk Testi

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ı:

######################################################################
✅ 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:

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:

<|available_tools|>
...
<|end_available_tools|>

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

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

Araçtan dönen sonuç:

<|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:

{
    "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:

<|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:

<bos>
...
<eos>

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

<|begin_of_chat|>
<|end_message|>

Generation Prompt

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

<|assistant|>

eklenir.

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

Kullanım Örneği

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

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ı

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support