Qwen3-8B vLLM 部署调用 - 详细Linux+VSCode教程

最新推荐文章于 2025-08-12 19:38:23 发布

原创最新推荐文章于 2025-08-12 19:38:23 发布 · 491 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#linux #vscode #运维

0基础学习python 专栏收录该内容

20 篇文章

订阅专栏

Qwen3-8B vLLM 部署调用 - 详细Linux+VSCode教程

本教程专为使用Linux系统、VSCode编辑器和Python 3.10.18环境的用户设计，将详细指导你完成Qwen3-8B模型的vLLM部署全过程。

1. 环境准备与验证

1.1 系统环境确认

在VSCode终端中执行以下命令：

# 查看系统版本
lsb_release -a

# 查看GPU信息
nvidia-smi

# 查看Python版本
python --version  # 确认显示Python 3.10.18

1.2 CUDA环境配置

# 检查CUDA版本
nvcc --version

# 如果未安装CUDA 12.x，执行以下步骤：
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin
sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/3bf863cc.pub
sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/ /"
sudo apt-get update
sudo apt-get -y install cuda-12-4

# 添加环境变量到~/.bashrc
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

1.3 Python环境配置

在VSCode中创建新终端(Ctrl+Shift+`)：

# 创建虚拟环境
python -m venv qwen_env
source qwen_env/bin/activate

# 安装必要依赖
pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 安装PyTorch(适配Python 3.10和CUDA 12)
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121

# 验证PyTorch能使用CUDA
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

2. 模型下载与准备

2.1 安装模型下载工具

pip install modelscope

2.2 创建模型下载脚本

在VSCode中新建文件model_download.py：

from modelscope import snapshot_download
import os

# 设置下载路径(建议至少30GB空间)
model_dir = "/home/your_username/models"  # 替换为你的实际路径
os.makedirs(model_dir, exist_ok=True)

# 下载模型
model_path = snapshot_download(
    'Qwen/Qwen3-8B',
    cache_dir=model_dir,
    revision='master'
)

print(f"模型已下载到: {model_path}")

2.3 执行下载

python model_download.py

下载过程可能持续30-60分钟，取决于网络速度。可以通过以下命令监控进度：

# 查看下载进度
du -sh /home/your_username/models/Qwen/Qwen3-8B

3. 基础调用测试

3.1 安装vLLM

pip install vllm==0.3.3  # 指定兼容版本

3.2 创建测试脚本

新建vllm_test.py文件：

from vllm import LLM, SamplingParams
from transformers import AutoTokenizer
import os

# 配置环境变量
os.environ['VLLM_USE_MODELSCOPE'] = 'True'

def initialize_model():
    # 修改为你的实际模型路径
    model_path = "/home/your_username/models/Qwen/Qwen3-8B"
    
    # 初始化分词器
    tokenizer = AutoTokenizer.from_pretrained(
        model_path,
        use_fast=False,
        trust_remote_code=True
    )
    
    # 初始化LLM
    llm = LLM(
        model=model_path,
        tokenizer=model_path,
        max_model_len=8192,
        trust_remote_code=True
    )
    
    return llm, tokenizer

def generate_response(llm, tokenizer, prompt):
    # 准备采样参数
    sampling_params = SamplingParams(
        temperature=0.6,
        top_p=0.95,
        top_k=40,
        max_tokens=1024,
        stop_token_ids=[151645, 151643]  # Qwen的特殊停止token
    )
    
    # 格式化提示词
    messages = [{"role": "user", "content": prompt}]
    formatted_prompt = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
        enable_thinking=True
    )
    
    # 生成响应
    outputs = llm.generate([formatted_prompt], sampling_params)
    return outputs[0]

if __name__ == "__main__":
    # 初始化模型
    llm, tokenizer = initialize_model()
    
    # 测试不同提示词
    test_prompts = [
        "解释量子计算的基本原理",
        "用Python写一个快速排序算法",
        "如何学习深度学习？给出详细路线图"
    ]
    
    for prompt in test_prompts:
        print("\n" + "="*50)
        print(f"用户提问: {prompt}")
        print("="*50)
        
        output = generate_response(llm, tokenizer, prompt)
        response = output.outputs[0].text
        
        # 处理思考过程与最终回答
        if "<think>" in response:
            think_part = response.split("<think>")[1].split("</think>")[0]
            answer_part = response.split("</think>")[1]
            
            print("[模型思考过程]:")
            print(think_part.strip())
            print("\n[最终回答]:")
            print(answer_part.strip())
        else:
            print(response)
        
        print("="*50)

3.3 运行测试

python vllm_test.py

4. 启动API服务

4.1 创建启动脚本

新建start_api.sh：

#!/bin/bash

# 激活虚拟环境
source /path/to/qwen_env/bin/activate

# 设置环境变量
export VLLM_USE_MODELSCOPE=true

# 启动API服务
vllm serve /home/your_username/models/Qwen/Qwen3-8B \
  --served-model-name Qwen3-8B \
  --max-model-len 8192 \
  --enable-reasoning \
  --reasoning-parser deepseek_r1 \
  --host 0.0.0.0 \
  --port 8000

4.2 使脚本可执行并运行

chmod +x start_api.sh
./start_api.sh

5. API测试与集成

5.1 基础测试

新建api_test.py：

import requests
import json

def test_completions_api():
    url = "http://localhost:8000/v1/completions"
    headers = {"Content-Type": "application/json"}
    data = {
        "model": "Qwen3-8B",
        "prompt": "请解释神经网络的工作原理<think>",
        "max_tokens": 1024,
        "temperature": 0.7
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

def test_chat_completions_api():
    url = "http://localhost:8000/v1/chat/completions"
    headers = {"Content-Type": "application/json"}
    data = {
        "model": "Qwen3-8B",
        "messages": [
            {"role": "system", "content": "你是一个AI助手"},
            {"role": "user", "content": "如何准备机器学习面试？<think>"}
        ],
        "max_tokens": 1024
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

if __name__ == "__main__":
    print("测试Completions API:")
    print(json.dumps(test_completions_api(), indent=2, ensure_ascii=False))
    
    print("\n测试Chat Completions API:")
    print(json.dumps(test_chat_completions_api(), indent=2, ensure_ascii=False))

5.2 使用OpenAI SDK测试

新建openai_test.py：

from openai import OpenAI
import time

def test_with_openai_sdk():
    client = OpenAI(
        base_url="http://localhost:8000/v1",
        api_key="no-key-required"
    )
    
    # 测试流式响应
    start_time = time.time()
    stream = client.chat.completions.create(
        model="Qwen3-8B",
        messages=[{"role": "user", "content": "详细说明Transformer架构"}],
        stream=True,
        max_tokens=1024
    )
    
    print("流式响应结果:")
    for chunk in stream:
        content = chunk.choices[0].delta.content or ""
        print(content, end="", flush=True)
    
    print(f"\n耗时: {time.time()-start_time:.2f}秒")

if __name__ == "__main__":
    test_with_openai_sdk()

6. VSCode配置优化

6.1 推荐扩展

Python (Microsoft)
Pylance
Jupyter
Docker (如需容器化)

6.2 工作区设置

在.vscode/settings.json中添加：

{
    "python.pythonPath": "qwen_env/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "autopep8",
    "files.autoSave": "afterDelay",
    "editor.renderWhitespace": "all"
}

7. 常见问题解决

7.1 CUDA内存不足

修改start_api.sh中的参数：

--max-model-len 4096 \  # 减少最大长度
--gpu-memory-utilization 0.8 \  # 限制GPU内存使用

7.2 安装冲突

如果遇到依赖冲突：

# 创建干净的虚拟环境
python -m venv clean_env
source clean_env/bin/activate

# 按顺序安装
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121
pip install modelscope vllm==0.3.3

7.3 模型加载失败

确保模型路径正确，并检查文件完整性：

ls -lh /home/your_username/models/Qwen/Qwen3-8B
# 应看到约15GB的模型文件

8. 进阶配置

8.1 量化加载

修改start_api.sh：

--quantization awq \  # 使用AWQ量化
--dtype half  # 使用半精度

8.2 多GPU支持

--tensor-parallel-size 2  # 使用2个GPU

9. 项目结构建议

qwen3-vllm/
├── models/                  # 模型目录
├── scripts/
│   ├── start_api.sh         # 启动脚本
│   └── stop_api.sh          # 停止脚本
├── src/
│   ├── model_download.py    # 模型下载
│   ├── vllm_test.py         # 测试脚本
│   └── api_test.py          # API测试
├── .vscode/                 # VSCode配置
└── README.md                # 项目说明

10. 监控与优化

10.1 资源监控

# 查看GPU使用情况
watch -n 1 nvidia-smi

# 查看内存使用
htop

10.2 性能优化

使用--enforce-eager模式减少内存开销
调整--block-size参数优化批处理
使用--swap-space指定交换空间位置

本教程已针对Python 3.10.18和Linux+VSCode环境进行了全面适配，按照步骤操作即可完成1:1复现。如遇到问题，建议先检查路径和权限设置，再查看终端错误日志获取具体问题信息。