跳到主要内容

依赖管理

如果需要安装额外的依赖，可以按照以下的方式做配置。这些配置文件会在部署服务启动时自动执行，无需手动干预。

工作空间与模型部署的依赖管理​

在进行模型部署之前，通常建议先在「工作空间」中完成模型的开发和测试。这样做有以下几个好处：

  1. 可以在工作空间中交互式地安装和测试依赖
  2. 使用 pip install --user 或创建独立环境（Conda / uv）的方式准备好所需的依赖环境
  3. 环境准备好后，可以直接将工作空间的目录（/openbayes/home）绑定到模型部署中使用
  4. 避免在模型部署阶段重复安装依赖，提高部署效率

最佳实践流程​

  1. 在工作空间中：

    • 使用 pip install --user xxx 安装 Python 包到 /openbayes/home/.pylibs
    • 或创建独立环境到 /openbayes/home/your_env_name（内置 Conda 的运行时用 conda create，uv 运行时用 uv venv，见用 uv 管理 Python 环境）
    • 完成模型开发和测试

  2. 在模型部署时：

    • 将工作空间的 /openbayes/home 目录绑定到模型部署
    • 如果使用自定义环境，需要在 start.sh 中激活该环境
    • 模型部署将自动继承工作空间中准备好的依赖环境

这种方式特别适合需要复杂依赖环境的模型部署场景。

依赖管理方式概览​

1. PyPI 依赖管理​

通过 requirements.txt 安装​

在模型部署文件夹的根目录下如果存在名为 requirements.txt 的文件，OpenBayes 模型部署在启动前会自动执行 pip install -r requirements.txt 命令，安装其中声明的 PyPI 库。

文件格式遵循标准的 Python requirements.txt 格式，示例：

requirements.txt
jieba
tqdm==4.11.2

使用 pip --user 安装持久化依赖​

  • 使用 pip install --user xxx 命令安装的依赖会保存在 /openbayes/home/.pylibs 目录下
  • 这些依赖在容器重启后依然可用
  • 注意: 在新创建的独立环境（conda 或 uv venv）中不要使用 --user 参数，避免依赖冲突

2. Conda 依赖管理​

通过 conda-packages.txt 安装​

OpenBayes 模型部署支持 Conda 包的安装。在部署服务启动之前会自动在部署目录的根目录下查找名为 conda-packages.txt 的文件，其文件格式遵循：

[channel::]package[=version[=buildid]]
备注

conda-packages.txt 仅在内置 Conda 的运行时中有效；使用 uv 的运行时（Ubuntu 24.04 及更新）请改用 requirements.txt。

示例：

conda-packages.txt
conda-forge::rdkit
conda-forge::pygpu

创建自定义 Conda 环境​

  • 可以在 /openbayes/home 下创建新的 conda 环境
  • 示例：
conda create -p /openbayes/home/open-mmlab python=3.9 -y
conda activate /openbayes/home/open-mmlab

在 start.sh 中激活 Conda 环境​

备注

内置 Conda 的运行时（Ubuntu 22.04 及更早）中，start.sh 通常需要先激活默认的 base 环境，即使不使用自定义的 conda 环境。使用 uv 的运行时见下一节。

如果使用自定义的 conda 环境，需要在 start.sh 中明确激活该环境。示例：

start.sh
#!/bin/bash

# 首先激活默认的 base 环境
source /usr/local/etc/profile.d/conda.sh
conda activate base

# 如果使用自定义环境，继续激活自定义环境
conda activate /openbayes/home/open-mmlab

# 启动模型服务
python app.py
备注

如果不使用自定义 conda 环境，而是使用系统默认环境或通过 pip install --user 安装的依赖，仍然需要激活 base 环境，但不需要额外的环境激活步骤。

uv 运行时：start.sh 通常无需激活环境​

使用 uv 的运行时（Ubuntu 24.04 及更新，如 vllm 0.20 及之后）中，默认环境开箱即用：start.sh 不需要任何激活步骤（也不需要 conda 运行时那样先激活 base），直接写启动命令即可；通过 pip install --user 准备的依赖会自动生效。

只有一种情况需要额外一行：你在工作空间自建了独立的 uv 环境并希望部署使用它，此时在 start.sh 开头 source 激活：

start.sh
#!/bin/bash

# 激活自定义环境
source /openbayes/home/myenv/bin/activate

# 启动模型服务
python app.py

3. 系统依赖管理​

通过 dependencies.sh 安装​

对于非 Conda 和 PyPI 的依赖，可以在根目录提供一个名为 dependencies.sh 的文件，在模型部署启动时它会自动被 bash 执行，并且其执行会早于 requirements.txt 和 conda-packages.txt 依赖的安装。

示例：

dependencies.sh
apt update && apt install tree -y

依赖安装顺序​

当多个依赖配置文件同时存在时，安装顺序为：

  1. dependencies.sh
  2. conda-packages.txt
  3. requirements.txt

最佳实践建议​

  1. 对于需要持久化的 Python 依赖：

    • 使用 pip install --user xxx 安装到用户目录
    • 在 /openbayes/home 下创建自定义独立环境（Conda 或 uv）
    • 在代码仓库中包含 requirements.txt/conda-packages.txt 文件
    • 如果使用自定义环境，确保在 start.sh 中正确激活环境

  2. 对于系统依赖：

    • 将安装命令保存在 dependencies.sh 中
    • 每次容器启动时会自动执行

  3. 注意事项：

    • 系统盘上的依赖在容器重启后会丢失
    • 工作目录 /openbayes/home 中的内容会持久化保存
    • 建议将重要依赖环境保存在工作目录中
    • 使用自定义 conda 环境时，确保 start.sh 中的环境路径正确
最后由 aisensiy 于 更新