一、框架概述

LLaMA-Factory 框架通過Alpaca/Sharegpt雙格式體系實現多任務適配，其中Alpaca專注結構化指令微調（含SFT/DPO/預訓練），Sharegpt支持多角色對話及多模態數據集成。核心配置依托 dataset_info.json 實現數據源映射、格式定義（formatting）、列名綁定（columns）及角色標簽（tags）設置，需特別注意多模態路徑與文本標記的嚴格匹配。優先級規則遵循：云端倉庫 > 本地腳本 > 文件直讀，配置時須規避角色標簽沖突和路徑驗證疏漏等常見誤區。

二、數據集配置規范

"數據集名稱": {"hf_hub_url": "Hugging Face 的數據集倉庫地址（若指定，則忽略 script_url 和 file_name）","ms_hub_url": "ModelScope 的數據集倉庫地址（若指定，則忽略 script_url 和 file_name）","script_url": "包含數據加載腳本的本地文件夾名稱（若指定，則忽略 file_name）","file_name": "該目錄下數據集文件夾或文件的名稱（若上述參數未指定，則此項必需）","formatting": "數據集格式（可選，默認：alpaca，可以為 alpaca 或 sharegpt）","ranking": "是否為偏好數據集（可選，默認：False）","subset": "數據集子集的名稱（可選，默認：None）","split": "所使用的數據集切分（可選，默認：train）","folder": "Hugging Face 倉庫的文件夾名稱（可選，默認：None）","num_samples": "該數據集所使用的樣本數量。（可選，默認：None）","columns（可選）": {"prompt": "數據集代表提示詞的表頭名稱（默認：instruction）","query": "數據集代表請求的表頭名稱（默認：input）","response": "數據集代表回答的表頭名稱（默認：output）","history": "數據集代表歷史對話的表頭名稱（默認：None）","messages": "數據集代表消息列表的表頭名稱（默認：conversations）","system": "數據集代表系統提示的表頭名稱（默認：None）","tools": "數據集代表工具描述的表頭名稱（默認：None）","images": "數據集代表圖像輸入的表頭名稱（默認：None）","videos": "數據集代表視頻輸入的表頭名稱（默認：None）","audios": "數據集代表音頻輸入的表頭名稱（默認：None）","chosen": "數據集代表更優回答的表頭名稱（默認：None）","rejected": "數據集代表更差回答的表頭名稱（默認：None）","kto_tag": "數據集代表 KTO 標簽的表頭名稱（默認：None）"},"tags（可選，用于 sharegpt 格式）": {"role_tag": "消息中代表發送者身份的鍵名（默認：from）","content_tag": "消息中代表文本內容的鍵名（默認：value）","user_tag": "消息中代表用戶的 role_tag（默認：human）","assistant_tag": "消息中代表助手的 role_tag（默認：gpt）","observation_tag": "消息中代表工具返回結果的 role_tag（默認：observation）","function_tag": "消息中代表工具調用的 role_tag（默認：function_call）","system_tag": "消息中代表系統提示的 role_tag（默認：system，會覆蓋 system column）"}
}

Alpaca 格式

指令監督微調數據集

• 樣例數據集

在指令監督微調時，instruction 列對應的內容會與 input 列對應的內容拼接后作為人類指令，即人類指令為 instruction\ninput。而 output 列對應的內容為模型回答。

如果指定，system 列對應的內容將被作為系統提示詞。

history 列是由多個字符串二元組構成的列表，分別代表歷史消息中每輪對話的指令和回答。注意在指令監督微調時，歷史消息中的回答內容也會被用于模型學習。

[{"instruction": "人類指令（必填）","input": "人類輸入（選填）","output": "模型回答（必填）","system": "系統提示詞（選填）","history": [["第一輪指令（選填）", "第一輪回答（選填）"],["第二輪指令（選填）", "第二輪回答（選填）"]]}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","columns": {"prompt": "instruction","query": "input","response": "output","system": "system","history": "history"}
}

預訓練數據集

• 樣例數據集

在預訓練時，只有 text 列中的內容會用于模型學習。

[{"text": "document"},{"text": "document"}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","columns": {"prompt": "text"}
}

偏好數據集

偏好數據集用于獎勵模型訓練、DPO 訓練、ORPO 訓練和 SimPO 訓練。

它需要在 chosen 列中提供更優的回答，并在 rejected 列中提供更差的回答。

[{"instruction": "人類指令（必填）","input": "人類輸入（選填）","chosen": "優質回答（必填）","rejected": "劣質回答（必填）"}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","ranking": true,"columns": {"prompt": "instruction","query": "input","chosen": "chosen","rejected": "rejected"}
}

KTO 數據集

KTO 數據集需要提供額外的 kto_tag 列。詳情請參閱 sharegpt。

多模態圖像數據集

多模態圖像數據集需要提供額外的 images 列。詳情請參閱 sharegpt。

多模態視頻數據集

多模態視頻數據集需要提供額外的 videos 列。詳情請參閱 sharegpt。

多模態音頻數據集

多模態音頻數據集需要提供額外的 audios 列。詳情請參閱 sharegpt。

Sharegpt 格式

指令監督微調數據集

• 樣例數據集

相比 alpaca 格式的數據集，sharegpt 格式支持更多的角色種類，例如 human、gpt、observation、function 等等。它們構成一個對象列表呈現在 conversations 列中。

注意其中 human 和 observation 必須出現在奇數位置，gpt 和 function 必須出現在偶數位置。

[{"conversations": [{"from": "human","value": "人類指令"},{"from": "function_call","value": "工具參數"},{"from": "observation","value": "工具結果"},{"from": "gpt","value": "模型回答"}],"system": "系統提示詞（選填）","tools": "工具描述（選填）"}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","system": "system","tools": "tools"}
}

預訓練數據集

尚不支持，請使用 alpaca 格式。

偏好數據集

• 樣例數據集

Sharegpt 格式的偏好數據集同樣需要在 chosen 列中提供更優的消息，并在 rejected 列中提供更差的消息。

[{"conversations": [{"from": "human","value": "人類指令"},{"from": "gpt","value": "模型回答"},{"from": "human","value": "人類指令"}],"chosen": {"from": "gpt","value": "優質回答"},"rejected": {"from": "gpt","value": "劣質回答"}}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","ranking": true,"columns": {"messages": "conversations","chosen": "chosen","rejected": "rejected"}
}

KTO 數據集

• 樣例數據集

KTO 數據集需要額外添加一個 kto_tag 列，包含 bool 類型的人類反饋。

[{"conversations": [{"from": "human","value": "人類指令"},{"from": "gpt","value": "模型回答"}],"kto_tag": "人類反饋 [true/false]（必填）"}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","kto_tag": "kto_tag"}
}

多模態圖像數據集

• 樣例數據集

多模態圖像數據集需要額外添加一個 images 列，包含輸入圖像的路徑。

注意圖片的數量必須與文本中所有 <image> 標記的數量嚴格一致。

[{"conversations": [{"from": "human","value": "<image>人類指令"},{"from": "gpt","value": "模型回答"}],"images": ["圖像路徑（必填）"]}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","images": "images"}
}

多模態視頻數據集

• 樣例數據集

多模態視頻數據集需要額外添加一個 videos 列，包含輸入視頻的路徑。

注意視頻的數量必須與文本中所有 <video> 標記的數量嚴格一致。

[{"conversations": [{"from": "human","value": "<video>人類指令"},{"from": "gpt","value": "模型回答"}],"videos": ["視頻路徑（必填）"]}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","videos": "videos"}
}

多模態音頻數據集

• 樣例數據集

多模態音頻數據集需要額外添加一個 audios 列，包含輸入音頻的路徑。

注意音頻的數量必須與文本中所有 <audio> 標記的數量嚴格一致。

[{"conversations": [{"from": "human","value": "<audio>人類指令"},{"from": "gpt","value": "模型回答"}],"audios": ["音頻路徑（必填）"]}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","audios": "audios"}
}

OpenAI 格式

OpenAI 格式僅僅是 sharegpt 格式的一種特殊情況，其中第一條消息可能是系統提示詞。

[{"messages": [{"role": "system","content": "系統提示詞（選填）"},{"role": "user","content": "人類指令"},{"role": "assistant","content": "模型回答"}]}
]

對于上述格式的數據，dataset_info.json 中的數據集描述應為：

"數據集名稱": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "messages"},"tags": {"role_tag": "role","content_tag": "content","user_tag": "user","assistant_tag": "assistant","system_tag": "system"}
}

三、常見問題排查

問題：dataset_info.json 中 hf_hub_url、ms_hub_url、script_url、file_name 的優先級關系是什么？

答案：

優先級為 hf_hub_url/ms_hub_url > script_url > file_name。若指定了 hf_hub_url 或 ms_hub_url，系統會直接從 Hugging Face 或 ModelScope 加載數據集，忽略 script_url 和 file_name；若未指定，則依次檢查 script_url 和 file_name。

誤區舉例：用戶可能同時填寫多個字段（如同時指定 hf_hub_url 和 file_name），導致實際加載數據集時忽略本地文件，引發數據路徑錯誤。

問題：偏好數據集（DPO/ORPO）的配置中，Alpaca 格式和 Sharegpt 格式的 columns 字段有何差異？

答案：

• Alpaca 格式需指定 chosen 和 rejected 列，對應優質和劣質回答，并設置 "ranking": true。
• Sharegpt 格式需將 chosen 和 rejected 配置為消息對象（如 {"from": "gpt", "value": "回答"}），并同樣設置 "ranking": true。

誤區舉例：用戶可能誤將 Sharegpt 格式的 chosen/rejected 配置為純文本（而非消息對象），導致解析失敗；或在 Alpaca 格式中遺漏 "ranking": true，導致數據集未被識別為偏好類型。

問題：多模態數據集（如圖像）的配置中，images 列與文本中的 <image> 標記為何需嚴格數量一致？

答案：

images 列中的文件路徑數量必須與文本中 <image> 標記的數量完全一致，以確保模型能正確關聯圖像輸入與文本指令。例如，若文本中有 2 個 <image> 標記，則 images 列必須包含 2 個路徑。

誤區舉例：用戶可能在數據預處理時未檢查標記數量與文件路徑的匹配性，導致訓練時因數據格式錯誤而中斷。

問題：Sharegpt 格式的 tags 字段（如 role_tag、user_tag）有何作用？如何適配 OpenAI 格式數據？

答案：

• tags 字段用于自定義消息中角色和內容的鍵名。例如，OpenAI 格式的 role 和 content 需通過 tags 映射為 role_tag: "role" 和 content_tag: "content"。
• 適配 OpenAI 格式需額外設置 user_tag: "user"、assistant_tag: "assistant"、system_tag: "system"。

誤區舉例：用戶可能未正確配置 tags，導致無法解析第三方格式（如 OpenAI）的消息結構，或因角色標簽沖突（如 system 覆蓋系統列）引發錯誤。

問題：KTO 數據集的 kto_tag 列在配置時需要注意什么？

答案：

kto_tag 列需包含布爾類型（True/False）的標簽，表示人類對回答的反饋。在 dataset_info.json 中需顯式聲明 "kto_tag": "列名"，且數據集格式必須為 Sharegpt。

誤區舉例：用戶可能誤將 kto_tag 配置為字符串（如 "true" 而非布爾值 true），或忘記設置 "formatting": "sharegpt"，導致數據加載失敗。

問題：在 Alpaca 格式中，history 列的作用是什么？如何正確配置它？

答案：

• 作用: history 列存儲歷史對話的指令和回答（二元組列表），用于多輪對話場景。模型會學習歷史對話內容，而不僅是當前指令和回答。
• 配置: 需在 dataset_info.json 中明確指定 "history": "列名"，且數據格式應為 [["指令1", "回答1"], ["指令2", "回答2"]]。

誤區舉例: 用戶可能忽略 history 列的存在，導致多輪對話數據未被利用；或錯誤配置為單字符串（如 "instruction,answer"），引發解析錯誤。

問題：預訓練數據集的 Alpaca 格式為何只需 text 列？如何與指令微調數據集區分？

答案：

• 原因: 預訓練目標是學習通用文本表示，因此僅需原始文本（text 列），無需指令或回答結構。
• 區分: 指令微調需 instruction/output 等列，而預訓練只需 "columns": {"prompt": "text"}。若誤用指令數據配置預訓練，會導致模型忽略關鍵字段。

誤區舉例: 用戶可能混淆預訓練和微調的數據格式，錯誤地將指令數據用于預訓練，浪費計算資源。

問題：Sharegpt 格式中，tools 列的作用是什么？是否必須與 function_call 角色配合使用？

答案：

• 作用: tools 列定義工具的描述（如 API 文檔），供模型生成工具調用參數（function_call 角色）。
• 配合要求: 是。若數據包含 function_call 消息，則需提供 tools 列；若無工具調用，可省略。

誤區舉例: 用戶可能遺漏 tools 列但保留 function_call 消息，導致模型無法理解工具定義；或反向誤配，引發訓練錯誤。

問題：如何正確處理多模態數據（如圖像、視頻）中的路徑問題？

答案：

• 要求: 文件路徑需為絕對路徑或相對于數據集根目錄的相對路徑，且確保文件實際存在。
• 驗證: 在加載數據集前，應檢查 images/videos/audios 列中的路徑是否有效，避免因路徑錯誤導致訓練中斷。

誤區舉例: 用戶可能使用錯誤路徑格式（如未處理系統路徑分隔符差異），或未驗證文件是否存在，導致多模態數據加載失敗。

問題：subset 和 split 字段在 dataset_info.json 中有何區別？

答案：

• subset: 指定 Hugging Face/ModelScope 數據集的子集名稱（如 "zh" 表示中文子集）。
• split: 定義數據切分（如 train、test），默認為 train。兩者可同時使用（如 "subset": "zh", "split": "test"）。

誤區舉例: 用戶可能誤將 subset 當作數據切分，或混淆兩者優先級，導致加載錯誤的數據子集。

問題：如何為自定義數據集選擇正確的 formatting 值（alpaca 或 sharegpt）？

答案：

• 關鍵判斷點:
  1. 角色多樣性: 若需多角色（如 human/gpt/function），選 sharegpt。
  2. 工具/多模態支持: 涉及工具調用或媒體輸入時，必須用 sharegpt。
  3. 結構簡化性: 若僅需 instruction-output 結構，用 alpaca。

誤區舉例: 用戶可能因未全面評估數據復雜度而選錯格式，導致后續配置無法適配。