1. 环境准备：从零搭建Qwen2.5-7B-Instruct的FastApi服务

想要在Ubuntu系统上玩转Qwen2.5-7B-Instruct模型？FastApi部署是最接地气的方案之一。我去年在智能客服项目中就用过这套组合，实测下来生成速度和稳定性都不错。不过很多新手容易在环境准备阶段翻车，今天我就把踩过的坑和最佳实践一次性说清楚。

先看基础配置需求。我的测试环境是Ubuntu 22.04 LTS，搭配NVIDIA RTX 3090显卡。这里有个关键点：CUDA版本必须和PyTorch版本严格匹配。有次我用CUDA 11.8配PyTorch 2.3.0，直接报错找不到cuBLAS库。后来发现PyTorch 2.3.0官方推荐搭配CUDA 12.1，换完瞬间解决问题。

1.1 Python环境配置

建议直接上Python 3.12，性能提升明显。用pyenv管理多版本特别方便：

# 安装编译依赖
sudo apt-get update
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# 安装pyenv
curl https://pyenv.run | bash
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

# 安装Python 3.12
pyenv install 3.12.3
pyenv global 3.12.3

验证安装时有个细节容易忽略：

python -c "import ssl; print(ssl.OPENSSL_VERSION)"

如果输出显示OpenSSL版本过旧，需要手动升级，否则后续pip安装可能报证书错误。

1.2 CUDA与PyTorch安装

CUDA安装建议用官方runfile方式，比deb包更灵活。先卸载旧驱动：

sudo apt-get purge nvidia*
sudo apt-get autoremove

下载CUDA 12.1安装包后，关键安装参数要这样选：

sudo sh cuda_12.1.1_530.30.02_linux.run \
--override \
--toolkit \
--samples \
--silent \
--driver

安装后需要手动配置环境变量。在~/.bashrc中添加：

export PATH=/usr/local/cuda-12.1/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

PyTorch安装务必用官方命令：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

验证安装时别只用torch.cuda.is_available()，还要测试实际计算：

import torch
x = torch.randn(3,3).cuda()
print(x @ x.T)  # 应该输出矩阵乘积结果

2. 依赖库安装与加速技巧

国内用户最头疼的就是pip安装超时问题。除了换清华源，还有几个加速妙招。先说基础操作：

python -m pip install --upgrade pip
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

2.1 关键依赖版本锁定

在Qwen2.5-7B-Instruct项目中，这些版本组合最稳定：

pip install \
requests==2.31.0 \
fastapi==0.115.1 \
uvicorn==0.30.6 \
transformers==4.44.2 \
huggingface-hub==0.25.0 \
accelerate==0.34.2 \
modelscope==1.18.0 \
flash-attn==2.5.8 --no-build-isolation

特别注意flash-attn的安装，如果直接pip可能会编译失败。推荐先安装编译环境：

sudo apt-get install -y ninja-build
pip install flash-attn --no-build-isolation

2.2 离线安装方案

在企业内网环境时，可以提前下载好whl文件：

pip download -d ./pip_packages \
-r requirements.txt \
--platform manylinux2014_x86_64 \
--python-version 3.12 \
--only-binary=:all:

然后用离线安装：

pip install --no-index --find-links=./pip_packages -r requirements.txt

3. 模型下载与配置

模型下载是最耗时的环节，15GB的Qwen2.5-7B-Instruct用常规方法可能要几小时。这里分享我的加速方案。

3.1 多线程下载技巧

在model_download.py中使用多线程：

from modelscope import snapshot_download
import os

os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
model_dir = snapshot_download(
    'qwen/Qwen2.5-7B-Instruct',
    cache_dir='/root/llm-weights',
    revision='master',
    max_workers=8  # 增加下载线程数
)

设置HF_ENDPOINT环境变量可以切换镜像源。如果中途断网，重新运行会自动续传。

3.2 模型验证方法

下载完成后务必验证模型完整性：

from transformers import AutoModel
model = AutoModel.from_pretrained('/root/llm-weights/qwen/Qwen2___5-7B-Instruct', trust_remote_code=True)
print(model.config)  # 应该输出模型配置信息

如果报错"Invalid checkpoint"，可能是下载不完整，需要删除缓存重新下载。

4. FastApi服务部署实战

api.py的编写有几个关键点需要注意，直接影响服务稳定性。

4.1 内存优化配置

在加载模型时加入内存优化参数：

model = AutoModelForCausalLM.from_pretrained(
    model_name_or_path,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=True,
    offload_folder="offload"  # 临时卸载目录
)

对于24GB显存的显卡，可以添加量化配置：

from transformers import BitsAndBytesConfig
quant_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16
)
model = AutoModelForCausalLM.from_pretrained(
    model_name_or_path,
    quantization_config=quant_config
)

4.2 服务端优化参数

uvicorn启动时调优参数能显著提升并发能力：

uvicorn.run(
    app,
    host='0.0.0.0',
    port=8848,
    workers=1,
    limit_concurrency=100,
    timeout_keep_alive=300,
    loop="uvloop",  # 比asyncio默认循环更快
    http="httptools"  # 高性能HTTP解析
)

对于生产环境，建议搭配nginx做反向代理：

location / {
    proxy_pass http://127.0.0.1:8848;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 300s;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

5. 接口调用与性能调优

服务部署好后，如何高效调用也很关键。实测发现几个参数对响应速度影响很大。

5.1 生成参数优化

在generate方法中调整这些参数：

generated_ids = model.generate(
    model_inputs.input_ids,
    max_new_tokens=512,
    temperature=0.7,  # 控制随机性
    top_p=0.9,  # 核采样阈值
    do_sample=True,
    repetition_penalty=1.1,  # 防重复
    pad_token_id=tokenizer.eos_token_id
)

对于长文本生成，建议启用流式响应：

from fastapi.responses import StreamingResponse

@app.post("/stream")
async def stream_response(request: Request):
    async def generate():
        for chunk in model.generate_stream(...):
            yield f"data: {chunk}\n\n"
    
    return StreamingResponse(generate(), media_type="text/event-stream")

5.2 压力测试方案

用locust模拟高并发场景：

from locust import HttpUser, task

class ApiUser(HttpUser):
    @task
    def generate_text(self):
        self.client.post(
            "/",
            json={"prompt": "写一篇关于人工智能的短文"},
            headers={"Content-Type": "application/json"}
        )

启动测试：

locust -f locustfile.py --headless -u 100 -r 10 -t 5m

根据测试结果调整uvicorn的并发参数。我发现在RTX 3090上，Qwen2.5-7B-Instruct的最佳并发数在8-12之间。