# 2025-mdf-hw2

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

## Basic Information

- **Project Name**: 2025-mdf-hw2
- **Description**: 2025年秋季国科大《GPU架构与编程》大作业二
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

本项目是一个极简的大模型推理服务模板，旨在帮助您快速构建一个可以通过API调用的推理服务器。


## 项目结构

- `Dockerfile`: 用于构建容器镜像的配置文件。**请不要修改此文件的 EXPOSE 端口和 CMD 命令，千万不要添加未经允许的镜像，会把硬盘撑爆**。
- `serve.py`: 推理服务的核心代码。您需要在此文件中修改和优化您的模型加载与推理逻辑。这个程序不能访问Internet。
- `requirements.txt`: Python依赖列表。您可以添加您需要的库。
- `.gitignore`: Git版本控制忽略的文件列表。
- `download_model.py`: 下载权重的脚本，可以自行修改，请确保中国大陆的网络能够下载到。可以把权重托管在阿里云对象存储等云平台，或者参考沐曦模板代码中的托管方式。
- `README.md`: 本说明文档。

## 如何修改

您需要关注的核心文件是 `serve.py`。

目前，它使用 `transformers` 库加载了模型 `Qwen/Qwen2.5-0.5B`。您可以完全替换 `serve.py` 的内容，只要保证容器运行后，能提供模板中的'/predict'和'/'等端点即可。

## serve.py 技术说明（qwen2.5-0.5B-instruct）

本项目在 `serve.py` 中使用以下技术与流程来提供推理服务：

- **FastAPI + Pydantic**：用 FastAPI 提供 HTTP API（`/predict` 与 `/`），用 Pydantic 定义请求/响应数据模型并进行校验。
- **vLLM 推理引擎**：用 `vllm.LLM` 在 GPU 上进行高吞吐推理，支持批量请求与高效调度。
- **Transformers Tokenizer**：用 `AutoTokenizer` 加载分词器，并通过 `apply_chat_template` 生成 Qwen 聊天格式提示词。
- **离线加载**：设置 `TRANSFORMERS_OFFLINE=1`，模型从本地 `./model` 加载，避免联网依赖。
- **模型与参数**：使用 `qwen2.5-0.5B-instruct`（本地权重），在 vLLM 中配置 `fp8` 量化与 `bfloat16` 计算，启用 `chunked prefill` 与 `prefix caching`，并设定 `max_model_len=512`、`max_num_seqs=358`、`gpu_memory_utilization=0.95` 等以平衡速度与显存。
- **Warmup**：启动时对模型做一次最小推理（"Hello"），提前初始化缓存与内核，降低首请求延迟。
- **生成参数**：通过 `SamplingParams(max_tokens=384)` 控制生成长度，后续可按需求扩展。
- **批量输入**：`/predict` 端点支持单条字符串或字符串列表输入，返回对应的文本列表。

如需调整性能或质量，可重点修改 `vllm.LLM` 的加载参数与 `SamplingParams`。


**重要**: 评测系统会向 `/predict` 端点发送 `POST` 请求，其JSON body格式为：

```json
{
  "prompt": "Your question here"
}

您的服务必须能够正确处理此请求，并返回一个JSON格式的响应，格式为：

```json
{
  "response": "Your model's answer here"
}
```

**请务必保持此API契约不变！**

## 环境说明

### 软件包版本

主要软件包(nvcr.io/nvidia/pytorch:25.04-py3)版本请参考[NGC Release Notes](https://docs.nvidia.com/deeplearning/frameworks/pytorch-release-notes/rel-25-04.html)


`软件使用的Note`:
- 目前支持

nvcr.io/nvidia/pytorch:25.04-py3 d1eac6220dd9

vllm/vllm-openai:latest 727aad66156b
（该镜像的原始信息为：https://hub.docker.com/layers/vllm/vllm-openai/latest/images/sha256-sha256:6766ce0c459e24b76f3e9ba14ffc0442131ef4248c904efdcbf0d89e38be01fe0

swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/vllm/vllm-openai:v0.11.0 d8d39b59e909

- 如果您需要其他的镜像，请参与[问卷](https://tp.wjx.top/vm/OciiNf5.aspx)。

### judge平台的配置说明

judge机器的配置如下：

``` text
os: ubuntu24.04
cpu: 14核
内存: 120GB
磁盘: 492GB（已用72GB）
GPU: RTX5090(显存：32GB)
网络带宽：100Mbps，这个网络延迟的波动性比较大，所以给build阶段预留了25分钟的时间
```

judge系统的配置如下：

``` text
docker build stage: 1500s
docker run - health check stage: 420s
docker run - predict stage: 360s
```