CACHE_DIR 是共享存储路径。

bash
展开代码
# 三个环境变量指定到共享存储路径。
    -e HF_DATASETS_CACHE=${CACHE_DIR}/HF_DATASETS_CACHE \
    -e HUGGINGFACE_HUB_CACHE=${CACHE_DIR}/HUGGINGFACE_HUB_CACHE \
    -e TRANSFORMERS_CACHE=${CACHE_DIR}/TRANSFORMERS_CACHE \

# 2个训练参数指定到共享存储路径。
--cache_dir ${CACHE_DIR}/cache_dir \
--tokenized_path ${CACHE_DIR}/tokenized_cache \
# 1个训练参数指定共享存储
--data_shared_file_system true \

以下是 VS Code 常用快捷键（适用于 Windows/Linux，Mac 用户将 Ctrl 替换为 Cmd）：

基础操作

在大模型训练过程中，意外中断（如服务器重启、显存溢出等）是常见问题。如何优雅地恢复训练进度，避免从头再来？LLamaFactory 基于 HuggingFace Transformers，天然支持断点续训（resume from checkpoint）。本文以 Qwen2VL 为例，详细介绍其断点续训机制、配置方法及源码实现位置。

bash
展开代码
echo 'exec /bin/bash' >> ~/.zshrc

Linux系统支持中文字符处理

要让Linux系统更好地支持中文字符处理，您可以安装以下软件包：

bash
展开代码
sudo apt-get update
sudo apt-get install -y locales fonts-noto-cjk language-pack-zh-hans

然后配置系统的语言环境：

bash
展开代码
sudo locale-gen zh_CN.UTF-8
sudo update-locale LANG=zh_CN.UTF-8 LC_ALL=zh_CN.UTF-8

对于Python程序处理中文文件名的问题，您可以确保系统环境变量设置正确：

bash
展开代码
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

您也可以使用locale命令检查当前系统的语言环境设置：

bash
展开代码
locale

LLaMA Factory 完全支持 JSONL 格式

LLaMA Factory 对 JSONL 格式的全面支持

官方文档明确声明

LLaMA Factory 官方文档在 data/README.md 中明确声明：

Currently we support datasets in alpaca and sharegpt format. Allowed file types include json, jsonl, csv, parquet, arrow.

这表明 JSONL 格式是 LLaMA Factory 原生支持的文件格式之一。

核心代码实现支持

1. 文件扩展名映射机制

在 src/llamafactory/extras/constants.py 中，LLaMA Factory 定义了完整的文件类型映射：

python
展开代码
FILEEXT2TYPE = {
    "arrow": "arrow",
    "csv": "csv", 
    "json": "json",
    "jsonl": "json",  # JSONL 被映射为 "json" 类型
    "parquet": "parquet",
    "txt": "text",
}

这个映射确保了 .jsonl 文件能够被正确识别和处理。

Read file: src/llamafactory/data/converter.py Read file: src/llamafactory/data/parser.py

LLaMA Factory 不是依靠位置读取的，而是依靠字段名映射！

关键发现：

1. 字段名映射机制

从 src/llamafactory/data/parser.py 第 47-53 行可以看出，LLaMA Factory 使用字段名映射而不是位置：

python
展开代码
# sharegpt tags
role_tag: Optional[str] = "from"        # 默认映射 "from" 字段
content_tag: Optional[str] = "value"    # 默认映射 "value" 字段
user_tag: Optional[str] = "human"       # 默认映射 "human" 值
assistant_tag: Optional[str] = "gpt"    # 默认映射 "gpt" 值

VLLM 部署 Qwen2VL 后，客户端用 OpenAI 兼容格式请求时，图片 token 插入位置的处理机制

1. 核心处理流程

VLLM 处理多模态请求的核心流程在 BaseMultiModalProcessor.apply() 方法中（第 1810-1870 行）：

python
展开代码
def apply(
    self,
    prompt: Union[str, list[int]],
    mm_data: MultiModalDataDict,
    hf_processor_mm_kwargs: Mapping[str, object],
    tokenization_kwargs: Optional[Mapping[str, object]] = None,
    return_mm_hashes: bool = False,
) -> MultiModalInputs:
    """
    处理多模态输入的主要步骤：
    1. 对提示文本和多模态数据一起应用 HF Processor
    2. 在 token IDs 中查找并更新序列，用占位符 token 替换
    3. 从处理后的 token IDs 中提取占位符 token 的信息
    """

1. 训练阶段：图片 token 插入位置

是的，图片通过编码器编码为 token 后，插入的位置就是 <image> 标记的位置。

具体实现机制：

Qwen2VL 的处理流程：

1. 占位符替换：在 Qwen2VLPlugin.process_messages 中（第 1630-1640 行）：

   python
   展开代码
   while IMAGE_PLACEHOLDER in content:
       image_seqlen = image_grid_thw[num_image_tokens].prod() // merge_length if self.expand_mm_tokens else 1
       content = content.replace(
           IMAGE_PLACEHOLDER, f"<|vision_start|>{self.image_token * image_seqlen}<|vision_end|>", 1
       )
       num_image_tokens += 1
   

2. Token 替换：在 Qwen2VLProcessor.__call__ 中（第 150-170 行）：

   python
   展开代码
   while self.image_token in text[i]:
       num_image_tokens = image_grid_thw[index].prod() // merge_length
       text[i] = text[i].replace(self.image_token, "<|placeholder|>" * num_image_tokens, 1)
       index += 1
   text[i] = text[i].replace("<|placeholder|>", self.image_token)
   

详细分析：ShareGPT + VLM + 指令监督微调格式

1. 你的数据格式分析

你提供的数据格式：

json
展开代码
{
    "image": "000443568.jpg",
    "width": 700,
    "height": 700,
    "conversations": [
        {
            "from": "human",
            "value": "Write a detailed description of this image..."
        },
        {
            "from": "gpt",
            "value": "The image is of a pair of silver earrings..."
        }
    ]
}

问题分析：

1. 缺少 <image> 标记：在 conversations 中没有 <image> 占位符
2. 图片路径格式：image 字段是单个字符串，但需要与对话中的 <image> 标记对应
3. 额外字段：width 和 height 字段在 LLaMA-Factory 中不会被使用