# metax-demo

**Repository Path**: kyleucas/metax-demo

## Basic Information

- **Project Name**: metax-demo
- **Description**: metax-demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 203
- **Created**: 2025-12-08
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CUDA编程知识问答模型服务

**课程**: 2025年秋季国科大《GPU架构与编程》  
**项目开源地址**: https://gitee.com/kyleucas/metax-demo  
**详细说明文档**: 请查看 [大作业二说明文档.md](./大作业二说明文档.md)

---

## 模型说明

本服务使用已上传到 ModelScope 的合并模型。模型在 Docker 构建阶段通过 `download_model.py` 预先下载，避免运行时下载导致健康检查超时。

- **ModelScope 模型ID**: `mxy333333/Qwen3-0.6B-GPU-basic`
- **基础模型**: Qwen3-0.6B
- **微调方式**: LoRA (Low-Rank Adaptation)
- **训练数据**: 500条CUDA编程问答数据
- **模型状态**: 已合并LoRA权重，可直接使用
- **加载方式**: 评测环境只从 ModelScope 加载模型

## 快速开始

### 构建镜像

```bash
docker build -t cuda-qa-service .
```

### 运行服务

```bash
docker run -p 8000:8000 --gpus all cuda-qa-service
```

### API 使用

#### 单个请求

```bash
curl -X POST http://localhost:8000/predict \
     -H 'Content-Type: application/json' \
     -d '{"prompt": "什么是CUDA中的共享内存？"}'
```

#### 批量请求

```bash
curl -X POST http://localhost:8000/predict \
     -H 'Content-Type: application/json' \
     -d '{"prompt": ["问题1", "问题2", "问题3"]}'
```

## 模型加载说明

### ModelScope 自动下载

服务启动时会自动从 ModelScope 下载模型（如果本地缓存不存在）：

1. **首次运行**: 会自动下载模型（约1-1.5GB，需要时间）
2. **后续运行**: 使用本地缓存，加载速度更快
3. **缓存位置**: `~/.cache/modelscope/hub/models/mxy333333/Qwen3-0.6B-GPU-basic`

### 环境变量

- `VLLM_USE_MODELSCOPE=True`: 启用 vLLM 的 ModelScope 支持（已在 Dockerfile 中设置）
- `MODELSCOPE_API_TOKEN` 或 `MS_TOKEN`: ModelScope 访问令牌（如果需要）

### ModelScope Token 设置

如果模型需要认证，需要设置 ModelScope 访问令牌：

1. **获取 Token**:
   - 访问 https://www.modelscope.cn/my/myaccesstoken
   - 登录后创建新的访问令牌

2. **设置方式**:
   
   **方式1: 构建时传入（推荐）**
   ```bash
   docker build --build-arg MODELSCOPE_TOKEN=your_token_here -t cuda-qa-service .
   ```
   
   **方式2: 运行时传入**
   ```bash
   docker run -p 8000:8000 --gpus all \
     -e MODELSCOPE_API_TOKEN=your_token_here \
     cuda-qa-service
   ```
   
   **方式3: 环境变量文件**
   ```bash
   # 创建 .env 文件
   echo "MODELSCOPE_API_TOKEN=your_token_here" > .env
   
   # 运行时使用
   docker run -p 8000:8000 --gpus all --env-file .env cuda-qa-service
   ```

### 模型加载方式

**评测环境只从 ModelScope 加载模型**：
- 模型ID: `mxy333333/Qwen3-0.6B-GPU-basic`
- 在 Docker 构建时预先下载
- 服务启动时从缓存加载，无需重新下载

## 技术细节

### 依赖

- vLLM (支持 ModelScope)
- ModelScope SDK
- FastAPI
- Transformers

### 服务配置

- **端口**: 8000
- **并发**: 支持批量请求
- **GPU**: 必须使用GPU（沐曦C500或其他CUDA兼容GPU）

## 健康检查

```bash
curl http://localhost:8000/
```

返回服务状态和初始化日志。

## 项目结构

```
metax-demo/
├── Dockerfile              # Docker 构建文件（必须提交）
├── requirements.txt        # Python 依赖（必须提交）
├── download_model.py       # 模型下载脚本（必须提交，Dockerfile 需要）
├── serve.py                # 服务代码（必须提交，Dockerfile 需要）
├── README.md               # 项目文档
└── .gitignore             # Git 忽略文件配置
```

**重要**：`download_model.py` 必须提交到代码仓库，因为 Dockerfile 在构建时需要它来下载模型。

## 注意事项

1. **构建阶段**: 模型在 Docker 构建时下载（约1-1.5GB，需要时间）
2. **运行阶段**: 服务从 ModelScope 缓存加载模型，无需重新下载
3. **网络要求**: 构建时需要能够访问 ModelScope (www.modelscope.cn)
4. **GPU要求**: 必须使用GPU，不支持CPU推理
5. **显存要求**: 建议至少4GB显存（0.6B模型较小）
6. **健康检查**: 模型在构建时已下载，服务启动时不会超时

## 模型信息

- **模型地址**: https://www.modelscope.cn/models/mxy333333/Qwen3-0.6B-GPU-basic
- **下载方式**: 
  ```python
  from modelscope import snapshot_download
  model_dir = snapshot_download('mxy333333/Qwen3-0.6B-GPU-basic')
  ```

## 详细说明文档

本项目包含详细的说明文档，请查看 [大作业二说明文档.md](./大作业二说明文档.md)，其中包含：

- 完整的项目概述和技术架构说明
- 详细的部署和使用指南
- **GPU推理速度优化详解**（重点内容，详细说明如何提升tokens/s性能）
- 性能测试方法和验证结果
- 常见问题解答

**课程**: 2025年秋季国科大《GPU架构与编程》  
**项目开源地址**: https://gitee.com/kyleucas/metax-demo