From 2541462f7e2afb73c4141e0db647273b00b46071 Mon Sep 17 00:00:00 2001 From: gongweibao Date: Thu, 26 Feb 2026 16:17:41 +0800 Subject: [PATCH] [Feature][Docs] Add Python-only quick install mode (BUILD_WHEEL=2) to build.sh (#6503) * add pythononly func * add * add more feature * add safe check * add rsync check * add * add * refine docs * add installation * add installation --- build.sh | 135 +++++++++++++++++- .../get_started/installation/kunlunxin_xpu.md | 38 +++++ docs/get_started/installation/nvidia_gpu.md | 38 +++++ .../get_started/installation/kunlunxin_xpu.md | 34 +++++ .../zh/get_started/installation/nvidia_gpu.md | 34 +++++ 5 files changed, 278 insertions(+), 1 deletion(-) diff --git a/build.sh b/build.sh index dd404974b9..647a24fa66 100644 --- a/build.sh +++ b/build.sh @@ -14,6 +14,32 @@ # See the License for the specific language governing permissions and # limitations under the License. +function show_help() { + echo "Usage: bash build.sh [BUILD_WHEEL] [PYTHON] [FD_CPU_USE_BF16] [FD_BUILDING_ARCS] [FD_USE_PRECOMPILED] [FD_COMMIT_ID]" + echo "" + echo "BUILD_WHEEL modes:" + echo " 0 Build custom ops only (no wheel packaging or pip install)" + echo " 1 Full build: compile C++ ops + build wheel + pip install (default)" + echo " 2 Python-only: sync .py files to site-packages (skip C++ compilation)" + echo "" + echo "Arguments:" + echo " PYTHON Python executable (default: python)" + echo " FD_CPU_USE_BF16 Enable CPU BF16 ops: true/false (default: false)" + echo " FD_BUILDING_ARCS Target CUDA architectures, e.g. \"[80, 90, 100]\"" + echo " FD_USE_PRECOMPILED Use precompiled ops: 0=source, 1=precompiled (default: 0)" + echo " FD_COMMIT_ID Commit ID for precompiled wheel lookup" + echo "" + echo "Examples:" + echo " bash build.sh 1 python false \"[90]\" # Full build for SM90" + echo " bash build.sh 2 python # Python-only quick install" + echo " bash build.sh 0 python false \"[80,90]\" # Build ops only" + exit 0 +} + +if [ "${1}" = "-h" ] || [ "${1}" = "--help" ]; then + show_help +fi + BUILD_WHEEL=${1:-1} PYTHON_VERSION=${2:-"python"} export python=$PYTHON_VERSION @@ -341,6 +367,111 @@ function build_and_install() { echo -e "${BLUE}[build]${NONE} ${GREEN}build fastdeploy wheel success${NONE}\n" } +function find_install_dir() { + INSTALL_DIR=$(${python} -c " +import sys, os, importlib.util +# Remove cwd and project root from sys.path to avoid finding local source +project_root = os.path.abspath('.') +sys.path = [p for p in sys.path if os.path.abspath(p) != project_root and p != ''] +spec = importlib.util.find_spec('fastdeploy') +if spec and spec.submodule_search_locations: + print(os.path.dirname(spec.submodule_search_locations[0])) +" 2>/dev/null) + + if [ -z "$INSTALL_DIR" ] || [ ! -d "${INSTALL_DIR}/fastdeploy" ]; then + echo -e "${RED}[FAIL]${NONE} fastdeploy is not installed. Please run a full build first (BUILD_WHEEL=1)." + exit 1 + fi + echo -e "${BLUE}[python-only]${NONE} Detected install directory: ${GREEN}${INSTALL_DIR}/fastdeploy/${NONE}" +} + +function check_same_directory() { + SRC_REAL=$(cd fastdeploy && pwd -P) + if [ -d "${INSTALL_DIR}/fastdeploy" ]; then + DST_REAL=$(cd ${INSTALL_DIR}/fastdeploy && pwd -P) + if [ "$SRC_REAL" = "$DST_REAL" ]; then + echo -e "${GREEN}[SKIP]${NONE} Source and target are the same directory: ${SRC_REAL}" + echo -e "${GREEN}[SKIP]${NONE} No sync needed (you may be using an editable install or running from site-packages)." + return 1 + fi + fi + return 0 +} + +function sync_python_files() { + # --exclude='__pycache__/' must come before --include='*/' so rsync ignores __pycache__ entirely + # --filter protects all non-.py files (.so, .txt, etc.) from being deleted + RSYNC_OUTPUT=$(rsync -avc --exclude='__pycache__/' --include='*/' --include='*.py' --filter='P *.so' --filter='P *.txt' --filter='P *.sh' --filter='P *.h' --filter='P *.hpp' --exclude='*' --delete fastdeploy/ ${INSTALL_DIR}/fastdeploy/ 2>&1) + RSYNC_EXIT=$? + + if [ $RSYNC_EXIT -ne 0 ]; then + echo "$RSYNC_OUTPUT" + echo -e "${RED}[FAIL]${NONE} rsync failed" + exit 1 + fi + + CHANGED_FILES=$(echo "$RSYNC_OUTPUT" | grep '\.py$' || true) + DELETED_FILES=$(echo "$RSYNC_OUTPUT" | grep '^deleting .*\.py$' || true) +} + +function verify_package_mapping() { + PKG_NAME=$(${python} -c " +import importlib.metadata +dist = importlib.metadata.packages_distributions()['fastdeploy'][0] +print(dist) +" 2>/dev/null) || true + + if [ -n "$PKG_NAME" ]; then + OUTSIDE_FILES=$(${python} -m pip show -f ${PKG_NAME} 2>/dev/null \ + | awk '/^Files:/{found=1; next} found && /\.py$/' \ + | grep -v '^\.\.\/' | grep -v '^ fastdeploy/' | grep -v '^ __pycache__' || true) + if [ -n "$OUTSIDE_FILES" ]; then + echo -e "${YELLOW}[WARNING]${NONE} Detected .py files installed outside fastdeploy/ directory:" + echo "$OUTSIDE_FILES" + echo -e "${YELLOW}[WARNING]${NONE} setup.py package mapping may have changed. Please run a full build (BUILD_WHEEL=1) instead." + exit 1 + fi + fi +} + +function print_sync_summary() { + PY_COUNT=$(find fastdeploy/ -name '*.py' | wc -l) + + echo "" + echo -e "${BLUE}======== Sync Summary ========${NONE}" + if [ -n "$CHANGED_FILES" ]; then + CHANGED_COUNT=$(echo "$CHANGED_FILES" | wc -l) + echo -e "${GREEN}[UPDATED]${NONE} ${CHANGED_COUNT} file(s) synced:" + echo "$CHANGED_FILES" | sed 's/^/ /' + fi + if [ -n "$DELETED_FILES" ]; then + DEL_COUNT=$(echo "$DELETED_FILES" | wc -l) + echo -e "${YELLOW}[DELETED]${NONE} ${DEL_COUNT} file(s) removed from site-packages:" + echo "$DELETED_FILES" | sed 's/^deleting / /' + fi + if [ -z "$CHANGED_FILES" ] && [ -z "$DELETED_FILES" ]; then + echo -e "${GREEN}[NO CHANGE]${NONE} All ${PY_COUNT} Python files are already up-to-date." + else + echo -e "${BLUE}[TOTAL]${NONE} ${PY_COUNT} Python files tracked, target: ${INSTALL_DIR}/fastdeploy/" + fi + echo -e "${BLUE}==============================${NONE}" +} + +function install_python_only() { + if ! command -v rsync &>/dev/null; then + echo -e "${RED}[FAIL]${NONE} 'rsync' is not installed. Please install it first (e.g. apt-get install rsync / yum install rsync)." + exit 1 + fi + + echo -e "${BLUE}[python-only]${NONE} Syncing Python files to installed site-packages..." + + find_install_dir + check_same_directory || return 0 + sync_python_files + verify_package_mapping + print_sync_summary +} + function version_info() { output_file="fastdeploy/version.txt" fastdeploy_git_commit_id=$(git rev-parse HEAD) @@ -452,10 +583,12 @@ if [ "$BUILD_WHEEL" -eq 1 ]; then echo -e "${GREEN}wheel install success${NONE}\n" trap : 0 -else +elif [ "$BUILD_WHEEL" -eq 0 ]; then init build_custom_ops version_info rm -rf $BUILD_DIR $EGG_DIR rm -rf $OPS_SRC_DIR/$BUILD_DIR $OPS_SRC_DIR/$EGG_DIR +elif [ "$BUILD_WHEEL" -eq 2 ]; then + install_python_only fi diff --git a/docs/get_started/installation/kunlunxin_xpu.md b/docs/get_started/installation/kunlunxin_xpu.md index 7c50697356..0a0cb3bdb3 100644 --- a/docs/get_started/installation/kunlunxin_xpu.md +++ b/docs/get_started/installation/kunlunxin_xpu.md @@ -110,6 +110,44 @@ bash build.sh The compiled outputs will be located in the ```FastDeploy/dist``` directory. +## 4. Python-only Quick Install (For Development) + +If you have already completed a full build (`bash build.sh 1`) and only modified Python files, you can use the python-only mode to quickly sync changes to `site-packages` **without recompiling C++ Custom Ops or rebuilding the wheel**. + +### Prerequisites + +A full build must have been completed at least once: + +```bash +bash build.sh 1 +``` + +### Usage + +```bash +# Argument 1: Must be 2 to enable python-only mode +# Argument 2 (optional): Python interpreter path (default: python) + +# Use default python +bash build.sh 2 + +# Use a specific python interpreter +bash build.sh 2 python3 + +# Use an absolute path to the interpreter +bash build.sh 2 /path/to/your/python +``` + +This command syncs `.py` files from the source tree directly into the installed `site-packages/fastdeploy/` directory via `rsync`. Compiled artifacts (`.so` files) are preserved. + +### When to Use + +| Scenario | Recommended Command | +|---|---| +| Only modified Python files | `bash build.sh 2` | +| Modified C++/CUDA code | `bash build.sh 1` | +| First-time build | `bash build.sh 1` | + ## Installation verification ```bash diff --git a/docs/get_started/installation/nvidia_gpu.md b/docs/get_started/installation/nvidia_gpu.md index c59467175d..756d422c24 100644 --- a/docs/get_started/installation/nvidia_gpu.md +++ b/docs/get_started/installation/nvidia_gpu.md @@ -125,6 +125,44 @@ After the build completes, the operator binaries can be found in `FastDeploy/fas > - For custom architectures or modified operator logic, please use **source compilation (Section 4)**. > - You can check whether the precompiled wheel for a specific commit has been successfully built on the [FastDeploy CI Build Status Page](https://github.com/PaddlePaddle/FastDeploy/actions/workflows/ci_image_update.yml). +## 6. Python-only Quick Install (For Development) + +If you have already completed a full build (`bash build.sh 1 ...`) and only modified Python files, you can use the python-only mode to quickly sync changes to `site-packages` **without recompiling C++ Custom Ops or rebuilding the wheel**. + +### Prerequisites + +A full build must have been completed at least once: + +```shell +bash build.sh 1 python false [80,90] +``` + +### Usage + +```shell +# Argument 1: Must be 2 to enable python-only mode +# Argument 2 (optional): Python interpreter path (default: python) + +# Use default python +bash build.sh 2 + +# Use a specific python interpreter +bash build.sh 2 python3 + +# Use an absolute path to the interpreter +bash build.sh 2 /path/to/your/python +``` + +This command syncs `.py` files from the source tree directly into the installed `site-packages/fastdeploy/` directory via `rsync`. Compiled artifacts (`.so` files) are preserved. + +### When to Use + +| Scenario | Recommended Command | +|---|---| +| Only modified Python files | `bash build.sh 2` | +| Modified C++/CUDA code | `bash build.sh 1 python false [80,90]` | +| First-time build | `bash build.sh 1 python false [80,90]` | + ## Environment Verification After installation, verify the environment with this Python code: diff --git a/docs/zh/get_started/installation/kunlunxin_xpu.md b/docs/zh/get_started/installation/kunlunxin_xpu.md index b0e7f2a64f..d784216d23 100644 --- a/docs/zh/get_started/installation/kunlunxin_xpu.md +++ b/docs/zh/get_started/installation/kunlunxin_xpu.md @@ -111,6 +111,40 @@ bash build.sh 编译后的产物在 ```FastDeploy/dist``` 目录下。 +## 4. Python-only 快速安装 + +如果你已经完成过一次完整编译安装，后续仅修改了 Python 代码，可以使用 Python-only 模式将 Python 文件快速同步到 `site-packages`，**跳过 C++ 算子编译和 Wheel 打包**。 + +### 前提条件 + +必须先完成过一次完整编译安装（即执行过 `bash build.sh 1 ...`），确保 `site-packages` 中已有编译产物（`.so` 文件）。 + +### 使用方式 + +```bash +# 使用默认 python +bash build.sh 2 + +# 指定 Python 解释器 +bash build.sh 2 python3 + +# 使用完整路径指定 Python 解释器 +bash build.sh 2 /path/to/your/python +``` + +- 第 1 个参数 `2`：表示使用 Python-only 模式 +- 第 2 个参数（可选）：Python 解释器路径或命令名，默认为 `python` + +### 适用场景 + +| 场景 | 推荐方式 | +|------|----------| +| 仅修改 Python 文件 | `bash build.sh 2` | +| 修改了 C++/CUDA 代码 | `bash build.sh 1 ...`（完整编译） | +| 首次编译 | `bash build.sh 1 ...`（完整编译） | + +> **注意：** 该模式需要系统安装 `rsync`，若未安装请先执行 `apt-get install rsync` 或 `yum install rsync`。 + ## 验证是否安装成功 ```python diff --git a/docs/zh/get_started/installation/nvidia_gpu.md b/docs/zh/get_started/installation/nvidia_gpu.md index 8e989db536..15ef9d2779 100644 --- a/docs/zh/get_started/installation/nvidia_gpu.md +++ b/docs/zh/get_started/installation/nvidia_gpu.md @@ -131,6 +131,40 @@ bash build.sh 1 python false [90] 1 8a9e7b53af4a98583cab65e4b44e3265a93e56d2 > - 若希望自定义架构或修改算子逻辑，请使用 **源码编译方式（第4节）**。 > - 您可以在 FastDeploy CI 构建状态页面查看对应 commit 的预编译 whl 是否已构建成功。 +## 6. Python-only 快速安装 + +如果你已经完成过一次完整编译安装，后续仅修改了 Python 代码，可以使用 Python-only 模式将 Python 文件快速同步到 `site-packages`，**跳过 C++ 算子编译和 Wheel 打包**。 + +### 前提条件 + +必须先完成过一次完整编译安装（即执行过 `bash build.sh 1 ...`），确保 `site-packages` 中已有编译产物（`.so` 文件）。 + +### 使用方式 + +```bash +# 使用默认 python +bash build.sh 2 + +# 指定 Python 解释器 +bash build.sh 2 python3 + +# 使用完整路径指定 Python 解释器 +bash build.sh 2 /path/to/your/python +``` + +- 第 1 个参数 `2`：表示使用 Python-only 模式 +- 第 2 个参数（可选）：Python 解释器路径或命令名，默认为 `python` + +### 适用场景 + +| 场景 | 推荐方式 | +|------|----------| +| 仅修改 Python 文件 | `bash build.sh 2` | +| 修改了 C++/CUDA 代码 | `bash build.sh 1 python false "[80,90]"` | +| 首次编译 | `bash build.sh 1 python false "[80,90]"` | + +> **注意：** 该模式需要系统安装 `rsync`，若未安装请先执行 `apt-get install rsync` 或 `yum install rsync`。 + ## 环境检查 在安装 FastDeploy 后，通过如下 Python 代码检查环境的可用性