PaddleX 3.0 是基于飞桨框架构建的低代码开发工具它集成了众多开箱即用的预训练模型可以实现模型从训练到推理的全流程开发支持国内外多款主流硬件助力AI 开发者进行产业实践。下面主要是官方文档源地址PaddleX 文档一、安装飞桨 PaddlePaddle官方文档开始使用_飞桨-源于产业实践的开源深度学习平台PaddlePaddle3.3安装cuda12.6python -m pip install paddlepaddle-gpu3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/二、PaddleX安装注意在安装 PaddleX 之前请确保您已具备基本的Python 运行环境注目前支持Python 3.8 至 Python 3.12。PaddleX 3.0-rc1 版本依赖的 PaddlePaddle 版本为3.0.0以上版本。1. 快速安装欢迎您使用飞桨低代码开发工具PaddleX在我们正式开始本地安装之前请首先明确您的开发需求并根据您的需求选择合适的安装模式。 PaddleX为您提供了两种安装模式Wheel包安装和插件安装下面分别对其应用场景进行介绍1.1 Wheel包安装模式若您使用PaddleX的应用场景为模型推理与集成那么推荐您使用更便捷、更轻量的Wheel包安装模式。快速安装轻量级的Wheel包之后您即可基于PaddleX支持的所有模型进行推理并能直接集成进您的项目中。您可直接执行如下指令快速安装PaddleX的Wheel包# 仅安装必须依赖可以在之后按需安装可选依赖pip install paddlex通过如下方式可以安装所需的可选依赖安装 PaddleX “基础功能”需要的全部依赖pip install paddlex[base]仅安装某项功能所需依赖pip install paddlex[ocr]1.2 插件安装模式若您使用PaddleX的应用场景为二次开发例如重新训练模型、微调模型、自定义模型结构、自定义推理代码等那么推荐您使用功能更加强大的插件安装模式。安装您需要的PaddleX插件之后您不仅同样能够对插件支持的模型进行推理与集成还可以对其进行模型训练等二次开发更高级的操作。PaddleX支持的模型训练相关插件如下请您根据开发需求确定所需的一个或多个插件名称插件和产线对应关系点击展开模型产线模块对应插件通用图像分类图像分类PaddleClas通用目标检测目标检测PaddleDetection通用语义分割语义分割PaddleSeg通用实例分割实例分割PaddleDetection通用OCR文档图像方向分类文本图像矫正文本检测文本行方向分类文本识别PaddleOCRPaddleClas通用表格识别版面区域检测表格结构识别文本检测文本识别PaddleOCRPaddleDetection文档场景信息抽取v3表格结构识别版面区域检测文本检测文本识别印章文本检测文本图像矫正文档图像方向分类PaddleOCRPaddleDetectionPaddleClas时序预测时序预测模块PaddleTS时序异常检测时序异常检测模块PaddleTS时序分类时序分类模块PaddleTS通用多标签分类图像多标签分类PaddleClas小目标检测小目标检测PaddleDetection图像异常检测无监督异常检测PaddleSeg若您需要安装的插件为PaddleXXX可以直接执行如下指令快速安装PaddleX的对应插件git clone https://github.com/PaddlePaddle/PaddleX.git cd PaddleX pip install -e . paddlex --install PaddleXXX # 例如PaddleOCR❗ 注采用这种安装方式后是可编辑模式安装当前项目的代码更改都会直接作用到已经安装的 PaddleX Wheel 包。如果上述安装方式可以安装成功则可以跳过接下来的步骤。若您使用Linux操作系统请参考2. Linux安装PaddleX详细教程。其他操作系统的安装方式敬请期待。2.2 Linux自定义方式安装PaddleX2.2.1 获取 PaddleX 源码接下来请使用以下命令从 GitHub 获取 PaddleX 最新源码git clone https://github.com/PaddlePaddle/PaddleX.git如果访问 GitHub 网速较慢可以从 Gitee 下载命令如下git clone https://gitee.com/paddlepaddle/PaddleX.git2.2.2 安装PaddleX获取 PaddleX 最新源码之后您可以选择Wheel包安装模式或插件安装模式。若您选择Wheel包安装模式请执行以下命令cd PaddleX # 安装 PaddleX whl # -e以可编辑模式安装当前项目的代码更改都会直接作用到已经安装的 PaddleX Wheel pip install -e .[base]若您选择插件安装模式并且您需要的插件名称为 PaddleXXX可以有多个请执行以下命令cd PaddleX # 安装 PaddleX whl # -e以可编辑模式安装当前项目的代码更改都会直接作用到已经安装的 PaddleX Wheel pip install -e .[base] # 安装 PaddleX 插件 paddlex --install PaddleXXX例如您需要安装PaddleOCR、PaddleClas插件则需要执行如下命令安装插件# 安装 PaddleOCR、PaddleClas 插件 paddlex --install PaddleOCR PaddleClas若您需要安装全部插件则无需填写具体插件名称只需执行如下命令# 安装 PaddleX 全部插件 paddlex --install插件的默认克隆源为 github.com同时也支持 gitee.com 克隆源您可以通过--platform指定克隆源。例如您需要使用 gitee.com 克隆源安装全部PaddleX插件只需执行如下命令# 安装 PaddleX 插件 paddlex --install --platform gitee.com安装完成后将会有如下提示All packages are installed.更多硬件环境的PaddleX安装请参考PaddleX多硬件使用指南2.3 选择性安装依赖PaddleX 的功能丰富而不同的功能需要的依赖也不尽相同。将 PaddleX 中不需要安装插件即可使用的功能归类为“基础功能”。PaddleX 官方 Docker 镜像预置了基础功能所需的全部依赖使用上文介绍的pip install ...[base]的安装方式也将安装基础功能需要的所有依赖。如果您只专注于 PaddleX 的某一项功能且希望保持安装的依赖的体积尽可能小可以通过指定“依赖组”的方式选择性地安装依赖# 以仅安装 OCR 类基础功能为例 # 安装预编译的 wheel 包 pip install paddlex[ocr] # 从源码安装 pip install -e .[ocr] # 也可以同时指定多个依赖组 pip install -e .[ocr,cv]PaddleX 目前提供如下依赖组依赖组名称对应的功能basePaddleX 的所有基础功能。cvCV 产线的基础功能。multimodal多模态产线的基础功能。ie信息抽取产线的基础功能。ocrOCR 类产线的基础功能。speech语音产线的基础功能。ts时序产线的基础功能。video视频产线的基础功能。trans翻译产线的基础功能。genai-client生成式 AI 客户端功能。安装此依赖组等效于安装 PaddleX 生成式 AI 客户端插件也可以通过 PaddleX CLI 安装生成式 AI 客户端插件。genai-sglang-serverSGLang 服务器功能。安装此依赖组等效于安装 PaddleX SGLang 服务器插件也可以通过 PaddleX CLI 安装SGLang 服务器插件。genai-vllm-servervLLM 服务器功能。安装此依赖组等效于安装 PaddleX vLLM 服务器插件也可以通过 PaddleX CLI 安装 vLLM 服务器插件。serving服务化部署功能。安装此依赖组等效于安装 PaddleX 服务化部署插件也可以通过 PaddleX CLI 安装服务化部署插件。paddle2onnxPaddle2ONNX 功能。安装此依赖组等效于安装 PaddleX Paddle2ONNX 插件也可以通过 PaddleX CLI 安装 Paddle2ONNX 插件。每一条产线属于且仅属于一个依赖组在各产线的使用文档中可以了解产线属于哪一依赖组。对于单功能模块安装任意包含该模块的产线对应的依赖组后即可使用相关的基础功能。2.4 PaddleX 对飞桨框架的依赖PaddleX 的绝大部分功能依赖飞桨框架因此在大多数情况下您需要在使用 PaddleX 前参考 飞桨PaddlePaddle本地安装教程 安装飞桨框架。不过对于以下几种情形不必安装飞桨框架也可以使用相应的功能使用 PaddleXgenai-vllm-server或genai-sglang-server插件提供的能力部署模型推理服务。使用 PaddleXgenai-client插件调用生成式 AI 推理服务。三、报错3.1、git版本报错error: subprocess-exited-with-error× Getting requirements to build editable did not run successfully.│ exit code: 1......LookupError: setuptools-scm was unable to detect version for /mnt/.../PaddleX-release-3.5下载的 PaddleX 是 GitHub 压缩包没有 .git 目录导致 setuptools_scm 无法自动读取版本号安装失败。方案 1手动指定版本号直接在安装命令前加一个环境变量告诉它版本号SETUPTOOLS_SCM_PRETEND_VERSION3.5.0 pip install -e .这是最快、最稳的解决办法不需要改文件。cmdWindows 终端SET SETUPTOOLS_SCM_PRETEND_VERSION3.5.0 pip install -e .PowerShellWindows 终端$env:SETUPTOOLS_SCM_PRETEND_VERSION3.5.0 pip install -e .方案 2降级 setuptools新版本 setuptools_scm 校验太严格降级即可pip install setuptools69.0.3 wheel0.42.0 pip install -e .方案 3用 git clone 下载源码你现在的目录没有.git所以报错重新克隆# 先退出当前目录 cd .. # 克隆完整带git的源码 git clone https://github.com/PaddlePaddle/PaddleX.git -b release/3.5 # 进入目录安装 cd PaddleX pip install -e .3.2、目录缺失FileNotFoundError: [Errno 2] No such file or directory: /xxx/lib/python3.12/site-packages/paddlex/repo_manager/repos问题## 问题分析这个错误是因为 repo_parent_dir 目录不存在导致的。错误堆栈分析1. 在 repo.py:430 RepositoryGroupGetter.get() 方法中当 forceTrue 时调用了 self.remove()2. remove() 方法遍历所有 repos 并调用每个 repo 的 remove() 方法3. 在 repo.py:190 的 Repository.remove() 方法中def remove(self):removewith switch_working_dir(self.repo_parent_dir):remove_repo_using_rm(self.name)4. switch_working_dir 函数在 utils.py:144 尝试 os.chdir(new_wd) 但 new_wd 即 repo_parent_dir 不存在所以抛出 FileNotFoundError根本原因repo_parent_dir 指向的是 /conda环境/lib/python3.12/site-packages/paddlex/repo_manager/repos 但这个目录不存在。可能的情况1. 这是第一次安装repos 目录还没有被创建通常由 download() 方法创建2. 之前的安装/下载过程中断导致目录没有正确创建3. 目录被手动删除或清理了## 解决方案你需要手动创建这个目录或者修改代码使其在目录不存在时自动创建。download() 方法会在 repo.py:182 使用 os.makedirs(self.repo_parent_dir, exist_okTrue) 创建目录但 remove() 方法没有检查目录是否存在。## 快速修复方法### 方法 手动创建目录最快在终端执行mkdir -p conda环境路径/lib/python3.12/ site-packages/paddlex/repo_manager/ repos3.3、CUDA环境问题错误信息ValueError: Not found CUDA runtime, please use export CUDA_HOMEXXX to specific it.表明1. 你的系统上没有安装 CUDA2. 物理机CUDA 已安装但conda环境找不到变量 CUDA_HOME3. conda环境中没cuda-toolkit解决conda安装cudatoolkit和cudnnconda install -c nvidia cuda-toolkit12.6 cudnn设置让 conda 环境内的 CUDA 优先于系统安装cudatoolkit后nvcc、cudnn.h、libcudart.so等都已存在于$CONDA_PREFIX中。接下来需要确保编译脚本找到的是它们而非系统/usr/local/cuda。1. 清理之前手动设置的环境变量打开终端先删除可能存在的旧设置仅当前会话unset CPLUS_INCLUDE_PATH unset C_INCLUDE_PATH unset LD_LIBRARY_PATH如果你把它们写入了激活脚本也请编辑删除rm -f $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh # 如果有的话2. 让 conda 环境自动设置正确的路径conda 在激活环境时会自动将$CONDA_PREFIX/bin加入PATH最前面这样nvcc就会优先使用 conda 内的版本。但头文件和库文件的搜索路径需要额外处理好在 conda 的cudatoolkit包通常会自动设置以下环境变量通过etc/conda/activate.d/脚本你可以检查是否存在ls $CONDA_PREFIX/etc/conda/activate.d/如果有类似cudatoolkit.sh的文件那它已经帮你设好了CPATH、LIBRARY_PATH、LD_LIBRARY_PATH等。如果没有有时旧版包不包含你可以手动创建激活脚本# 创建激活脚本目录 mkdir -p $CONDA_PREFIX/etc/conda/activate.d # 写入激活脚本关键将 pip 安装的 cuDNN 库路径放在 LD_LIBRARY_PATH 最前面 cat EOF $CONDA_PREFIX/etc/conda/activate.d/cuda_env.sh #!/bin/sh # 编译时头文件路径来自 conda 安装的 cudnn 开发包 export CFLAGS-I${CONDA_PREFIX}/include $CFLAGS export CPPFLAGS-I${CONDA_PREFIX}/include $CPPFLAGS export C_INCLUDE_PATH${CONDA_PREFIX}/include:${C_INCLUDE_PATH} export CPLUS_INCLUDE_PATH${CONDA_PREFIX}/include:${CPLUS_INCLUDE_PATH} # 链接时库路径用于编译 export LIBRARY_PATH${CONDA_PREFIX}/lib:${CONDA_PREFIX}/lib/stubs:${LIBRARY_PATH} # 运行时库路径优先使用 pip 安装的 cuDNN 9.5.1与 Paddle 匹配再使用 conda 的 lib export LD_LIBRARY_PATH${CONDA_PREFIX}/lib/python3.12/site-packages/nvidia/cudnn/lib:${CONDA_PREFIX}/lib:${CONDA_PREFIX}/lib/stubs:${LD_LIBRARY_PATH} export CUDA_HOME${CONDA_PREFIX} EOF同时创建停用脚本清理这些变量以免影响其他环境mkdir -p $CONDA_PREFIX/etc/conda/deactivate.d cat EOF $CONDA_PREFIX/etc/conda/deactivate.d/cuda_env.sh #!/bin/sh unset CFLAGS unset CPPFLAGS unset C_INCLUDE_PATH unset CPLUS_INCLUDE_PATH unset LIBRARY_PATH unset LD_LIBRARY_PATH unset CUDA_HOME EOF注意LIBRARY_PATH和LD_LIBRARY_PATH中的lib/stubs是为了解决某些库的 stub 链接问题没有可去掉。3. 重新激活环境使配置生效conda deactivate conda activate paddle_gpu # 换成你的环境名4. 验证确认所有 CUDA 工具都来自 condawhich nvcc # 应显示 $CONDA_PREFIX/bin/nvcc nvcc --version # 应显示对应的 CUDA 版本 echo $CUDA_HOME # 应等于 $CONDA_PREFIX find $CONDA_PREFIX/include -name cudnn.h # 应有输出 find $CONDA_PREFIX/lib -name libcudart* # 应有输出如果which nvcc仍是/usr/local/cuda/bin/nvcc说明PATH中系统路径优先级更高可以手动调整export PATH$CONDA_PREFIX/bin:$PATH上面的激活脚本并没有修改PATH因为 conda 默认管理PATH但若你的系统配置干扰可临时这样处理重新运行编译以 PaddleDetection 自定义算子为例现在环境已经自包含直接执行原来的编译命令即可# 确保在正确的 conda 环境内 conda activate paddle_gpu # 进入你要编译的项目目录或者运行 paddlex 安装命令 paddlex ... # 你的原始命令编译过程中观察是否还出现cudnn.h: 没有那个文件或目录之类的错误。若一切正常所有.cu文件会顺利通过。库版本不匹配ModuleNotFoundError: No module named pkg_resources因为setuptools版本过高≥82移除了pkg_resources模块。执行以下命令即可修复pip install setuptools82之后重新运行训练命令。如果还有其他缺失如visualdl也一并补上pip install visualdlopencv-python版本要求4.6.0paddledet 0.0.0 requires opencv-python4.6.0, which is not installed. paddle3d 0.0.0 requires opencv-python4.6.0.66, which is not installed. paddle3d 0.0.0 requires opencv-python-headless4.6.0.66, which is not installed.第一步彻底清理 OpenCV执行以下命令卸载所有可能与 OpenCV 冲突的包为干净的安装扫清障碍。pip uninstall opencv-python opencv-contrib-python opencv-python-headless -y第二步安装正确的 OpenCV 版本清理后我推荐你先尝试安装对 PaddleX 整体兼容性较好的opencv-python 4.5.5.64。pip install opencv-python4.5.5.64如果这个版本仍然报cv2.dnn.DictValue错误说明依赖间的冲突仍然存在。这时可以改用paddle3d所需的4.6.0.66版本。但在重新安装前务必再次执行第1步中的清理命令。pip install opencv-python4.6.0.66第三步重启内核并验证安装完成后请完全关闭并重启你的 Python 终端或 Jupyter Kernel。这是确保新配置生效的关键一步。重启后你可以在 Python 环境中运行以下代码来验证import cv2 print(cv2.__version__) # 检查有问题的属性是否存在 from cv2.dnn import DictValue print(OpenCV 导入成功DictValue 属性正常)如果看到打印出的 OpenCV 版本和 “导入成功” 的信息就说明修复成功了可以重新开始训练。TypeError: only 0-dimensional arrays can be converted to Python scalars这个错误是 PaddleOCR 代码中的一个 bug与 NumPy 版本无关即使在旧版 NumPy 中也会出现。np.random.choice(axis, size1)返回的是一个形状为(1,)的一维数组而int()无法直接转换数组需要取出第一个元素。步骤 1打开文件vim PaddleX-release-3.5/paddlex/repo_manager/repos/PaddleOCR/ppocr/data/imaug/random_crop_data.py或使用你喜欢的编辑器。步骤 2找到第 73 行附近该行内容应该是xx int(np.random.choice(axis, size1))步骤 3修改为以下两种方式之一推荐第一种方式一更简洁xx np.random.choice(axis) # 直接返回标量不需要 int()方式二保留 int 转换xx int(np.random.choice(axis, size1)[0])常见问题排查找不到cudnn.h确认cudnn已安装conda list cudnn检查$CONDA_PREFIX/include下有cudnn.h链接错误 / 找不到-lcudart确认libcudart.so在$CONDA_PREFIX/lib中检查LIBRARY_PATH和LD_LIBRARY_PATH是否包含该路径编译时仍调用系统 nvcc运行which nvcc确认如果不对临时export PATH$CONDA_PREFIX/bin:$PATH运行时找不到动态库添加$CONDA_PREFIX/lib到LD_LIBRARY_PATH激活脚本已做