PaddleHub 安装指南：环境依赖、pip 安装与网络/离线使用说明

PaddleHub 安装指南：环境依赖、pip 安装与网络/离线使用说明

【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers

本篇指南基于 PaddleFormers 仓库中的 安装文档，系统讲解 PaddleHub 的完整安装流程：从操作系统、Python 与 PaddlePaddle 的版本依赖，到 GPU/CPU 两个版本的飞桨框架安装、PaddleHub 包安装，再到安装后的网络连接校验与离线使用配置。读完本文，你将能够独立完成 PaddleHub 环境的搭建，并理解安装过程中的版本校验、依赖安装与目录结构等底层机制。

环境依赖

PaddleHub 的运行依赖三个层面的环境条件，缺一不可：

依赖项	版本要求
操作系统	Windows / macOS / Linux
Python	>= 3.6.2
PaddlePaddle	>= 2.0.0

其中PaddlePaddle 版本要求是硬性约束。查看仓库 paddlehub/init.py 可以看到，包导入时即执行版本校验：

_paddle_version = Version(paddle.__version__) if _paddle_version < Version('2.0.0') and _paddle_version != Version('0.0.0'): raise RuntimeError( 'Version mismatch in PaddleHub and PaddlePaddle, you need to upgrade PaddlePaddle to version 2.0.0 or above.')

也就是说，如果本机安装的 PaddlePaddle 低于 2.0.0（开发版0.0.0除外），导入paddlehub会直接抛出RuntimeError并提示升级，而不是等到运行时才暴露问题。

第 1 步：安装 PaddlePaddle

PaddleHub 建立在 PaddlePaddle 深度学习框架之上，因此必须先安装飞桨框架。根据是否有 GPU 环境，二选一执行：

# 安装 GPU 版本的 PaddlePaddle pip install paddlepaddle-gpu -U # 或者安装 CPU 版本的 PaddlePaddle # pip install paddlepaddle -U

• -U参数表示升级到最新版本，确保满足>= 2.0.0的版本约束；
• GPU 版本还需注意本机 CUDA / cuDNN 与飞桨版本的匹配关系，具体安装方式以官方安装文档为准；
• 若需在特定环境中安装（如 Conda 虚拟环境），务必先激活目标环境再执行上述命令。

第 2 步：安装 PaddleHub

飞桨框架就绪后，通过 pip 安装 PaddleHub：

pip install paddlehub==2.1.0

依赖包自动安装

安装 PaddleHub 时会自动拉取其声明的全部依赖。从 requirements.txt 可以看到主要依赖包括：paddlenlp >= 2.0.0（NLP 预训练模型支撑）、paddle2onnx（模型导出）、visualdl（可视化训练）、flask与pyzmq（模型服务部署）、gradio（Web Demo）、opencv-python、Pillow（图像处理）、numpy、pyyaml、tqdm等。其中gunicorn带平台条件sys_platform != "win32"，即仅在非 Windows 系统安装。

安装完成后，pip 会在 setup.py 声明的entry_points作用下注册hub命令行工具（对应paddlehub.commands.utils:execute），后续可以直接使用hub install、hub run等子命令管理模型模块。

加速安装（可选）

若默认 PyPI 源下载缓慢，可以参考仓库 linux_quickstart.md 中的做法，使用百度镜像源加速：

pip install paddlehub -i https://mirror.baidu.com/pypi/simple

注意：paddlehub==2.1.0为文档标注的稳定版本号；当前仓库源码中paddlehub/__init__.py的__version__ = 'develop'表示仓库处于开发迭代状态，直接通过源码运行与固定版本安装存在差异，生产使用建议按固定版本安装。

第 3 步：验证安装与网络连通性

安装完成后可执行hub help查看命令行是否可用（命令入口定义见 paddlehub/commands/utils.py）。

PaddleHub 的预训练模型和预置数据集需要从服务端下载，因此安装机器的网络连通性是模型可用的前提。文档提供了 Python 接口校验方式：

import paddlehub paddlehub.server_check() # 如果可以连接远端 PaddleHub-Server，则显示 Request Hub-Server successfully。 # 如果无法连接远端 PaddleHub-Server，则显示 Request Hub-Server unsuccessfully。

该方法在 paddlehub/server/init.py 中实现：通过module_server获取默认服务源（default_hub_server）并调用is_connected()探测连通性，实际请求逻辑在 paddlehub/server/server_source.py 中——向服务端发送一次search请求，返回 HTTP 200 即视为连通。

默认服务地址配置在 paddlehub/config.py 中：http://paddlepaddle.org.cn/paddlehub。该地址可通过hub config命令或修改配置文件更换，详见 config.py。

离线使用与数据目录

文档同时说明：如果本地已存在相关的数据集和预训练模型，则可以离线运行 PaddleHub。首次在线运行时会自动下载模型与数据集，并缓存到本地目录，之后即可脱离网络使用。

数据落地位置由环境变量HUB_HOME控制。从 paddlehub/env.py 可以看到其目录结构设计：

• 未设置HUB_HOME时，默认路径为~/.paddlehub；
• 各子目录职责如下：

子目录	用途
modules	存放已安装的 PaddleHub Module
cache	缓存数据
dataset	自动下载的数据集
conf	默认配置文件（如config.yaml）
thirdparty	第三方库
tmp	运行期间产生的临时文件（一般会自动清理）
sources	已安装的代码源
log	运行日志（按日存储）

若需将缓存目录迁移到指定磁盘或自定义位置，可在安装前设置：

export HUB_HOME=/your/custom/path

（Windows 下使用set HUB_HOME=...。）

常见问题与注意事项

1. 导入时报版本不匹配：报错Version mismatch in PaddleHub and PaddlePaddle，说明 PaddlePaddle 低于 2.0.0，需先升级飞桨框架（见上文版本校验源码 paddlehub/init.py）。
2. server_check()返回 unsuccessfully：说明本机无法访问默认模型服务端，常见原因是网络限制或代理设置。此时需确保可访问外网；若已有本地缓存的模型与数据集，则不影响离线使用。
3. 模型安装时提示环境不匹配：hub install在安装模块时会校验 PaddlePaddle / PaddleHub 版本与模块的兼容区间（逻辑见 paddlehub/server/server_source.py），可加--ignore_env_mismatch参数跳过校验（见 paddlehub/commands/install.py），但可能带来运行期异常，仅在确有必要时使用。
4. Windows 中文路径警告：当HUB_HOME或主目录包含中文字符时，部分模块可能执行异常，源码 paddlehub/init.py 会打印警告，建议通过set HUB_HOME指定纯英文路径。

小结

完整的安装链路可归纳为三步：安装满足版本要求的 PaddlePaddle → 通过pip install paddlehub==2.1.0安装 PaddleHub → 执行server_check()校验模型服务连通性。PaddleHub 对 PaddlePaddle 版本有强校验（>= 2.0.0），模型与数据首次使用需联网下载并缓存至HUB_HOME目录，本地已有资源时则完全支持离线运行。

【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers