Surya项目离线部署方案详解

背景说明

在实际生产环境中，我们经常会遇到需要在无互联网访问权限的服务器上部署AI模型的需求。Surya作为一款基于HuggingFace生态的OCR工具，其标准安装流程需要在线下载模型文件。本文将详细介绍如何实现Surya在CentOS等Linux系统上的离线部署方案。

核心原理

Surya依赖的模型文件默认会缓存在用户目录的.cache/datalab/文件夹中。通过预先获取这些模型文件并设置环境变量，可以实现离线环境下的正常运行。

详细部署步骤

1. 环境准备阶段

• 操作系统：CentOS 7.9（其他Linux发行版也可参考）
• Python版本：3.10+
• 需要约5GB的磁盘空间用于模型缓存

2. 在线环境准备工作

在有网络连接的环境中执行：

# 安装surya
pip install surya-ocr

# 首次运行触发模型下载
python -c "from surya.model.recognition import load_model; load_model()"
python -c "from surya.model.detection import load_model; load_model()"

3. 模型文件收集

模型下载完成后，定位缓存目录：

ls ~/.cache/datalab/

该目录下会包含多个模型文件，需要完整保留这些文件。

4. 离线环境部署

将收集的模型文件复制到目标服务器的相同路径下：

# 确保目录结构一致
mkdir -p ~/.cache/datalab/
# 复制所有模型文件到此目录

5. 环境变量配置

在离线服务器上设置关键环境变量：

export HF_HUB_OFFLINE=1

这个设置会强制Surya使用本地缓存而不会尝试连接网络。

6. 验证部署

在离线环境中运行测试命令：

from surya.model.recognition import load_model
from surya.model.detection import load_model

# 应该能正常加载模型而不报网络错误
rec_model = load_model()
det_model = load_model()

注意事项

1. 模型版本兼容性：确保离线环境与在线环境使用的Surya版本一致
2. 存储空间：完整模型文件需要约3-4GB空间
3. 权限问题：在容器化部署时需要注意缓存目录的挂载
4. 后续更新：如需更新模型，需要重新在有网络环境下载后同步

高级技巧

对于需要长期维护的离线环境，建议：

1. 将模型文件打包成RPM/DEB等系统安装包
2. 建立内部版本控制系统管理模型文件
3. 编写自动化部署脚本处理环境变量设置

通过以上方法，可以确保Surya在严格隔离的网络环境中稳定运行，同时便于后续的维护和更新。