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