在实际项目中，从零开始构建一个大模型，无论是用于研究、实验还是特定领域的应用，都是一个涉及多环节、多工具的复杂工程。很多开发者最初接触时，会感到无从下手，因为“大模型”这个概念背后，包含了从模型选择、环境搭建、数据准备、微调训练到部署推理、应用开发等一系列步骤。本文将以一个工程实践者的视角，带你梳理一条清晰的路径，从理解核心概念开始，逐步完成一个本地可运行的大模型微调与部署案例，并解释每个环节的关键决策和常见陷阱。

我们将聚焦于一个具体且可复现的场景：使用开源框架对一个大语言模型进行指令微调，并将其部署为本地可用的API服务。这个过程会涉及GPU环境准备、模型下载、数据准备、微调训练、模型合并、推理部署等关键步骤。通过本文，你将能理解大模型微调与部署的核心工作流，掌握必要的工具链，并具备排查常见问题的能力。

1. 理解大模型微调与部署的核心概念

在动手之前，需要先厘清几个关键概念，这能帮助你理解后续每一步操作的目的和意义。

1.1 什么是大模型微调

大模型微调，通常指在预训练好的大型语言模型基础上，使用特定领域或任务的数据集进行额外的训练，使模型适应新的任务或风格。预训练模型（如 LLaMA、Qwen、ChatGLM）已经具备了强大的通用语言理解和生成能力，但可能不擅长你需要的具体任务，比如法律文书分析、医疗问答或代码生成。微调就是“教”模型学会这些新技能。

微调主要分为两种类型：

  • 全参数微调 ：更新模型的所有参数。效果好，但需要巨大的计算资源（多张高端GPU）和显存。
  • 参数高效微调 ：只更新一小部分新增的参数（如 LoRA、QLoRA 中的适配器），而冻结原始模型的大部分参数。这是目前个人开发者和研究者最常用的方法，因为它能在消费级GPU（如单张RTX 3090/4090）上实现，且效果接近全参数微调。

对于绝大多数从零开始的实践， 参数高效微调（特别是QLoRA）是首选方案 。

1.2 微调与部署的典型工作流

一个完整的从零到部署的流程可以概括为以下步骤，这也是本文后续章节展开的路线图：

  1. 环境准备 ：配置包含CUDA、PyTorch、Python的GPU开发环境。
  2. 模型选择与下载 ：选择一个合适的开源基础模型（如 Qwen1.5-7B-Chat），并从Hugging Face等平台下载。
  3. 数据准备 ：准备符合指令微调格式（如 instruction-input-output ）的JSON或JSONL文件。
  4. 选择微调框架 ：使用一个集成的微调框架（如 LLaMA-Factory、xturing）来简化训练代码。
  5. 配置与启动微调 ：配置训练参数（学习率、批次大小、LoRA秩等），启动训练过程。
  6. 模型合并与导出 ：将训练好的LoRA权重与基础模型合并，导出为完整的、可独立运行的模型。
  7. 部署与推理 ：使用推理引擎（如 vLLM、FastChat）或轻量级工具（如 Ollama）将合并后的模型部署为API服务。
  8. 应用开发 ：基于部署好的API，开发前端或后端应用。

1.3 关键工具与框架介绍

  • LLaMA-Factory ：一个功能强大、易于使用的开源大模型微调框架，支持多种模型和微调方法（全参数、LoRA、QLoRA等），并提供Web UI，极大降低了上手门槛。
  • Ollama ：一个专注于在本地运行大模型的工具，它简化了模型的下载、加载和运行过程，通过命令行即可启动一个模型服务，非常适合快速原型验证和本地测试。
  • vLLM ：一个高性能、易用的大模型推理和服务引擎，以其高效的PagedAttention注意力算法而闻名，能够显著提升推理吞吐量，适合生产环境部署。
  • Hugging Face ：模型、数据集和代码的“集散中心”，绝大多数开源模型和微调框架都围绕其 transformers 库构建。

本文将主要使用 LLaMA-Factory 进行微调，使用 Ollama 进行轻量级部署演示，因为这两者组合对新手最为友好。同时会介绍 vLLM 作为生产级部署的选项。

2. 环境准备与依赖配置

一个稳定且版本匹配的环境是后续所有步骤的基础。环境配置错误是新手遇到最多问题的地方。

2.1 硬件与基础软件要求

  • GPU ：至少需要一张具有8GB以上显存的NVIDIA GPU（如RTX 3060 12G, RTX 3090/4090 24G）。显存大小决定了你能微调多大的模型。
  • 操作系统 ：Linux（Ubuntu 20.04/22.04）或 Windows WSL2。本文示例基于 Ubuntu 22.04。
  • CUDA ：根据你的PyTorch版本选择对应的CUDA版本。PyTorch 2.0+ 通常需要 CUDA 11.8 或 12.1。
  • Python ：推荐 Python 3.10，这是目前大多数AI框架兼容性最好的版本。

2.2 逐步配置开发环境

首先，更新系统并安装必要的编译工具。 

sudo apt update
sudo apt upgrade -y
sudo apt install -y python3-pip python3-dev build-essential

接下来，安装 Miniconda 来管理Python环境，避免包冲突。 

# 下载Miniconda安装脚本（以Linux x86_64为例）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
# 运行安装脚本
bash Miniconda3-latest-Linux-x86_64.sh
# 按照提示操作，安装完成后激活conda
source ~/.bashrc

创建一个独立的conda环境用于本项目。 

conda create -n llama_factory python=3.10 -y
conda activate llama_factory

现在安装 PyTorch。务必去 PyTorch官网 根据你的CUDA版本选择正确的安装命令。假设你的CUDA版本是11.8。 

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

验证PyTorch和CUDA是否安装成功。 

# 在python交互环境中执行
import torch
print(torch.__version__)
print(torch.cuda.is_available())
print(torch.cuda.get_device_name(0))

如果最后一行能正确打印出你的GPU型号（如 NVIDIA GeForce RTX 4090 ），则环境配置成功。

2.3 安装微调框架 LLaMA-Factory

在conda环境中，使用pip安装LLaMA-Factory及其依赖。 

pip install llama-factory

安装完成后，可以检查是否安装成功。 

python -c "import llama_factory; print(llama_factory.__version__)"

LLaMA-Factory 也提供了Web UI，如果需要可以通过以下命令安装额外依赖并启动。 

# 安装Web UI依赖
pip install llama-factory[webui]
# 启动Web UI (后续会详细介绍)
# llamafactory-cli webui --port 7860

注意 ：依赖安装过程可能会因网络问题失败。可以考虑配置 pip 镜像源（如清华源）来加速下载。如果遇到特定包版本冲突，可以尝试先创建一个全新的conda环境。

3. 模型选择、下载与数据准备

有了环境，下一步是获取“原材料”：基础模型和训练数据。

3.1 选择与下载基础模型

对于入门，建议从较小的、对话能力优秀的模型开始。 Qwen1.5-7B-Chat 是一个很好的选择，它在多项评测中表现良好，且对中文支持优秀。

我们可以使用 huggingface-cli 工具来下载模型。首先安装该工具。 

pip install huggingface-hub

然后使用命令行下载模型。你需要先在 Hugging Face 注册账号并登录（在命令行中）。 

# 登录（会提示输入token，在HF网站设置页面生成）
huggingface-cli login
# 下载模型到指定目录
huggingface-cli download Qwen/Qwen1.5-7B-Chat --local-dir ./model/Qwen1.5-7B-Chat

下载过程可能需要较长时间，取决于你的网络速度。模型文件大约15GB。

常见坑点1：磁盘空间不足 。确保你的目标目录有足够的空间（至少20GB）。 --local-dir 指定的目录需要提前创建好。

3.2 准备微调数据集

微调需要结构化的数据。对于指令微调，通常每条数据包含三个字段： instruction （指令）、 input （可选输入）、 output （期望输出）。

我们创建一个简单的示例数据集 data/train.jsonl （JSON Lines格式，每行一个JSON对象）。 

{"instruction": "将以下中文翻译成英文。", "input": "今天天气真好。", "output": "The weather is really nice today."}
{"instruction": "用Python写一个函数，计算斐波那契数列的第n项。", "input": "", "output": "def fibonacci(n):\n    if n <= 1:\n        return n\n    a, b = 0, 1\n    for _ in range(2, n+1):\n        a, b = b, a + b\n    return b"}
{"instruction": "解释什么是机器学习。", "input": "", "output": "机器学习是人工智能的一个分支，它使计算机系统能够从数据中学习并改进其性能，而无需进行明确的编程。它通过识别数据中的模式并做出预测或决策来工作。"}

在实际项目中，你需要准备成百上千条这样的高质量数据。数据质量直接决定微调效果。

LLaMA-Factory支持多种数据格式。你需要创建一个数据集信息配置文件 dataset_info.json 来告诉框架如何读取你的数据。 

{
  "my_custom_dataset": {
    "file_name": "train.jsonl",
    "formatting": "alpaca" // 指定数据格式为Alpaca（instruction-input-output）
  }
}

将 dataset_info.json 放在你的数据目录（如 data/ ）下。

4. 使用 LLaMA-Factory 进行指令微调

这是最核心的步骤。我们将使用QLoRA方式对Qwen1.5-7B-Chat模型进行微调。

4.1 配置训练参数

LLaMA-Factory可以通过YAML配置文件或命令行参数来指定训练细节。我们创建一个配置文件 train_config.yaml 。 

# model
model_name_or_path: ./model/Qwen1.5-7B-Chat # 基础模型路径
template: qwen # 使用Qwen模型的对话模板

# data
dataset: my_custom_dataset # 对应dataset_info.json中定义的名称
dataset_dir: ./data # 数据集目录

# training
stage: sft # 监督微调
finetuning_type: lora # 使用LoRA（实际上是QLoRA）
lora_target: all # 对所有线性层应用LoRA
output_dir: ./sft_checkpoint # 训练输出目录

# 量化配置（QLoRA关键）
quantization_bit: 4 # 4位量化，极大减少显存占用
bnb_4bit_compute_dtype: bfloat16 # 计算数据类型

# 训练超参数
per_device_train_batch_size: 2 # 根据你的GPU显存调整
gradient_accumulation_steps: 4 # 梯度累积，等效批次大小=2*4=8
learning_rate: 1e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_steps: 100
logging_steps: 10
save_steps: 500
eval_steps: 500

# 节省显存
fp16: true

关键参数解释：

  • quantization_bit: 4 ：启用4位量化（QLoRA），这是能在消费级GPU上微调7B模型的关键。
  • per_device_train_batch_size ：单个GPU上的批次大小。如果出现OOM（显存不足），首先降低这个值。
  • gradient_accumulation_steps ：梯度累积步数。等效批次大小 = per_device_train_batch_size * gradient_accumulation_steps 。增大此值可以模拟更大的批次，但不会增加显存占用。
  • output_dir ：训练过程中保存的检查点（主要是LoRA权重）将存放在这里。

4.2 启动训练

使用 llamafactory-cli 命令启动训练。 

conda activate llama_factory
llamafactory-cli train --config train_config.yaml

训练开始后，终端会输出日志，包括损失值、学习率等信息。训练时间取决于数据量、epoch数和你的GPU性能。对于示例的小数据集和3个epoch，在RTX 4090上可能只需几分钟到几十分钟。

常见坑点2：CUDA Out Of Memory (OOM) 。如果遇到OOM错误，请按顺序尝试：

  1. 降低 per_device_train_batch_size （例如从2降到1）。
  2. 启用梯度检查点（在配置中加 gradient_checkpointing: true ），这会用计算时间换显存。
  3. 如果还不行，可以考虑使用更小的模型（如Qwen1.5-4B）或进一步减少 lora_target （如只针对 q_proj, v_proj ）。

4.3 检查训练结果

训练完成后，在 ./sft_checkpoint 目录下，你会看到类似 checkpoint-500 的文件夹，里面包含了 adapter_model.bin （LoRA权重）和 adapter_config.json （LoRA配置）等文件。这些就是你的微调成果。

你可以使用以下命令快速测试一下微调后的模型（需要加载基础模型和LoRA权重）。 

llamafactory-cli export \
  --model_name_or_path ./model/Qwen1.5-7B-Chat \
  --adapter_name_or_path ./sft_checkpoint/checkpoint-500 \
  --template qwen \
  --finetuning_type lora \
  --export_dir ./merged_model \
  --export_size 2 \
  --export_legacy_format false

这个命令会将LoRA权重合并到基础模型中，并导出为 ./merged_model 目录。但更常见的做法是直接使用动态加载LoRA的方式进行推理，我们将在下一节部署中介绍。

5. 模型部署与推理服务化

训练好的模型需要被应用调用，这就需要部署成服务。我们介绍两种方式：轻量级的 Ollama 和生产级的 vLLM。

5.1 使用 Ollama 进行本地部署（快速验证）

Ollama 非常适合本地快速启动和测试。首先，你需要将微调后的模型转换为 Ollama 支持的 Modelfile 格式。LLaMA-Factory 提供了直接导出为 Ollama 格式的功能。

确保你在 llama_factory 环境中，并安装 llama-factory 的最新版本。 

# 使用LLaMA-Factory的export命令，指定ollama格式
llamafactory-cli export \
  --model_name_or_path ./model/Qwen1.5-7B-Chat \
  --adapter_name_or_path ./sft_checkpoint/checkpoint-500 \
  --template qwen \
  --finetuning_type lora \
  --export_dir ./ollama_model \
  --export_platform ollama

执行成功后，在 ./ollama_model 目录下会生成一个 Modelfile 文件。接下来，使用 Ollama 创建并运行模型。

首先，安装 Ollama（如果你还没有安装）。 

# Linux/macOS
curl -fsSL https://ollama.com/install.sh | sh
# Windows 直接下载安装包

然后，进入 ./ollama_model 目录，使用 Modelfile 创建模型。 

cd ./ollama_model
ollama create my-tuned-qwen -f ./Modelfile

创建完成后，就可以运行这个模型了。 

ollama run my-tuned-qwen

你会进入一个交互式对话界面，可以直接输入指令进行测试，例如输入我们在数据集中教过的翻译指令“将以下中文翻译成英文：今天天气真好。”，观察输出是否符合预期。

Ollama 也提供了 API 服务，默认在 11434 端口。 

# 在后台运行服务
ollama serve &
# 使用curl测试API
curl http://localhost:11434/api/generate -d '{
  "model": "my-tuned-qwen",
  "prompt": "解释什么是机器学习。",
  "stream": false
}'

5.2 使用 vLLM 进行高性能部署（生产推荐）

对于需要高并发、低延迟的生产环境，vLLM 是更好的选择。它需要先将 LoRA 权重与基础模型合并成一个完整的模型文件。

使用 LLaMA-Factory 合并模型（如果之前没做的话）。 

llamafactory-cli export \
  --model_name_or_path ./model/Qwen1.5-7B-Chat \
  --adapter_name_or_path ./sft_checkpoint/checkpoint-500 \
  --template qwen \
  --finetuning_type lora \
  --export_dir ./merged_model_for_vllm

安装 vLLM。 

pip install vllm

使用 vLLM 启动一个 OpenAI 兼容的 API 服务器。 

python -m vllm.entrypoints.openai.api_server \
  --model ./merged_model_for_vllm \
  --served-model-name my-tuned-qwen \
  --api-key token-abc123 \
  --port 8000
  • --model : 指定合并后模型的路径。
  • --served-model-name : 服务中模型的名称。
  • --api-key : 设置一个简单的API密钥（可选，但生产环境建议设置）。
  • --port : 服务端口。

服务启动后，你可以使用 curl 或任何 HTTP 客户端调用它。 

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token-abc123" \
  -d '{
    "model": "my-tuned-qwen",
    "prompt": "用Python写一个函数，计算斐波那契数列的第n项。",
    "max_tokens": 256,
    "temperature": 0.1
  }'

vLLM 也支持 ChatCompletions 接口，更适合对话场景。

常见坑点3：vLLM 版本与模型不兼容 。vLLM 对模型架构的支持在快速更新。如果遇到加载失败，请检查 vLLM 的官方文档，确认其是否支持你使用的模型（如 Qwen1.5）。有时需要从源码安装特定分支的 vLLM。

6. 常见问题排查与性能优化

在实际操作中，你几乎一定会遇到各种问题。下面是一个快速排查清单。

6.1 训练阶段问题

问题现象 可能原因 检查与解决
CUDA Out Of Memory (OOM) 1. 批次大小 ( per_device_train_batch_size ) 太大。
2. 模型太大，显存放不下。
3. 未启用量化或量化配置错误。 		1. 减小 per_device_train_batch_size 。
2. 使用更小的模型或启用梯度检查点 ( gradient_checkpointing: true )。
3. 确保配置中 quantization_bit: 4 和 bnb_4bit_compute_dtype: bfloat16 已设置。
训练损失 (loss) 不下降或为 NaN 1. 学习率 ( learning_rate ) 过高或过低。
2. 数据格式错误，模型无法理解。
3. 梯度爆炸。 		1. 尝试经典的学习率，如 1e-4 , 2e-5 。
2. 检查 dataset_info.json 和数据文件格式，确保与 template 匹配。
3. 启用梯度裁剪 ( max_grad_norm: 1.0 )。
找不到模型或数据集 路径错误或文件缺失。 1. 检查 model_name_or_path 和 dataset_dir 的路径是否为绝对路径或正确的相对路径。
2. 确认 dataset_info.json 中的 file_name 和 formatting 正确。

6.2 部署与推理阶段问题

问题现象 可能原因 检查与解决
Ollama 运行模型时提示“unexpected end of JSON input” Modelfile 格式错误或模型文件损坏。 1. 重新使用 LLaMA-Factory 的 export 命令生成 Modelfile。
2. 确保基础模型下载完整。
vLLM 启动失败，提示不支持该模型 vLLM 版本过旧或模型架构较新。 1. 升级 vLLM 到最新版本： pip install -U vllm 。
2. 查阅 vLLM GitHub Issues，看是否有关于该模型的讨论。
API 调用返回速度慢 1. 首次加载需要时间。
2. 硬件性能不足。
3. 未启用批处理。 		1. 预热模型（发送一个简单请求）。
2. 对于 vLLM，可以调整 --max-num-seqs 参数增加并行处理数，但注意显存占用。
3. 确保使用的是 GPU 推理。
生成的内容不符合预期或胡言乱语 1. 微调数据量太少或质量差。
2. 训练轮数 ( num_train_epochs ) 过多导致过拟合。
3. 推理时温度 ( temperature ) 参数过高。 		1. 增加高质量的训练数据。
2. 减少训练轮数，或在验证集上早停。
3. 降低 temperature （如设为0.1）以获得更确定性的输出。

6.3 性能优化建议

  1. 推理优化 ：

    • vLLM ：利用其内置的连续批处理和 PagedAttention，这是目前最快的推理方案之一。
    • 量化 ：训练后可以使用 GPTQ、AWQ 等量化技术进一步压缩模型，提升推理速度并降低显存，但可能会轻微损失精度。
    • TensorRT-LLM ：NVIDIA 官方的高性能推理库，能为特定 GPU 和模型生成高度优化的引擎，性能极致，但部署复杂度较高。

  2. 训练优化 ：

    • Flash Attention ：在训练配置中启用 Flash Attention-2（如果硬件和模型支持），可以大幅提升训练速度并减少显存。
    • 梯度累积 ：合理设置 gradient_accumulation_steps ，在有限的显存下使用更大的有效批次大小，有助于训练稳定。
    • 数据加载 ：将数据集预处理成内存映射格式（如 Arrow），可以加速数据读取。

7. 从原型到生产：最佳实践与扩展方向

完成一个本地可运行的Demo只是第一步。要将大模型能力集成到实际应用中，还需要考虑更多工程化因素。

7.1 生产环境检查清单

在将上述流程应用于生产环境前，请逐一核对以下事项：

  • 模型安全与合规 ：确认所使用的开源模型许可证允许商业使用。对生成内容进行安全过滤和审查。
  • 配置外置化 ：所有路径、密钥、超参数都应通过环境变量或配置文件管理，不要硬编码在代码中。
  • 健壮的API服务 ：
    • 为 vLLM API 添加反向代理（如 Nginx），配置 SSL/TLS。
    • 实现 API 密钥认证、请求限流和频率限制。
    • 添加完善的日志记录（请求、响应、耗时、错误）。
  • 监控与告警 ：
    • 监控 GPU 使用率、显存占用、API 响应延迟和成功率。
    • 设置告警阈值，如延迟超过 5 秒或错误率超过 1%。
  • 版本管理与回滚 ：对微调后的模型进行版本化管理。部署新模型时，保留旧版本以便快速回滚。
  • 数据隐私 ：确保微调数据和用户推理数据的安全存储与传输，遵守相关数据保护法规。

7.2 扩展学习方向

掌握了基础流程后，你可以向更深处探索：

  1. 更高效的微调技术 ：深入研究 LoRA、QLoRA 的原理，尝试不同的 lora_target （如 q_proj,v_proj 与 all 的差异），调整 lora_rank （秩）和 lora_alpha （缩放系数）对效果的影响。
  2. 更复杂的任务 ：尝试对话微调（使用多轮对话数据）、代码微调、数学推理微调等。每种任务的数据格式和训练技巧有所不同。
  3. 全参数微调 ：如果你拥有充足的算力（如多张 A100/H100），可以尝试全参数微调，追求极致的性能表现。
  4. 模型评估 ：学习使用 MT-Bench、AlpacaEval 等基准，或构建自己的领域测试集，科学地评估微调前后模型的性能变化。
  5. 多模态大模型 ：将流程扩展到视觉-语言模型（如 LLaVA），学习如何处理图像和文本的联合输入。
  6. 推理优化进阶 ：学习使用 TensorRT-LLM 或 FasterTransformer 进行极致的推理优化，满足高并发、低延迟的线上需求。

大模型技术栈迭代迅速，核心在于理解工作流背后的原理（为什么做量化？LoRA如何起作用？注意力优化如何提升吞吐？），这样无论工具如何变化，你都能快速上手。建议从一个小而具体的任务开始，完整走通本文所述的“环境-数据-训练-部署”闭环，积累第一手的排错经验，这是学习大模型工程化最有效的路径。

# LLaMA-Factory # Ollama
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

cover

AI 已经能直接改设计稿了:Windows部署Penpot，接入Codex MCP实测

avatar 码道开发者社区
cover

【AI大模型】-DeepSeek Harness 深度解析

avatar 码道开发者社区
cover

实测推荐 3 个 Skill，轻松上手 Codex 网页设计与交付流程

avatar 码道开发者社区