Qwen3-4B-Thinking-GGUF部署教程Ubuntu 22.04 NVIDIA驱动 vLLM环境完整配置想在自己的Ubuntu服务器上快速部署一个强大的文本生成模型吗今天我就带你一步步搞定Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF模型的完整部署。这个模型在GPT-5-Codex的1000个高质量示例上进行了微调推理能力相当不错而且通过vLLM部署速度飞快。整个流程从零开始包括系统环境准备、驱动安装、vLLM环境搭建一直到模型部署和前端调用。即使你之前没怎么接触过模型部署跟着这篇教程走也能顺利跑起来。1. 环境准备从零搭建Ubuntu服务器在开始部署模型之前我们需要一个干净、稳定的运行环境。Ubuntu 22.04 LTS是个不错的选择长期支持版本社区资源丰富遇到问题也容易找到解决方案。1.1 系统要求检查首先确保你的服务器满足以下基本要求操作系统Ubuntu 22.04 LTS其他版本可能需要调整部分命令内存至少16GB RAM模型本身约4GB加上运行内存16GB比较稳妥存储至少50GB可用空间用于存放模型文件、Python环境等GPUNVIDIA显卡推荐RTX 3060 12GB或更高显存越大越好网络稳定的网络连接下载模型文件需要一定时间如果你用的是云服务器这些配置通常可以在创建实例时选择。本地机器的话检查一下硬件配置是否达标。1.2 系统更新与基础工具安装登录到你的Ubuntu服务器我们先做一些基础设置# 更新系统包列表 sudo apt update # 升级已安装的包到最新版本 sudo apt upgrade -y # 安装一些常用的工具 sudo apt install -y curl wget git build-essential software-properties-common这些工具在后续的安装过程中都会用到特别是curl和wget用于下载文件git用于克隆代码仓库build-essential包含编译工具链。2. NVIDIA驱动与CUDA环境配置要让模型在GPU上跑起来NVIDIA驱动和CUDA是必不可少的。这一步稍微有点繁琐但跟着做就不会出错。2.1 安装NVIDIA驱动Ubuntu 22.04自带了NVIDIA驱动但版本可能比较旧。我们安装官方的最新驱动# 添加NVIDIA驱动PPA源 sudo add-apt-repository ppa:graphics-drivers/ppa -y sudo apt update # 查看可用的驱动版本 ubuntu-drivers devices # 安装推荐的驱动版本通常是nvidia-driver-535或更高 sudo apt install -y nvidia-driver-535 # 重启系统使驱动生效 sudo reboot重启后登录回服务器检查驱动是否安装成功# 检查NVIDIA驱动状态 nvidia-smi如果看到类似下面的输出说明驱动安装成功了--------------------------------------------------------------------------------------- | NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 | |------------------------------------------------------------------------------------- | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | | | | MIG M. | || | 0 NVIDIA GeForce RTX 4060 Ti Off | 00000000:01:00.0 Off | N/A | | 0% 38C P8 10W / 160W | 0MiB / 16384MiB | 0% Default | | | | N/A | -------------------------------------------------------------------------------------2.2 安装CUDA ToolkitvLLM需要CUDA环境。我们安装CUDA 12.1版本这是目前比较稳定的选择# 下载CUDA 12.1安装包 wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run # 安装CUDA sudo sh cuda_12.1.0_530.30.02_linux.run安装过程中注意以下几点接受许可协议取消勾选驱动安装因为我们已经安装了驱动只选择CUDA Toolkit安装路径使用默认的/usr/local/cuda-12.1安装完成后配置环境变量# 编辑bash配置文件 echo export PATH/usr/local/cuda-12.1/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH ~/.bashrc # 使配置生效 source ~/.bashrc # 验证CUDA安装 nvcc --version如果看到CUDA版本信息说明安装成功。3. Python环境与vLLM安装现在我们来准备Python环境。我推荐使用Miniconda来管理Python环境这样可以避免系统Python环境被污染。3.1 安装Miniconda# 下载Miniconda安装脚本 wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh # 运行安装脚本 bash Miniconda3-latest-Linux-x86_64.sh # 按照提示完成安装通常一路回车即可 # 安装完成后重启终端或执行 source ~/.bashrc3.2 创建Python虚拟环境# 创建一个名为qwen的Python 3.10环境 conda create -n qwen python3.10 -y # 激活环境 conda activate qwen3.3 安装vLLM及相关依赖vLLM是一个高性能的推理引擎专门为大语言模型优化。安装时需要注意版本兼容性# 升级pip pip install --upgrade pip # 安装PyTorch与CUDA 12.1兼容的版本 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装vLLM pip install vllm # 安装其他必要的包 pip install fastapi uvicorn chainlit这里解释一下各个包的作用torchPyTorch深度学习框架vllm我们的主角高性能推理引擎fastapi和uvicorn用于创建API服务chainlit一个漂亮的Web前端用于交互式测试模型4. 下载与部署Qwen3-4B-Thinking模型环境准备好了现在可以下载并部署我们的模型了。4.1 下载模型文件Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF模型文件可以从Hugging Face下载。GGUF格式是GGML的升级版优化了内存使用和推理速度。# 创建一个目录存放模型 mkdir -p ~/models/qwen3-4b-thinking cd ~/models/qwen3-4b-thinking # 下载模型文件这里以示例URL为例实际需要替换为正确的下载链接 # 注意模型文件较大约4GB下载需要一些时间 wget https://huggingface.co/TeichAI/Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF/resolve/main/qwen3-4b-thinking-2507-gpt-5-codex-distill.Q4_K_M.gguf如果下载速度慢可以考虑使用镜像源或者先下载到本地再上传到服务器。4.2 创建vLLM启动脚本创建一个Python脚本来启动vLLM服务# 创建文件start_vllm.py import argparse from vllm import LLM, SamplingParams def main(): parser argparse.ArgumentParser() parser.add_argument(--model, typestr, default./qwen3-4b-thinking-2507-gpt-5-codex-distill.Q4_K_M.gguf) parser.add_argument(--host, typestr, default0.0.0.0) parser.add_argument(--port, typeint, default8000) parser.add_argument(--gpu-memory-utilization, typefloat, default0.9) args parser.parse_args() # 初始化模型 print(f正在加载模型: {args.model}) llm LLM( modelargs.model, gpu_memory_utilizationargs.gpu_memory_utilization, max_model_len4096, trust_remote_codeTrue ) print(f模型加载完成服务地址: http://{args.host}:{args.port}) print(可以使用以下命令测试API) print(fcurl http://{args.host}:{args.port}/v1/completions \\) print( -H Content-Type: application/json \\) print( -d \{model: qwen3-4b-thinking, prompt: 你好请介绍一下你自己, max_tokens: 100}\) if __name__ __main__: main()4.3 启动vLLM服务现在我们可以启动模型服务了# 确保在模型文件所在目录 cd ~/models/qwen3-4b-thinking # 启动vLLM服务 python start_vllm.py --model ./qwen3-4b-thinking-2507-gpt-5-codex-distill.Q4_K_M.gguf --port 8000第一次启动时vLLM需要一些时间来加载模型到GPU内存。根据你的GPU性能这个过程可能需要1-5分钟。看到模型加载完成的提示后服务就正常启动了。4.4 验证服务是否正常运行打开另一个终端窗口测试一下API是否正常工作# 测试completions接口 curl http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d { model: qwen3-4b-thinking, prompt: 请用Python写一个快速排序算法, max_tokens: 200, temperature: 0.7 }如果看到返回了JSON格式的响应包含生成的代码说明服务运行正常。5. 使用Chainlit创建Web前端虽然API接口能用但命令行测试不够直观。我们可以用Chainlit创建一个漂亮的Web界面来交互式地使用模型。5.1 创建Chainlit应用创建一个新的Python文件作为Chainlit应用# 创建文件chainlit_app.py import chainlit as cl from openai import OpenAI # 配置OpenAI客户端指向我们的vLLM服务 client OpenAI( base_urlhttp://localhost:8000/v1, api_keynot-needed # vLLM不需要API key ) cl.on_message async def main(message: cl.Message): 处理用户消息 # 显示加载指示器 msg cl.Message(content) await msg.send() try: # 调用vLLM API response client.chat.completions.create( modelqwen3-4b-thinking, messages[ {role: system, content: 你是一个有帮助的AI助手。}, {role: user, content: message.content} ], temperature0.7, max_tokens1024, streamTrue # 启用流式输出 ) # 流式接收响应 full_response for chunk in response: if chunk.choices[0].delta.content is not None: word chunk.choices[0].delta.content full_response word await msg.stream_token(word) # 更新最终消息 await msg.update() except Exception as e: await msg.update(f抱歉出错了: {str(e)}) cl.on_chat_start async def start(): 聊天开始时的初始化 await cl.Message( content你好我是基于Qwen3-4B-Thinking模型的AI助手。有什么可以帮你的吗 ).send()5.2 配置Chainlit创建一个Chainlit配置文件# 创建文件.chainlit/config.yaml ui: name: Qwen3-4B-Thinking Chat description: 基于Qwen3-4B-Thinking模型的聊天界面 theme: light features: - memory - feedback model: name: Qwen3-4B-Thinking provider: vLLM auth: enabled: false # 生产环境建议设置为true并配置认证5.3 启动Chainlit服务在模型服务运行的情况下启动Chainlit# 启动Chainlit指定端口为7860 chainlit run chainlit_app.py -w --port 7860现在打开浏览器访问http://你的服务器IP:7860就能看到一个漂亮的聊天界面了。你可以在这里直接和模型对话体验它的文本生成能力。6. 常见问题与解决方案部署过程中可能会遇到一些问题这里整理了一些常见问题的解决方法。6.1 模型加载失败问题启动vLLM时提示模型加载失败。可能原因和解决方案模型文件损坏重新下载模型文件检查文件完整性GPU内存不足尝试降低gpu_memory_utilization参数如从0.9降到0.8模型格式不支持确保下载的是GGUF格式的模型文件# 检查模型文件大小应该是4GB左右 ls -lh qwen3-4b-thinking-2507-gpt-5-codex-distill.Q4_K_M.gguf # 尝试用更少的内存启动 python start_vllm.py --gpu-memory-utilization 0.86.2 API调用超时问题调用API时长时间没有响应或超时。解决方案检查服务状态确认vLLM服务正在运行查看日志检查vLLM的输出日志看是否有错误信息增加超时时间在客户端设置更长的超时时间# 在Chainlit应用中增加超时设置 import httpx client OpenAI( base_urlhttp://localhost:8000/v1, api_keynot-needed, timeouthttpx.Timeout(60.0) # 60秒超时 )6.3 生成速度慢问题模型响应速度很慢。优化建议调整生成参数减少max_tokens降低生成文本的最大长度使用量化版本确保使用的是量化后的模型如Q4_K_M检查GPU使用率使用nvidia-smi查看GPU是否满载运行# 优化生成参数 response client.chat.completions.create( modelqwen3-4b-thinking, messagesmessages, temperature0.7, max_tokens512, # 减少生成长度 top_p0.9, frequency_penalty0.1, presence_penalty0.1 )6.4 Chainlit无法连接vLLM问题Chainlit界面显示连接错误。检查步骤确认vLLM服务正在运行端口8000检查防火墙设置确保端口可访问如果使用云服务器检查安全组规则# 检查端口是否监听 netstat -tlnp | grep 8000 # 测试本地连接 curl http://localhost:8000/v1/models7. 进阶配置与优化基础部署完成后你可以根据需要进行一些进阶配置。7.1 使用systemd管理服务为了让服务在后台持续运行可以使用systemd来管理# 创建vLLM服务文件 sudo nano /etc/systemd/system/vllm-qwen.service添加以下内容[Unit] DescriptionvLLM Qwen3-4B-Thinking Service Afternetwork.target [Service] Typesimple User你的用户名 WorkingDirectory/home/你的用户名/models/qwen3-4b-thinking EnvironmentPATH/home/你的用户名/miniconda3/envs/qwen/bin ExecStart/home/你的用户名/miniconda3/envs/qwen/bin/python start_vllm.py --model ./qwen3-4b-thinking-2507-gpt-5-codex-distill.Q4_K_M.gguf --port 8000 Restartalways RestartSec10 [Install] WantedBymulti-user.target保存后启用服务# 重新加载systemd配置 sudo systemctl daemon-reload # 启用服务 sudo systemctl enable vllm-qwen.service # 启动服务 sudo systemctl start vllm-qwen.service # 查看服务状态 sudo systemctl status vllm-qwen.service7.2 配置Nginx反向代理如果你希望通过域名访问可以配置Nginx反向代理# 安装Nginx sudo apt install nginx -y # 创建站点配置 sudo nano /etc/nginx/sites-available/qwen-ai添加以下配置server { listen 80; server_name 你的域名; location / { proxy_pass http://localhost:7860; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /api/ { proxy_pass http://localhost:8000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }启用配置并重启Nginx# 创建符号链接 sudo ln -s /etc/nginx/sites-available/qwen-ai /etc/nginx/sites-enabled/ # 测试配置 sudo nginx -t # 重启Nginx sudo systemctl restart nginx7.3 性能监控与优化监控服务的运行状态很重要这里有几个实用的命令# 查看GPU使用情况 watch -n 1 nvidia-smi # 查看内存使用 free -h # 查看服务日志 sudo journalctl -u vllm-qwen.service -f # 查看API访问日志如果配置了的话 tail -f /var/log/nginx/access.log8. 总结通过这篇教程我们完成了从零开始部署Qwen3-4B-Thinking模型的完整流程。让我们回顾一下关键步骤环境准备搭建了Ubuntu 22.04系统安装了必要的工具和驱动CUDA配置安装了NVIDIA驱动和CUDA Toolkit为GPU加速做好准备Python环境使用Miniconda创建了独立的Python环境安装了vLLM和相关依赖模型部署下载了GGUF格式的模型文件使用vLLM启动了高性能推理服务前端搭建用Chainlit创建了美观的Web聊天界面方便交互测试问题排查整理了常见问题的解决方案帮助你快速定位和解决问题进阶配置介绍了如何用systemd管理服务、用Nginx做反向代理这个部署方案有几个明显的优势性能优秀vLLM针对大语言模型做了深度优化推理速度快资源友好GGUF格式的模型内存占用小4B参数在消费级GPU上就能运行易于使用Chainlit提供了开箱即用的Web界面无需前端开发经验扩展性强基于标准API接口可以轻松集成到其他应用中实际使用中这个模型在代码生成、文本创作、问答对话等场景表现不错。特别是在GPT-5-Codex示例上微调后代码相关的任务处理能力有所提升。如果你在部署过程中遇到问题或者有改进建议欢迎交流讨论。技术总是在不断进步部署方案也会持续优化。最重要的是动手实践在实际使用中积累经验。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。