Template | Twinkle

DeepSeek-V4 Template

Mon, 01 Jan 0001 00:00:00 +0000

The DeepseekV4Template provides native support for DeepSeek V4’s custom chat template encoding, including its unique thinking mode, tool-call protocol, and multi-token special tokens.

Usage

from twinkle.template import DeepseekV4Template

template = DeepseekV4Template(
 model_id='deepseek-ai/DeepSeek-V4',
 enable_thinking=True,
)

Features

Custom tokenizer wrapper: Overrides apply_chat_template with DeepSeek V4’s encoding protocol
Thinking mode: Supports thinking / chat modes with configurable reasoning effort
Tool calls: Native DSML (DeepSeek Markup Language) tool-call encoding
Multi-token EOS: Handles DeepSeek V4’s multi-character special tokens

Thinking Modes

# Enable deep thinking (reasoning mode)
template = DeepseekV4Template(model_id='...', enable_thinking=True)

# Control reasoning effort
# 'max' or 'high' enables extended reasoning budget
template.encode(messages, reasoning_effort='max')

Tool Call Support

DeepSeek V4 uses its own DSML protocol for structured function calling:

messages = [
 {'role': 'user', 'content': 'What is the weather in Shanghai?'},
]
tools = [
 {'type': 'function', 'function': {'name': 'get_weather', 'parameters': {...}}}
]

features = template.encode(messages, tools=tools)

Key Differences from Base Template

Feature	Base Template	DeepseekV4Template
Chat template	HuggingFace native	Custom DSML encoding
Thinking	`<think>` tags	Native thinking mode toggle
Tool calls	Hermes/Qwen format	DSML tool blocks
EOS handling	Single token	Multi-token special markers

Tool Call Parsers

Mon, 01 Jan 0001 00:00:00 +0000

Twinkle’s template system includes a modular tool-call parsing framework for training models with function calling capabilities.

Architecture

ToolCallRegistry
├── HermesQwenParser — Hermes/Qwen style <tool_call>...</tool_call>
├── ReActParser — ReAct Thought/Action/Observation
├── ClineParser — Cline XML-based tool calls
└── VCPParser — VCP protocol

ToolCallParser Interface

from twinkle.template.tools import ToolCallParser

class ToolCallParser(ABC):
 name: str = ''
 open_marker: str | None = None
 close_marker: str | None = None

 def detect(self, text: str) -> bool:
 """Check if text contains this format's markup."""
 ...

 def parse(self, text: str) -> List[Dict[str, Any]]:
 """Extract tool calls in OpenAI format."""
 ...

 def clean(self, text: str) -> str:
 """Strip markup, return plain content."""
 ...

ToolCallRegistry

The registry auto-discovers parsers and routes detection:

from twinkle.template.tools import ToolCallRegistry

# Detect which format a completion uses
parser = ToolCallRegistry.detect_first(completion_text)
if parser:
 tool_calls = parser.parse(completion_text)
 clean_text = parser.clean(completion_text)

Built-in Parsers

HermesQwenParser

Parses Hermes/Qwen-style function calls:

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

ReActParser

Parses ReAct-style reasoning traces:

Thought: I need to check the weather
Action: get_weather
Action Input: {"city": "Shanghai"}
Observation: ...

ClineParser

Parses Cline XML-based tool invocations with structured parameters.

VCPParser

Parses VCP (Visual Code Protocol) tool calls.

Usage in Training

Tool call parsers integrate with the Template during preprocessing:

from twinkle.template import Template

template = Template(
 model_id='ms://Qwen/Qwen3.5-4B',
 enable_thinking=True,
)

# Template automatically uses ToolCallRegistry for
# tool-call aware tokenization during encoding
features = template.encode(messages, tools=tool_definitions)

Template

Mon, 01 Jan 0001 00:00:00 +0000

The template is a key component for converting Trajectory to InputFeature.

class Template:

 def __init__(self,
 model_id: str,
 use_chat_template: bool = True,
 max_length: Optional[int] = 8192,
 truncation_strategy: Literal['raise', 'left', 'right', 'split', 'delete'] = 'raise',
 default_system: Optional[str] = None):
 ...

 def batch_encode(self, trajectories: Union[Dict[str, Any], List[Trajectory]]) -> List[InputFeature]:
 # Batch encode samples
 ...

 def check(self, trajectory: Trajectory) -> Optional[Trajectory]:
 # Encode one sample and return the original sample
 # Generally used to check data reasonableness in RL algorithms like GRPO
 ...

 def batch_check(self, trajectories: List[Trajectory]) -> List[Optional[Trajectory]]:
 # Batch check samples
 ...

 def decode(self, token_ids: List[int], **kwargs) -> str:
 # Decode sample
 ...

 def batch_decode(self, token_ids: List[List[int]], **kwargs) -> List[str]:
 # Batch decode samples
 ...

model_id: Model id containing tokenizer or processor
use_chat_template: Whether to use chat_template. If not used, it is generally a pre-training scenario
max_length: Maximum length of a single sample
truncation_strategy: How to handle the sample if it exceeds the maximum length
- raise: Throw an exception. Generally used for very precise dataset scenarios
- left: Remove tokens on the left to conform to max_length
- right: Remove tokens on the right to conform to max_length
- split: Split the oversized sample into multiple max_length chunks (not supported for multimodal, LazyDataset, or IterablePackingDataset)
- delete: Drop the entire sample if it exceeds max_length
default_system: If the dataset does not have a system message, use the default system

Template does not support using functions as replacements because it needs to support many functions internally. If you need to write a new Template, please inherit the Template class. Generally speaking, using the Template base class is sufficient for pure text models. In the base class, we use tokenizer.apply_chat_template to encode the model, which is universal for general pure text models.

Template mapping

Currently, the model-template mapping is simple:

Template class: Supported in all pure text LLMs.
DeepseekV4Template class: For DeepSeek V4, rewrites the chat template encoding logic, encode_messages is built into twinkle.
Qwen3_5Template class: For Qwen3.5 MLLMs.

Template

The template is a key component for converting Trajectory to InputFeature.

class Template:

 def __init__(self,
 model_id: str,
 use_chat_template: bool = True,
 max_length: Optional[int] = 8192,
 truncation_strategy: Literal['raise', 'left', 'right', 'split'] = 'raise',
 default_system: Optional[str] = None):
 ...

 def batch_encode(self, trajectories: Union[Dict[str, Any], List[Trajectory]]) -> List[InputFeature]:
 # Batch encode samples
 ...

 def check(self, trajectory: Trajectory) -> Optional[Trajectory]:
 # Encode one sample and return the original sample
 # Generally used to check data reasonableness in RL algorithms like GRPO
 ...

 def batch_check(self, trajectories: List[Trajectory]) -> List[Optional[Trajectory]]:
 # Batch check samples
 ...

 def decode(self, token_ids: List[int], **kwargs) -> str:
 # Decode sample
 ...

 def batch_decode(self, token_ids: List[List[int]], **kwargs) -> List[str]:
 # Batch decode samples
 ...

model_id: Model id containing tokenizer or processor
use_chat_template: Whether to use chat_template. If not used, it is generally a pre-training scenario
max_length: Maximum length of a single sample
truncation_strategy: How to handle the sample if it exceeds the maximum length
- raise: Throw an exception. Generally used for very precise dataset scenarios
- left: Remove tokens on the left to conform to max_length
- right: Remove tokens on the right to conform to max_length
- default_system: If the dataset does not have a system, use the default system

Template does not support using functions as replacements because it needs to support many functions internally. If you need to write a new Template, please inherit the Template class. Generally speaking, using the Template base class is sufficient for pure text models. In the base class, we use tokenizer.apply_chat_template to encode the model, which is universal for general pure text models.

Template mapping

Currently, the model-template mapping is simple:

Template class：Supported in all pure text LLMs.
Qwen3_5Template class: For Qwen3.5 MLLMs.