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 Studio 以 messages 格式的 JSONL 接受 ChatML 風格的對話:由 role 與 content 物件組成的清單,可選擇以一則 system 訊息開頭,接著是 user 與 assistant 的對話輪次。content 欄位中請勿放入 <|im_start|> 之類的原始範本標記。Studio 會在訓練時套用所選基礎模型自己的對話範本,因此同一份資料集既能訓練使用 ChatML 的模型,也能訓練使用其他範本的模型。

    Studio 的資料集編輯器 Data Craft 也以相同方式建立對話:以 USER 與 ASSISTANT 對話輪次呈現,可以編輯、保留版本並標記為已核准。

    Related Resources

    Ship AI that runs on your users' devices.

    Start free with 150 credits after card verification. Paid plans from $20/mo USD.