berkbirkan/custom-chat-template

Custom ChatML Tool-Calling Template

Bu depo, bir dil modelinin system, user, assistant ve tool mesajlarını birbirinden ayırması için hazırlanmış özel bir Hugging Face/Jinja2 sohbet şablonu içerir.

Tasarım

Şablon ChatML rol sınırlarını kullanır:

<|im_start|>system
Sistem mesajı<|im_end|>
<|im_start|>user
Kullanıcı mesajı<|im_end|>
<|im_start|>assistant
Asistan yanıtı<|im_end|>

Araç tanımları OpenAI uyumlu JSON Schema biçiminde <tools> bloğuna eklenir. Asistanın araç isteği <tool_call>, dış sistemin gerçek cevabı ise <tool_response> içinde serileştirilir.

<tool_call>
{"name":"get_weather","arguments":{"city":"İstanbul"}}
</tool_call>

Bu ayrım modelin bir aracı çalıştırmadığını, yalnızca uygulamanın çalıştırması için yapılandırılmış bir istek ürettiğini açık tutar.

Desteklenen özellikler

• system, user, assistant ve tool rolleri
• OpenAI uyumlu tools listesi
• Tek veya birden fazla assistant tool_calls kaydı
• Metin veya JSON biçimindeki tool sonuçları
• add_generation_prompt
• System mesajı bulunmadığında araçlar için güvenli varsayılan system mesajı
• Bilinmeyen roller ve hatalı tool çağrıları için açık Jinja hataları

Dosyalar

• chat_template.jinja: Teslim edilen asıl sohbet şablonu
• examples/basic_chat.json: Normal konuşma örneği
• examples/tool_call_chat.json: Uçtan uca tool-calling örneği
• tests/test_chat_template.py: Render ve doğrulama testleri

Transformers ile kullanım

Şablon bir tokenizer'a atanabilir:

from pathlib import Path
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("MODEL_ID")
tokenizer.chat_template = Path("chat_template.jinja").read_text()

rendered = tokenizer.apply_chat_template(
    messages,
    tools=tools,
    tokenize=False,
    add_generation_prompt=True,
)
print(rendered)

Kullanılan model/tokenizer <|im_start|> ve <|im_end|> özel tokenlarını tanımalıdır. Farklı özel tokenlara sahip bir modelde bu iki sınır tokenı modelin kendi tokenlarıyla değiştirilmelidir. Bir chat template modeli yeni bir formata tek başına eğitmez; üretimde şablonun modelin eğitim formatıyla eşleşmesi gerekir.

Testler

Python 3.9 veya üzeriyle:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest

Testler rol sınırlarını, tool tanımlarını, tool çağrı/cevaplarını, generation prompt davranışını ve geçersiz girdilerde hata üretimini doğrular.

Güvenlik ve halüsinasyon notu

Şablon, tool yanıtını assistant mesajından ayrı tutar ve varsayılan system mesajında gerçek tool sonucu uydurulmamasını söyler. Bununla birlikte gerçek bir uygulama tool çağrısını ayrıca doğrulamalı, aracı kendi kodunda çalıştırmalı ve yalnızca doğrulanmış sonucu modele tool mesajı olarak geri vermelidir.

Lisans

Eğitim ve ödev amacıyla MIT Lisansı altında sunulmuştur.