模板 | Twinkle

DeepSeek-V4 模板

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

DeepseekV4Template 为 DeepSeek V4 提供原生支持，包括其独特的思考模式、工具调用协议和多 token 特殊标记。

使用方法

from twinkle.template import DeepseekV4Template

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

特性

自定义 tokenizer 包装：用 DeepSeek V4 的编码协议覆盖 apply_chat_template
思考模式：支持 thinking / chat 模式切换
工具调用：原生 DSML 工具调用编码
多 token EOS：处理 DeepSeek V4 的多字符特殊标记

与基础模板的区别

特性	基础模板	DeepseekV4Template
Chat 模板	HuggingFace 原生	自定义 DSML 编码
思考模式	`<think>` 标签	原生思考模式开关
工具调用	Hermes/Qwen 格式	DSML 工具块
EOS 处理	单 token	多 token 特殊标记

工具调用解析器

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

Twinkle 的模板系统包含模块化的工具调用解析框架，用于训练具有函数调用能力的模型。

架构

ToolCallRegistry
├── HermesQwenParser — Hermes/Qwen 风格 <tool_call>...</tool_call>
├── ReActParser — ReAct Thought/Action/Observation
├── ClineParser — Cline XML 工具调用
└── VCPParser — VCP 协议

ToolCallParser 接口

from twinkle.template.tools import ToolCallParser

class ToolCallParser(ABC):
 name: str = ''

 def detect(self, text: str) -> bool:
 """检查文本是否包含此格式的标记"""

 def parse(self, text: str) -> List[Dict[str, Any]]:
 """提取 OpenAI 格式的工具调用"""

 def clean(self, text: str) -> str:
 """去除标记，返回纯内容"""

ToolCallRegistry

注册表自动发现解析器并路由检测：

from twinkle.template.tools import ToolCallRegistry

# 检测补全使用了哪种格式
parser = ToolCallRegistry.detect_first(completion_text)
if parser:
 tool_calls = parser.parse(completion_text)

内置解析器

解析器	格式说明
HermesQwenParser	`<tool_call>{"name": "...", "arguments": {...}}</tool_call>`
ReActParser	Thought/Action/Action Input/Observation
ClineParser	Cline XML 结构化参数
VCPParser	Visual Code Protocol

Template

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

模板是用于将 Trajectory 转换为 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]:
 # 批量编码样本
 ...

 def check(self, trajectory: Trajectory) -> Optional[Trajectory]:
 # 编码一条样本，并返回原样本
 # 一般用于在GRPO等RL算法中检查数据合理性
 ...

 def batch_check(self, trajectories: List[Trajectory]) -> List[Optional[Trajectory]]:
 # 批量检查样本
 ...

 def decode(self, token_ids: List[int], **kwargs) -> str:
 # 解码样本
 ...

 def batch_decode(self, token_ids: List[List[int]], **kwargs) -> List[str]:
 # 批量解码样本
 ...

model_id: 包含tokenizer或者processor的模型id
use_chat_template: 是否使用 chat_template。如果不使用，一般是预训练场景
max_length: 单样本的最大长度
truncation_strategy: 如果超过了最大长度，如何处理该样本
- raise: 抛出异常。一般用于非常精确的数据集场景
- left: 移除左边的 token，使其符合 max_length
- right: 移除右边的 token，使其符合 max_length
- split: 将超长样本切分为多个 max_length 的片段（不支持多模态、LazyDataset、IterablePackingDataset）
- delete: 直接丢弃超长样本
default_system: 如果数据集没有 system，则使用默认 system

Template 不支持使用函数来代替，因为其内部要支持的功能较多。如果需要编写新的 Template，请继承 Template 类。一般来说，纯文本模型使用 Template 基类就足够了，在基类中我们使用了 tokenizer.apply_chat_template 来编码模型，对一般的纯文本模型是通用的。

模板对应关系

目前模板关系较为简单：

Template类：纯文本模型通用
DeepseekV4Template类：DeepSeek V4 使用，重写了 chat template 编码逻辑，encode_messages 已内置在 twinkle 中
Qwen3_5Template类：Qwen3.5多模态模型使用