一、项目背景

基于vLLM推理引擎部署Google Gemma-4-E2B-it多模态大模型，实现图片+文本的多模态问答功能，并通过FastAPI封装为可视化API服务，最终完成本地接口测试

二、环境准备与依赖安装

2.1 核心依赖安装

项目核心依赖为vLLM（高性能大模型推理引擎），安装过程中遇到网络连接超时问题，通过国内镜像源+延长超时时间完成安装：

（1）初始安装失败：直接执行pip install vllm，因境外源网络限制出现连接超时；

（2）清华镜像尝试：使用清华PyPI镜像仍超时，命令：

pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple

（3）最终解决方案：切换阿里云镜像+延长超时时间至300秒，成功安装：

pip install vllm --default-timeout=300 -i https://mirrors.aliyun.com/pypi/simple/

2.2 版本兼容问题处理

安装完成后，运行模型服务时出现版本不兼容报错，通过升级依赖包解决：

升级vLLM和transformers至最新稳定版：

# 升级到最新版本 pip install --upgrade vllm transformers # 或者从源码安装最新版 vLLM（支持更多新模型） pip install git+https://github.com/vllm-project/vllm.git # 升级 transformers 到最新 pip install --upgrade transformers

2.3 系统环境依赖安装

运行过程中提示缺少C编译器，vLLM编译需要GCC/G++环境，执行以下命令安装：

Ubuntu/Debian系统完整安装编译工具：

apt-get update apt-get install -y build-essential

极简安装（仅安装核心编译器）：

apt-get install -y gcc g++

验证安装结果：

gcc --version g++ --version

三、模型部署与服务启动

3.1 vLLM模型直接启动测试

完成环境配置后，通过vllm serve命令直接启动模型服务，验证模型加载与基础推理能力：

vllm serve /home/models/models--google--gemma-4-E2B-it/snapshots/b4a601102c3d45e2b7b50e2057a6d5ec8ed4adcf \     --host 0.0.0.0 \     --port 8100

参数说明：--host 0.0.0.0允许外部设备访问，--port 8100指定服务端口；

作用：快速验证模型文件、vLLM环境、GPU环境是否正常。

3.2 离线多模态推理脚本开发

编写gemma_vllm.py本地推理脚本，实现离线模式下的图片+文本问答，核心功能：

1.配置离线环境：禁止联网请求，使用本地模型文件；

2.加载模型处理器（AutoProcessor）与vLLM推理引擎；

3.构建多模态输入（图片+文本提示词）；

4.调用vLLM生成回答，并解析输出结果。

脚本核心配置：

•模型路径：/home/models/models--google--gemma-4-E2B-it/snapshots/b4a601102c3d45e2b7b50e2057a6d5ec8ed4adcf

•GPU配置：指定CUDA_VISIBLE_DEVICES=1，GPU内存利用率85%；

•推理参数：温度值0.7，最大生成token数512。

四、API服务封装与测试

4.1 FastAPI接口服务开发

为实现模型服务化，编写gemma_vllm_api.py，基于FastAPI封装多模态推理接口，核心特性：

1.生命周期管理：服务启动时自动加载模型，避免重复加载耗时；

2.离线部署：完全禁用Hugging Face联网，仅使用本地模型；

3.日志优化：添加心跳日志，避免模型加载过程中误以为服务卡死；

4.接口设计：提供/predict（图片问答）和/health（健康检查）接口。

4.2 启动API服务

执行命令启动FastAPI服务，对外提供8000端口访问：

uvicorn gemma_vllm_api:app --host 0.0.0.0 --port 8000

服务启动后，自动加载Processor和Gemma模型到GPU，加载完成后可接收外部请求。

4.3 接口测试脚本开发与执行

编写test_gemma_vllm.py测试脚本，通过HTTP请求调用API服务，验证功能可用性：

1.脚本功能：读取本地图片，向API发送图片+提示词，打印模型回复；

2.测试配置：请求地址http://10.8.100.10:8107/predict，测试图片./data/1.jpg；

3.执行测试：

cd /home/tests python test_gemma_vllm.py

4.测试结果：成功接收模型返回的图片描述，验证服务正常运行。

五、项目成果与总结

5.1 核心成果

1.解决了vLLM安装的网络超时、版本兼容、系统依赖缺失三大问题，完成环境搭建；

2.成功部署Google Gemma-4-E2B-it多模态大模型，支持图片+文本联合推理；

3.基于vLLM实现高性能推理，结合FastAPI封装为标准化API服务；

4.完成离线部署，无需联网即可稳定运行，满足生产环境安全要求；

5.通过测试脚本验证接口功能，实现图片内容描述、问答等多模态能力。

5.2 关键问题解决总结

问题类型	解决方案
pip安装超时	阿里云镜像+延长超时时间--default-timeout=300
版本不兼容	升级vLLM和transformers至最新版
缺少C编译器	安装build-essential/gcc、g++
模型联网加载	设置环境变量开启离线模式

5.3 总结

完成了从环境搭建→模型部署→服务封装→接口测试。基于vLLM的推理引擎大幅提升模型响应速度，FastAPI接口可直接集成到业务系统中，适用于智能问答、图片分析、多模态交互等实际应用场景。