项目实践13—全球证件智能识别系统（内网离线部署大模型并调用）

目录

• 一、任务概述
• 二、操作系统安装与初始化
• • [2.1 准备工作](#2.1 准备工作)
  • [2.2 启动与 BIOS 设置](#2.2 启动与 BIOS 设置)
  • [2.3 安装配置（核心步骤）](#2.3 安装配置（核心步骤）)
  • [2.4 安装后彻底清空剩余磁盘（如果服务器有多块硬盘）](#2.4 安装后彻底清空剩余磁盘（如果服务器有多块硬盘）)
  • [2.5 基础离线依赖准备（重要！！！）](#2.5 基础离线依赖准备（重要！！！）)
• 三、离线安装NVIDIA显卡驱动
• • [3.1 禁用 Nouveau 驱动](#3.1 禁用 Nouveau 驱动)
  • [3.2 安装 Data Center Driver](#3.2 安装 Data Center Driver)
• [四、离线安装 Docker 与 NVIDIA Container Toolkit](#四、离线安装 Docker 与 NVIDIA Container Toolkit)
• • [4.1 离线安装 Docker Engine (Community)](#4.1 离线安装 Docker Engine (Community))
  • • [1. 下载安装包（在互联网机器操作）](#1. 下载安装包（在互联网机器操作）)
    • [2. 传输与安装（在内网服务器操作）](#2. 传输与安装（在内网服务器操作）)
  • [4.2 离线安装 NVIDIA Container Toolkit](#4.2 离线安装 NVIDIA Container Toolkit)
  • • [1. 下载安装包（在互联网机器操作）](#1. 下载安装包（在互联网机器操作）)
    • [2. 传输与安装（在内网服务器操作）](#2. 传输与安装（在内网服务器操作）)
    • [3. 配置 Docker 运行时（关键步骤）](#3. 配置 Docker 运行时（关键步骤）)
    • [4. 最终环境验证](#4. 最终环境验证)
• 五、离线模型权重准备
• • [5.1 模型下载（互联网端操作）](#5.1 模型下载（互联网端操作）)
  • [5.2 数据迁移与校验（内网端操作）](#5.2 数据迁移与校验（内网端操作）)
• [六、构建离线 Docker 镜像](#六、构建离线 Docker 镜像)
• • [6.1 拉取并导出镜像（互联网端操作）](#6.1 拉取并导出镜像（互联网端操作）)
  • [6.2 导入镜像（内网端操作）](#6.2 导入镜像（内网端操作）)
• 七、容器化部署与服务启动
• • [7.1 启动脚本编写](#7.1 启动脚本编写)
  • [7.2 服务启动与日志监控](#7.2 服务启动与日志监控)
  • [7.3 本地回路测试](#7.3 本地回路测试)
• 八、生产环境网络配置
• • [8.1 识别物理网卡](#8.1 识别物理网卡)
  • [8.2 备份原有配置](#8.2 备份原有配置)
  • [8.3 编写静态 IP 配置文件](#8.3 编写静态 IP 配置文件)
  • [8.4 应用配置与验证](#8.4 应用配置与验证)
  • [8.5 启用SSH](#8.5 启用SSH)
  • • [8.5.1 检查 SSH 服务是否正在运行](#8.5.1 检查 SSH 服务是否正在运行)
    • [8.5.2 检查端口监听情况](#8.5.2 检查端口监听情况)
    • [8.5.3 检查并配置防火墙 (UFW)](#8.5.3 检查并配置防火墙 (UFW))
    • [8.5.4 检查 SSH 配置文件](#8.5.4 检查 SSH 配置文件)
• 九、验证
• 十、总结

一、任务概述

在之前的开发阶段，全球证件智能识别系统已成功集成图文多模态大模型，实现了对国外证件版面信息的深度结构化提取。此前，该功能依赖于外部的云端API（硅基流动）。然而，在实际的政务、金融等高敏感业务场景中，数据隐私与网络安全尤为重要。按照严格的网络安全要求，核心业务数据严禁流出内网，服务器必须处于物理隔离状态。

为了满足上述要求，同时保持系统的智能化水平，本篇博客将详细阐述如何在完全断网的内网GPU服务器上，从零开始部署Qwen3-VL-8B-Thinking多模态大模型。

服务器硬件与环境现状：

• 硬件配置：4张 NVIDIA Tesla T4 显卡，单卡显存16GB（总显存64GB）；CPU为x86架构。
• 网络环境：完全断网，无互联网连接。数据传输仅能通过高权限的移动存储介质（U盘或移动硬盘）进行摆渡。
• 操作说明 ：原服务器系统环境陈旧，不满足大模型运行依赖。需执行清盘操作，重新安装 Ubuntu Server 24.04.3 LTS 操作系统，并部署适配的驱动与容器化推理环境。

技术路线：

鉴于内网环境无法使用 apt 或 pip 在线安装依赖，本次部署将采用 "全容器化" 方案：

1. 系统层：离线安装Ubuntu 24.04及NVIDIA Data Center Driver。
2. 引擎层：离线安装Docker及NVIDIA Container Toolkit。
3. 应用层：在互联网机器上预构建包含vLLM推理框架的Docker镜像，导出后通过硬盘拷贝至内网服务器导入。
4. 模型层：离线下载模型权重文件，挂载至容器运行。

---

二、操作系统安装与初始化

2.1 准备工作

1. 下载镜像 (ISO)

   • 访问 Ubuntu 官方网站下载 Ubuntu Server 24.04 LTS 的 ISO 文件，或者使用阿里镜像。
   • 注意：虽然目前可能显示为 24.04.x，但安装步骤对于所有 24.04 系列都是通用的。

2. 制作 USB 启动盘

   • 准备一个至少 4GB 的 U 盘（里面的数据也会被清空）。
   • Windows 用户 ：推荐使用 Rufus 。
     • 插入 U 盘，打开 Rufus。
     • "设备"选择U 盘。
     • "引导类型选择"点击"选择"，找到下载好的 Ubuntu ISO 文件。
     • 点击"开始"，选择"以 ISO 模式写入"或推荐模式，等待完成。

3. 连接服务器

   • 将制作好的 U 盘插入服务器 USB 接口。
   • 连接显示器和键盘。

---

2.2 启动与 BIOS 设置

1. 进入 BIOS/UEFI
   • 启动服务器，立即连续按下启动热键（通常是 F11、F12、F2 或 Del，具体取决于服务器品牌，如 Dell、HP、Lenovo 等）。
2. 选择启动项
   • 在 Boot Menu（启动菜单）中，选择 UEFI: [U盘名称] 或 USB Disk。
3. 开始引导
   • 你会看到 GRUB 菜单，选择第一项 "Try or Install Ubuntu Server" 并回车。
   • 系统会加载安装程序，这可能需要几分钟，直到出现语言选择界面。

---

2.3 安装配置（核心步骤）

Ubuntu Server 使用的是文本向导式安装界面。使用 方向键 移动，空格键 选择/取消选择，Enter 确认。

1. Language (语言)

   • 建议选择 English。服务器环境通常推荐使用英语以避免命令行乱码问题。

2. Keyboard configuration (键盘配置)

   • Layout 默认 English (US) 即可。
   • 选择 Done。

3. Choose type of install (选择安装类型)

   • 默认选择 Ubuntu Server。
   • 如果想要极简系统，可选 "Ubuntu Server (minimized)"，但通常标准版更好用。
   • 选择 Done。

4. Network connections (网络连接)

   • 如果插了网线且有 DHCP，应该会自动获取 IP（显示为 eth0: 192.168.x.x）。
   • 如果要配置静态 IP，选中网卡按回车，选择 "Edit IPv4"，将 Automatic 改为 Manual 并填写 Subnet/Address/Gateway/DNS。
   • 确认无误后选择 Done。

5. Configure proxy (配置代理)

   • 如果没有代理服务器，留空。
   • 选择 Done。

6. Configure Ubuntu archive mirror (配置镜像源)

   • 默认是 Ubuntu 官方源。如果在国内，为了速度，可以将地址手动改为阿里云或清华源（例如：http://mirrors.aliyun.com/ubuntu/）。
   • 或者直接用默认的，安装完再换也行。
   • 选择 Done。

7. Storage configuration (存储配置 - 关键步骤)

   • 自动清空系统盘（主硬盘）
     1. 选中 "Use an entire disk"（使用整块磁盘）。
     2. 在下方选中要安装系统的那个硬盘（例如 /dev/sda 或 /dev/nvme0n1）。
     3. Set up this disk as an LVM group ：建议不勾选（纯物理分区）。
     4. 选择 Done。
     5. 系统会弹出一个摘要界面，显示分区布局。确认无误后选择 Done。
     6. 红色警告弹窗 ：系统会提示 "Confirm destructive action"（确认破坏性操作）。选择 Continue 。此时，选中的这块硬盘数据将被完全格式化。

8. Profile setup (创建用户)

   • Your name: 你的名字（随意）。
   • Your server's name : 主机名（例如 ubuntu-server）。
   • Pick a username : 登录用户名（不能是 root ，例如 admin）。
   • Choose a password: 设置密码。
   • 选择 Done。

9. Upgrade to Ubuntu Pro

   • 通常选择 "Skip for now"（先跳过）。
   • 选择 Continue。

10. SSH Setup (SSH 设置)

    • 务必勾选 "Install OpenSSH server"（按空格键勾选）。这是远程管理服务器的基础。
    • Import SSH identity 可以不选。
    • 选择 Done。

11. Featured Server Snaps (预装软件)

    • 这里列出了 Docker, Kubernetes 等常用软件。
    • 建议什么都不选，等系统装好后手动安装最新版更干净。
    • 选择 Done。

12. Installing System (开始安装)

    • 系统开始格式化磁盘并复制文件。
    • 屏幕下方会显示 "Installing kernel..." 等日志。
    • 待显示 "Install Complete!" 后，选择底部的 "Reboot Now"。
    • 拔掉 U 盘，然后按回车键重启。

---

2.4 安装后彻底清空剩余磁盘（如果服务器有多块硬盘）

1. 登录系统

   • 输入刚才设置的用户名和密码。

2. 查看所有磁盘

   lsblk

   • 假设系统装在 /dev/sda，发现还有 /dev/sdb, /dev/sdc 等硬盘。

3. 清空非系统盘数据

   • 警告：请仔细核对磁盘名称，不要误删系统盘！

   • 使用 wipefs 清除磁盘的所有签名（快速清空）：

     # 假设 sdb2 是要清空的数据盘
     sudo wipefs -a /dev/sdb2

   • 或者使用 dd 命令向磁盘写入零（彻底销毁数据，速度慢，视硬盘大小而定）：

     # 彻底覆盖数据
     sudo dd if=/dev/zero of=/dev/sdb2 bs=1M status=progress

4. 重新分区并格式化（可选）

   • 如果需要使用这些空盘，可以创建一个新文件系统：

     sudo mkfs.ext4 /dev/sdb2

---

至此，Ubuntu Server 24.04.3 LTS 已成功安装，且旧数据已被清理。

2.5 基础离线依赖准备（重要！！！）

系统重启并登录后，由于无法联网使用 apt，需手动安装构建驱动所需的基础工具。

1. 准备离线包 ：

   在互联网机器上下载以下 .deb 包（确保与 Ubuntu 24.04 内核版本匹配）：

   • build-essential 元包及其依赖（含 gcc, make, libc-dev 等）。
   • linux-headers-$(uname -r)：内核头文件，编译显卡驱动必须。
     注意！！！ 由于整个.deb离线包比较多，嵌套比较深，建议参考我的另一篇博客教程来下载和操作，此教程中的方法目前是离线安装的最佳方案，虽然麻烦，但是可以确保不出问题。

2. 传输并安装 ：

   挂载U盘或移动硬盘，将 .deb 文件复制到服务器，执行批量安装：

   # 挂载硬盘
   sudo mkdir -p /mnt/usb
   sudo mount /dev/sdb1 /mnt/usb
   cd /mnt/usb
   sudo mkdir /home/qb/copy
   sudo cp ./*.deb /home/qb/copy/
   cd /home/qb/copy
   sudo dpkg -i *.deb

   此步骤为后续编译安装 NVIDIA 驱动提供了必要的编译环境。

安装完成后，验证 gcc 与内核头文件是否就绪。

gcc --version
ls /usr/src/linux-headers-$(uname -r)

如果上述步骤没问题，那么说明目标服务器已经具备了完整的编译环境。

三、离线安装NVIDIA显卡驱动

Ubuntu 24.04 默认使用开源的 nouveau 驱动，该驱动不支持CUDA计算。必须将其禁用并安装官方闭源驱动。

3.1 禁用 Nouveau 驱动

1. 创建禁用配置文件：

   sudo bash -c "echo 'blacklist nouveau' > /etc/modprobe.d/blacklist-nouveau.conf"
   sudo bash -c "echo 'options nouveau modeset=0' >> /etc/modprobe.d/blacklist-nouveau.conf"

2. 更新内核镜像并重启：

   sudo update-initramfs -u
   sudo reboot

3. 重启后验证禁用状态（若无输出则表示禁用成功）：

   lsmod | grep nouveau

3.2 安装 Data Center Driver

英伟达驱动搜索网站：https://www.nvidia.cn/drivers/lookup/

选择最新CUDA版下载。准备好离线下载的驱动文件：NVIDIA-Linux-x86_64-590.480.01.run。注意一定要下载run后缀的文件。

1. 挂载硬盘 （假设U盘设备名为 /dev/sdb1）：

   sudo mount /dev/sdb1 /mnt/usb
   # 将驱动复制到本地目录
   cp /mnt/usb/drivers/NVIDIA-Linux-x86_64-590.480.01.run /home/qb/

   如果要卸载硬盘，可以使用命令：

   sudo umount /mnt/usb

2. 赋予执行权限并安装：

   sudo chmod +x NVIDIA-Linux-x86_64-590.480.01.run
   sudo ./NVIDIA-Linux-x86_64-590.480.01.run --no-x-check --no-nouveau-check --no-opengl-files

   安装过程中全部选择默认即可。

3. 验证驱动 ：

   安装完成后，执行以下命令检查GPU状态：

   nvidia-smi

   若正确显示4张Tesla T4显卡信息及驱动版本 580.105.08，则驱动安装成功。

---

四、离线安装 Docker 与 NVIDIA Container Toolkit

在内网离线环境中，无法使用 apt-get install 自动解决依赖。我们需要精准地从官方仓库下载对应的 .deb 安装包，并按照严格的顺序进行安装。

⚠️ 前置准备 ：

请在有互联网连接 的电脑上新建两个文件夹：docker_pkg 和 nvidia_pkg，用于分别存放下载的安装包。

4.1 离线安装 Docker Engine (Community)

Docker 是运行大模型容器的基础。对于 Ubuntu 24.04 (代号 Noble)，需要从 Docker 官方的 Linux 软件源中提取安装包。

1. 下载安装包（在互联网机器操作）

请访问 Docker 官方 Ubuntu 软件源仓库：
下载地址 ：https://download.docker.com/linux/ubuntu/dists/noble/pool/stable/amd64/

在该页面中，找到并下载以下 7 个 .deb 文件（版本号可能会更新，下载列表中的最新版即可）：

1. containerd.io
   • 示例文件名：containerd.io_2.2.1-1~ubuntu.24.04~noble_amd64.deb
2. docker-ce-cli
   • 示例文件名：docker-ce-cli_29.1.3-1~ubuntu.24.04~noble_amd64.deb
3. docker-ce
   • 示例文件名：docker-ce_29.1.3-1~ubuntu.24.04~noble_amd64.deb
4. docker-buildx-plugin
   • 示例文件名：docker-buildx-plugin_0.30.1-1~ubuntu.24.04~noble_amd64.deb
5. docker-model-plugin
   • 示例文件名：docker-model-plugin_1.0.6-1~ubuntu.24.04~noble_amd64.deb
6. docker-ce-rootless-extras
   • 示例文件名：docker-ce-rootless-extras_29.1.3-1~ubuntu.24.04~noble_amd64.deb
7. docker-compose-plugin
   • 示例文件名：docker-compose-plugin_5.0.0-1~ubuntu.24.04~noble_amd64.deb

注意 ：请务必确保文件名中包含 noble 字样（代表适配 Ubuntu 24.04）。下载后放入 docker_pkg 文件夹。

2. 传输与安装（在内网服务器操作）

将 docker_pkg 文件夹通过移动硬盘拷贝至服务器（假设路径为 /home/qb/docker_pkg）。

# 进入目录
cd /home/qb/docker_pkg

# 批量安装（dpkg 会自动尝试理顺同级目录下的依赖关系）
sudo dpkg -i *.deb

# 验证安装是否成功
sudo docker --version
# 输出示例: Docker version 29.1.3, build ...

4.2 离线安装 NVIDIA Container Toolkit

仅安装 Docker 是无法让容器调用 GPU 的。必须安装 NVIDIA Container Toolkit 才能实现 GPU 的"透传"。

1. 下载安装包（在互联网机器操作）

链接：https://mirror.cs.uchicago.edu/nvidia-docker/libnvidia-container/stable/

选择对应系统版本后下载文件（没有ubuntu24.04就下载最新的ubuntu20.04）

文件包括：

在该页面中，找到并下载以下 8个 .deb 文件（版本号可能会更新，下载列表中的最新版即可）：

1. libnvidia-container-dev
   • 示例文件名：libnvidia-container-dev_1.13.5-1_amd64.deb
2. libnvidia-container-tools
   • 示例文件名：libnvidia-container-tools_1.13.5-1_amd64.deb
3. libnvidia-container1-dbg
   • 示例文件名：libnvidia-container1-dbg_1.13.5-1_amd64.deb
4. libnvidia-container
   • 示例文件名：libnvidia-container1_1.13.5-1_amd64.deb
5. nvidia-container-runtime
   • 示例文件名：nvidia-container-runtime_3.13.0-1_all.deb
6. nvidia-container-toolkit-base
   • 示例文件名：nvidia-container-toolkit-base_1.13.5-1_amd64.deb
7. nvidia-container-toolkit
   • 示例文件名：nvidia-container-toolkit_1.13.5-1_amd64.deb
8. nvidia-docker2
   • 示例文件名：nvidia-docker2_2.13.0-1_all.deb

下载后放入 nvidia_pkg 文件夹。

2. 传输与安装（在内网服务器操作）

将 nvidia_pkg 文件夹拷贝至服务器。

# 进入目录
cd /home/qb/nvidia_pkg

# 批量安装
sudo dpkg -i *.deb

如果安装过程中报错提示"依赖缺失"，请检查是否遗漏了上述列表中的某一个包。通常 dpkg -i *.deb 能一次性解决这四个包的内部循环依赖。

3. 配置 Docker 运行时（关键步骤）

安装完成后，必须配置 Docker 守护进程以识别 NVIDIA 运行时。

# 1. 生成配置
sudo nvidia-ctk runtime configure --runtime=docker

# 2. 重启 Docker 服务以生效
sudo systemctl restart docker

4. 最终环境验证

此时，显卡驱动、Docker、NVIDIA Toolkit 均已就绪。我们可以进行一次联合测试（虽然还没有大模型镜像，但可以用 nvidia-smi 验证容器层）：

由于没有网络拉取 hello-world 镜像，我们可以简单检查 Docker 是否识别到了 NVIDIA Runtime：

# 查看 Docker 信息，寻找 Runtimes 字段
docker info | grep -i runtime

如果输出中包含 Runtimes: ... nvidia ...，则说明环境配置成功，可以进入下一步导入大模型镜像了。

---

五、离线模型权重准备

在内网环境部署大模型，最核心的资产即为模型权重文件。由于目标服务器无法连接互联网，必须利用一台具有公网访问权限的"摆渡机"完成模型的下载，并通过移动存储介质迁移至内网服务器。

5.1 模型下载（互联网端操作）

在具有互联网连接的机器上，需使用 modelscope 或 huggingface 的 CLI 工具下载完整的模型文件。鉴于 Qwen3-VL-8B-Thinking 模型包含大量的权重分片文件（.safetensors），务必确保下载的完整性。

执行以下命令下载模型至本地目录：

# 安装 modelscope（若尚未安装）
pip install modelscope

# 下载模型至当前目录下的 download_temp 文件夹
modelscope download --model Qwen/Qwen3-VL-8B-Thinking --local_dir ./download_temp/Qwen3-VL-8B-Thinking

下载完成后，建议核对文件总大小（约 15GB - 20GB）及文件数量，确保无缺失。

5.2 数据迁移与校验（内网端操作）

1. 数据传输 ：将 download_temp 文件夹打包并拷贝至移动硬盘，随后连接至内网服务器，挂载硬盘并将模型文件复制到服务器的高速存储路径下（建议使用 NVMe SSD 路径以提升加载速度）。

   假设目标路径为 /data/models：

   # 创建目录
   sudo mkdir -p /data/models
   
   # 复制文件（假设挂载点为 /mnt/usb）
   cp -r /mnt/usb/download_temp/Qwen3-VL-8B-Thinking /data/models/

2. 权限修正：确保当前用户或 Docker 容器有权限读取该目录：

   sudo chmod -R 755 /data/models/Qwen3-VL-8B-Thinking

---

六、构建离线 Docker 镜像

vLLM 框架依赖复杂的 Python 环境（如 torch, cuda, triton 等），在离线环境中手动解决依赖极其困难且易出错。最佳实践是采用 "镜像搬运" 策略：在互联网机器上拉取官方封装好的 Docker 镜像，导出为压缩包，再导入内网服务器。

6.1 拉取并导出镜像（互联网端操作）

vLLM 官方提供了集成好的 Docker 镜像。根据本项目的硬件环境（CUDA 12.x），选择适配的镜像版本。

1. 拉取镜像：

   # 拉取 vLLM 官方镜像（支持 OpenAI API 协议）  hub.rat.dev可以替换为其他源
   docker pull hub.rat.dev/vllm/vllm-openai:latest

2. 导出镜像 ：

   将镜像保存为 .tar 文件，以便传输。

   # 导出镜像至文件 vllm_image.tar
   docker save -o vllm_image.tar hub.rat.dev/vllm/vllm-openai:latest

   注：该镜像文件通常较大（约 15GB - 25GB），请确保存储空间充足。

6.2 导入镜像（内网端操作）

将 vllm_image.tar 通过移动介质传输至内网服务器的 /home/qb/copy 目录，执行导入操作：

# 加载镜像
sudo docker load -i /home/qb/vllm_image.tar

# 验证镜像是否加载成功
sudo docker images

若输出中包含 hub.rat.dev/vllm/vllm-openai 且 TAG 为 latest，则说明镜像导入成功。

---

七、容器化部署与服务启动

环境、模型、镜像三者就绪后，即可通过 Docker 启动推理服务。针对 4x Tesla T4 的硬件配置，需特别配置 张量并行（Tensor Parallelism） 参数，以聚合 4 张显卡的显存和算力。

7.1 启动脚本编写

为了便于管理和维护，建议创建一个启动脚本 start_vllm.sh。

nano start_vllm.sh

写入以下内容：

#!/bin/bash

# 定义模型在宿主机上的绝对路径
MODEL_HOST_PATH="/home/qb/copy/Qwen3-VL-8B-Thinking"
# 定义模型在容器内的挂载路径
MODEL_CONTAINER_PATH="/model"

# 启动容器
sudo docker run -d \
    --name qwen3-vl-server \
    --restart unless-stopped \
    --gpus all \
    --ipc=host \
    -p 8000:8000 \
    -v "$MODEL_HOST_PATH":"$MODEL_CONTAINER_PATH" \
    -e NCCL_P2P_DISABLE=1 \  # 针对T4卡的设置，如果是更高级的显卡，可以不用设置
    -e NCCL_IB_DISABLE=1 \   # 针对T4卡的设置，如果是更高级的显卡，可以不用设置
    hub.rat.devvllm/vllm-openai:latest \
    --model "$MODEL_CONTAINER_PATH" \
    --served-model-name Qwen3-VL-8B-Thinking \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.80 \  # 针对T4卡的设置，如果是更高级的显卡，可以设置为0.9
    --max-model-len 8192 \
    --dtype float16 \
    --trust-remote-code

关键参数解析：

• --gpus all：启用 NVIDIA Container Toolkit，将所有 GPU 透传给容器。
• --ipc=host：至关重要。vLLM 使用 NCCL 进行多卡通信，需共享主机内存，否则会导致通信失败或性能极低。
• -v ...：将宿主机的模型目录挂载到容器内部，避免在容器内重复下载。
• --tensor-parallel-size 4：设置张量并行度为 4。因 Tesla T4 单卡显存 16GB，虽然勉强能加载 8B 模型（FP16 约需 16GB），但为了保证推理时的 KV Cache 空间及处理高分辨率图像，必须利用多卡并行。此设置将模型切分到 4 张卡上运行。
• --dtype float16：Tesla T4 属于 Turing 架构，对 BF16 支持有限，推荐强制指定为 float16 以确保数值稳定性。
• --trust-remote-code：Qwen 系列模型通常包含自定义代码，需开启此选项。

7.2 服务启动与日志监控

1. 赋予脚本执行权限并运行：

   chmod +x start_vllm.sh
   ./start_vllm.sh

2. 查看启动日志：

   sudo docker logs -f qwen3-vl-server

   正常启动流程：

   1. 检测到 4 张 GPU。
   2. 开始加载模型权重（Loading safetensors...）。
   3. 初始化 NCCL 通信组。
   4. 进行 GPU 显存预分配（Profiling GPU memory...）。
   5. 最终输出：Uvicorn running on http://0.0.0.0:8000。

   若日志中未出现 Error，且显存占用（通过 nvidia-smi 查看）均匀分布在 4 张卡上，则说明服务启动成功。

7.3 本地回路测试

服务启动后，需要在内网环境验证其可用性。该服务提供了兼容 OpenAI API 格式的接口，极大地降低了对接难度。

首先在服务器本机进行测试，确认端口监听正常。

创建一个 Python 测试脚本 test_internal.py：

import requests
import json

# 定义接口地址
url = "http://localhost:8000/v1/chat/completions"

# 构造请求体（模拟 OpenAI 格式）
payload = {
    "model": "Qwen3-VL-8B-Thinking",
    "messages": [
        {
            "role": "user",
            "content": "introduce yourself in English"
        }
    ],
    "temperature": 0.7
}

headers = {"Content-Type": "application/json"}

try:
    response = requests.post(url, headers=headers, json=payload)
    if response.status_code == 200:
        print("--- response success ---")
        print(json.dumps(response.json(), indent=2, ensure_ascii=False))
    else:
        print(f"request failure, status：{response.status_code}")
        print(response.text)
except Exception as e:
    print(f"connect error：{e}")

执行脚本：

python3 test_internal.py

若能返回包含模型回答的 JSON 数据，证明模型推理功能正常。

八、生产环境网络配置

在完成模型服务部署与本地回路测试后，服务器即将接入内部业务网络。鉴于大模型推理服务（FastAPI 后端）需要通过固定的 API 地址访问算力服务器，且生产环境通常禁用 DHCP 自动分配 IP，必须在物理接入交换机前，为 GPU 服务器配置静态 IP 地址、子网掩码及网关。

Ubuntu Server 24.04 LTS 默认使用 Netplan 工具进行网络配置，配置文件遵循 YAML 语法格式。

8.1 识别物理网卡

首先需确认负责承载业务流量的物理网卡名称。在终端执行以下命令：

ip link show

输出示例与说明：

系统将列出所有网络接口（如 lo, eno1, enp3s0, docker0 等）。

• lo：回环接口，用于本机通信。
• docker0：Docker 虚拟网桥，无需处理。
• eno1 或 enp3s0 ：通常为物理网卡名称。需记录下用于连接内网网线的接口名称（本例假设为 eno1）。

8.2 备份原有配置

Netplan 配置文件位于 /etc/netplan/ 目录下。文件名通常为 50-cloud-init.yaml 或 00-installer-config.yaml。在修改前，务必对原文件进行备份，以便配置错误时恢复。

# 进入配置目录
cd /etc/netplan/

# 查看当前配置文件名
ls

# 执行备份（假设文件名为 00-installer-config.yaml）
sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak

8.3 编写静态 IP 配置文件

使用文本编辑器（如 nano 或 vim）修改配置文件。

sudo nano 00-installer-config.yaml

配置规范：

YAML 文件对缩进要求极严，严禁使用 Tab 键，必须使用空格（通常为 2 个或 4 个空格）进行层级缩进。

修改前（DHCP 模式示例）：

network:
  ethernets:
    eno1:
      dhcp4: true
  version: 2

修改后（静态 IP 模式示例）：

假设规划的网络参数如下：

• IP 地址 ：192.168.10.100
• 子网掩码 ：255.255.255.0（CIDR 写法为 /24）
• 网关 ：192.168.10.1
• DNS （可选，内网环境若无 DNS 可省略）：192.168.10.1

请将配置文件修改为如下内容：

network:
  version: 2
  ethernets:
    eno1:                       # 需替换为实际网卡名称
      dhcp4: false              # 关闭 DHCP
      addresses:
        - 192.168.10.100/24     # 静态 IP 及掩码
      routes:                   # Ubuntu 24.04 推荐使用 routes 替代 gateway4
        - to: default
          via: 192.168.10.1     # 网关地址
      nameservers:              # DNS 配置（可选）
        addresses: [192.168.10.1]

编辑完成后，按 Ctrl + O 保存，Ctrl + X 退出编辑器。

注意 ：Ubuntu 24.04 的 Netplan 版本已弃用 gateway4 字段，建议使用 routes 列表定义默认路由，以确保配置的兼容性。

8.4 应用配置与验证

配置文件修改完成后，需通过 Netplan 命令应用更改。

1. 应用配置：

   # 限制配置文件权限（安全建议）
   sudo chmod 600 /etc/netplan/00-installer-config.yaml
   
   # 应用配置
   sudo netplan apply

   若命令执行无报错，说明语法正确且配置已生效。若出现报错，需检查 YAML 缩进是否规范。

2. 验证 IP 地址 ：

   再次查看网络接口信息：

   ip addr show eno1

   确认输出中的 inet 字段已变更为设定的静态 IP（192.168.10.100/24）。

3. 验证路由表：

   ip route

   确认存在指向设定网关的 default via ... 记录。

至此，服务器网络配置已固化。此时可接入网线，并在同一局域网下的其他机器上通过 ping 192.168.10.100 测试连通性。连通后，即可在 FastAPI 后端服务的配置文件中，将大模型服务的地址永久指向该静态 IP。

8.5 启用SSH

入网以后，后续就可以通过远程SSH的方式登录服务器。但是，首先还是要在服务器端做一些检查和设置。

8.5.1 检查 SSH 服务是否正在运行

在物理终端登录后，执行以下命令查看 SSH 服务状态：

sudo systemctl status ssh

情况判定：

• 绿色 active (running)：服务正常。
• 白色 inactive (dead) ：服务未启动。
  • 解决 ：执行 sudo systemctl start ssh 启动服务，并执行 sudo systemctl enable ssh 设置开机自启。
• 提示 Unit ssh.service could not be found ：说明安装系统时（2.3节 第10步）未勾选 "Install OpenSSH server"。
  • 解决 ：你需要找到之前拷贝进来的 U 盘或离线包，安装 openssh-server 的 deb 包。

---

8.5.2 检查端口监听情况

确认 SSH 确实监听在 22 端口：

sudo ss -ltnp | grep sshd

预期输出：

应该能看到 LISTEN 0 128 0.0.0.0:22 或 [::]:22。

• 如果没有输出：说明 SSH 配置可能有误，或者被 Socket 激活机制接管（Ubuntu 新版特性）。
• 如果有输出：说明端口已打开，问题可能在防火墙。

---

8.5.3 检查并配置防火墙 (UFW)

Ubuntu 默认安装了 UFW，即使是内网环境，默认策略也可能拦截了入站连接。

1. 查看防火墙状态：

   sudo ufw status

2. 处理方案：

   • 如果显示 Status: inactive：防火墙已关闭，可以直接跳过此步（说明不是防火墙的问题）。

   • 如果显示 Status: active ：必须放行 SSH。

     # 放行 22 端口
     sudo ufw allow ssh
     # 或者指定端口
     sudo ufw allow 22/tcp
     
     # 重新加载规则
     sudo ufw reload

---

8.5.4 检查 SSH 配置文件

虽然默认配置通常可用，但为了保险起见，建议检查 /etc/ssh/sshd_config。

sudo nano /etc/ssh/sshd_config

重点检查以下几项（去掉行首的 # 注释）：

1. 端口 ：

   Port 22

2. 允许密码登录 （如果你还没配置密钥对，必须开启）：

   PasswordAuthentication yes

3. Root 登录限制 ：
   Ubuntu 默认禁止 Root 直接远程登录。

   • 如果你尝试用 root 连接，必然失败。
   • 必须使用安装系统时创建的普通用户（如 admin 或 qb）登录。
   • 如果确实需要 root 登录（不推荐），修改为 PermitRootLogin yes。

修改完成后，重启 SSH 服务：

sudo systemctl restart ssh

---

九、验证

在证件识别系统的后端服务器（FastAPI 应用所在机器）上，修改 llm_recognizer.py 中的配置，使其指向这台 GPU 推理服务器的 IP 地址。

假设 GPU 服务器内网 IP 为 192.168.10.100，修改 FastAPI 后端代码：

# llm_recognizer.py

client = OpenAI(
    api_key="empty",  # vLLM 本地部署默认不需要 Key，填写任意值即可
    base_url="http://192.168.10.100:8000/v1/"
)

随后触发一次证件版面识别请求，观察 GPU 服务器的 Docker 日志是否产生新的访问记录，以及 FastAPI 后端是否正确接收并解析了返回的 OCR 结果。

---

十、总结

本篇博客详细记录了在完全断网、硬件受限（Tesla T4） 的严苛环境下，部署 Qwen3-VL-8B-Thinking 多模态大模型的全过程。

通过 "磁盘清洗 -> 系统重装 -> 离线驱动/Docker安装 -> 镜像/模型摆渡 -> 容器化并行启动" 这一标准化作业流程，成功构建了一套安全、可控的内网 AI 推理基础设施。

1. 安全性：全流程无公网连接，物理隔离，彻底消除了数据外泄风险，符合高密级业务的安全合规要求。
2. 高性能：利用 Docker + NVIDIA Container Toolkit + vLLM 技术栈，结合 Tensor Parallelism 策略，充分榨干了 4 张 Tesla T4 的算力，实现了对 8B 参数多模态模型的流畅推理。
3. 标准化 ：对外暴露标准的 OpenAI API 接口，使得上层应用（FastAPI 后端）无需修改代码逻辑，仅需变更 base_url 即可在"云端 API"与"本地内网模型"之间无缝切换。

至此，全球证件智能识别系统不仅具备了强大的识别能力，更拥有了独立自主、安全可控的本地化智能引擎，为系统在政务专网、金融内网等封闭场景下的落地应用扫清了最后的障碍。

上述实践方案我完成了，但是我无法通过SSH访问，怎么确保我安装的这台服务器SSH开着呢？