使用 Python SDK 管理通用服务

Python SDK 可用于将通用服务接入自动化发布流程。使用本文示例前，请先完成 Python SDK 快速开始，并准备服务镜像、资源池、实例规格、端口、启动命令和访问方式等配置。

创建通用服务

以下示例创建一个单工作负载通用服务，并配置端口、网关、鉴权、自定义指标和 Volume 挂载。

from siflow import SiFlow
from siflow.types.generalsvc import (
    CreateGeneralsvcRequest,
    CustomMetricsConfig,
    HostItem,
    Image,
    Instance,
    Volume,
    Workload,
)

client = SiFlow(region="cn-beijing", cluster="auriga")

res = client.generalsvc.create(
    request=CreateGeneralsvcRequest(
        name="sdk-general-demo",
        ports=[8000],
        useBaseUrl=False,
        authEnabled=True,
        customMetrics=CustomMetricsConfig(
            enabled=True,
            path="/metrics",
            port=8000,
        ),
        hosts=[
            HostItem(
                host="<SERVICE_DOMAIN>",
                type="dedicated",
                paths={"8000": "/sdk-general-demo"},
            )
        ],
        workloads=[
            Workload(
                versionName="v1",
                version="v1",
                replicas=1,
                resourcePool="<RESOURCE_POOL>",
                instances=[
                    Instance(name="sci.c23-2", countPerPod=1),
                ],
                image=Image(
                    url="registry-cn-shanghai.siflow.cn/ai-infra/custom-app:v1.0.0-a1b2c3d",
                ),
                cmd="python app.py --port 8000",
                volumes=[
                    Volume(
                        volumeId=230,
                        mountDir="/volume/models",
                        subPath="models",
                        readOnly=True,
                    ),
                    Volume(
                        volumeId=231,
                        mountDir="/volume/data",
                    ),
                ],
                extraTerminationGraceSeconds=60,
            )
        ],
    ),
)

print(res)

创建参数如下：

参数	说明
`name`	通用服务名称。
`ports`	对外暴露端口。
`useBaseUrl`	是否使用 base URL。开启后，平台按 base URL 组织访问路径；关闭时按网关配置访问。
`authEnabled`	是否开启访问鉴权。
`customMetrics`	自定义指标采集配置。`path` 和 `port` 需要与服务实际暴露的 Prometheus 指标地址一致。
`hosts`	网关访问配置。`type`、`host` 和 `paths` 需要按目标网关填写。
`workloads`	工作负载配置。单服务可包含一个或多个工作负载版本。

Workload 常用字段如下：

参数	说明
`versionName` / `version`	工作负载版本名称和版本号。
`replicas`	副本数。
`resourcePool`	工作负载使用的资源池。
`instances`	每个 Pod 使用的实例规格和数量。
`image`	工作负载镜像。使用 `url` 时，镜像名称、版本和类型不会用于定位镜像。
`volumes`	Volume 挂载配置。挂载目录级 Volume 时，需要配置 `subPath` 和 `readOnly`。
`cmd`	启动命令。
`env`	环境变量。
`livenessProbe` / `readinessProbe`	存活探针和就绪探针。
`extraTerminationGraceSeconds`	优雅终止额外等待时间。省略或传 `0` 时使用默认终止等待时间。

查询通用服务

查询列表：

page = client.generalsvc.list(
    page=1,
    page_size=10,
    name="sdk-general-demo",
    status=["Running"],
    resource_pool=["<RESOURCE_POOL>"],
    sort_by="createTime",
    sort_order="desc",
)

print(page.total)
for item in page.rows:
    print(item.uuid, item.name, item.status)

查询详情：

detail = client.generalsvc.get(id="<GENERAL_SERVICE_UUID>")
print(detail)

列表接口支持按 name、status、resource_pool、generalsvc_uuid、sort_by、sort_order 和 show_all 等参数过滤。

更新服务配置

更新服务配置时，建议只修改目标字段。涉及网关配置时，优先使用 patch_hosts，避免因全量更新遗漏已有网关配置。

from siflow.types.generalsvc import HostItem, PatchGeneralsvcHostsRequest, UpdateGeneralsvcRequest

client.generalsvc.update(
    id="<GENERAL_SERVICE_UUID>",
    request=UpdateGeneralsvcRequest(authEnabled=False),
)

client.generalsvc.patch_hosts(
    id="<GENERAL_SERVICE_UUID>",
    request=PatchGeneralsvcHostsRequest(
        hosts=[
            HostItem(
                host="<SERVICE_DOMAIN>",
                type="dedicated",
                paths={"8000": "/sdk-general-demo"},
            )
        ]
    ),
)

启停、重启和扩缩容

根据目标选择对应操作，不要在同一次变更中连续执行启停和重启：

client.generalsvc.offline(id="<GENERAL_SERVICE_UUID>")

client.generalsvc.online(id="<GENERAL_SERVICE_UUID>")

client.generalsvc.restart(id="<GENERAL_SERVICE_UUID>")

扩缩容时，按工作负载版本设置目标副本数：

client.generalsvc.scale(
    id="<GENERAL_SERVICE_UUID>",
    scale={"v1": 2},
)

下线会影响服务访问；扩缩容会改变资源占用。执行前请确认业务流量、资源配额和变更窗口。

公开和分享服务

client.generalsvc.set_visibility(
    id="<GENERAL_SERVICE_UUID>",
    is_public=False,
)

# 全量覆盖分享名单。
client.generalsvc.share(
    id="<GENERAL_SERVICE_UUID>",
    share_users=["alice", "bob"],
)

增量追加用户：

# 增量追加用户。
client.generalsvc.share_add_users(
    id="<GENERAL_SERVICE_UUID>",
    users_to_add=["carol"],
)

增量删除用户：

# 增量删除用户。
client.generalsvc.share_delete_users(
    id="<GENERAL_SERVICE_UUID>",
    users_to_remove=["bob"],
)

share 会把服务分享名单替换为传入列表；share_add_users 和 share_delete_users 用于在现有名单基础上追加或移除用户。

管理定时策略、Deployment 和 Pod

配置定时策略：

client.generalsvc.cronjob(
    id="<GENERAL_SERVICE_UUID>",
    job_type="restart",
    enable=True,
    action_time="0 */3 * * *",
)

查询和管理 Deployment：

deployments = client.generalsvc.list_deployments(
    general_svc_uuid="<GENERAL_SERVICE_UUID>",
)

for deployment in deployments:
    print(deployment)

需要重启指定 Deployment 时：

client.generalsvc.restart_deployment(
    workload_name="sdk-general-demo-v1",
    general_svc_uuid="<GENERAL_SERVICE_UUID>",
)

确认不再需要指定 Deployment 后再删除：

client.generalsvc.delete_deployment(
    workload_name="sdk-general-demo-v1",
    general_svc_uuid="<GENERAL_SERVICE_UUID>",
)

查询和管理 Pod：

pods = client.generalsvc.list_pods(
    id="<GENERAL_SERVICE_UUID>",
    page=1,
    page_size=10,
    status=["Running"],
    sort_by="podName",
    sort_order="asc",
)

for pod in pods.rows:
    print(pod)

需要重启指定 Pod 时：

client.generalsvc.restart_pod(
    id="<GENERAL_SERVICE_UUID>",
    pod_name="<POD_NAME>",
)

pod_statuses = client.generalsvc.list_pod_statuses(id="<GENERAL_SERVICE_UUID>")
service_statuses = client.generalsvc.list_statuses()

查询看板汇总：

dashboard = client.generalsvc.dashboard(
    details_limit=5,
    resource_pool="<RESOURCE_POOL>",
)

print(dashboard)

查询日志

通用服务继承 SDK 的日志能力，可按服务 ID 查询或下载日志。

logs = client.generalsvc.query_logs(
    "<GENERAL_SERVICE_UUID>",
    limit=100,
    sort_order="desc",
)

file_path = client.generalsvc.download_logs(
    "<GENERAL_SERVICE_UUID>",
    file_path="./generalsvc.log",
)

也可以直接查询单个 Pod 容器日志：

resp = client.generalsvc.get_pod_container_logs(
    pod_name="<POD_NAME>",
    general_svc_uuid="<GENERAL_SERVICE_UUID>",
    container_name="main",
    lines=200,
    previous=False,
)

print(resp)

更多日志分页、下载和系统日志示例，请参考使用 Python SDK 查询日志和指标。

灰度发布和版本回滚

灰度发布适合在保留稳定版本的同时验证候选配置。以下示例按“发起灰度、查看状态、调整流量、查看差异、完成或回滚”的顺序组织。

发起灰度

client.generalsvc.canary_publish(
    id="<GENERAL_SERVICE_UUID>",
    request={
        "mode": "advanced",
        "workloads": [
            {
                "version": "v1",
                "replicas": 2,
                "image": {
                    "url": "registry-cn-shanghai.siflow.cn/ai-infra/custom-app:v1.0.1-b2c3d4e",
                },
                "cmd": "python app.py --port 8000",
            }
        ],
        "rollout": {
            "initialWeight": 0,
            "initialTotalReplicas": 2,
            "initialNewReplicas": 1,
            "surgeStrategy": "extra",
        },
    },
)

workloads 应只填写需要变更的候选配置；未变更字段按基线配置继承。

查询和调整灰度

rollout = client.generalsvc.get_rollout(id="<GENERAL_SERVICE_UUID>")
print(rollout)

client.generalsvc.patch_rollout(
    id="<GENERAL_SERVICE_UUID>",
    request={
        "weight": 50,
        "totalReplicas": 3,
        "newReplicas": 2,
        "surgeStrategy": "extra",
    },
)

diff = client.generalsvc.get_rollout_diff(id="<GENERAL_SERVICE_UUID>")
print(diff)

完成、放弃或回滚

# 灰度成功后完成发布。
client.generalsvc.complete_rollout(id="<GENERAL_SERVICE_UUID>")

complete_rollout() 提交全量发布后，需要等待灰度状态变为 completed，再执行收尾：

rollout = client.generalsvc.get_rollout(id="<GENERAL_SERVICE_UUID>")
print(rollout.state)

if rollout.state == "completed":
    client.generalsvc.finalize_rollout(id="<GENERAL_SERVICE_UUID>")

灰度异常时，放弃本次灰度并回到稳定版本：

client.generalsvc.rollback_rollout(id="<GENERAL_SERVICE_UUID>")

需要回滚到历史版本时，先查询版本，再选择目标版本：

versions = client.generalsvc.list_versions(
    id="<GENERAL_SERVICE_UUID>",
    page=1,
    page_size=10,
)

client.generalsvc.rollback_version(
    id="<GENERAL_SERVICE_UUID>",
    version="<VERSION_ID>",
)

灰度发布会同时影响服务流量和资源占用。执行前，请确认候选版本配置、资源配额和回滚路径。

删除通用服务

res = client.generalsvc.delete(id="<GENERAL_SERVICE_UUID>")
print(res)

删除会影响服务可用性。执行前，请确认该服务不再承载线上流量，并已保存需要保留的配置或数据。

开始使用

资源准备

开发与训练

模型与推理

运维与治理

开发者接入

使用 Python SDK 管理通用服务

创建通用服务

查询通用服务

更新服务配置

启停、重启和扩缩容

公开和分享服务

管理定时策略、Deployment 和 Pod

查询日志

灰度发布和版本回滚

发起灰度

查询和调整灰度

完成、放弃或回滚

删除通用服务

相关文档

​创建通用服务

​查询通用服务

​更新服务配置

​启停、重启和扩缩容

​公开和分享服务

​管理定时策略、Deployment 和 Pod

​查询日志

​灰度发布和版本回滚

​发起灰度

​查询和调整灰度

​完成、放弃或回滚

​删除通用服务

​相关文档

创建通用服务

查询通用服务

更新服务配置

启停、重启和扩缩容

公开和分享服务

管理定时策略、Deployment 和 Pod

查询日志

灰度发布和版本回滚

发起灰度

查询和调整灰度

完成、放弃或回滚

删除通用服务

相关文档