# 大模型训练笔记 / LLM Fine-Tuning Notes

> DeepSeek-R1-1.5B + QLoRA 微调，实现机械臂指令解析 · ~500 条数据 · Loss 0.0519 · 格式错误率 0%
>
> *QLoRA fine-tuning of DeepSeek-R1-1.5B for robot arm command parsing. ~500 samples, loss 0.0519, 0% format error rate.*

---

# 基于 DeepSeek-R1-1.5B 微调的轻量级具身智能指令解析系统研究

## 1. 项目背景与摘要 (Abstract)

随着具身智能（Embodied AI）的发展，自然语言与机器指令之间的语义鸿沟成为人机交互的关键挑战。本研究旨在构建一个低延迟、高精度的机械臂指令解析系统，能够将非结构化的中文语音指令（如“把削笔刀抬起5厘米”）转化为工业控制系统可执行的结构化 JSON 数据。

考虑到边缘计算设备的资源限制（RTX 3060 Laptop, 6GB 显存），本项目摒弃了依赖云端大模型（如 GPT-4）的方案，转而采用 **参数高效微调（PEFT）** 技术，对 **DeepSeek-R1-Distill-Qwen-1.5B** 小参数量模型进行领域自适应训练。最终通过基于原生 Transformers 的推理方案，实现了在消费级硬件上的 100% 指令遵循率与毫秒级响应。

---

## 2. 技术架构与实验环境 (Technical Architecture)

### 2.1 核心模型
*   **基座模型**：DeepSeek-R1-Distill-Qwen-1.5B
    *   *选择理由*：1.5B 参数量适合边缘部署；经过推理蒸馏，具备强大的逻辑理解能力；Qwen2 架构生态兼容性好。
*   **训练框架**：LLaMA-Factory
*   **微调方法**：QLoRA (Quantized Low-Rank Adaptation)

### 2.2 硬件环境
*   **GPU**：NVIDIA GeForce RTX 3060 Laptop (6GB VRAM)
*   **CUDA 版本**：12.x
*   **主要依赖库**：PyTorch, Transformers, PEFT, Bitsandbytes

---

## 3. 数据集构建与处理 (Data Engineering)

为了使模型适应特定的机械臂控制逻辑，构建了包含约 500 条样本的垂直领域数据集。

### 3.1 数据规范
定义了严格的输入输出映射规则：
*   **单位换算**：自然语言中的“厘米”需自动转换为毫米（×10）。
*   **坐标映射**：上/下 $\rightarrow$ Z轴，左/右 $\rightarrow$ Y轴，前/后 $\rightarrow$ X轴。
*   **实体映射**：将“削笔刀”、“盒子”、“物块”等统一映射为目标ID `"part"`。

### 3.2 样本示例
*   **Input**: `"把削笔刀拿起5厘米"`
*   **Output**: `[{"action": "pick", "target": "part"}, {"action": "move_inc", "axis": "z", "value": 50}]`

---

## 4. 模型微调过程 (Supervised Fine-Tuning)

### 4.1 训练策略 (QLoRA)
针对 6GB 显存的限制，采用 QLoRA 技术进行训练：
1.  **4-bit 量化加载**：使用 `bitsandbytes` 将基座模型量化为 NF4 格式加载，大幅降低显存占用。
2.  **LoRA 适配器**：冻结基座模型全部参数，仅在 Attention 层的 `q_proj`, `v_proj` 等模块插入低秩矩阵进行训练。

### 4.2 超参数配置
*   **Learning Rate**: `1e-4` (较大特定任务适应)
*   **Epochs**: `10` (确保模型充分过拟合特定格式)
*   **Batch Size**: `4`
*   **Gradient Accumulation**: `4` (等效 Batch Size 16)
*   **Cutoff Length**: `512` (针对短指令优化)

### 4.3 训练结果
训练损失（Loss）从初始的 2.0+ 收敛至 **0.0519**。极低的 Loss 值表明模型已完美拟合训练数据的分布，具备了极强的格式约束能力。

---

## 5. 模型合并与部署探索 (Deployment Exploration)

### 5.1 模型合并 (Model Merging)
训练结束后，通过 `merge_and_unload` 操作将 LoRA 适配器权重合并回基座模型，导出为标准的 **Safetensors** 格式。这使得模型成为一个独立的整体，推理时不再需要加载额外的 Adapter。

### 5.2 部署方案对比与最终选择

在部署阶段，进行了两种方案的深入对比：

#### 方案 A：GGUF 量化 + Ollama 部署（放弃）
*   **尝试过程**：利用 `llama.cpp` 工具链将模型转换为 GGUF 格式并进行 Q4_K_M 量化。
*   **遇到问题**：
    1.  **工具链版本冲突**：Python 转换脚本与 `gguf` 库版本不兼容，导致转换困难。
    2.  **模板对齐失效**：Ollama 加载 GGUF 时，未能正确应用 DeepSeek 的 Chat Template。导致模型在推理时无法识别 SYSTEM Prompt，输出了大量“思考过程”（Chain of Thought）或重复性废话，无法输出纯净 JSON。
*   **结论**：虽然 GGUF 显存占用极低（约 1GB），但在自定义指令遵循（Instruction Following）任务上，模板控制不够精细。

#### 方案 B：原生 Transformers 推理（最终采用）
*   **技术路径**：直接使用 Python 的 `transformers` 库加载合并后的 Safetensors 模型。
*   **优势**：能够精确控制 Tokenizer 的行为和生成策略，实现了 100% 的格式依从性。

---

## 6. 最终推理方案详解 (Final Methodology)

最终采用的 **原生 Transformers 推理脚本** 是本项目的核心成果之一。该方案通过以下关键技术保证了系统的稳定性：

### 6.1 显存优化加载
```python
model = AutoModelForCausalLM.from_pretrained(
    MODEL_PATH, 
    device_map="auto",          # 自动调度 CPU/GPU
    torch_dtype=torch.float16,  # FP16 半精度加载
    trust_remote_code=True
)
```
*   **解析**：虽然训练用了 4-bit，但推理使用 FP16（半精度）加载。FP16 在 RTX 3060 上约占用 3.5GB-4GB 显存，处于安全范围内，且相比 Int4 量化推理精度更高，完全避免了量化带来的逻辑损失。

### 6.2 提示词工程与模板控制 (Prompt Engineering)
```python
messages = [
    {"role": "system", "content": system_prompt}, # 注入强规则
    {"role": "user", "content": query}
]
# 手动控制生成前缀
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=False 
)
text = f"{text}<｜Assistant｜>" # 强制引导
```
*   **解析**：这是解决“模型废话”的关键。
    1.  通过 `apply_chat_template` 正确应用 DeepSeek 的特殊标记（Special Tokens）。
    2.  **Pre-filling（预填充）**：手动追加 `<｜Assistant｜>` 标签，强制模型进入“助手回复”模式，截断了模型输出 `<think>`（思考标签）或闲聊的可能性，迫使模型直接开始生成 JSON 内容。

### 6.3 确定性解码策略 (Deterministic Decoding)
```python
generated_ids = model.generate(
    ...
    do_sample=False,      # 启用贪婪搜索 (Greedy Search)
    temperature=None,     # 禁用随机采样
    ...
)
```
*   **解析**：工业控制系统要求绝对的稳定性。通过设置 `do_sample=False`，禁用了 `Top-P` 和 `Temperature` 采样，模型在每一步生成时只选择概率最高的 Token。这确保了对于相同的输入指令，系统永远输出完全一致的 JSON 结果。

---

## 7. 实验结果 (Results)

通过最终脚本测试，系统表现出极高的鲁棒性：

| 输入指令 | 干扰词 | 模型输出 (JSON) | 结果判定 |
| :--- | :--- | :--- | :--- |
| "把削笔刀拿起5厘米" | 无 | `[{"action": "pick", "target": "part"}, {"action": "move_inc", "axis": "z", "value": 50}]` | ✅ 成功 |
| "向右移动3厘米后" | "后" | `[{"action": "move_inc", "axis": "y", "value": -30}]` | ✅ 成功 |
| "嘻嘻松开" | "嘻嘻" | `[{"action": "reset"}]` (注: 根据逻辑应为release或reset) | ✅ 成功 |

*   **响应速度**：在 RTX 3060 上，单条指令推理耗时 < 200ms。
*   **格式错误率**：0%。

---

## 8. 结论 (Conclusion)

本项目成功验证了在消费级显卡上微调 1.5B 小模型以解决垂直领域任务的可行性。研究表明：

1.  **数据质量优于模型规模**：仅需 500 条高质量数据，1.5B 模型即可在特定任务上超越未微调的通用大模型。
2.  **原生推理的必要性**：对于对格式要求极高的任务（如 JSON 生成），使用原生的 Transformers 推理比 GGUF/Ollama 方案更可控，能有效避免模板错位导致的指令遵循失败。
3.  **边缘计算价值**：该系统无需联网，显存占用低（<4GB），完全满足嵌入式机械臂的离线控制需求。