# 2025-fyh-hw2

**Repository Path**: gpuap/2025-fyh-hw2

## Basic Information

- **Project Name**: 2025-fyh-hw2
- **Description**: https://github.com/13064606210/gpu2
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 2025年秋季国科大《GPU架构与编程》大作业二

本项目包含用于 Qwen 系列模型（如 Qwen2.5/Qwen3）的微调训练脚本与高性能推理服务。项目针对摩尔线程（Moore Threads）显卡进行了适配，并支持 Batch 推理以优化生产环境吞吐量。

## 目录结构

```text
.
├── train.py                  # LoRA 微调训练脚本
├── inference_server.py       # 基于 FastAPI + MUSA 的批量推理服务
├── qwen3_lora_5p_output/     # (自动生成) 训练输出目录
├── local-model/              # (需准备) 原始模型权重目录
│   ├── config.json
│   ├── model.safetensors
│   ├── tokenizer.json
│   └── chat_template.jinja   # 必需：对话模板文件
├── data.json                 # (示例) 训练数据文件
└── README.md                 # 说明文档
```

## 环境依赖

### 通用依赖
```bash
pip install -r requirements.txt
```

### 摩尔线程 (MUSA) 依赖
推理服务依赖 `torch_musa`，请确保运行环境已安装适配摩尔线程显卡的 PyTorch 版本。
```bash
# 请查阅摩尔线程开发者文档安装
pip install torch_musa
```

---

## 1. 模型微调 (Training)

`train.py` 使用 LoRA (Low-Rank Adaptation) 技术对模型进行指令微调。

### 特性
*   **智能 Masking**: 自定义 `process_data` 函数，自动屏蔽 User 提问部分的 Loss，模型仅学习 Assistant 的回答。
*   **显存优化**: 支持 fp16/bf16 训练，可配置 `BitsAndBytesConfig` 进行 4bit 量化加载。
*   **LoRA 配置**: 默认针对 Qwen 架构的所有线性层 (`q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`)。

### 数据格式
准备 JSON 文件（如 `data.json`），需包含 `question` 和 `answer` 两个字段：
```json
[
  {
    "question": "cuda是什么？",
    "answer": "cuda是..."
  },
  {
    "question": "...",
    "answer": "..."
  }...
]
```

### 运行训练
1.  修改 `train.py` 中的路径配置：
    ```python
    MODEL_ID = "/path/to/your/local-model"  # 基座模型路径
    DATA_FILE = "/path/to/your/data.json"    # 数据路径
    OUTPUT_DIR = "./qwen3_lora_5p_output"    # 输出路径
    ```
2.  启动训练：
    ```bash
    python train.py
    ```

---

## 2. 推理服务 (Inference API)

`inference_server.py` 提供了一个兼容 OpenAI 风格（简化版）的 HTTP 接口。

### 特性
*   **MUSA 加速**: 显式调用 `.to("musa")`，利用摩尔线程显卡加速推理。
*   **Batch Inference**: 实现了 `process_batch_prompts`，支持一次性处理多条 Prompt，大幅提升吞吐量。
*   **Padding 修正**: 强制设置 `padding_side='left'`，解决了 Decoder-only 模型在 Batch 推理时的乱码问题。
*   **离线模式**: 强制 `TRANSFORMERS_OFFLINE=1`，仅使用本地模型文件。

### 部署前准备
*   **Chat Template**: 必须在模型文件夹内提供 `chat_template.jinja` 文件。
*   **检查设备**: 确保机器可以运行 `import torch_musa`。

### 启动服务
```bash
# 推荐单进程启动以独占显卡资源
uvicorn inference_server:app --host 0.0.0.0 --port 8000 --workers 1
```

### API 使用示例

**URL**: `POST /predict`

**Case A: 单条测试**
```bash
curl -X POST "http://127.0.0.1:8000/predict" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "你好，请介绍一下你自己。"}'
```

**Case B: 批量测试 (Batch)**
发送列表格式的 prompt，服务端将自动进行 Padding 并行推理。
```bash
curl -X POST "http://127.0.0.1:8000/predict" \
     -H "Content-Type: application/json" \
     -d '{"prompt": ["鲁迅和周树人是什么关系？", "1+1等于几？", "写一首关于秋天的诗。"]}'
```

## 3. 模型合并 (merge_model.py)

由于train代码仅保存lora部分，需要使用合并脚本将基座模型和lora参数进行合并，生成完整的模型参数。

## 4. 模型下载 (download_model.py)

`download_model.py` 提供了一个基于豆包生成数据集微调的Qwen3模型，通过运行该文件即可下载，下载完毕后会在当前目录下生成一个local_model文件夹，存放模型权重，chat模板等相关文件。

---

## 注意事项

1.  **路径修改**: 请务必将代码中硬编码的绝对路径替换为您实际的本地路径。
2.  **显存管理**: 推理服务加载了 float16 模型。如果遇到 OOM (显存溢出) 错误，请减小 `batch_size` 或在加载模型时启用 4-bit 量化。
3.  **编译加速**: 代码中保留了 `torch.compile` 的注释，如果在支持的环境下（Linux + 较新 PyTorch），可取消注释以获得更快的推理速度。