# 2025-zk-hw2

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

## Basic Information

- **Project Name**: 2025-zk-hw2
- **Description**: 2025-zk-hw2
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 2025年秋季国科大《GPU架构与编程》作业二：vLLM High-Performance Inference Service

这是一个基于 [vLLM](https://github.com/vllm-project/vllm) 和 [FastAPI](https://fastapi.tiangolo.com/) 构建的高性能 LLM 推理服务。

该服务专为 **CUDA/GPU 编程** 问答场景优化，使用了 基于`Qwen2.5-0.5B`微调的`Plus-Qwen0.5B-GPU-v1` 模型，并针对批量请求（Batch Processing）进行了深度调优。

项目地址：https://gitee.com/gpuap/gpu2bq.git

## ✨ 核心特性

- **极致性能**:
  - 使用 vLLM 的 `AsyncLLMEngine` 进行异步推理。
  - 针对高并发场景优化配置：`max_num_seqs=512`，确保请求一次性进入 GPU 处理，避免排队。
  - 显存利用率设置为 `0.95`，充分利用硬件资源。
  - 关闭无关日志 (`disable_log_stats=True`) 以减少 CPU 开销。
- **特定领域优化**:
  - 内置 System Prompt，强制设定为 CUDA 和 GPU 编程专家角色。
  - 输出格式严格控制：直接输出答案，无废话，保留术语。
- **自动预热 (Warmup)**:
  - 启动时自动执行一次推理预热，触发 CUDA Kernel 编译，消除首字延迟。

## 🛠️ 环境依赖

请确保安装了以下 Python 库（以及 vLLM 及其依赖的 CUDA 环境）：

```bash
pip install -r requirements.txt
pip install vllm
```

*注意：vLLM 需要 Linux 环境及支持 CUDA 的 GPU。*

## ⚙️ 模型配置

在 `serve.py` 中，模型路径配置在 `model_local_dict` 中。请根据实际情况修改模型路径或 ModelScope ID：

```python
# serve.py
model_local_dict = {
    # 修改为你的本地绝对路径 或 ModelScope 模型 ID
    "Plus-Qwen0.5B-GPU-v1": "/app/kkkz9988/Plus-Qwen0.5B-GPU-v1"
}
```

## 🚀 启动服务

使用 uvicorn 运行：

```bash
uvicorn serve:app --host 0.0.0.0 --port 8000
```

服务启动后会进行模型加载和预热，看到 `Warmup completed.` 即表示服务就绪。

## 🔌 API 接口说明

### 1. 健康检查 / 模式识别

- **URL**: `/`

- **Method**: `GET`

- **Response**:

  ```json
  {"status": "batch"}
  ```

### 2. 推理接口

- **URL**: `/predict`
- **Method**: `POST`
- **Content-Type**: `application/json`
- **Request Body**:

支持单个 Prompt 字符串或 Prompt 列表（Batch 模式）。

```json
{
  "prompt": "如何优化 CUDA kernel 的 shared memory 访问？"
}
```

或者批量（推荐）：

```json
{
  "prompt": [
    "解释 Warp Divergence",
    "什么是 Coalesced Memory Access？"
  ]
}
```

- **Response**:

```json
{
  "response": [
    "Warp Divergence 发生在同一个 warp 中的线程执行不同的指令路径时...",
    "Coalesced Memory Access 是指..."
  ]
}
```

## 📝 调优参数说明

代码中包含针对特定评测/竞赛场景的硬编码优化：

- **System Prompt**: 

  > 你是CUDA和GPU编程专家。直接输出答案，不要发散, 不要输出思考过程, 术语、函数名、符号、英文关键词保持原样。

- **Sampling Params**:

  - `temperature=0.0`: 贪婪采样，保证结果确定性。
  - `max_tokens=512`: 防止生成过长内容。
  - `stop_token_ids`: 包含 Qwen 特定的结束符。

## ⚠️ 注意事项

1. **显存要求**: 默认配置 `gpu_memory_utilization=0.95`，请确保 GPU 有足够显存。
2. **并发设置**: `max_num_seqs=512` 是为了应对大批量输入，请根据实际显存大小适当调整，防止 OOM（Out Of Memory）。