使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/suanleme/gongji-skills --skill suanli-image-preheat开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
共绩算力 Job 批处理 API
前置
向用户确认凭证(平台:右上角头像 → API 密钥)。模板见 `.env.example`,复制为 .env 后填入,勿提交 .env。
| 变量 | 说明 |
|---|---|
SUANLI_TOKEN | API 密钥(推荐简易模式,无需加签) |
SUANLI_RSA_PRIVATE_KEY | 非简易模式时 RSA 私钥(Base64),用于 sign_str |
SUANLI_BASE_URL | 默认 https://openapi.suanli.cn |
公共 Header(所有请求):
token: <SUANLI_TOKEN>
timestamp: <毫秒时间戳>
version: 1.0.0
sign_str: <非简易模式必填,见下>
Content-Type: application/json # POST 时加签(非简易模式):对字符串 /api{path含query}\n{version}\n{timestamp}\n{token}\n{body} 用 RSA 私钥 PKCS#1 v1.5 + SHA256 签名,Base64 为 sign_str;解码后须 256 字节,否则换新 timestamp 重签。GET 时 body 为空串。
响应:{ code, message, data };code === "0000" 成功,否则 data 为 null。
简易模式优先用 `scripts/call.sh`,避免重复生成请求代码。
端点速查
| 操作 | 方法 | 路径 |
|---|---|---|
| 镜像预热任务可用集群列表 | GET | /api/task/image_preheat/get_regions |
| 镜像预热任务列表查询接口 | GET | /api/task/image_preheat/search |
| 镜像预热任务详情查询接口 | GET | /api/task/image_preheat/detail |
| 镜像预热任务创建接口 | POST | /api/task/image_preheat/create |
| 镜像预热任务更新接口 | POST | /api/task/image_preheat/update |
| 镜像预热任务停止接口 | POST | /api/task/image_preheat/stop |
完整字段见 `api/` 下对应文档;仅在构造复杂 body 时读取,勿整篇加载。
工作流
1. 创建镜像预热任务
- 选任务类型(默认 集群预热,见下节)后提交创建。
推荐用户选择集群预热
创建镜像预热任务时支持以下两种预热类型:
仅集群预热:提前将镜像缓存到目标集群,加速后续任务启动。该模式按区域执行,不指定具体资源规格、节点数量和调度策略。
节点预热:提前准备计算节点,减少任务启动时的拉取镜像等待时间。提前把机器准备好,但不会提前占用算力。该模式支持配置跨区调度策略。
- (可选)查集群 — 使用集群预热时
GET /api/task/image_preheat/get_regions 见 api/region-query.md。
- (可选)查资源(取
mark与resource) — 使用节点预热时
GET /deployment/resource/search?task_type=ImagePreHeat&device_type=GpuDevice 从 data.results[].regions[] 取条目:mark.mark、mark.resource、region_name。如果条目的inventory <= 0,告知用户“该集群当前无库存,预热行为将在GPU被释放后开始”
任务类型(默认 集群预热):
| 类型 | 字段 | 说明 |
|---|---|---|
| 节点预热 | points | 仅节点预热传。期望预热的节点数量,必须大于等于 1 |
| 节点预热 | scheduler_strategy | 仅节点预热传。用于跨区调度开关 |
| 节点预热 | resources | 仅节点预热传。参考上一节的 3. (可选)查资源 |
| 集群预热 | regions | 仅集群预热传。参考上一节的 2. (可选)查集群 |
- 集群预热 创建 body 示例:
{
"task_name": "<名称>",
"regions": [
{
"region": { /* 来自集群接口 */ },
"region_name": { /* 来自集群接口 */ }
}
],
"services": [
{
"service_image": "<镜像>",
"service_name": "container-01"
}
],
"task_type": "ImagePreHeat",
}集群预热 时无需传 resources、scheduler_strategy 和 points(或设 null)。
- 成功返回
data.task_id。
示例与可选字段:api/image-preheat-create.md
- 节点预热 创建 body 示例:
{
"task_name": "<名称>",
"points": "<期望的节点数>",
"resources": [
{
"mark": { /* 来自资源接口 */ },
}
],
"services": [
{
"service_image": "<镜像>",
"service_name": "container-01"
}
],
"task_type": "ImagePreHeat",
}节点预热 时无需传 regions(或设 null),必须传points、resources。
- 成功返回
data.task_id。
示例与可选字段:api/image-preheat-create.md
2. 查询状态
- 单任务:
GET /api/task/image_preheat/detail?task_id=<task_id> - 列表:
GET /api/task/image_preheat/search?page=1&page_size=10&search_value=&status=Paused,Running
可选 query:task_ids(逗号分隔任务id)、search_value(任务名)、分页。
轮询建议:每次轮询间隔时,将当前进度通知给使用者。间隔 ≥10s,对于集群预热任务:regioncacheinfo.[number].status 为 Completed 是已预热,当所有的集群都 Completed 时,代表所有集群都预热成功;对于节点预热:availablepoints为已预热节点数,points 为期望节点数,当 availablepoints >= points 时,为满足期望状态。或用户取消时停止。
详情:api/image-preheat-detail.md · 列表:api/image-preheat-list.md
3. 用已经预热的镜像去发任务
当预热的节点成功后,询问用户是否需要发JOB或者发弹性部署服务,并使用对应的skills进行操作:
| 发任务 | 要使用的skill |
|---|---|
| 发JOB任务 | suanli-job |
| 发弹性部署任务 | suanli-deployment |
4. 停止预热任务(停止的任务在ui上不可见)
POST /api/task/image_preheat/stop
{ "task_id": <task_id> }仅对 Running/Paused 有效。见 api/image-preheat-stop.md
TODO 对话执行约定
- 缺 token 时先向用户索取,勿猜测。
- 提前告知用户以下内容:预热是一种提前准备机制,不是资源预留,任务提交时仍需根据实时资源情况进行调度。
- 创建前确认:预热类型、镜像、如果是集群预热,需要向用户确认集群,如果是节点预热,需要向用户确认资源。
- 集群预热查集群时,需要同步查资源,并告诉用户每个集群下有什么规格的GPU,方便用户选择,一定要说明一个概念:集群预热。
- 创建成功后回报
task_id。询问是否轮询;集群预热轮询只展示集群预热状态,节点预热展示各集群卡型的已用数,已预热数量,期望预热数量。 - 错误时输出
code+message。 - 加签失败时建议用户换简易模式密钥,或提供私钥。
脚本
export SUANLI_TOKEN="<密钥>"
# GET
./scripts/call.sh GET /api/task/image_preheat/search "status=Running,Paused&page=1&page_size=10"
./scripts/call.sh GET /api/task/image_preheat/detail "task_id=123"
./scripts/call.sh GET /api/task/image_preheat/get_regions
# POST
./scripts/call.sh POST /api/task/image_preheat/stop '{"task_id":123}'
./scripts/call.sh POST /api/task/image_preheat/create @payload.json # @ 文件为 body