从零到一：在Mac上使用LLaMA Factory微调大模型并部署至Ollama全流程指南

在个人设备上微调并部署专属的大型语言模型（LLM），正成为开发者探索AI应用的热门方式。本文将手把手带你完成在Mac系统上，利用LLaMA Factory工具对开源模型进行指令微调，并最终将其成功导入Ollama进行本地化部署的全过程。我们将详细拆解每个步骤，并重点记录其中可能遇到的“坑”及其解决方案，助你高效完成自己的第一个大模型微调项目。

一、环境搭建：LLaMA Factory的安装与配置

万事开头难，一个稳定、隔离的Python环境是成功的第一步。我们强烈建议使用虚拟环境来管理项目依赖，以避免与系统或其他项目的Python包发生冲突。对于Mac用户，可以使用conda或venv来创建。虽然原文作者尝试了最新的Python 3.14，但实践中我们更推荐使用Python 3.10或3.12等经过广泛测试的稳定版本，这能有效规避后续因库版本不兼容导致的问题，例如在数据集加载时可能出现的函数接口错误。

安装LLaMA Factory的核心步骤如下：

  • 创建并激活一个独立的Python虚拟环境。
  • 克隆LLaMA Factory的官方代码仓库。
  • 使用pip安装项目依赖。如果遇到权限或路径问题，可以尝试添加--user参数或指定清华镜像源来加速。

以下是安装命令示例：

# 通过git下载项目
git clone https://github.com/hiyouga/LLaMA-Factory.git
# 进入目录
cd LLaMA-Factory
# 安装
pip install -e ".[torch,metrics]"

在安装过程中，你可能会遇到第一个问题：

ERROR: Package 'llamafactory' requires a different Python: 3.9.6 not in '>=3.11.0'

这通常与Python版本或某些系统库有关。作者通过升级到Python 3.14解决，但我们更建议降级到3.12。如果选择创建虚拟环境，可以这样做：

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
    xyz, where xyz is the package you are trying to
    install.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
# 安装anaconda
brew install --cask anaconda
# 创建虚拟环境 lora
conda create -n lora python=3.14
# 激活该环境
conda activate lora

然后再次执行安装命令：

pip install -e ".[torch,metrics]"

如果仍有问题，可以尝试添加特定参数来解决依赖冲突：

pip install --break-system-packages -e ".[torch,metrics]"

安装成功后，在项目根目录下启动Web UI服务：

llamafactory-cli webui

在浏览器中访问 http://localhost:7860，如果能看到LLaMA Factory的图形化界面，则说明安装成功。这对于不习惯纯命令行操作的开发者来说非常友好，大大降低了使用门槛。

在这里插入图片描述

二、模型准备：下载与验证基础模型

微调需要从一个预训练好的基础模型开始。为了在个人电脑（尤其是Mac）上实现快速实验，选择一个参数量较小的模型是关键。例如，我们可以从ModelScope平台下载 DeepSeek-R1-Distill-Qwen-1.5B 这类经过蒸馏的轻量级模型。

使用Git命令下载模型：

# 因为存在大文件下载，需要安装 lfs
git lfs install
# 下载模型
git clone https://www.modelscope.cn/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B.git

下载完成后，在LLaMA Factory的Web界面中配置模型路径并加载。这是第一个验证点，如果加载失败，后续步骤都无法进行。

在这里插入图片描述

这里很可能遇到第二个“坑”：模型文件下载不完整。初次加载时可能会抛出异常：

  self.model = load_model(
                 ~~~~~~~~~~^
        self.tokenizer, model_args, finetuning_args, is_trainable=False, add_valuehead=(not self.can_generate)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )  # must after fixing tokenizer to resize vocab
    ^
  File "/Users/xxx/Documents/workspace/python/LLaMA-Factory/src/llamafactory/model/loader.py", line 178, in load_model
    model = load_class.from_pretrained(**init_kwargs)
  File "/opt/homebrew/lib/python3.14/site-packages/transformers/models/auto/auto_factory.py", line 372, in from_pretrained
    return model_class.from_pretrained(
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        pretrained_model_name_or_path, *model_args, config=config, **hub_kwargs, **kwargs
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/opt/homebrew/lib/python3.14/site-packages/transformers/modeling_utils.py", line 4109, in from_pretrained
    load_info = cls._load_pretrained_model(model, state_dict, checkpoint_files, load_config)
  File "/opt/homebrew/lib/python3.14/site-packages/transformers/modeling_utils.py", line 4218, in _load_pretrained_model
    file_pointer = safe_open(file, framework="pt", device="cpu")
safetensors_rust.SafetensorError: Error while deserializing header: header too large

这是因为Git LFS（大文件存储）在下载大模型文件时可能中断或出错。解决方法是通过huggingface-cli或直接去官网核对文件大小：

DeepSeek-R1-Distill-Qwen-1.5B

检查关键文件，如：

model.safetensors

确保其大小与官方页面显示的一致。如果不一致，需要手动下载缺失的文件并放入对应目录。模型成功加载后，可以在Chat标签页进行简单的对话测试，确保基础模型工作正常。

在这里插入图片描述在这里插入图片描述 [AFFILIATE_SLOT_1]

三、数据工程：准备微调数据集

数据集是微调的灵魂，决定了模型学习的新知识和技能。我们继续从ModelScope寻找合适的小规模数据集进行实验，例如“甄嬛1M数据集”。下载后，需要将其放置在LLaMA Factory规定的目录下。

具体操作是将数据集文件：

huanhuan.json

移动到以下目录：

${dir}/LLaMA-Factory/data

接着，需要修改该目录下的数据集配置文件，以注册我们的新数据集。找到文件：

dataset_info.json

在文件末尾添加你数据集的配置信息，格式如下：

{
  // 原本的不动
  ,"huanhuan": {
    	"file_name": "huanhuan.json"
   }
}

配置完成后，在Web界面的“Train”标签页中，应该能搜索到你的数据集名称（例如：

huanhuan

）。点击预览，若能正常显示数据样本，则说明数据集配置成功。这一步确保了微调过程有“料”可学。

在这里插入图片描述

四、核心训练：执行微调与效果验证

一切就绪后，就可以开始训练了。在LLaMA Factory的Train页面，你可以调整各种超参数，如学习率、训练轮次（epoch）、批处理大小等。对于初次实验，使用默认配置是一个不错的起点。

在这里插入图片描述

这里我们遇到了第三个关键问题：Python版本兼容性。正如前文所预警的，使用Python 3.14可能会导致数据集加载函数不兼容，出现类似错误：

  File "/opt/homebrew/lib/python3.14/site-packages/dill/_dill.py", line 1217, in save_module_dict
    StockPickler.save_dict(pickler, obj)
    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/python@3.14/3.14.3_1/Frameworks/Python.framework/Versions/3.14/lib/python3.14/pickle.py", line 1064, in save_dict
    self._batch_setitems(obj.items(), obj)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
TypeError: Pickler._batch_setitems() takes 2 positional arguments but 3 were given

最佳实践建议：将Python版本切换回3.10或3.12等稳定版本，可以完美解决此问题。这提醒我们，在AI开发中，并非一味追求最新版本就是最好的，社区的稳定性和库的兼容性同样重要。这与使用其他主流语言如Java或Go进行企业级开发时的理念相通——稳定性优先。

切换Python版本并重新配置环境后，启动训练。训练时间取决于你的数据集大小、模型参数量和Mac的硬件性能（特别是GPU/Apple Silicon芯片的性能）。作者使用一个较小数据集在1.5B模型上训练了约46分钟，日志输出如下：

***** train metrics *****
  epoch                    =        3.0
  num_input_tokens_seen    =     776520
  total_flos               =  6738458GF
  train_loss               =     4.5287
  train_runtime            = 0:46:36.50
  train_samples_per_second =        4.0
  train_steps_per_second   =      0.251
Figure saved at: saves/DeepSeek-R1-1.5B-Distill/lora/train_2026-02-12-16-14-47/training_loss.png
[WARNING|2026-02-12 17:01:53] llamafactory.extras.ploting:149 >> No metric eval_loss to plot.
[WARNING|2026-02-12 17:01:53] llamafactory.extras.ploting:149 >> No metric eval_accuracy to plot.

训练完成后，会在指定目录生成模型检查点（checkpoint）。在LLaMA Factory的“Model”页面，你需要先卸载当前加载的原始模型，然后选择我们刚训练好的检查点路径并重新加载。加载成功后，再次进行聊天测试。例如，询问“我是谁”，如果微调数据集是关于特定角色（如甄嬛）的，模型的回答应该从原始的通用回答转变为符合该角色设定的回答，这直观地证明了微调是有效的。

在这里插入图片描述

五、部署实践：导出模型并集成到Ollama

模型微调好后，下一步就是将其投入实际使用。Ollama是一个强大的本地大模型运行和部署工具，提供了简洁的API，方便与Python、JavaScript/TypeScript（通过Fetch API）或Go等后端服务集成。

在LLaMA Factory的“Export”标签页，选择导出格式为“Ollama”，并指定导出路径，即可将微调后的模型打包成Ollama可识别的格式。

在这里插入图片描述

导出完成后，你会得到一个包含Modelfile等文件的目录。通过Ollama的命令行工具，即可创建并运行你的自定义模型。使用以下命令，其中模型文件路径指向：

Modelfile

你可以为你的模型起一个自定义名称，例如：

test_DeepSeek

创建命令如下：

# 安装导出的模型
ollama create test_DeepSeek -f /Users/xxx/Documents/workspace/model/Modelfile
# 查看
ollama list
# 运行模型, 名称默认带上:latest标签
ollama run test_DeepSeek:latest

创建成功后，使用ollama run your_model_name即可在命令行与你的模型交互。更重要的是，Ollama会在本地启动一个API服务（默认端口11434），你的应用程序可以通过HTTP请求与该服务通信，从而调用你专属的微调模型，完成对话、摘要、翻译等各种任务。

[AFFILIATE_SLOT_2]

总结与延伸思考

通过以上五个步骤，我们完整地走通了在Mac上使用LLaMA Factory微调大模型并部署到Ollama的流程。整个过程涵盖了环境配置、模型获取、数据准备、训练调试和部署上线等关键环节。核心经验在于：重视环境隔离与Python版本管理、仔细验证模型与数据文件的完整性、以及理解从训练到部署的格式转换流程。

这套方法论不仅适用于Mac，经过适当调整（主要是环境配置和路径设置），同样可以在Linux或Windows（通过WSL）上运行。将微调后的模型通过Ollama部署，为你打开了构建个性化AI应用的大门，无论是开发智能客服、专业领域助手，还是进行有趣的创意实验，都拥有了坚实的基础。希望这篇详细的踩坑记录能成为你探索大模型微调世界的得力助手。

posted on 2026-03-22 08:13  blfbuaa  阅读(728)  评论(0)    收藏  举报

博客园  ©  2004-2026
浙公网安备 33010602011771号 浙ICP备2021040463号-3