> ## 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. # 使用 Python SDK 管理镜像 > 使用人工智能平台 Python SDK 创建镜像、查询镜像、分享镜像、停止构建、删除镜像和查看镜像仓库事件。 Python SDK 可用于在 CI/CD 流程中构建和维护镜像。使用本文示例前，请先完成 [Python SDK 快速开始](./python-sdk-quickstart)，并确认已准备构建资源池、实例规格、基础镜像或 Dockerfile 等依赖。 ## 创建镜像 SDK 支持多种镜像构建方式： * 基于平台已有镜像构建，对应 `baseSiflowImage`。 * 基于 Dockerfile 构建，对应 `baseDockerfile`。 * 基于第三方镜像地址构建，对应 `baseThirdImage`。 * 基于镜像仓库中已有但尚未登记到平台的镜像构建，对应 `baseExistImage`。 * 从 JupyterLab 或 VSCS 开发环境保存镜像，对应 `baseFromJob`。 ### 配置构建方式 以下示例展示几类构建配置。实际创建镜像时，从中选择一种传入 `image_build_config`。 ```python theme={null} from siflow import SiFlow from siflow.types import ( ImageBuildConfigArgRequest, ImageBuildConfigRequest, InstanceRequest, ) client = SiFlow(region="cn-beijing", cluster="auriga") # 方式 1：基于平台已有镜像构建。 base_siflow_image = ImageBuildConfigRequest( commit_id="demo-build-001", build_method="baseSiflowImage", basic_image_type="custom", basic_image_url="registry-cn-shanghai.siflow.cn/ai-infra/base-runtime:v1.0.0-a1b2c3d", description="Build from AI Platform image", ) # 方式 2：基于 Dockerfile 构建。 dockerfile_args = [ ImageBuildConfigArgRequest( hidden=False, key="VERSION", value="0.0.1", ), ImageBuildConfigArgRequest( hidden=False, key="APP_NAME", value="demo", ), ] base_dockerfile = ImageBuildConfigRequest( commit_id="demo-build-002", build_method="baseDockerfile", dockerfile_content=( "FROM ubuntu:20.04\n" "ARG VERSION\n" "ARG APP_NAME\n" "LABEL app.version=${VERSION}\n" "RUN apt-get update && apt-get install -y curl\n" "RUN echo \"Hello from ${APP_NAME} ${VERSION}\" > /image-info.txt\n" "CMD [\"cat\", \"/image-info.txt\"]" ), # 也可以使用 dockerfile_path 指定本地 Dockerfile 路径。 # dockerfile_path="/path/to/Dockerfile", description="Build from Dockerfile", dockerfile_arg=dockerfile_args, ) # 方式 3：基于第三方镜像地址构建。 base_third_image = ImageBuildConfigRequest( commit_id="demo-build-003", build_method="baseThirdImage", docker_hub_url="mysql:8.0", description="Build from third-party image", ) # 方式 4：基于镜像仓库中已有但尚未登记到平台的镜像构建。 base_existing_image = ImageBuildConfigRequest( commit_id="demo-build-004", build_method="baseExistImage", docker_hub_url="registry-cn-shanghai.siflow.cn/ai-infra/custom-base:v0.1.0-a1b2c3d", description="Register existing repository image", ) # 方式 5：从开发环境保存镜像。 base_from_job = ImageBuildConfigRequest( commit_id="demo-build-005", build_method="baseFromJob", source_job_type="vscs", source_job_name="", source_job_id="", ) ``` 构建配置参数如下： | 参数 | 说明 | | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `commit_id` | 镜像构建标识。 | | `build_method` | 构建方式，可选择 `baseSiflowImage`、`baseDockerfile`、`baseThirdImage`、`baseExistImage` 或 `baseFromJob`。 | | `basic_image_type` / `basic_image_url` | 使用 `baseSiflowImage` 构建时填写。`basic_image_type` 表示基础镜像类型，`basic_image_url` 表示基础镜像完整地址。 | | `dockerfile_content` / `dockerfile_path` | 使用 `baseDockerfile` 构建时二选一。`dockerfile_content` 直接传入 Dockerfile 内容，`dockerfile_path` 指向 Dockerfile 文件路径。 | | `docker_hub_url` | 使用 `baseThirdImage` 或 `baseExistImage` 构建时填写。 | | `description` | 镜像构建说明。 | | `pip` / `apt` | 需要安装的 Python 或系统依赖。也可以在 Dockerfile 中直接安装，或通过依赖文本文件生成安装命令，再把命令放入 Dockerfile 的合适位置。 | | `dockerfile_arg` | Dockerfile 构建参数。`hidden=True` 可隐藏参数值，适合传入不希望明文展示的构建参数。 | | `source_job_type` / `source_job_name` / `source_job_id` | 使用 `baseFromJob` 从开发环境保存镜像时填写。`source_job_type` 可选择 `jupyter` 或 `vscs`。 | ### 提交构建 配置构建方式后，调用 `client.images.create()` 创建镜像构建任务。 ```python theme={null} instances_config = [ InstanceRequest( name="sci.c23-2", countPerPod=1, ) ] image_info = client.images.create( name="demo-image", version="0.0.1", major_category="siflow", minor_category="cicd", image_build_type="custom", image_build_region="cn-beijing", image_build_cluster="auriga", image_build_config=base_dockerfile, resource_pool="", instances=instances_config, ) print(image_info) ``` 创建参数如下： | 参数 | 说明 | | -------------------------------------------- | -------------------------------- | | `name` | 镜像名称。 | | `version` | 镜像版本。 | | `major_category` | 镜像主分类。示例使用 `siflow`。 | | `minor_category` | 镜像分类。 | | `image_build_type` | 镜像类型，例如 `custom` 或 `preset`。 | | `image_build_region` / `image_build_cluster` | 构建镜像使用的区域和集群。 | | `image_build_config` | 镜像构建配置。 | | `resource_pool` | 构建镜像使用的资源池。使用专属构建资源池时，请先确认资源池名称。 | | `instances` | 构建镜像使用的实例规格和数量。 | ## 查询镜像 ```python theme={null} images = client.images.list( page=1, pageSize=5, minor_category="", image_build_type="custom", image_build_cluster="auriga", image_build_region="cn-beijing", keyword="demo", ) for image in images: print(image) ``` 查询参数如下： | 参数 | 说明 | | -------------------------------------------- | ---------------------------- | | `page` / `pageSize` | 分页参数。 | | `minor_category` | 镜像分类。 | | `image_build_type` | 镜像类型，例如 `custom` 或 `preset`。 | | `image_build_region` / `image_build_cluster` | 按构建区域或集群筛选。 | | `keyword` | 按镜像名称或镜像版本模糊搜索。 | ## 分享镜像 通过 SDK 创建的镜像可以分享给指定用户或项目组。 ```python theme={null} from siflow.types import ImageShareProjectGroup share = client.images.share( image_id=123, is_show_all_users=False, users=["alice", "bob"], project_groups=[ ImageShareProjectGroup( group_name="", is_shared=False, ), ], ) print(share) ``` 分享参数如下： | 参数 | 说明 | | ------------------- | ------------------------------------------------------ | | `image_id` | 镜像 ID，可通过查询镜像列表获取。 | | `is_show_all_users` | 是否共享给所有用户。普通用户不建议设置为 `True`；如果启用后共享给所有用户，`users` 会被忽略。 | | `users` | 指定可见用户列表。 | | `project_groups` | 指定项目组共享范围。`group_name` 为项目组名称，`is_shared` 表示是否在项目组内公开。 | 如果当前环境按项目组做访问控制，优先通过 `project_groups` 分享： ```python theme={null} share = client.images.share( image_id=123, project_groups=[ ImageShareProjectGroup(group_name="", is_shared=False), ], ) ``` 如果当前环境未使用项目组访问控制，可通过 `users` 分享给指定用户： ```python theme={null} share = client.images.share( image_id=123, is_show_all_users=False, users=["alice", "bob"], ) ``` ## 停止镜像构建 如果镜像仍在构建中，可以按镜像 ID 停止构建任务。 ```python theme={null} resp = client.images.stop(image_id=123) print(resp) ``` 停止构建会中断当前构建流程。执行前，请确认不再需要本次构建结果。 ## 删除镜像 ```python theme={null} resp = client.images.delete(image_id=123) print(resp) ``` 删除前，请确认镜像不再被训练任务、开发环境或推理服务引用。 ## 查看镜像仓库事件 镜像仓库事件可用于追踪镜像推送、删除或同步结果。 ```python theme={null} resp = client.images.list_webhook_events( page=1, pageSize=15, name="demo-image", tag="0.0.1", region="cn-beijing", ) print(resp.total) for item in resp.rows: print(item.id, item.name, item.tag, item.eventType, item.status, item.occurAt) ``` 返回字段中，重点关注以下信息： | 字段 | 说明 | | -------------- | ---------------------- | | `eventType` | 事件类型，例如镜像推送、镜像删除或平台同步。 | | `status` | 事件状态，例如待处理、处理完成或处理失败。 | | `errorMessage` | 失败时的错误信息。 | | `operator` | 操作人或触发来源。 | | `occurAt` | 事件发生时间。 | ## 相关文档 * [Python SDK 快速开始](./python-sdk-quickstart) * [构建自定义镜像](../images/build-custom-images) * [管理自定义镜像](../images/manage-custom-images) * [同步镜像到其他集群](../images/sync-images-across-clusters)