系统部署指南

部署概述

本章介绍岐黄智鉴系统的实际部署方案，基于GLM-4.1V-9B-Thinking模型和LoRA微调技术的简化部署流程。

系统要求

硬件配置

组件	最低配置	推荐配置	说明
CPU	4核心	8核心+	用于CPU推理模式
内存	16GB	32GB+	模型加载需要充足内存
GPU	GTX 1080Ti 11GB	RTX 4090 24GB	CUDA支持，显存影响推理速度
存储	30GB 可用空间	50GB	存储模型文件和依赖

软件环境

软件	版本要求	说明
Python	3.9-3.11	推荐使用conda管理
CUDA	11.8+ 或 12.x	GPU推理必需
Git	任意版本	克隆代码仓库

快速部署

1. 环境准备

创建虚拟环境

bash

# 使用conda创建虚拟环境
conda create -n qihuang python=3.10
conda activate qihuang

# 或使用venv
python -m venv qihuang_env
# Windows
qihuang_env\Scripts\activate
# Linux/Mac
source qihuang_env/bin/activate

克隆项目代码

bash

git clone https://github.com/your-repo/qihuang-zhijian.git
cd qihuang-zhijian

2. 安装依赖

核心依赖安装

bash

# 安装PyTorch (根据CUDA版本选择)
# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# CPU版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

特殊Transformers版本

重要： GLM-4.1V需要特定版本的transformers：

bash

# 安装GLM-4.1V专用transformers版本
pip install transformers-v4.55.0-GLM-4.5V-preview

其他依赖

bash

# 从requirements.txt安装其他依赖
pip install -r requirements.txt

# 或手动安装核心组件
pip install gradio>=5.42.0
pip install accelerate>=1.10.0
pip install PyMuPDF>=1.26.3  # PDF处理
pip install av>=15.0.0       # 视频处理

3. 模型下载

方式一：自动下载（推荐）

系统会自动从以下源下载模型，无需手动操作：

本地模型：models/GLM-4.1V-9B-Thinking/
魔搭社区：ZhipuAI/GLM-4.1V-9B-Thinking
HuggingFace：THUDM/GLM-4.1V-9B-Thinking

方式二：手动下载

bash

# 使用HuggingFace Hub下载
pip install huggingface_hub
huggingface-cli download THUDM/GLM-4.1V-9B-Thinking --local-dir models/GLM-4.1V-9B-Thinking

# 或使用git lfs
git lfs install
git clone https://huggingface.co/THUDM/GLM-4.1V-9B-Thinking models/GLM-4.1V-9B-Thinking

方式三：使用魔搭社区（国内推荐）

bash

# 安装ModelScope
pip install modelscope

# Python代码下载
python -c "
from modelscope import snapshot_download
snapshot_download('ZhipuAI/GLM-4.1V-9B-Thinking', 
                  cache_dir='./models')
"

4. LoRA适配器配置

LoRA微调文件应放置在 models/lora/ 目录下：

models/
├── GLM-4.1V-9B-Thinking/    # 基础模型
│   ├── config.json
│   ├── tokenizer.json
│   └── pytorch_model.bin
└── lora/                    # LoRA适配器
    ├── adapter_config.json
    ├── adapter_model.safetensors
    └── ...

启动服务

Gradio Web界面（推荐）

bash

# 启动Gradio界面
python src/backend/glm4.1v_infer_gradio.py

# 或指定端口
python src/backend/glm4.1v_infer_gradio.py --port 7860

启动后访问：http://localhost:7860

FastAPI后端服务

bash

# 启动API服务
python src/backend/demo_api_fastapi.py

# 或使用uvicorn
uvicorn src.backend.demo_api_fastapi:app --host 0.0.0.0 --port 8000

API文档访问：http://localhost:8000/docs

前端界面

bash

# 启动简单HTTP服务器查看前端
cd src/frontend
python -m http.server 8080

# 访问 http://localhost:8080

部署配置

环境变量设置

bash

# 设置CUDA设备
export CUDA_VISIBLE_DEVICES=0

# 设置模型路径（可选）
export MODEL_PATH="/path/to/your/models"

# 设置缓存目录
export HF_HOME="/path/to/cache"

内存优化配置

python

# 在代码中设置内存优化
import torch

# 启用内存映射
torch_dtype = torch.bfloat16  # 使用半精度
device_map = "auto"           # 自动设备映射

# 梯度检查点（训练时）
gradient_checkpointing = True

GPU配置检查

python

import torch

# 检查CUDA可用性
print(f"CUDA可用: {torch.cuda.is_available()}")
print(f"CUDA版本: {torch.version.cuda}")
print(f"GPU数量: {torch.cuda.device_count()}")

if torch.cuda.is_available():
    print(f"当前GPU: {torch.cuda.get_device_name()}")
    print(f"GPU内存: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f}GB")

常见问题解决

1. Transformers版本问题

错误：ImportError: No module named 'glm4v'

解决：确保安装了正确的transformers版本

bash

pip uninstall transformers
pip install transformers-v4.55.0-GLM-4.5V-preview

2. 内存不足

错误：CUDA out of memory

解决：降低batch size或使用CPU推理

python

# 使用CPU推理
device_map = "cpu"
torch_dtype = torch.float32

# 或者使用模型并行
device_map = "auto"
max_memory = {0: "10GiB", 1: "10GiB"}

3. 模型下载失败

解决：使用国内镜像或手动下载

bash

# 设置HuggingFace镜像
export HF_ENDPOINT=https://hf-mirror.com

# 或使用魔搭社区
pip install modelscope

4. 文件格式不支持

错误：PDF或PPT转换失败

解决：安装额外依赖

bash

# PDF处理
pip install PyMuPDF

# PPT处理需要LibreOffice
# Ubuntu/Debian
sudo apt-get install libreoffice

# Windows: 下载安装LibreOffice

5. 权限问题

错误：文件访问权限不足

解决：检查文件权限

bash

# Linux/Mac
chmod -R 755 models/
chmod -R 755 cache/

# Windows: 右键属性设置权限

性能优化

1. 推理加速

python

# 使用torch.compile (PyTorch 2.0+)
model = torch.compile(model)

# 启用Flash Attention
torch.backends.cuda.enable_flash_sdp(True)

# 使用量化推理
load_in_4bit = True  # 4bit量化
load_in_8bit = True  # 8bit量化

2. 内存优化

python

# 启用CPU offload
device_map = {
    "model.embed_tokens": 0,
    "model.layers": 0,
    "model.norm": 0,
    "lm_head": "cpu"
}

# 使用梯度累积
gradient_accumulation_steps = 4

3. 并发处理

bash

# 启动多个worker
gunicorn src.backend.demo_api_fastapi:app \
    --workers 2 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000

Docker部署（可选）

构建镜像

dockerfile

FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 7860

CMD ["python", "src/backend/glm4.1v_infer_gradio.py"]

启动容器

bash

# 构建镜像
docker build -t qihuang-zhijian .

# 启动容器（GPU支持）
docker run --gpus all -p 7860:7860 qihuang-zhijian

# 启动容器（CPU模式）
docker run -p 7860:7860 qihuang-zhijian

监控与维护

系统监控

python

# 监控GPU使用情况
import nvidia_ml_py3 as nvml
nvml.nvmlInit()
handle = nvml.nvmlDeviceGetHandleByIndex(0)
info = nvml.nvmlDeviceGetMemoryInfo(handle)
print(f"GPU内存使用: {info.used/1e9:.1f}GB / {info.total/1e9:.1f}GB")

日志配置

python

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('logs/qihuang.log'),
        logging.StreamHandler()
    ]
)

定期维护

bash

# 清理缓存
rm -rf ~/.cache/huggingface/transformers/

# 清理临时文件
find . -name "*.tmp" -delete
find . -name "__pycache__" -exec rm -rf {} +

部署建议

首次部署：建议使用CPU模式测试，确认环境正常后再切换到GPU
生产环境：推荐使用Docker部署，便于管理和扩展
性能调优：根据硬件配置调整batch size和并发数
安全考虑：生产环境需要配置防火墙和访问控制

技术支持：遇到部署问题可参考GLM-4.1V官方文档或提交Issue获取帮助。

系统部署指南 ​

系统要求 ​

硬件配置 ​

软件环境 ​

快速部署 ​

1. 环境准备 ​

创建虚拟环境 ​

克隆项目代码 ​

2. 安装依赖 ​

核心依赖安装 ​

特殊Transformers版本 ​

其他依赖 ​

3. 模型下载 ​

方式一：自动下载（推荐） ​

方式二：手动下载 ​

方式三：使用魔搭社区（国内推荐） ​

4. LoRA适配器配置 ​

启动服务 ​

Gradio Web界面（推荐） ​

FastAPI后端服务 ​

前端界面 ​

部署配置 ​

环境变量设置 ​

内存优化配置 ​

GPU配置检查 ​

常见问题解决 ​

1. Transformers版本问题 ​

2. 内存不足 ​

3. 模型下载失败 ​

4. 文件格式不支持 ​

5. 权限问题 ​

性能优化 ​

1. 推理加速 ​

2. 内存优化 ​

3. 并发处理 ​

Docker部署（可选） ​

构建镜像 ​

启动容器 ​

监控与维护 ​

系统监控 ​

日志配置 ​

定期维护 ​

系统部署指南

系统要求

硬件配置

软件环境

快速部署

1. 环境准备

创建虚拟环境

克隆项目代码

2. 安装依赖

核心依赖安装

特殊Transformers版本

其他依赖

3. 模型下载

方式一：自动下载（推荐）

方式二：手动下载

方式三：使用魔搭社区（国内推荐）

4. LoRA适配器配置

启动服务

Gradio Web界面（推荐）

FastAPI后端服务

前端界面

部署配置

环境变量设置

内存优化配置

GPU配置检查

常见问题解决

1. Transformers版本问题

2. 内存不足

3. 模型下载失败

4. 文件格式不支持

5. 权限问题

性能优化

1. 推理加速

2. 内存优化

3. 并发处理

Docker部署（可选）

构建镜像

启动容器

监控与维护

系统监控

日志配置

定期维护