Gemma-3-12B-IT WebUI部署教程：离线环境安装依赖与模型权重预加载方案

Gemma-3-12B-IT WebUI部署教程离线环境安装依赖与模型权重预加载方案1. 引言为什么选择Gemma-3-12B-IT如果你正在寻找一个性能强大、部署成本可控的开源大语言模型Google的Gemma-3-12B-IT绝对值得关注。这个模型在推理能力、多语言支持和运行效率上相比前两代有了显著提升。120亿参数的规模让它既保持了不错的性能又不会像动辄几百亿参数的大模型那样“吃”掉你所有的硬件资源。更重要的是它是专门针对人类指令进行优化的版本这意味着它在对话、代码生成、任务执行这些实际应用场景中表现会比基础预训练版好得多。今天我要分享的是如何在一个离线环境中完整部署Gemma-3-12B-IT的WebUI界面。我会重点解决两个关键问题离线环境下的依赖安装和模型权重的预加载方案。无论你是个人开发者想本地部署还是企业需要在内部网络中使用这套方案都能帮你绕过网络限制顺利把模型跑起来。2. 环境准备离线部署的挑战与对策在离线环境下部署AI模型最大的挑战就是“断网”。所有在线安装、自动下载的功能都会失效。我们需要提前把所有需要的“零件”都准备好。2.1 硬件与系统要求先来看看你需要准备什么硬件资源类型最低要求推荐配置说明内存24GB32GB模型加载需要约23GB加上系统开销32GB比较稳妥存储50GB100GB模型文件23GBPython环境、依赖包等还需要额外空间GPU可选NVIDIA GPU (8GB)有GPU能大幅提升推理速度CPU也能跑但会慢很多系统Ubuntu 20.04Ubuntu 22.04 LTS其他Linux发行版也可以但Ubuntu的兼容性最好2.2 离线环境的核心思路离线部署的核心就一句话把所有需要从网上下载的东西提前在有网的环境下准备好然后搬到离线环境。具体来说需要准备三样东西Python依赖包所有pip安装的库模型权重文件Gemma-3-12B-IT的模型文件WebUI代码图形界面的前端和后端代码3. 第一步离线依赖包准备这是最繁琐但最关键的一步。我们需要在有网的环境下创建一个完整的依赖包仓库。3.1 创建虚拟环境并导出依赖首先在有网的机器上操作# 创建项目目录 mkdir gemma-3-offline cd gemma-3-offline # 创建虚拟环境 python3.11 -m venv venv source venv/bin/activate # 安装基础依赖这些是WebUI运行必需的 pip install torch2.8.0 --index-url https://download.pytorch.org/whl/cu118 pip install transformers4.40.0 pip install accelerate0.30.0 pip install gradio4.29.0 pip install sentencepiece0.2.0 pip install protobuf3.20.3 # 导出依赖列表 pip freeze requirements.txt3.2 下载所有依赖包到本地现在我们要把所有这些包包括它们的依赖全部下载到本地# 创建存放包的目录 mkdir -p offline_packages # 批量下载所有依赖包 pip download -r requirements.txt -d offline_packages --no-deps # 对于每个包再下载它的所有依赖 for package in $(cat requirements.txt | cut -d -f1); do pip download $package -d offline_packages done这里有个小技巧先下载主包--no-deps再单独下载每个包的依赖。这样做是为了避免重复下载也能更好地控制下载过程。3.3 创建离线安装脚本下载完所有包后我们需要创建一个安装脚本让离线环境能正确安装# 创建 install_offline.sh cat install_offline.sh EOF #!/bin/bash echo 开始安装离线依赖包... # 检查Python版本 if ! python3 --version | grep -q 3.11; then echo 错误需要Python 3.11当前版本$(python3 --version) exit 1 fi # 创建虚拟环境 python3 -m venv venv source venv/bin/activate # 安装本地包 echo 安装基础包... for package in offline_packages/*.whl offline_packages/*.tar.gz; do if [ -f $package ]; then pip install --no-index --find-linksoffline_packages $package fi done # 特殊处理torch可能需要特定版本 echo 检查torch安装... python -c import torch; print(fTorch版本: {torch.__version__}) echo 依赖安装完成 EOF chmod x install_offline.sh这个脚本的关键是--no-index --find-links参数它告诉pip不要从网络索引查找包只从本地目录安装。4. 第二步模型权重预加载方案模型权重文件很大约23GB在离线环境下传输需要一些技巧。4.1 在有网环境下载模型如果你能访问Hugging Face可以直接下载# 创建模型目录 mkdir -p models/gemma-3-12b-it # 使用huggingface-cli下载需要先登录 pip install huggingface-hub huggingface-cli login # 输入你的token # 下载模型 huggingface-cli download google/gemma-3-12b-it \ --local-dir models/gemma-3-12b-it \ --local-dir-use-symlinks False如果无法直接访问可以尝试以下替代方案使用镜像源有些地区有Hugging Face的镜像分块下载用wget或curl分块下载大文件从其他源获取一些开源社区会提供模型文件的BT种子或网盘链接4.2 模型文件完整性验证下载完成后一定要验证文件的完整性# 生成校验和 cd models/gemma-3-12b-it find . -type f -name *.bin -o -name *.safetensors | sort | xargs sha256sum model_checksums.txt # 检查文件结构 ls -la # 应该看到类似这样的结构 # config.json # generation_config.json # model.safetensors.index.json # model-00001-of-00003.safetensors # model-00002-of-00003.safetensors # model-00003-of-00003.safetensors # tokenizer.json # tokenizer_config.json4.3 离线传输方案23GB的文件传输根据你的实际情况选择传输方式适用场景注意事项移动硬盘最可靠格式化为exFAT兼容Windows/Linux局域网传输内部网络用rsync支持断点续传rsync -avP --progress source/ usertarget:/path/分卷压缩网络不稳定tar czvf - model/增量同步经常更新只传输变化的文件节省时间我个人的建议是如果只是部署一次用移动硬盘最省心。如果需要频繁更新可以搭建一个内部的文件服务器。5. 第三步WebUI代码与配置5.1 获取WebUI代码WebUI代码相对较小我们可以直接从GitHub获取# 在有网环境克隆代码 git clone https://github.com/your-repo/gemma-3-webui.git # 如果没有公开的repo可以自己准备一个简单的WebUI # 或者这里我提供一个最小化的WebUI示例 cat app.py EOF import gradio as gr import torch from transformers import AutoTokenizer, AutoModelForCausalLM import os # 模型路径配置 MODEL_PATH ./models/gemma-3-12b-it class GemmaChat: def __init__(self): self.device cuda if torch.cuda.is_available() else cpu print(f使用设备: {self.device}) # 加载tokenizer print(加载tokenizer...) self.tokenizer AutoTokenizer.from_pretrained(MODEL_PATH) # 加载模型 print(加载模型...) self.model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.float16 if self.device cuda else torch.float32, device_mapauto if self.device cuda else None, low_cpu_mem_usageTrue ) if self.device cpu: self.model self.model.to(self.device) print(模型加载完成) def generate_response(self, message, history, temperature0.7, max_tokens512): # 构建对话历史 prompt if history: for user_msg, assistant_msg in history: prompt f用户: {user_msg}\n助手: {assistant_msg}\n prompt f用户: {message}\n助手: # 编码输入 inputs self.tokenizer(prompt, return_tensorspt) if self.device cuda: inputs {k: v.to(self.device) for k, v in inputs.items()} # 生成回复 with torch.no_grad(): outputs self.model.generate( **inputs, max_new_tokensmax_tokens, temperaturetemperature, do_sampleTrue, top_p0.9, pad_token_idself.tokenizer.eos_token_id ) # 解码输出 response self.tokenizer.decode(outputs[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue) return response # 创建聊天实例 chatbot GemmaChat() def predict(message, history, temperature, max_tokens): try: response chatbot.generate_response(message, history, temperature, max_tokens) return response except Exception as e: return f生成回复时出错: {str(e)} # 创建Gradio界面 with gr.Blocks(titleGemma-3-12B-IT 聊天助手) as demo: gr.Markdown(# Gemma-3-12B-IT 聊天助手) gr.Markdown(基于Google Gemma-3-12B指令微调模型的本地部署版本) chatbot_interface gr.Chatbot(height500) with gr.Row(): with gr.Column(scale4): msg gr.Textbox( label输入消息, placeholder输入您的问题..., lines3 ) with gr.Column(scale1): with gr.Row(): submit gr.Button(发送, variantprimary) clear gr.Button(清空) with gr.Accordion(高级参数, openFalse): temperature gr.Slider( minimum0.1, maximum1.5, value0.7, step0.1, labelTemperature (随机性) ) max_tokens gr.Slider( minimum64, maximum2048, value512, step64, label最大生成长度 ) def user(message, history): return , history [[message, None]] def bot(history, temperature, max_tokens): message history[-1][0] response predict(message, history[:-1], temperature, max_tokens) history[-1][1] response return history msg.submit(user, [msg, chatbot_interface], [msg, chatbot_interface], queueFalse).then( bot, [chatbot_interface, temperature, max_tokens], chatbot_interface ) submit.click(user, [msg, chatbot_interface], [msg, chatbot_interface], queueFalse).then( bot, [chatbot_interface, temperature, max_tokens], chatbot_interface ) clear.click(lambda: None, None, chatbot_interface, queueFalse) gr.Markdown(### 使用提示) gr.Markdown( - **创意写作**: Temperature 调到 1.0-1.5 - **代码生成**: Temperature 调到 0.2-0.5 - **知识问答**: Temperature 调到 0.7 左右 - 如果回复慢可以调低最大生成长度 ) if __name__ __main__: demo.launch( server_name0.0.0.0, server_port7860, shareFalse ) EOF5.2 创建管理脚本为了方便管理我们创建几个实用的脚本# 创建启动脚本 start.sh cat start.sh EOF #!/bin/bash # 激活虚拟环境 source venv/bin/activate # 设置Python路径 export PYTHONPATH$(pwd):$PYTHONPATH # 设置模型路径 export MODEL_PATH$(pwd)/models/gemma-3-12b-it # 启动WebUI echo 启动Gemma-3-12B-IT WebUI... echo 访问地址: http://localhost:7860 echo 按CtrlC停止服务 python app.py EOF chmod x start.sh # 创建停止脚本 stop.sh cat stop.sh EOF #!/bin/bash echo 停止Gemma-3 WebUI服务... pkill -f python app.py sleep 2 # 检查是否停止成功 if pgrep -f python app.py /dev/null; then echo 强制停止... pkill -9 -f python app.py fi echo 服务已停止 EOF chmod x stop.sh # 创建状态检查脚本 status.sh cat status.sh EOF #!/bin/bash echo Gemma-3-12B-IT WebUI 状态检查 echo # 检查进程 if pgrep -f python app.py /dev/null; then echo ✅ 服务正在运行 echo 进程信息: ps aux | grep python app.py | grep -v grep else echo ❌ 服务未运行 fi echo echo 端口检查 if netstat -tlnp 2/dev/null | grep :7860 /dev/null; then echo ✅ 端口7860已被占用 netstat -tlnp | grep :7860 else echo ❌ 端口7860未被占用 fi echo echo 模型文件检查 MODEL_DIR./models/gemma-3-12b-it if [ -d $MODEL_DIR ]; then echo ✅ 模型目录存在 file_count$(find $MODEL_DIR -name *.safetensors -o -name *.bin | wc -l) echo 找到 $file_count 个模型文件 # 检查关键文件 for file in config.json tokenizer.json; do if [ -f $MODEL_DIR/$file ]; then echo ✅ $file 存在 else echo ❌ $file 缺失 fi done else echo ❌ 模型目录不存在: $MODEL_DIR fi echo echo 虚拟环境检查 if [ -f venv/bin/activate ]; then echo ✅ 虚拟环境存在 # 检查关键包 source venv/bin/activate for package in torch transformers gradio; do if python -c import $package 2/dev/null; then echo ✅ $package 已安装 else echo ❌ $package 未安装 fi done deactivate else echo ❌ 虚拟环境不存在 fi EOF chmod x status.sh6. 第四步离线环境完整部署流程现在我们把所有准备好的东西转移到离线环境开始正式部署。6.1 文件传输与结构在离线环境创建项目目录# 在离线服务器上 mkdir -p /opt/gemma-3-webui cd /opt/gemma-3-webui # 从移动硬盘或内部服务器复制文件 # 假设你的文件在 /mnt/usb/gemma-offline/ cp -r /mnt/usb/gemma-offline/* .最终目录结构应该是这样的/opt/gemma-3-webui/ ├── offline_packages/ # 所有Python依赖包 │ ├── torch-2.8.0-cp311-cp311-linux_x86_64.whl │ ├── transformers-4.40.0-py3-none-any.whl │ └── ... (其他所有包) ├── models/ │ └── gemma-3-12b-it/ # 模型权重文件 │ ├── config.json │ ├── tokenizer.json │ ├── model.safetensors.index.json │ ├── model-00001-of-00003.safetensors │ ├── model-00002-of-00003.safetensors │ └── model-00003-of-00003.safetensors ├── app.py # WebUI主程序 ├── requirements.txt # 依赖列表 ├── install_offline.sh # 离线安装脚本 ├── start.sh # 启动脚本 ├── stop.sh # 停止脚本 └── status.sh # 状态检查脚本6.2 执行离线安装# 1. 安装系统依赖如果需要 # Ubuntu/Debian sudo apt-get update sudo apt-get install -y python3.11 python3.11-venv python3-pip # CentOS/RHEL sudo yum install -y python3.11 python3.11-devel # 2. 运行离线安装脚本 ./install_offline.sh # 3. 验证安装 source venv/bin/activate python -c import torch; print(fPyTorch版本: {torch.__version__}) python -c import transformers; print(fTransformers版本: {transformers.__version__}) python -c import gradio; print(fGradio版本: {gradio.__version__})如果一切顺利你会看到各个库的版本号输出。6.3 首次运行测试# 1. 先检查状态 ./status.sh # 2. 启动服务第一次会比较慢因为要加载模型 ./start.sh # 在另一个终端查看日志 tail -f nohup.out # 或者查看具体的日志文件第一次启动时模型加载可能需要几分钟时间具体取决于你的硬件。在日志中你会看到类似这样的信息加载tokenizer... 加载模型... Loading checkpoint shards: 100%|██████████| 3/3 [01:2300:00, 27.67s/it] 模型加载完成 Running on local URL: http://0.0.0.0:7860看到最后一行就说明服务启动成功了。7. 常见问题与解决方案离线部署过程中可能会遇到各种问题这里我总结了一些常见的情况和解决方法。7.1 依赖安装问题问题1pip安装时报版本冲突ERROR: Cannot install package1x.x.x and package2y.y.y解决方案# 在有网环境重新整理依赖 # 1. 清除虚拟环境 deactivate rm -rf venv # 2. 重新创建并安装 python3.11 -m venv venv source venv/bin/activate # 3. 按顺序安装先安装基础包 pip install torch2.8.0 pip install transformers4.40.0 # ... 其他包 # 4. 重新导出requirements.txt pip freeze requirements_new.txt # 5. 重新下载所有包 pip download -r requirements_new.txt -d offline_packages_new问题2缺少系统库error: command x86_64-linux-gnu-gcc failed with exit status 1解决方案# Ubuntu/Debian sudo apt-get install -y build-essential python3-dev # CentOS/RHEL sudo yum install -y gcc gcc-c python3-devel7.2 模型加载问题问题1内存不足CUDA out of memory. Tried to allocate XX GiB解决方案# 修改app.py中的加载参数 self.model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.float16, # 使用半精度 device_mapauto, low_cpu_mem_usageTrue, offload_folderoffload, # 设置offload目录 offload_state_dictTrue # 启用状态字典offload )问题2模型文件损坏Error loading model file: model-00001-of-00003.safetensors解决方案# 验证文件完整性 cd models/gemma-3-12b-it md5sum *.safetensors *.bin # 与原始校验和对比 # 如果文件损坏需要重新传输7.3 运行时报错问题1端口被占用Address already in use解决方案# 查看占用7860端口的进程 sudo lsof -i :7860 # 停止占用进程 sudo kill -9 PID # 或者修改app.py中的端口 demo.launch(server_port7861) # 改为其他端口问题2CUDA版本不匹配CUDA error: no kernel image is available for execution on the device解决方案# 检查CUDA版本 nvidia-smi # 安装对应版本的PyTorch # 离线环境下需要提前下载对应版本的torch # CUDA 11.8: torch-2.8.0cu118 # CUDA 12.1: torch-2.8.0cu1218. 性能优化建议部署完成后我们可以做一些优化来提升使用体验。8.1 内存优化配置如果你的内存比较紧张可以尝试这些配置# 在app.py的模型加载部分添加这些参数 self.model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.float16, # 半精度减少内存占用 device_mapauto, low_cpu_mem_usageTrue, # 量化配置进一步减少内存 load_in_8bitTrue, # 8位量化 # 或者 load_in_4bitTrue, # 4位量化需要bitsandbytes # 优化配置 use_cacheTrue, attn_implementationsdpa, # 使用SDPA注意力更快 )8.2 使用Supervisord管理进程对于生产环境建议用Supervisord来管理服务# 安装supervisor在有网环境提前下载 # Ubuntu/Debian sudo apt-get install -y supervisor # 创建配置文件 sudo cat /etc/supervisor/conf.d/gemma-webui.conf EOF [program:gemma-webui] command/opt/gemma-3-webui/venv/bin/python /opt/gemma-3-webui/app.py directory/opt/gemma-3-webui useryour_username autostarttrue autorestarttrue stopasgrouptrue killasgrouptrue stderr_logfile/var/log/gemma-webui.err.log stdout_logfile/var/log/gemma-webui.out.log environmentPYTHONPATH/opt/gemma-3-webui EOF # 启动服务 sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start gemma-webui # 查看状态 sudo supervisorctl status gemma-webui8.3 启用API接口如果你需要其他程序调用可以添加API支持# 在app.py中添加FastAPI支持 from fastapi import FastAPI, HTTPException from pydantic import BaseModel import uvicorn app FastAPI() class ChatRequest(BaseModel): message: str temperature: float 0.7 max_tokens: int 512 app.post(/api/chat) async def chat_endpoint(request: ChatRequest): try: response chatbot.generate_response( request.message, [], request.temperature, request.max_tokens ) return {response: response} except Exception as e: raise HTTPException(status_code500, detailstr(e)) # 在main函数中同时启动Gradio和FastAPI if __name__ __main__: import threading # 启动Gradio gradio_thread threading.Thread( targetlambda: demo.launch(server_name0.0.0.0, server_port7860, shareFalse) ) gradio_thread.start() # 启动FastAPI uvicorn.run(app, host0.0.0.0, port8000)9. 总结通过这套完整的离线部署方案你应该已经成功在离线环境中部署了Gemma-3-12B-IT的WebUI。让我们回顾一下关键步骤环境准备在有网环境准备好所有依赖包和模型文件依赖打包使用pip download下载所有Python包到本地模型获取从Hugging Face或镜像源下载模型权重代码准备准备WebUI代码和管理脚本离线传输通过移动硬盘或内部网络传输所有文件本地安装在离线环境运行安装脚本服务启动启动WebUI服务并验证这套方案的优点很明显完全离线不依赖任何外部网络可重复部署一次准备多次使用灵活性强可以轻松迁移到其他离线环境维护方便所有依赖都在本地版本可控在实际使用中你可能会遇到一些具体的问题。我的建议是先测试再部署在有网环境完整测试整个流程做好备份模型文件很大传输前做好校验监控资源注意内存和GPU使用情况定期更新虽然离线但可以定期更新依赖和模型Gemma-3-12B-IT是一个相当实用的模型120亿参数的规模在性能和资源消耗之间取得了很好的平衡。通过这个WebUI你可以方便地进行对话、代码生成、文档写作等各种任务。希望这篇教程能帮助你在离线环境中顺利部署和使用这个强大的模型。如果在部署过程中遇到问题欢迎参考常见问题部分或者根据错误信息搜索解决方案。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。