ChatML Format Guide

    用於結構化 LLM 對話的聊天標記語言

    Conversation

    Specification

    ChatML(Chat Markup Language,聊天標記語言)是一種結構化文字格式,用於表示與大型語言模型的多輪對話。最初由 OpenAI 推出並在整個產業中被採用,ChatML 使用特殊標記來分隔訊息邊界和角色識別符,提供了一種明確的方式將對話編碼為單一標記序列,用於模型訓練和推論。該格式確保模型能可靠地區分系統指令、使用者輸入和助手回應,即使訊息內容包含可能與結構元素混淆的文字。

    ChatML 格式用特殊標記分隔符包裝每條訊息。每條訊息以起始標記開頭,後跟角色識別符和換行符,包含訊息正文,並以結束標記結尾。標準角色為「system」(行為指令)、「user」(人類輸入)和「assistant」(模型回應)。某些實作以額外角色進行擴展,如「tool」用於函數呼叫結果或「ipython」用於程式碼執行輸出。特殊標記(通常呈現為 <|im_start|> 和 <|im_end|>)在訓練期間添加到模型的詞彙表中,永遠不會作為常規文字輸出的一部分生成。

    ChatML 已成為許多開源模型的預設聊天範本,包括 Qwen、Yi 和使用 OpenAI 相容格式微調的模型。Hugging Face Transformers 程式庫使用基於 Jinja2 的聊天範本在結構化訊息列表和 ChatML 格式文字之間進行轉換,每個模型的分詞器指定其自己的範本。這種標準化使不同模型供應商和推論框架之間的行為保持一致,因為結構化格式消除了一條訊息在何處結束和另一條訊息在何處開始的歧義。

    When to Use ChatML

    當您的目標模型使用 ChatML 聊天範本時,請使用 ChatML——這包括 Qwen 系列模型、Yi 系列模型以及許多基於 OpenAI 對話格式的社群微調模型。如果您的訓練框架(Axolotl、LLaMA-Factory、TRL)期望您指定聊天範本,且您的基礎模型是使用 ChatML 進行預訓練或指令微調的,您應該以 ChatML 格式準備訓練資料或使用可轉換為 ChatML 的結構化格式。

    當您需要明確的訊息邊界偵測時,選擇 ChatML 而非原始文字或臨時提示格式。特殊標記分隔符確保模型永遠不會將訊息內容與結構標記混淆,這對安全性(防止提示注入)和可靠性(確保多輪對話中的正確輪次交替)至關重要。當您的部署使用 OpenAI 相容的 API 格式時,ChatML 也是首選格式,因為結構化訊息列表直接對應到 ChatML 編碼。

    當您的目標模型使用不同的聊天範本時,ChatML 的相關性較低(LLaMA 使用不同的格式,Mistral 使用自己的標記)。在這些情況下,使用模型的原生範本。對於更簡單的格式如 Alpaca 即可滿足的單輪任務,或者當您的訓練框架自動從結構化對話資料(ShareGPT 格式)處理範本套用時,該格式也是不必要的。

    Schema / Structure

    text
    ChatML Token Structure:
    <|im_start|>system
    {system_message}<|im_end|>
    <|im_start|>user
    {user_message}<|im_end|>
    <|im_start|>assistant
    {assistant_message}<|im_end|>
    
    Special Tokens:
      <|im_start|>  - Message start delimiter
      <|im_end|>    - Message end delimiter
    
    Roles:
      system     - Behavioral instructions (optional, first message)
      user       - Human/user input
      assistant  - Model/AI response
      tool       - Tool/function call result (extended format)
    
    Jinja2 Chat Template (HuggingFace):
    {% for message in messages %}
    <|im_start|>{{ message.role }}
    {{ message.content }}<|im_end|>
    {% endfor %}
    <|im_start|>assistant
    ChatML 格式規格,包含特殊標記、角色和 Jinja2 範本

    Example Data

    text
    <|im_start|>system
    You are a senior software engineer who provides concise, practical code reviews.<|im_end|>
    <|im_start|>user
    Please review this Python function:
    
    def get_user(id):
        conn = sqlite3.connect('app.db')
        cursor = conn.cursor()
        cursor.execute(f"SELECT * FROM users WHERE id = {id}")
        return cursor.fetchone()<|im_end|>
    <|im_start|>assistant
    This function has several critical issues:
    
    1. **SQL Injection vulnerability**: Using f-string interpolation in SQL queries is dangerous. Use parameterized queries instead:
    ```python
    cursor.execute("SELECT * FROM users WHERE id = ?", (id,))
    ```
    
    2. **Resource leak**: The database connection is never closed. Use a context manager:
    ```python
    with sqlite3.connect('app.db') as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM users WHERE id = ?", (id,))
        return cursor.fetchone()
    ```
    
    3. **Hardcoded database path**: Move 'app.db' to a configuration variable.
    
    4. **No error handling**: Add try/except for database errors and handle the case where no user is found.<|im_end|>
    <|im_start|>user
    Good points. Can you show the corrected version?<|im_end|>
    <|im_start|>assistant
    ```python
    import sqlite3
    from typing import Optional, Tuple
    
    def get_user(user_id: int, db_path: str = "app.db") -> Optional[Tuple]:
        try:
            with sqlite3.connect(db_path) as conn:
                cursor = conn.cursor()
                cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
                return cursor.fetchone()
        except sqlite3.Error as e:
            logging.error(f"Database error fetching user {user_id}: {e}")
            return None
    ```
    
    Key improvements: parameterized query, context manager, type hints, configurable DB path, error handling, and renamed parameter to avoid shadowing the built-in `id`.<|im_end|>
    帶有系統提示的 ChatML 格式多輪程式碼審查對話

    Ertas Support

    Ertas Data Suite 支援 ChatML 作為對話訓練資料的匯入和匯出格式。您可以匯入 ChatML 格式的文字資料集、在保留特殊標記結構的同時套用 PII 編輯,並匯出具有完整訊息邊界的已處理對話。平台驗證 ChatML 結構,包括正確的標記配對、有效的角色識別符和正確的訊息交替模式。

    Ertas Studio 在微調使用 ChatML 聊天範本的模型時自動處理 ChatML 範本套用,在訓練資料準備期間將結構化對話資料轉換為正確分詞的 ChatML 序列。

    Related Resources

    Ship AI that runs on your users' devices.

    Early bird pricing starts at $14.50/mo — locked in for life. Plans for builders and agencies.