Skip to main content
Python SDK 可用于自动化管理大模型推理服务。使用本文示例前,请先完成 Python SDK 快速开始,并准备模型来源、推理引擎、资源池、实例规格、端口和访问配置。

初始化客户端

大模型推理服务通过 client.inference 管理。服务 ID 通常为整数,例如 123。

查询创建前可用选项

创建服务前,建议先查询当前集群支持的引擎、存储类型、KV Cache 选项和资源包。
这些查询结果可帮助您确认当前集群可选的引擎版本、模型来源和实例规格,避免创建时使用不可用配置。

创建 vLLM 推理服务

以下示例使用模型仓库作为模型来源,并创建一个单节点 vLLM 推理服务。请按实际环境替换资源池、模型名称、模型版本、实例规格、服务名称和网关配置。
常用配置块如下: 建议使用字典构造请求,再交给 ServiceCreateParams 校验。提交前可通过 model_dump(by_alias=True, exclude_none=True) 打印最终请求体,确认字段名和嵌套结构符合预期。

配置不同模型来源

以下片段用于替换上一节 payload 中的 modelConfig。完成替换后,重新构造 ServiceCreateParams 并调用 create_service() 提交服务。

使用 Volume

开启目录级权限的 Volume 通常需要配置 subPath;subPath 为卷内相对路径。

使用 PVC

使用 OSS

OSS 密钥不建议硬编码到代码仓库。示例中用环境变量读取,生产环境可结合密钥管理系统注入。

创建自定义引擎服务

使用自定义引擎时,通常需要在 roleConfig.worker 中指定镜像、启动命令、参数、端口和资源规格。

创建多角色或多机服务

多机推理通常会拆分为 worker、router、server 等角色。具体角色名和资源约束取决于引擎版本的 executeTypeRoles 以及服务端支持能力,可先查询引擎版本确认。
示例:

查询和调用服务

查询服务详情

查询服务列表

列表接口常用过滤参数如下:

测试网关

gateway_test 适合在正式接入前验证网关是否能访问。

使用 OpenAI 兼容接口调用

如果服务暴露的是 OpenAI 兼容接口,可以使用 OpenAI Python SDK 调用。base_url 需要按实际网关地址和路径设置。
流式调用:

更新、扩缩容和生命周期管理

更新服务配置

更新服务时,建议先读取当前服务配置,再在此基础上修改目标字段,避免遗漏需要保留的配置。
只更新网关注册配置时,可以使用 update_service_register:
如果更新过程需要中止:

扩缩容

scale_service 用于调整角色副本数,最常见的是调整 worker.replicas。
停止正在进行的扩缩容:

上线、下线和删除

上线服务:
下线服务:
确认服务不再使用后再删除:
批量上线服务:
也可以按服务名称批量上线:
批量下线服务:
也可以按服务名称批量下线:
确认目标服务不再使用后再批量删除:
也可以按服务名称批量删除:
上线、下线、扩缩容和删除都会影响服务可用性或资源占用。执行前,请确认业务流量、资源配额和变更窗口。

共享和公开服务

共享给指定用户:
需要向所有符合权限条件的用户公开服务时:
需要取消公开时:

灰度发布和版本回滚

查看服务版本

回滚服务版本

回滚到上一版本:
需要回滚到指定历史版本时:

发起灰度

调整和完成灰度

complete_rollout() 提交全量发布后,需要等待灰度状态变为 completed,再执行收尾:
灰度异常时回滚:

查询 Pod、日志和指标

查询服务 Pod:
下线状态或需要读取 offline endpoint 时:
重建单个 Pod:
按服务 ID 查询日志:
读取指定 Pod 容器日志:
实时流式日志需要安装 siflow[websocket]:
查询服务 metrics:
查询大模型服务 Dashboard 汇总:
更多日志分页、下载和系统日志示例,请参考 使用 Python SDK 查询日志和指标。

管理模板和引擎

使用模板创建服务

从已有服务创建模板

创建、更新和删除模板

确认不再需要模板后再删除:

查询引擎版本

创建、更新或删除引擎版本通常属于平台管理操作。业务调用方一般只需要查询当前可用引擎和版本。

压测和接口一致性测试

创建测试任务前,建议先查询服务当前启用的测试类型;测试所需的资源规格、数据源和目标端点以当前服务端能力及集群配置为准。

创建压测任务

创建接口一致性测试

查询、停止、删除任务和获取报告

测试任务完成后,获取测试报告:
需要中止仍在运行的测试任务时:
确认不再需要测试任务及其记录后再删除:
get_load_test_report 会先读取任务的 test_type,压测任务返回 LoadTestReport,一致性测试返回 ConformanceReport。

驱逐 Pod

evict_pod 用于优雅驱逐一个推理 Pod,由其控制器重新创建。该接口属于运维能力,需要相应权限;生产环境建议先使用 dryRun=True 校验目标和权限,再执行实际驱逐。
nodeName 和 podName 为必填字段;workloadUUID、source、action、reason、operator 和 workloadName 为可选上下文。返回值包含 action 和 detail。

常见问题

创建或更新失败时,先检查什么? 先打印最终请求体,确认字段名、资源池、模型路径和角色配置是否符合服务端预期。
为什么建议更新前先 get_service()? update_service() 通常需要完整或接近完整的服务配置。先读取当前配置,再修改目标字段,可以减少误删已有配置的风险。 日志流式读取提示缺少依赖怎么办? 安装 WebSocket 依赖后重试:

相关文档