> ## Documentation Index > Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt > Use this file to discover all available pages before exploring further. # 构建自定义镜像 > 在人工智能平台中构建自定义镜像，配置镜像名称、版本、构建资源、依赖、Dockerfile 和构建方式。 自定义镜像用于沉淀自有运行环境。当内置镜像不满足框架版本、系统依赖、Python 包或工具链要求时，您可以基于已有镜像、Dockerfile、第三方镜像仓库或已构建镜像创建自定义镜像。构建完成后，自定义镜像可在开发环境、训练任务和推理服务中选择使用。 ## 镜像命名与 URL 自定义镜像通常通过名称、版本和提交 ID 区分不同迭代。镜像 URL 由镜像仓库地址、项目名称、镜像名称、版本和提交 ID 组成： ```text theme={null} //:- ``` | 字段 | 说明 | | -------------- | -------------------------------------- | | `harbor_url` | 镜像仓库地址，由平台根据区域和集群生成。 | | `project_name` | 镜像仓库项目，通常由平台根据租户或项目归属生成。 | | `name` | 镜像名称。建议使用小写英文、数字、中划线或下划线，并能体现框架、用途或项目。 | | `version` | 镜像版本，用于管理同一镜像的不同版本。 | | `commit_id` | 镜像标签或提交标识，用于区分同名同版本下的不同迭代。 | 同一名称和版本下可以有多个标签版本。创建开发环境、训练任务或推理服务时，通常按镜像名称和版本选择镜像；如果同一版本存在多个标签，以当前页面实际选择和展示的镜像 URL 为准。 ## 创建自定义镜像 构建镜像会消耗实例资源。创建前，请确认当前区域和集群有可用的构建资源，并关注镜像仓库存储用量。若镜像后续需要在多个集群使用，请在创建或构建完成后配置镜像同步。 ### 1. 进入创建页 1. 进入 **镜像管理 > 自定义镜像**。 2. 在 **可用镜像列表** 页签，单击 **新建**。 ### 2. 填写配置信息 #### 基本信息 | 配置项 | 说明 | | ----- | -------------------------------------------------------------- | | 区域 | 选择镜像构建所在区域。 | | 集群 | 选择镜像构建所在集群。 | | 分享项目组 | 配置镜像可见范围。需要共享给其他项目组时，单击 **新增项目组** 添加；不添加时，通常按构建用户所在项目组的默认范围授权。 | | 名称 | 镜像名称。建议使用小写英文、数字、中划线或下划线，并能表达框架、用途或项目。 | | 版本 | 镜像版本，用于同一镜像的多版本管理。建议使用稳定、可排序的版本号，避免使用空格、斜杠或特殊符号。 | | 提交 ID | 镜像标签或代码提交标识，用于区分同名同版本的不同迭代。建议使用代码仓库提交 ID 的前几位，便于追溯来源。 | | 镜像类型 | 镜像分类，例如 `pytorch`、`base`、`python`、`LLM` 等，以对镜像进行分类和管理。 | | 标签 | 用于检索和归类镜像。 | | 描述 | 说明镜像来源、用途、框架版本、依赖或使用限制。 | #### 运行信息 | 配置项 | 说明 | | ------- | --------------------------------------------------------------------------------------------- | | 资源类型 | 选择构建任务使用的资源计费类型，例如 **预留实例**、**按量实例** 或 **Spot**。 | | 实例 | 使用 **预留实例** 时，选择资源池。 | | 实例类型、数量 | 支持 **GPU** 和 **CPU**。在实例列表中勾选构建任务使用的实例规格，并配置 **单节点实例规格数**。选择实例时，重点关注 **用户剩余配额** 和 **资源池可用量**。 | | 资源优先级 | 勾选实例后配置调度优先级。按优先级从高到低排序，调度时优先使用排在前面的实例。 | #### 编译配置 先选择编译方法，再填写对应的构建配置。 基于已有镜像适合在内置镜像或已有自定义镜像上补充依赖。 | 配置项 | 说明 | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | 基础镜像 | 选择 **内置** 或 **自定义** 镜像作为基础镜像。 | | 依赖库包 | 添加系统依赖和 Python 依赖，支持以下方式：
  • 在 **apt** 中添加系统包，例如 `vim`。
  • 在 **pip3** 中添加 Python 3 依赖和版本。
  • 上传 `apt.txt`、`pip.txt` 批量导入依赖。
| `apt.txt` 和 `pip.txt` 是文本文件，每行填写一个依赖项。 依赖安装方式需要与基础镜像匹配。**apt** 通常适用于 Ubuntu 系统依赖，**yum** 通常适用于 CentOS 系统依赖；**pip2** 和 **pip3** 分别对应 Python 2 和 Python 3 依赖。 * `apt.txt` 示例： ```text theme={null} python3=3.8.2-0ubuntu2 python3-pip=20.0.2-5ubuntu1.11 curl=7.68.0-1ubuntu2.25 wget=1.20.3-1ubuntu2.1 ``` * `pip.txt` 示例： ```text theme={null} requests==2.31.0 flask==2.3.3 ``` 基于编译文件适合通过 Dockerfile 沉淀完整构建逻辑。选择该方式后，请填写 Dockerfile 内容和构建参数。构建参数用于在构建过程中动态传入变量，并在 Dockerfile 中引用。 如果需要安装 **apt** 或 **pip** 依赖，可以使用以下方式： * 直接在 Dockerfile 中编写安装命令。 * 在依赖库包中添加依赖，或上传 `apt.txt`、`pip.txt`。平台返回对应安装命令后，将命令复制到 Dockerfile 中的适当位置。 示例： ```dockerfile theme={null} FROM ubuntu:18.04 RUN apt-get update && apt-get install -y --no-install-recommends \ python3-pip \ vim && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* RUN pip3 install \ numpy==1.19.5 \ scipy==1.5.4 RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime ``` 当前暂不支持在构建过程中将内容复制到共享目录中。如果构建依赖大文件、私有代码或模型文件，建议先确认这些内容是否应放入镜像，还是通过 Volume 在负载运行时挂载。 选择 **支持第三方镜像仓库地址下载** 时，请填写外部镜像地址，并确认平台可以访问该地址。该方式适合将外部公共镜像仓库或云厂商镜像仓库中的镜像导入平台镜像仓库后统一使用。 选择 **导入现有镜像** 时，请填写已构建镜像的地址，并确认镜像已包含后续负载运行所需的依赖和启动工具。该方式适合登记未通过平台构建、但已经推送到镜像仓库的镜像。导入后，平台会将镜像登记到自定义镜像列表，便于开发环境、训练任务或推理服务选择。 ### 3. 提交创建 配置完成后，单击 **新建** 提交构建任务。 提交后，您可以在 **构建任务列表** 中查看构建状态和构建日志。构建成功后，镜像会出现在 **可用镜像列表** 中。 ## 从开发环境保存镜像 您也可以将开发环境保存为自定义镜像。该操作适合把已经调试好的开发环境沉淀为可复用镜像；保存完成后，可回到镜像管理中查看和管理。 保存镜像期间，开发环境可能暂时不可用。建议在无交互操作时执行，并确认需要保留的文件、依赖和配置已经写入镜像或持久化存储。具体操作请参考[使用 JupyterLab 开发环境](../development/use-jupyterlab-development-environment)或[使用 VSCS 开发环境](../development/use-vscode-server-development-environment)。 ## 查看构建结果 构建任务提交后，在 **构建任务列表** 中查看状态。构建失败时，优先查看构建日志中的报错，再结合调度信息判断是依赖安装、Dockerfile、镜像拉取、资源调度还是同步配置导致失败。 | 操作 | 说明 | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 编译日志 | 查看镜像构建日志。构建失败时，优先通过日志定位依赖安装、Dockerfile、镜像拉取或命令执行问题。 | | 编译配置 | 查看构建任务的配置，包括基础镜像、Dockerfile、依赖组件、构建参数和资源配置等。 | | 更新配置 | 修改构建任务配置。更新前请确认镜像不在构建中，等待构建成功、失败或停止后再操作。更新影响通常如下：
  • **名称**、**版本**、**构建区域** 和 **构建集群** 通常不可修改。
  • 修改构建方式、基础镜像、Dockerfile、构建参数、依赖、同步配置、提交 ID、实例配置或资源池等构建相关字段，可能会触发重新构建。
  • 只修改描述、镜像类型、框架版本、Python / CUDA / NCCL 版本、芯片类型、标签或项目组等元数据，通常不需要重新构建。
  • 通过开发环境保存或镜像仓库同步生成的镜像，可能只允许更新元数据。
| | 查看镜像 | 跳转查看构建完成后生成的镜像。若构建尚未成功，可能无法查看可用镜像。 | | 克隆 | 基于当前构建任务的配置创建新的构建任务，适合复用基础镜像、依赖和构建参数。 | | 停止 | 停止正在进行的构建任务。停止后镜像不会继续构建，是否已有可用镜像以当前构建结果为准。 | | 删除 | 删除不再需要的构建任务记录。删除前，请确认不再需要查看该任务的构建日志或配置。 | ## 后续操作 * [管理自定义镜像](./manage-custom-images)