# cuda-gpt

**Repository Path**: quzitsix/cuda-gpt

## Basic Information

- **Project Name**: cuda-gpt
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大模型推理服务模板(MetaX 沐曦)

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

## 项目结构

- `Dockerfile`: 用于构建容器镜像的配置文件，MetaX提供docker构建流程，该文件中
    - `FROM`是通过拉取服务器中已存在的docker，因此不要进行改动
    - `EXPOSE`的端口是作为评测的主要接口，因此不要随意变动
- `serve.py`: 推理服务的核心代码，您需要在此文件中修改和优化您的模型加载与推理逻辑
    - `model_local_dict`: 是将模型映射到本地模型的dict
    - Notes: 这个程序不能访问Internet。
- `requirements.txt`: Python依赖列表。您可以添加需要的库。
- `.gitignore`: Git版本控制忽略的文件列表。
- `download_model.py`: 下载权重的脚本，不建议进行修改，模型参数、下载位置和版本都可以在`Dockerfile`中进行调整
    - `--model_name`: 模型名称，该名称是在modelscope中可以被检索的，例如：需要下载`DeepSeek-V3.2`,在modelscope中可知，`model_name`为`deepseek-ai/DeepSeek-V3.2`, 那么配置为`deepseek-ai/DeepSeek-V3.2`即可从modelscope中下载模型，如果您需要下载自己的微调模型，可以在modelscope中上传自己的模型，并调整该参数即可使用；
    - `--cache_dir`: 模型缓存地址，该地址是model存储的位置，例如指定下载`DeepSeek-V3.2`，在`/app`路径中，那么模型存放的位置在`/app/deepseek-ai/DeepSeek-V3.2`中；
    - `--revision`: 模型参数的Git版本，该版本对应modelscope仓库中的版本，您可根据自己微调数个版本，上传到同一仓库中，拉取时采用不同版本的revision即可；
    - Notes: 如果您的模型为非公开，请打开`download_model.py`进行相应的配置，本模板已将该部分注释([代码](download_model.py#L16-L17))，对注释内容取消注释并注入相应的内容即可配置非公开模型。在使用非公开模型时，建议在非judge环境中进行download_model的环境验证，以免浪费judge次数。
- `README.md`: 本说明文档

## 代码优化点详解

## 一、vLLM深度优化配置

### 1. **注意力算子优化**
```python
disable_custom_all_reduce=False  # 启用自定义AllReduce，提升多GPU通信效率
```

### 2. **KV Cache优化**
```python
enable_prefix_caching=True      # 前缀缓存，共享prompt的KV cache
enable_chunked_prefill=True     # 分块预填充，减少长prompt的延迟
block_size=32                   # 优化的块大小，平衡内存和速度
```
**优化效果**: 对于重复或相似的prompt，大幅减少计算量

### 3. **内存优化**
```python
gpu_memory_utilization=0.98     # 最大化GPU内存使用
kv_cache_dtype="auto"           # 自动选择KV cache数据类型
dtype="auto"                    # 自动选择计算数据类型
```
**优化效果**: 在64GB显存下充分利用资源

### 4. **批处理调度优化**
```python
max_num_batched_tokens=131072   # 单批最大token数
max_num_seqs=2048               # 最大并发序列数
scheduling_policy="fcfs"        # 先到先服务调度
async_scheduling=True           # 异步调度，提升吞吐
```
**优化效果**: 支持高并发请求处理

## 二、RAG系统优化

### 1. **轻量级相似度算法**
```python
def simple_similarity(s1: str, s2: str) -> float:
    """字符级Jaccard相似度（超轻量，速度快）"""
    # 移除空白字符减少噪声
    s1 = s1.replace(" ", "").replace("\n", "").replace("\t", "")
    s2 = s2.replace(" ", "").replace("\n", "").replace("\t", "")
    # 使用集合运算计算相似度
    set1 = set(s1)
    set2 = set(s2)
    intersection = len(set1 & set2)
    union = len(set1 | set2)
    return intersection / union if union > 0 else 0.0
```
**优化效果**: O(n)时间复杂度，无额外依赖，适合高频查询

### 2. **二级检索策略**
```python
def query_rag(question: str, threshold: float = 0.9):
    # 1. 精确匹配优先（O(1)查找）
    if question_clean in RAG_DATABASE:
        return RAG_DATABASE[question_clean]
    
    # 2. 相似度匹配（阈值控制）
    best_score = 0.0
    for db_question, db_answer in RAG_DATABASE.items():
        score = simple_similarity(question_clean, db_question)
        if score > best_score:
            best_score = score
            best_answer = db_answer
    
    # 3. 阈值过滤
    if best_score >= threshold:
        return best_answer
```
**优化效果**: 兼顾准确率和召回率

### 3. **RAG重写采样策略**
```python
rag_rewrite_sampling_params = SamplingParams(
    stop=["</OUT>", "<|endoftext|>", "<|im_end|>"],  # 特殊停止标记
    # 其他参数与主采样保持一致
)
```
**优化效果**: 对RAG命中结果进行约束性生成，保持答案一致性

## 三、提示词工程优化

### 1. **提示词模板缓存**
```python
@lru_cache(maxsize=10000)  # LRU缓存，避免重复模板化
def format_prompt(tokenizer, msg: str) -> str:
    message = [{"role": "user", "content": msg}]
    return tokenizer.apply_chat_template(
        message, 
        tokenize=False,
        add_generation_prompt=True,
        enable_thinking=False  # 禁用思考过程，直接生成
    )
```
**优化效果**: 对于重复prompt，模板化速度提升100倍

### 2. **RAG增强提示构造**
```python
merged_msg = (
    f"问题：{msg}"
    f"参考答案：{rag_answer}"
    "任务：请参考答案进行作答，最好只做换行和空格的删减，不修改内容。\n"
)
```
**优化效果**: 明确指导模型行为，减少自由发挥

## 四、推理过程优化

### 1. **差异化采样参数**
```python
per_prompt_params: List[SamplingParams] = []
# 根据是否命中RAG分配不同参数
if rag_answer:
    per_prompt_params.append(rag_rewrite_sampling_params)
else:
    per_prompt_params.append(sampling_params)
```
**优化效果**: 针对不同任务类型优化生成策略

### 2. **批量处理兼容性**
```python
try:
    outputs = llm.generate(final_prompt_texts, per_prompt_params)
except Exception as e:
    # 降级策略：统一使用默认参数
    outputs = llm.generate(final_prompt_texts, sampling_params)
```
**优化效果**: 确保服务鲁棒性，避免单点故障

## 五、预热与初始化优化

### 1. **模型预热**
```python
from warm_up import warmup_inputs
warmup_prompts = [format_prompt(tokenizer, inp) for inp in warmup_inputs]
outputs = llm.generate(warmup_prompts, sampling_params)
```
**优化效果**: 
- 预热CUDA内核
- 初始化KV cache
- 减少首次推理延迟

### 2. **RAG预加载**
```python
# 进程启动时加载一次RAG
load_rag_database()
```
**优化效果**: 避免运行时IO延迟，内存常驻访问

## 六、资源管理优化

### 1. **内存分配策略**
```python
os.environ['PYTORCH_ALLOC_CONF'] = 'expandable_segments:True'
```
**优化效果**: 允许PyTorch动态扩展内存段，减少内存碎片

### 2. **多进程优化**
```python
os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"
```
**优化效果**: 更稳定的多进程启动方式

## 七、文本后处理优化

### 1. **空白字符规范化**
```python
def _collapse_whitespace(text: str) -> str:
    return re.sub(r"\s+", " ", (text or "").strip())
```
**优化效果**: 统一输出格式，减少不必要的空白

### 2. **内容提取优化**
```python
def _extract_between(text: str, start_tag: str, end_tag: str) -> str:
    # 增强鲁棒性：处理未生成结束标记的情况
    if end == -1:
        end = len(text)  # 取到末尾
    return text[start:end].strip()
```
**优化效果**: 避免因生成不完整导致的错误

## 八、统计与监控优化

### 1. **RAG命中统计**
```python
RAG_STATS_LOCK = Lock()  # 线程安全统计
RAG_LAST_REQUEST_STATS = {
    "total": 0,
    "hits": 0,
    "hit_rate": 0.0,
    "timestamp": None,
}
```
**优化效果**: 实时监控RAG效果，便于调优

### 2. **网络连通性检测**
```python
def check_internet(host="8.8.8.8", port=53, timeout=3):
    """快速网络检测"""
    try:
        socket.setdefaulttimeout(timeout)
        socket.socket(socket.AF_INET, socket.SOCK_STREAM).connect((host, port))
        return True
    except Exception:
        return False
```
**优化效果**: 快速判断运行环境，适应不同部署场景

## 总结：核心优化收益

| 优化点 | 性能提升 | 资源节省 |
|--------|----------|----------|
| vLLM前缀缓存 | 重复prompt推理速度提升50%+ | 减少30% KV cache内存 |
| RAG相似度匹配 | 检索速度<1ms/query | 无外部依赖，内存占用小 |
| 提示词模板缓存 | 模板化速度提升100倍 | 减少CPU计算开销 |
| 批量差异化采样 | 提升RAG答案一致性 | 更精准的控制资源 |
| 模型预热 | 首次推理延迟降低70% | 避免冷启动峰值 |

这些优化使得服务在64GB显存的MXC500 GPU上能够高效运行，支持高并发请求，同时保持较低的响应延迟。

主要的测试结果可以见下图：

![alt text](draw/Figure_1.png)


## 如何修改

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

您可以完全替换`serve.py`的内容，只要保证容器运行后，能提供模板中的'/predict'和'/'等端点即可。

## 评测系统的规则

评测系统会向 /predict 端点发送 POST 请求，其JSON body格式为: 
```json
{
  "prompt": "Your question here"
}
```
您的服务必须能够正确处理此请求，并返回一个JSON格式的响应，格式为: 
```json
{
  "response": "Your model's answer here"
}
```
请务必保持此API契约不变！

## 环境说明

### 软件包版本

主要软件包(vllm:maca.ai3.1.0.7-torch2.6-py310-ubuntu22.04-amd64)版本如下：

|软件|版本|
|:--:|:--:|
|python|3.10|
|ubuntu|22.04|
|pytorch|2.6|
|vLLM|0.10.0|

`软件使用的Note`:
- 如果您需要其他的镜像，请您先查询[沐曦开发者社区](https://developer.metax-tech.com/softnova/docker)，查找您需要的docker镜像，后联系龚昊助教添加相应的镜像。
- 建议您先在`OpenHydra`中使用添加的软件，避免软件兼容性带来的问题（非GPU相关的软件都可以兼容，GPU相关软件或依赖GPU相关软件的软件建议验证后使用）。
- `OpenHydra`的访问地址请查询`沐曦GPU实验平台操作手册`，欢迎您的使用。

### judge平台的配置说明

judge机器的配置如下：

``` text
os: ubuntu24.04
cpu: 24核
内存: 200GB
磁盘: 1T
GPU: MXC500(显存：64GB)
网络带宽：100Mbps
```

judge系统的配置如下：

``` text
docker build stage: 900s
docker run - health check stage: 180s
docker run - predict stage: 360s
```

### 本地测试说明

请注意，其他代码为优化过程中的中间版本，具有一定参考价值，`serve.py`为最好的呈现结果

```
运行服务器
uvicorn serve:app --host 0.0.0.0 --port 8000
本地测试
python client.py --mode batch
前端导入
streamlit run web_gui.py
```