Qwen2.5-7B-Instruct部署实操vLLM API服务封装与Swagger文档生成想快速部署一个高性能的Qwen2.5-7B-Instruct模型服务并拥有一个清晰易用的API文档界面吗今天我们就来手把手实现这个目标。我们将使用vLLM这个强大的推理引擎来部署模型它能显著提升大模型的推理速度。然后我们会将vLLM服务封装成标准的RESTful API并自动生成Swagger文档。最后我们还会用Chainlit搭建一个简单的前端界面让你能直观地与模型对话。整个过程清晰明了即使你之前没有太多部署经验也能跟着一步步完成。我们开始吧。1. 环境准备与快速部署在开始之前我们需要准备好运行环境。这里假设你有一台配备了NVIDIA GPU的Linux服务器并且已经安装了基础的Python环境和Docker。1.1 系统与硬件要求为了流畅运行Qwen2.5-7B-Instruct模型建议满足以下条件操作系统Ubuntu 20.04 LTS或更高版本其他Linux发行版也可但以下命令以Ubuntu为例。GPU至少16GB显存的NVIDIA GPU如RTX 4090、A100等。7B模型对显存要求相对友好。内存建议32GB或以上系统内存。存储至少需要20GB的可用磁盘空间来存放模型和依赖。1.2 安装必要工具首先更新系统包并安装一些基础工具。# 更新软件包列表 sudo apt-get update # 安装Python3、pip和虚拟环境工具 sudo apt-get install -y python3-pip python3-venv curl # 验证安装 python3 --version pip3 --version接下来我们使用venv创建一个独立的Python虚拟环境避免包冲突。# 创建项目目录并进入 mkdir qwen2.5-deploy cd qwen2.5-deploy # 创建Python虚拟环境 python3 -m venv venv # 激活虚拟环境 source venv/bin/activate激活后你的命令行提示符前会出现(venv)字样。1.3 安装vLLM与FastAPIvLLM是我们的核心推理引擎FastAPI则用来构建API服务。# 升级pip pip install --upgrade pip # 安装vLLM。根据你的CUDA版本可以选择不同的安装命令。 # 对于CUDA 12.1常见于较新显卡 pip install vllm # 如果你使用的是CUDA 11.8可以尝试 # pip install vllm --extra-index-url https://pypi.nvidia.com # 安装FastAPI及相关依赖用于构建API服务 pip install fastapi[all] uvicorn # 安装用于生成Swagger文档的依赖 pip install pydantic-settings安装完成后可以通过以下命令简单验证python -c import vllm; print(vLLM导入成功) python -c import fastapi; print(FastAPI导入成功)2. 启动vLLM推理服务器vLLM自带了一个高性能的OpenAI兼容API服务器我们可以直接用它来启动模型服务。2.1 编写启动脚本创建一个名为start_vllm_server.py的Python脚本。# start_vllm_server.py from vllm import AsyncEngineArgs, AsyncLLMEngine from vllm.entrypoints.openai import api_server import argparse import uvicorn def main(): parser argparse.ArgumentParser(description启动 vLLM OpenAI API 服务器) parser.add_argument(--model, typestr, defaultQwen/Qwen2.5-7B-Instruct, helpHugging Face模型名称或本地路径) parser.add_argument(--host, typestr, default0.0.0.0, help服务监听地址) parser.add_argument(--port, typeint, default8000, help服务监听端口) parser.add_argument(--gpu-memory-utilization, typefloat, default0.9, helpGPU显存利用率) parser.add_argument(--max-model-len, typeint, default8192, help模型最大上下文长度) args parser.parse_args() # 配置引擎参数 engine_args AsyncEngineArgs( modelargs.model, gpu_memory_utilizationargs.gpu_memory_utilization, max_model_lenargs.max_model_len, tensor_parallel_size1, # 如果有多张GPU卡可以增加此值 trust_remote_codeTrue, # 信任远程代码对于Qwen模型是必须的 ) # 打印启动信息 print(f正在加载模型: {args.model}) print(f服务地址: http://{args.host}:{args.port}) print(fGPU显存利用率: {args.gpu_memory_utilization}) print(f最大上下文长度: {args.max_model_len}) # 启动OpenAI兼容API服务器 uvicorn.run( api_server.app, hostargs.host, portargs.port, log_levelinfo, # 将引擎参数传递给app app_kwargs{engine_args: engine_args} ) if __name__ __main__: main()这个脚本做了以下几件事定义了命令行参数方便你自定义模型、端口等配置。设置了vLLM引擎的参数包括模型路径、显存利用率和上下文长度。最后启动了一个uvicorn服务器运行vLLM提供的OpenAI兼容API。2.2 启动服务并验证在终端中运行这个脚本。首次运行会从Hugging Face下载模型需要一些时间请确保网络通畅。python start_vllm_server.py --port 8000你会看到类似下面的输出表示模型正在加载正在加载模型: Qwen/Qwen2.5-7B-Instruct 服务地址: http://0.0.0.0:8000 GPU显存利用率: 0.9 最大上下文长度: 8192 INFO 07-10 14:30:00 llm_engine.py:149] Initializing an LLM engine (v0.3.3)... INFO 07-10 14:30:00 llm_engine.py:150] Args: EngineArgs(...) INFO 07-10 14:30:00 model_runner.py:405] Loading model weights...当看到INFO: Application startup complete.和INFO: Uvicorn running on http://0.0.0.0:8000时说明服务已经启动成功。现在打开另一个终端我们可以测试一下服务是否正常。# 测试聊天补全接口 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen2.5-7B-Instruct, messages: [ {role: user, content: 你好请介绍一下你自己。} ], max_tokens: 100, temperature: 0.7 }如果返回一个包含模型回复的JSON说明vLLM服务运行正常。至此我们已经拥有了一个高性能的模型推理后端。3. 封装API服务并生成Swagger文档虽然vLLM提供了OpenAI兼容的接口但有时我们想拥有更自定义的API路径、参数校验或者想集成其他功能。这时我们可以用FastAPI再封装一层并自动生成Swagger文档。3.1 创建FastAPI应用创建一个新的文件custom_api_server.py。# custom_api_server.py from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel, Field from typing import List, Optional import asyncio from openai import AsyncOpenAI import uvicorn import logging # 配置日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) # 初始化FastAPI应用 app FastAPI( titleQwen2.5-7B-Instruct API 服务, description基于vLLM封装的Qwen2.5-7B-Instruct模型API服务提供聊天、文本补全等功能。, version1.0.0, docs_url/docs, # Swagger UI 地址 redoc_url/redoc, # ReDoc 地址 ) # 添加CORS中间件允许前端跨域访问 app.add_middleware( CORSMiddleware, allow_origins[*], # 生产环境应限制为具体域名 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 定义请求和响应的数据模型 class Message(BaseModel): role: str Field(..., description消息角色如 user, assistant, system) content: str Field(..., description消息内容) class ChatCompletionRequest(BaseModel): messages: List[Message] Field(..., description对话消息列表) model: str Field(defaultQwen2.5-7B-Instruct, description模型名称) max_tokens: Optional[int] Field(default512, description生成的最大token数) temperature: Optional[float] Field(default0.7, ge0.0, le2.0, description采样温度控制随机性) top_p: Optional[float] Field(default0.9, ge0.0, le1.0, description核采样参数) stream: Optional[bool] Field(defaultFalse, description是否使用流式输出) class ChatCompletionResponse(BaseModel): id: str object: str chat.completion created: int model: str choices: List[dict] usage: dict # 初始化OpenAI客户端连接到我们本地的vLLM服务 client AsyncOpenAI( base_urlhttp://localhost:8000/v1, # vLLM服务的地址 api_keytoken-abc123, # vLLM不需要有效的API_KEY但需要提供一个非空值 ) app.on_event(startup) async def startup_event(): 服务启动时执行用于健康检查 logger.info(Qwen2.5 API 服务启动中...) # 可以在这里添加一些初始化逻辑比如检查vLLM服务是否可用 try: # 简单测试vLLM服务连通性 await asyncio.sleep(2) # 给vLLM一点启动时间 logger.info(服务启动完成Swagger文档地址: http://localhost:8001/docs) except Exception as e: logger.error(f启动时发生错误: {e}) app.get(/health) async def health_check(): 健康检查端点 return {status: healthy, service: qwen2.5-api} app.post(/v1/chat/completions, response_modelChatCompletionResponse) async def chat_completion(request: ChatCompletionRequest): 聊天补全接口 - **messages**: 对话历史是一个消息对象列表 - **model**: 使用的模型名称 - **max_tokens**: 生成的最大token数量 - **temperature**: 温度参数值越高输出越随机 - **top_p**: 核采样参数 - **stream**: 是否流式输出 try: logger.info(f收到聊天请求消息数: {len(request.messages)}) # 将请求转发给底层的vLLM服务 response await client.chat.completions.create( modelrequest.model, messages[{role: msg.role, content: msg.content} for msg in request.messages], max_tokensrequest.max_tokens, temperaturerequest.temperature, top_prequest.top_p, streamrequest.stream, ) # 将响应转换为我们的格式 return ChatCompletionResponse( idresponse.id, createdresponse.created, modelresponse.model, choices[choice.dict() for choice in response.choices], usageresponse.usage.dict(), ) except Exception as e: logger.error(f处理聊天请求时出错: {e}) raise HTTPException(status_code500, detailstr(e)) app.post(/v1/completions) async def text_completion(prompt: str, max_tokens: int 100): 文本补全接口简易版 - **prompt**: 输入提示文本 - **max_tokens**: 生成的最大token数量 try: response await client.completions.create( modelQwen/Qwen2.5-7B-Instruct, promptprompt, max_tokensmax_tokens, ) return response except Exception as e: raise HTTPException(status_code500, detailstr(e)) app.get(/v1/models) async def list_models(): 列出可用的模型 try: models await client.models.list() return models except Exception as e: # 如果vLLM的/models端点不可用返回一个模拟响应 return { object: list, data: [ { id: Qwen2.5-7B-Instruct, object: model, created: 1677610602, owned_by: custom } ] } if __name__ __main__: uvicorn.run( custom_api_server:app, host0.0.0.0, port8001, # 使用8001端口避免与vLLM服务的8000端口冲突 reloadTrue, # 开发模式下启用热重载 log_levelinfo )3.2 启动自定义API服务确保vLLM服务在8000端口正在运行然后在新终端中启动我们的自定义API服务。# 激活虚拟环境如果尚未激活 source venv/bin/activate # 启动自定义API服务 python custom_api_server.py服务启动后访问http://localhost:8001/docs你就能看到自动生成的Swagger API文档界面了。这个界面非常实用清晰的API列表所有接口一目了然。交互式测试可以直接在网页上填写参数并调用接口看到实时返回结果。模型定义请求和响应的数据结构都有详细说明。代码示例页面上还提供了不同语言的调用示例。3.3 通过Swagger界面测试API现在让我们直接在Swagger界面上测试一下打开浏览器访问http://localhost:8001/docs。找到POST /v1/chat/completions这个接口点击它。点击右侧的 Try it out 按钮。在请求体中修改示例JSON比如{ messages: [ { role: user, content: 用Python写一个快速排序函数 } ], model: Qwen2.5-7B-Instruct, max_tokens: 300, temperature: 0.7 }点击 Execute 按钮。稍等片刻你就能在下方看到模型的响应了。这种方式比用curl命令测试要直观方便得多特别适合调试和演示。4. 使用Chainlit构建前端对话界面有了功能完善的API服务我们再来给它加一个简单的前端界面。Chainlit是一个专门为AI应用设计的UI框架可以快速构建聊天界面。4.1 安装Chainlit并创建应用首先安装Chainlitpip install chainlit创建一个名为chainlit_app.py的文件# chainlit_app.py import chainlit as cl import aiohttp import json from typing import Optional # 配置API端点 API_BASE_URL http://localhost:8001 # 我们的自定义API服务地址 async def call_qwen_api(messages: list, max_tokens: int 512, temperature: float 0.7) - Optional[str]: 调用Qwen2.5 API获取回复 url f{API_BASE_URL}/v1/chat/completions payload { messages: messages, model: Qwen2.5-7B-Instruct, max_tokens: max_tokens, temperature: temperature, stream: False # 非流式简化处理 } headers { Content-Type: application/json } try: async with aiohttp.ClientSession() as session: async with session.post(url, jsonpayload, headersheaders) as response: if response.status 200: data await response.json() if data.get(choices) and len(data[choices]) 0: return data[choices][0][message][content] else: return 抱歉我没有收到有效的回复。 else: error_text await response.text() return fAPI调用失败 (状态码: {response.status}): {error_text} except Exception as e: return f请求发生异常: {str(e)} cl.on_chat_start async def on_chat_start(): 聊天开始时执行 # 设置默认的模型参数 settings await cl.ChatSettings( [ cl.input_widget.Slider( idTemperature, label温度 (Temperature), initial0.7, min0, max2, step0.1, description控制回复的随机性值越高越有创意 ), cl.input_widget.Slider( idMaxTokens, label最大生成长度 (Max Tokens), initial512, min50, max2048, step50, description控制回复的最大长度 ), ] ).send() # 发送欢迎消息 welcome_msg 你好我是基于 Qwen2.5-7B-Instruct 模型的AI助手。 我可以帮你 - 回答各种问题 - 协助写作和编程 - 进行创意对话 - 分析和总结内容 请在下方的输入框中开始对话吧 await cl.Message(contentwelcome_msg).send() cl.on_message async def on_message(message: cl.Message): 处理用户消息 # 获取用户设置 temperature message.elements[0].value if message.elements else 0.7 max_tokens message.elements[1].value if len(message.elements) 1 else 512 # 显示正在思考的提示 msg cl.Message(content) await msg.send() # 构建消息历史 messages [ {role: system, content: 你是一个乐于助人的AI助手请用中文回答用户的问题。}, {role: user, content: message.content} ] # 调用API获取回复 response_text await call_qwen_api( messagesmessages, max_tokensint(max_tokens), temperaturefloat(temperature) ) # 更新消息内容 msg.content response_text await msg.update() cl.on_settings_update async def on_settings_update(settings): 处理设置更新 # 这里可以保存或处理设置变更 print(f设置已更新: {settings}) cl.password_auth_callback def auth_callback(username: str, password: str): 简单的身份验证可选 # 在实际应用中这里应该连接数据库或LDAP进行验证 if (username, password) (admin, admin123): return cl.User(identifieradmin) else: return None if __name__ __main__: # 启动Chainlit应用 cl.run( mainchainlit_app, host0.0.0.0, port8002, # Chainlit服务端口 debugTrue )4.2 启动Chainlit前端在终端中运行Chainlit应用# 激活虚拟环境如果尚未激活 source venv/bin/activate # 启动Chainlit应用 chainlit run chainlit_app.py -w-w参数启用自动重载方便开发时修改代码。启动后打开浏览器访问http://localhost:8002你就能看到一个简洁的聊天界面了。4.3 与模型对话在Chainlit界面中你可以调整参数在输入框上方的设置中可以调整温度和最大生成长度。温度控制回复的随机性。值越高接近2.0回复越有创意但可能不准确值越低接近0回复越确定和保守。最大生成长度控制回复的最大长度。开始对话在底部的输入框中输入问题比如用简单的语言解释什么是机器学习帮我写一个Python函数计算斐波那契数列写一首关于春天的短诗查看回复模型会生成回复并显示在聊天窗口中。这个前端界面虽然简单但包含了核心的对话功能并且可以直观地展示模型的能力。5. 完整系统架构与使用流程现在我们已经搭建了一个完整的三层系统5.1 系统架构用户界面 (Chainlit, 端口 8002) ↓ 自定义API服务 (FastAPI Swagger, 端口 8001) ↓ 模型推理服务 (vLLM, 端口 8000) ↓ Qwen2.5-7B-Instruct 模型每一层都有明确的责任vLLM层负责高效运行模型提供最基础的推理能力。FastAPI层封装业务逻辑提供更友好的API接口和文档。Chainlit层提供用户交互界面降低使用门槛。5.2 一键启动脚本为了方便管理我们可以创建一个启动脚本start_all.sh#!/bin/bash # start_all.sh - 一键启动所有服务 echo 启动 Qwen2.5-7B-Instruct 完整服务栈 echo # 检查是否在虚拟环境中 if [ -z $VIRTUAL_ENV ]; then echo 请先激活Python虚拟环境: source venv/bin/activate exit 1 fi # 启动vLLM服务后台运行 echo 1. 启动 vLLM 模型服务 (端口 8000)... nohup python start_vllm_server.py --port 8000 vllm.log 21 VLLM_PID$! echo vLLM 服务已启动PID: $VLLM_PID # 等待vLLM服务启动 echo 等待模型加载约1-2分钟... sleep 90 # 启动FastAPI服务后台运行 echo 2. 启动 FastAPI 服务 (端口 8001)... nohup python custom_api_server.py fastapi.log 21 FASTAPI_PID$! echo FastAPI 服务已启动PID: $FASTAPI_PID echo Swagger文档: http://localhost:8001/docs # 等待FastAPI服务启动 sleep 5 # 启动Chainlit前端前台运行 echo 3. 启动 Chainlit 前端界面 (端口 8002)... echo 前端界面: http://localhost:8002 echo 按 CtrlC 停止所有服务 echo # 保存PID到文件方便后续停止服务 echo VLLM_PID$VLLM_PID service_pids.txt echo FASTAPI_PID$FASTAPI_PID service_pids.txt # 启动Chainlit前台运行方便查看日志 chainlit run chainlit_app.py --port 8002 --host 0.0.0.0再创建一个停止脚本stop_all.sh#!/bin/bash # stop_all.sh - 停止所有服务 echo 停止 Qwen2.5-7B-Instruct 服务栈 echo if [ -f service_pids.txt ]; then # 读取并终止进程 source service_pids.txt if [ ! -z $FASTAPI_PID ]; then echo 停止 FastAPI 服务 (PID: $FASTAPI_PID)... kill $FASTAPI_PID 2/dev/null fi if [ ! -z $VLLM_PID ]; then echo 停止 vLLM 服务 (PID: $VLLM_PID)... kill $VLLM_PID 2/dev/null fi # 删除PID文件 rm -f service_pids.txt echo 所有服务已停止 else echo 未找到服务PID文件尝试查找并停止相关进程... # 尝试查找并停止相关进程 pkill -f chainlit_app.py 2/dev/null pkill -f custom_api_server.py 2/dev/null pkill -f start_vllm_server.py 2/dev/null echo 已发送停止信号 fi # 清理日志文件 echo 清理日志文件... rm -f vllm.log fastapi.log 2/dev/null echo 完成给脚本添加执行权限chmod x start_all.sh stop_all.sh现在你可以用./start_all.sh一键启动所有服务用./stop_all.sh一键停止。5.3 服务验证与测试启动所有服务后可以通过以下方式验证vLLM服务curl http://localhost:8000/v1/modelsFastAPI服务访问http://localhost:8001/docsChainlit前端访问http://localhost:8002如果一切正常你就拥有了一个完整的Qwen2.5-7B-Instruct模型服务栈从底层推理到API接口再到用户界面一应俱全。6. 常见问题与解决方案在部署和使用过程中可能会遇到一些问题。这里列出一些常见问题及其解决方法。6.1 模型加载失败问题vLLM启动时卡在加载模型阶段或者报错。可能原因和解决网络问题首次运行需要从Hugging Face下载模型确保网络通畅。# 可以尝试先单独下载模型 python -c from transformers import AutoModel; AutoModel.from_pretrained(Qwen/Qwen2.5-7B-Instruct)显存不足7B模型需要约14-16GB显存。如果显存不足可以尝试使用量化版本Qwen/Qwen2.5-7B-Instruct-GPTQ-Int8减少--gpu-memory-utilization参数值使用CPU卸载性能会下降CUDA版本不匹配确保安装的vLLM版本与CUDA版本兼容。6.2 API调用超时或失败问题通过Swagger或Chainlit调用API时超时或返回错误。解决步骤检查所有服务是否都在运行ps aux | grep -E (vllm|fastapi|chainlit)检查端口是否被占用netstat -tlnp | grep -E (8000|8001|8002)查看服务日志tail -f vllm.log # vLLM日志 tail -f fastapi.log # FastAPI日志6.3 生成速度慢问题模型回复生成速度较慢。优化建议调整vLLM参数# 在start_vllm_server.py中调整 engine_args AsyncEngineArgs( modelargs.model, gpu_memory_utilization0.9, # 可以适当调高但不要超过1.0 max_model_len4096, # 如果不是需要长上下文可以减小这个值 tensor_parallel_size1, # 如果有多个GPU可以增加这个值 block_size16, # 可以尝试调整块大小 )使用流式输出修改API支持流式响应让用户能更快看到部分结果。硬件升级如果经常使用考虑升级GPU。6.4 回复质量不理想问题模型的回复不符合预期。调整方法调整温度参数需要创造性回答时提高温度0.8-1.2需要确定性回答时降低温度0.1-0.5优化提示词# 更好的系统提示词示例 system_prompt 你是一个专业的AI助手请遵循以下要求 1. 回答要准确、有用 2. 如果不知道就诚实地说不知道 3. 用中文回答除非用户要求其他语言 4. 保持友好和专业的语气使用更长的最大生成长度对于复杂问题增加max_tokens参数。6.5 内存或显存泄漏问题长时间运行后服务变慢或崩溃。监控和解决监控资源使用# 查看GPU使用情况 nvidia-smi # 查看内存使用 free -h # 查看进程资源使用 top -p $(pgrep -f python)定期重启服务可以设置定时任务每天在低峰期重启服务。使用Docker容器将服务容器化可以更容易地管理和重启。7. 总结通过本文的步骤我们成功搭建了一个完整的Qwen2.5-7B-Instruct模型服务栈。让我们回顾一下主要成果7.1 我们实现了什么高性能模型服务使用vLLM部署了Qwen2.5-7B-Instruct模型获得了接近原生的推理性能。标准化API接口用FastAPI封装了RESTful API提供了清晰的接口定义和参数校验。交互式API文档自动生成了Swagger文档让API测试和调试变得非常简单。用户友好界面用Chainlit构建了聊天前端让非技术用户也能轻松使用模型。完整部署脚本提供了一键启动和停止脚本简化了运维工作。7.2 这个方案的优势性能优秀vLLM提供了接近最优的推理速度。易于扩展三层架构让每一层都可以独立扩展和升级。开发友好Swagger文档大大降低了API的使用和调试难度。用户体验好Chainlit界面直观易用适合各种用户。维护简单清晰的架构和脚本让运维工作变得简单。7.3 下一步可以做什么如果你想让这个系统更加完善可以考虑添加身份验证在FastAPI层添加JWT或OAuth2认证保护API接口。实现速率限制防止API被滥用保证服务稳定性。添加监控告警集成Prometheus和Grafana监控服务状态。支持多模型扩展系统以支持多个不同的模型。添加缓存机制对常见问题答案进行缓存提高响应速度。容器化部署使用Docker和Kubernetes实现更专业的部署。7.4 最后的建议对于初学者建议先从本文的基础版本开始确保能正常运行。然后根据自己的需求逐步添加新功能。对于生产环境一定要做好安全防护、监控和备份。大模型服务虽然强大但也需要妥善管理。希望这个教程能帮助你快速上手Qwen2.5-7B-Instruct的部署和使用。如果在实践中遇到问题欢迎参考常见问题部分或者查阅相关工具的官方文档。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。