LLaMA-Factory 部署与 DeepSeek-R1-Distill-Qwen 模型乱码问题解决全记录摘要本文记录了在远程 A100 服务器上部署 LLaMA-Factory并加载 DeepSeek-R1-Distill-Qwen 系列模型时遇到的输出乱码问题。通过强制指定 Qwen2Tokenizer最终完美解决。全过程包括环境配置、CUDA 版本协调、模型下载、问题排查与修复。0、一点小废话请注意AI环境版本迭代很快本文编辑和实验时间2026年7月2日您看到此文章时LLaMA-Factory框架、PyTorch、CUDA版本可能会有变动请以三者官网公布最新的适配版本为准进行配置。一、环境概览本地VSCode Remote-SSH 插件服务器Ubuntu 24.04.3 LTS (NVIDIA A100)目标框架LLaMA-Factory测试模型deepseek-ai/DeepSeek-R1-Distill-Qwen-7B及 1.5B 版本最终稳定模型Qwen/Qwen2.5-1.5B-Instruct验证正常二、LLaMA-Factory 安装步骤1. 克隆仓库gitclone--depth1https://github.com/hiyouga/LLaMA-Factory.gitcdLLaMA-Factory2. 准备 Conda 环境推荐若未安装 Miniconda# 进入你的家目录cd~# 下载最新 Miniconda 安装包Linux x86_64wgethttps://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh# 执行安装按提示操作空格翻页yes 接受协议回车确认安装位置bashMiniconda3-latest-Linux-x86_64.sh# 安装完成后关闭并重新打开终端或者执行source~/.bashrc⚠️ 若为 root 用户建议将 conda 缓存和 envs 目录挂载到数据盘如/root/autodl-tmp/conda避免占满系统盘。参考挂载指令mkdir-p/root/autodl-tmp/conda/pkgs conda config--addpkgs_dirs /root/autodl-tmp/conda/pkgsmkdir-p/root/autodl-tmp/conda/envs conda config--addenvs_dirs /root/autodl-tmp/conda/envs3. 创建虚拟环境conda create-nllama-factorypython3.13.5# 也可换为 3.11conda activate llama-factory4. 安装 LLaMA-Factory 及其依赖pipinstall-e.[torch,metrics]5. 检验安装llamafactory-cli version若无报错则基础安装完成。三、CUDA 与 PyTorch 版本协调重要安装后执行llamafactory-cli version可能出现警告CUDA version mismatch因为默认安装的 PyTorch 编译时使用的 CUDA 版本与系统驱动不一致。服务器 CUDA 版本12.9默认 PyTorch 编译版本13.0不兼容解决方案查看当前 PyTorch 信息python-cimport torch; print(PyTorch version:, torch.__version__); print(CUDA compiled version:, torch.version.cuda)卸载默认 PyTorchpip uninstall-ytorch torchvision torchaudio安装与 CUDA 12.9 兼容的 PyTorch推荐 CUDA 12.6 版本查询PyTorch官网了解到目前适配12大版本CUDA的对应稳定版本是CU126安装指令参考官网的版本pipinstalltorch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126出现了三个报错主要是有两个包版本过高需要降级还有torchaudio漏装了下面进行修复若torchaudio未装补装pipinstalltorchaudio --index-url https://download.pytorch.org/whl/cu126降级冲突包如fsspec,pillowpipinstallfsspec2025.3.0pillow11.3.0✅ 也可直接新建 conda 环境先装Python和 PyTorch 全家桶再装 LLaMA-Factory避免依赖冲突然后再把出错的conda环境删掉conda create-nllama-factory-311python3.11-yconda activate llama-factory-311 pipinstalltorch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126cd~/LLaMA-Factory pipinstall-e.[torch,metrics]最终验证python-cimport torch; print(torch.cuda.is_available()); print(torch.version.cuda)# 应输出 True 和 12.6别忘了确认llamafactory环境是否正常llamafactory-cli version如下图所示没有出现警告说明安装成功。四、下载 HuggingFace 模型记得先新建一条路径用来存储待会下载的模型可以参考下面的代码1. 设置下载目录与镜像可选如下指令只会在当前会话生效若需要长期生效可以写入配置文件。你的文件路径大概率和我的不同请将下面的路径配置为你自己准备下载模型的路径。exportHF_HOME/your/data/path/Hugging-Face# 请替换为你的实际路径exportHF_ENDPOINThttps://hf-mirror.com# 镜像加速# 下面两条指令用于验证上面的临时环境变量是否配置成功echo$HF_ENDPOINTecho$HF_HOME2. 安装huggingface_hub使用官方的下载器来下载pipinstall-Uhuggingface_hub3. 下载目标模型hf download deepseek-ai/DeepSeek-R1-Distill-Qwen-7B模型会被保存至$HF_HOME/hub/下的 snapshot 目录。上述指令中使用的模型名字可以通过Huggingface官网直接找到你想要的模型后复制完整的名字五、运行llama-factory验证模型是否可用1.启动webuillamafactory-cliwebui2.选择模型名称先选择模型名称为DeepSeek-R1-Distill-Qwen-7B3.替换模型路径找到下载的模型文件快照目录下对应的唯一哈希值命名的文件夹复制该路径4.设置模型路径并加载设置模型路径后在chat页面下选择加载模型等待加载完成5.尝试进行模型对话发现对话中参入了很多乱码六、问题模型输出乱码现象描述在 LLaMA-Factory WebUI 中加载DeepSeek-R1-Distill-Qwen-7B或 1.5B后对话输出出现大量不可读字符例如Hello! How can I assist you today? ðŁĺĬ或出现C\Git、大量G和Ġ等符号。初步尝试更换模型版本7B → 1.5B—— 无效更换 Python 版本3.13 → 3.11—— 无效重装 PyTorch 不同 CUDA 版本 —— 无效手动清理Ġ和Ċ占位符 —— 残留其他乱码如 EMJ根本原因AutoTokenizer默认加载了LlamaTokenizer而非该模型所需的Qwen2Tokenizer。原因是模型目录下的tokenizer_config.json中tokenizer_class缺失或错误导致 Transformers 库回退到错误的分词器造成 token ID 与词表不匹配。七、最终解决方案强制指定 Qwen2Tokenizer1. 编写 Python 脚本测试importtorchfromtransformersimportAutoModelForCausalLM,AutoTokenizer,Qwen2Tokenizer MODEL_PATH/home/xiezhongjun/hugging-face/hub/models--deepseek-ai--DeepSeek-R1-Distill-Qwen-7B/snapshots/916b56a44061fd5cd7d6a8fb632557ed4f724f60print(正在加载模型...)modelAutoModelForCausalLM.from_pretrained(MODEL_PATH,dtypetorch.bfloat16,device_mapauto)# 关键修复强制使用 Qwen2Tokenizer并添加 trust_remote_codeTruetokenizerQwen2Tokenizer.from_pretrained(MODEL_PATH,trust_remote_codeTrue,use_fastTrue# Qwen2 必须用 fast 版本)# 验证是否修复成功打印词表大小Qwen2-7B 应为 151643 左右print(f词表大小验证:{len(tokenizer)})# 如果输出是 32000 或 50000说明加载依然错误print(模型加载完成。输入 quit 退出。)whileTrue:user_inputinput(\n你: )ifuser_input.lower()quit:breakmessages[{role:user,content:user_input}]prompttokenizer.apply_chat_template(messages,tokenizeFalse,add_generation_promptTrue)inputstokenizer(prompt,return_tensorspt).to(model.device)withtorch.no_grad():outputsmodel.generate(**inputs,max_new_tokens512,temperature0.6,top_p0.95,do_sampleTrue,eos_token_idtokenizer.eos_token_id,pad_token_idtokenizer.pad_token_id,)# 获取新生成的 token ids去掉输入部分output_idsoutputs[0][inputs.input_ids.shape[1]:]# 使用标准解码responsetokenizer.decode(output_ids,skip_special_tokensTrue,clean_up_tokenization_spacesTrue# 这一句是关键让分词器自行处理空格)# 手动修复字节级占位符将 Ġ 替换为空格Ċ 替换为换行#response response.replace(Ġ, ).replace(Ċ, \n)# 移除思维链if/thinkinresponse:responseresponse.split(/think)[-1]# 可选压缩多余空白#response \n.join(line.strip() for line in response.splitlines() if line.strip())print(f模型:{response})运行该脚本输出正常无乱码。2. 在 LLaMA-Factory WebUI 中应用WebUI 无法直接修改代码需通过修正模型配置文件来让AutoTokenizer自动选中正确类。操作步骤进入模型 snapshot 目录cd/your/Hugging-Face/hub/models--deepseek-ai--DeepSeek-R1-Distill-Qwen-7B/snapshots/916b56a...查看tokenizer_config.json的tokenizer_class字段将其修改为Qwen2Tokenizer重启 LLaMA-Factory WebUI重新加载模型即可正常对话。llamafactory-cliwebui八、验证与对比模型分词器加载输出结果DeepSeek-R1-Distill-Qwen-7B/1.5B默认LlamaTokenizer错误乱码含 Ġ, Ċ, 特殊字符DeepSeek-R1-Distill-Qwen-7B/1.5B强制 Qwen2TokenizerQwen2Tokenizer正确正常中文/英文Qwen/Qwen2.5-1.5B-InstructAutoTokenizer 自动正确正常无需修改结论该模型本质是基于 Qwen 架构分词器必须使用Qwen2Tokenizer。九、经验总结分词器不匹配是导致解码乱码的常见原因尤其是基于 Qwen 的衍生模型。当AutoTokenizer加载错误时应检查tokenizer_config.json中的tokenizer_class字段。若 WebUI 无法手动指定分词器类可直接修正配置文件或使用脚本方式调用。安装 LLaMA-Factory 时注意 CUDA 与 PyTorch 版本兼容性推荐使用 conda 隔离环境。十、参考资料LLaMA-Factory GitHubHuggingFace 模型下载PyTorch 官网Bilibili堂吉诃德拉曼查的英豪 – – LoRA 算法论文解读 开发人员如何微调大模型并暴露可调用接口最终测试在修复后的环境下DeepSeek-R1-Distill-Qwen-7B/1.5B 以及Qwen/Qwen2.5-1.5B-Instruct均可正常进行中文对话输出流畅、无乱码。问题圆满解决。
