使用 Python SDK 管理镜像

Python SDK 可用于在 CI/CD 流程中构建和维护镜像。使用本文示例前，请先完成 Python SDK 快速开始，并确认已准备构建资源池、实例规格、基础镜像或 Dockerfile 等依赖。

创建镜像

SDK 支持多种镜像构建方式：

基于平台已有镜像构建，对应 baseSiflowImage。
基于 Dockerfile 构建，对应 baseDockerfile。
基于第三方镜像地址构建，对应 baseThirdImage。
基于镜像仓库中已有但尚未登记到平台的镜像构建，对应 baseExistImage。
从 JupyterLab 或 VSCS 开发环境保存镜像，对应 baseFromJob。

配置构建方式

以下示例展示几类构建配置。实际创建镜像时，从中选择一种传入 image_build_config。

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="<DEVELOPMENT_ENVIRONMENT_NAME>",
    source_job_id="<DEVELOPMENT_ENVIRONMENT_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() 创建镜像构建任务。

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="<BUILD_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`	构建镜像使用的实例规格和数量。

查询镜像

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 创建的镜像可以分享给指定用户或项目组。

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="<PROJECT_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 分享：

share = client.images.share(
    image_id=123,
    project_groups=[
        ImageShareProjectGroup(group_name="<PROJECT_GROUP_NAME>", is_shared=False),
    ],
)

如果当前环境未使用项目组访问控制，可通过 users 分享给指定用户：

share = client.images.share(
    image_id=123,
    is_show_all_users=False,
    users=["alice", "bob"],
)

停止镜像构建

如果镜像仍在构建中，可以按镜像 ID 停止构建任务。

resp = client.images.stop(image_id=123)
print(resp)

停止构建会中断当前构建流程。执行前，请确认不再需要本次构建结果。

删除镜像

resp = client.images.delete(image_id=123)
print(resp)

删除前，请确认镜像不再被训练任务、开发环境或推理服务引用。

查看镜像仓库事件

镜像仓库事件可用于追踪镜像推送、删除或同步结果。

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 管理镜像

创建镜像

配置构建方式

提交构建

查询镜像

分享镜像

停止镜像构建

删除镜像

查看镜像仓库事件

相关文档

​创建镜像

​配置构建方式

​提交构建

​查询镜像

​分享镜像

​停止镜像构建

​删除镜像

​查看镜像仓库事件

​相关文档

创建镜像

配置构建方式

提交构建

查询镜像

分享镜像

停止镜像构建

删除镜像

查看镜像仓库事件

相关文档