一、部署环境准备
1. 基础环境要求
- 操作系统：Linux（推荐欧拉系统、Ubuntu 等）
- Python 版本：3.8 及以上
- 依赖工具：
pip、git、curl - 可选依赖：
- GPU 环境：NVIDIA GPU（支持 CUDA 11.7+）、
nvidia-smi
- GPU 环境：NVIDIA GPU（支持 CUDA 11.7+）、
2. 依赖安装脚本 install_vllm.sh
#!/bin/bash# 创建并激活虚拟环境
python3 -m venv vllm_env
source vllm_env/bin/activate# 安装vLLM及其依赖
pip install vllm fastapi uvicorn huggingface_hub requestsecho "依赖安装完成，请使用以下命令激活环境："
echo "source vllm_env/bin/activate"二、模型获取与部署流程
1. 模型下载方法
方法 1：通过huggingface-cli直接下载（推荐）
# 临时设置国内镜像加速（解决网络限制）
export HF_ENDPOINT=https://hf-mirror.com# 下载模型到指定目录
huggingface-cli download --resume-download \deepseek-ai/deepseek-llm-7b-chat \--local-dir /data/VLLM_MODE/deepseek-llm-7b-chat
方法 2：手动下载（网络严格受限场景）
- 在可联网机器下载模型：
# 本地机器执行 huggingface-cli download --resume-download \deepseek-ai/deepseek-llm-7b-chat \--local-dir ./deepseek-llm-7b-chat - 通过
scp上传到服务器：# 本地机器执行，上传到目标服务器 scp -r ./deepseek-llm-7b-chat root@服务器IP:/data/storage/data/VLLM_MODE/
2. 部署脚本准备（deploy_model.py）
# deploy_model.py
import argparse
import os
import torch
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Dict, Any
from vllm import LLM, SamplingParamsapp = FastAPI(title="LLM Inference Service")# 全局 LLM 实例
llm = Noneclass InferenceRequest(BaseModel):prompt: strtemperature: float = 0.7max_tokens: int = 1024def main():global llmparser = argparse.ArgumentParser(description='Deploy LLM with vLLM')# 核心参数parser.add_argument('--model', type=str, required=True, help="模型本地路径或Hugging Face仓库ID")parser.add_argument('--port', type=int, default=8000, help="服务端口")parser.add_argument('--host', type=str, default='0.0.0.0', help="绑定主机地址（0.0.0.0允许外部访问）")# 可选参数parser.add_argument('--cache-dir', type=str, default=None, help="模型缓存目录")parser.add_argument('--tensor-parallel-size', type=int, default=1, help="GPU并行数量")parser.add_argument('--gpu-memory-utilization', type=float, default=0.9, help="GPU内存利用率（0.0-1.0）")parser.add_argument('--max-model-len', type=int, default=4096, help="模型最大序列长度")parser.add_argument('--use-cpu', action='store_true', help="强制使用CPU运行")parser.add_argument('--quantization', type=str, default=None, help="量化方式（如awq、gptq-4bit）")args = parser.parse_args()# 设置GPUif args.gpu:os.environ["CUDA_VISIBLE_DEVICES"] = args.gpuprint(f"Using GPUs: {args.gpu}")# 设置设备if args.use_cpu:device = "cpu"kwargs = {"dtype": torch.float32, # CPU不支持半精度}print("Running model on CPU")else:device = "cuda"kwargs = {}print(f"Running model on GPU with {args.tensor_parallel_size} devices")# 初始化LLMllm = LLM(model=args.model,tensor_parallel_size=args.tensor_parallel_size,trust_remote_code=args.trust_remote_code,download_dir=args.cache_dir, # 指定模型下载路径**kwargs)# 启动API服务print(f"Model {args.model} loaded. Serving on port {args.port}")import uvicornuvicorn.run(app, host="0.0.0.0", port=args.port)@app.post("/generate")
async def generate(request: InferenceRequest):try:sampling_params = SamplingParams(temperature=request.temperature,max_tokens=request.max_tokens,)outputs = llm.generate(request.prompt,sampling_params,)return {"prompt": request.prompt,"generated_text": outputs[0].outputs[0].text,}except Exception as e:raise HTTPException(status_code=500, detail=str(e))if __name__ == "__main__":main()3. 启动服务命令
python deploy_model.py \--model /VLLM_MODE/deepseek-llm-7b-chat \--cache-dir /VLLM_MODE \--port 8000 \
启动脚本：run deepseek-llm-7b-chat 脚本 可下载多个模型运行 只需修改端口和GPU（GPU内容有限）
#!/bin/bash# 激活虚拟环境cd /vllm_env上级目录
source vllm_env/bin/activate# 启动API服务器
python deploy_model.py \--model /VLLM_MODE/deepseek-llm-7b-chat \--cache-dir /VLLM_MODE \--port 8000 \
三、常见问题与解决方案
1. 网络连接问题
错误表现
- 提示 “Failed to establish a new connection: Network is unreachable”
- 模型下载停滞或无法克隆 GitHub 仓库
解决方案
- 使用国内镜像：
bash
# 永久设置Hugging Face镜像（欧拉系统） echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc source ~/.bashrc # 立即生效 - GitHub 仓库镜像克隆：
bash
git clone https://gitclone.com/github.com/deepseek-ai/DeepSeek-VL - 检查防火墙：
bash
# 开放8000端口（允许外部访问服务） firewall-cmd --add-port=8000/tcp --permanent firewall-cmd --reload
2. 模型下载相关问题
问题 1：模型未出现在指定目录
- 原因：
huggingface_hub默认将模型移动到~/.cache/huggingface/hub - 解决：使用
local_dir参数强制指定路径（见 “模型下载方法 1”）
问题 2：下载中断或文件损坏
- 解决：使用
--resume-download断点续传：bash
huggingface-cli download --resume-download \deepseek-ai/deepseek-llm-7b-chat \--local-dir /data/storage/data/VLLM_MODE/deepseek-llm-7b-chat
3. GPU 相关错误
错误 1：CUDA 内存不足（CUDA out of memory）
- 表现：日志出现 “torch.OutOfMemoryError: CUDA out of memory”
- 解决：
bash
# 1. 释放占用GPU的进程 nvidia-smi # 查看进程ID（PID） kill -9 <PID> # 终止占用进程# 2. 降低内存占用（可选） python deploy_model.py ... \--quantization awq \ # 使用量化--gpu-memory-utilization 0.95 # 提高内存利用率
错误 2：KV 缓存容量不足
- 表现：提示 “The model's max seq len is larger than KV cache”
- 解决：
bash
# 方法1：增加KV缓存容量 python deploy_model.py ... --gpu-memory-utilization 0.95# 方法2：降低最大序列长度 python deploy_model.py ... --max-model-len 1952
4. 服务启动问题
问题 1：端口未启动或无法访问
- 原因：端口被占用、未指定
--host 0.0.0.0或防火墙拦截 - 解决：
bash
# 检查端口占用 netstat -tulpn | grep 8000# 更换端口或终止占用进程 python deploy_model.py ... --port 8001
问题 2：参数不识别（如 --host）
- 原因：脚本未定义该参数
- 解决：在
deploy_model.py的argparse部分添加参数（见脚本示例）
5. CPU 运行配置
- 适用场景：无 GPU 或 GPU 内存不足
- 启动命令：
bash
python deploy_model.py \--model /data/storage/data/VLLM_MODE/deepseek-llm-7b-chat \--port 8000 \--use-cpu - 注意：7B 模型需 32GB 以上内存，生成速度较慢
四、服务验证与测试
检查服务状态：
bash
netstat -tulpn | grep 8000 # 确认端口监听发送测试请求：
bash
curl -X POST "http://localhost:8000/generate" \-H "Content-Type: application/json" \-d '{"prompt": "你好，请介绍一下自己", "temperature": 0.7, "max_tokens": 200}'预期响应：
json
{"prompt": "你好，请介绍一下自己","generated_text": "我是DeepSeek-LLM-7B-Chat，是一款由深度求索（DeepSeek）开发的对话模型..." }
五、扩展说明
- 模型存储路径：建议将模型统一存储在
/data/storage/data/VLLM_MODE等大容量目录 - 多模型部署：不同模型使用不同端口（如 8000、8001）避免冲突
- 性能优化：GPU 环境下优先使用量化（AWQ/INT4）和合理设置
gpu-memory-utilization - 日志排查：启动时添加
--log-level debug查看详细日志，便于定位问题
内存管理、通信)
