Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/suanleme/gongji-skills --skill suanli-jobAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
共绩算力 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`,避免重复生成请求代码。
计费与价格
平台按秒计费,内部计量单位为点(与 Job 完成次数 points 不同)。
| 换算 | 公式 |
|---|---|
| 元 ↔ 点 | 1 元 = 1,000,000 点 |
| 卡时价 → 每秒点数 | 点/秒 = 卡时价(元/小时) × 1,000,000 / 3600 |
| 点 → 用户消耗(元) | 元 = 点 / 1,000,000 |
示例:卡时价 1.98 元/小时 → 每秒 1.98 × 1,000,000 / 3600 ≈ 550 点;运行 1 小时消耗 550 × 3600 = 1,980,000 点 = 1.98 元。
出账周期:平台每 5 分钟出账一次;出账前实时消耗见 forecast_value,已出账累计见 billing_value。
| 字段 | 来源 | 说明 |
|---|---|---|
price / discount_price | 资源列表 regions[] | 设备卡时参考价(元/小时);计费优先按 discount_price |
billing_value | 任务详情/列表 | 已累计出账消耗(点) |
forecast_value | 任务详情/列表 | 当前周期尚未出账的实时消耗(点) |
billing_points | 任务详情 | 计费中 Pod 数 |
向用户展示金额时,将 billing_value、forecast_value、billing_coin、discount_coin 除以 1,000,000 转为元;预估费用可用「卡时价 × 运行小时数」或「每秒点数 × 运行秒数 / 1,000,000」。
历史账单(按时间段或任务汇总):
| 字段 | 来源 | 说明 |
|---|---|---|
billing_coin | 计费查询接口 | 时间段/任务总账(点) |
discount_coin | 计费查询接口 | 优惠抵扣(点) |
端点速查
| 操作 | 方法 | 路径 |
|---|---|---|
| 创建 Job | POST | /task/job/create |
| 任务详情 | GET | /task/job/detail?task_id= |
| 任务列表 | GET | /task/job/search |
| 停止任务 | POST | /task/job/stop |
| 任务组列表 | GET | /job/queue/group/search?queue_id= |
| 任务组详情 | GET | /job/queue/group/detail?group_id= |
| 时间维度计费 | GET | /billing/get_billing_record |
| 任务维度计费 | GET | /billing/get_task_billing_record |
| 设备资源 | GET | /deployment/resource/search |
| 对象存储 | GET | /storage/get_storage |
完整字段见 `api/` 下对应文档;仅在构造复杂 body 时读取,勿整篇加载。
工作流
询问用户是否要先进行镜像预热,提前把任务所需的镜像准备到目标计算资源附近,可以降低任务冷启动时间,如果使用者需要:请使用 suanli-preheat 这个 skill。
1. 创建 Job
- 查资源(取
mark与resource)
GET /deployment/resource/search?task_type=Job&device_type=GpuDevice 从 data.results[].regions[] 取 inventory > 0 的条目:mark.mark、mark.resource、region_name。
- (可选)挂载存储(三类字段勿混用)
| 字段 | 用途 | storage_id 来源 |
|---|---|---|
storage_config | 对象存储加速(JuiceFS) | /storage/get_storage |
share_storage_config | 共享存储 | /storage/get_storage |
nas_storage_config | NAS 集群存储卷 | suanli-nas-storage 的 /storage/nas/v1/list |
JuiceFS:GET /storage/get_storage?storage_type=Juicefs&status=Activate。 NAS:卷须 Active,地域与任务 resources[].region_name 一致;创建/扩容卷切到 suanli-nas-storage。 见 api/object-storage.md · api/job-create.md。
- 选任务类型(默认 Spot,见下节)后提交创建。
任务类型(默认 Spot):
| 模式 | sub_type | 额外必填 |
|---|---|---|
| Spot(默认) | "Spot" | job_support.estimated_exec_sec(预估运行秒数,1–86400,略长于实际运行、略短于 timeout) |
| OnDemand | 不传或 null | 无 |
默认 Spot;仅以下情况改发 OnDemand:
- 用户明确要求 OnDemand / 按需任务
- 资源列表无可用库存(
inventory <= 0或无匹配 region/device),或 Spot 创建失败且错误指向资源不可用
Spot 创建 body 示例:
{
"task_name": "<名称>",
"sub_type": "Spot",
"resources": [{ "mark": "<mark>", "resource": { /* 来自资源接口 */ }, "region_name": "<区域名>" }],
"points": 1,
"job_support": {
"estimated_exec_sec": 3600,
"timeout_sec": 7200,
"parallelism": 1,
"mod_param": { "default": { "backoff_limit": 3, "restart_policy": "OnFailure" } }
},
"services": [{
"service_name": "container-01",
"service_image": "<镜像>",
"resource_weight": { "cpu_weight": 1, "mem_weight": 1, "gpu_weight": 1 },
"start_script": { "command": ["<cmd>"], "args": ["..."] },
"nas_storage_config": [{ "storage_id": 1001, "target_dir": "/mnt/nas" }]
}]
}OnDemand 时去掉 sub_type(或设 null),并移除 estimated_exec_sec。
- 共享卷:先声明
share_disk_volumes/share_mem_volumes,再在services配share_disk_config/share_mem_config。 - NAS:
nas_storage_config[].storage_id+target_dir(容器内挂载路径);不挂 NAS 时省略该字段。 - 成功返回
data.task_id。
示例与可选字段:api/job-create.md
2. 查询状态
- 单任务:
GET /task/job/detail?task_id=<id> - 列表:
GET /task/job/search?status=Running&page=1&page_size=20
可选 query:status(逗号分隔 Pending/Running/Paused/End)、search_value(任务名,URL 编码)、分页。
状态字段:
| 字段 | 值 | 含义 |
|---|---|---|
status | Pending / Running / Paused / End | 任务生命周期 |
job_status.status | Pending / Manual / Running / Complete / Failed | Job 执行状态 |
schedule_status | Scheduled / Queued | 仅 Spot |
轮询建议:间隔 ≥10s,Complete/Failed/Paused/End 或用户取消时停止。关注消耗时可一并展示 billing_value、forecast_value(换算见计费节);有 NAS 时看 services[].nas_storage_config。
详情:api/job-detail.md · 列表:api/job-tasks.md
3. 停止任务
POST /task/job/stop
{ "task_id": <id> }仅对 Running/Pending 有效。见 api/job-stop.md
4. Job 任务队列
查询已有队列下的任务组。返回的 task_dto.services[].nas_storage_config 为 NAS 挂载配置。
- 列表:
GET /job/queue/group/search?queue_id=<id>&page=1&page_size=10 - 详情:
GET /job/queue/group/detail?group_id=<id>
见 api/job-queue-list.md · api/job-queue-detail.md
5. 历史计费查询
必填 query:range(hour/day/week/month)、start_time、end_time(RFC3339,如 2026-01-01T00:00:00+08:00)。
- 按时间汇总:
GET /billing/get_billing_record?range=day&start_time=...&end_time=...
可选 task_ids(逗号分隔,空表示全部任务)、分页。 返回各时间段 billing_coin、discount_coin。
- 按任务汇总:
GET /billing/get_task_billing_record?range=day&start_time=...&end_time=...
可选分页。返回 task_id、task_type、task_name、billing_coin、discount_coin。
Job 实时消耗优先看任务详情/列表的 billing_value、forecast_value;历史汇总用上述计费接口。展示金额时将 billing_coin、discount_coin 除以 1,000,000 转为元。
详情:api/fee-time-query.md · api/fee-task-query.md
对话执行约定
- 缺 token 时先向用户索取,勿猜测。
- 强烈建议用户先进行镜像预热,提前把任务所需的镜像准备到目标计算资源附近,可以降低任务冷启动时间,如果使用者需要:请使用 suanli-preheat 这个 skill。
- 创建前确认:镜像、资源规格(或让用户选 region/device)、启动命令、并行度/完成次数;挂 NAS 时确认卷
storage_id、挂载路径、卷为 Active 且地域匹配。未指定任务类型时默认 Spot,并向用户确认estimated_exec_sec(或根据脚本/命令时长估算)。 - 查资源时优先选
inventory > 0的 region;全无库存再告知用户并改发 OnDemand(或换规格)。 - 创建成功后回报
task_id及任务类型(Spot/OnDemand);Spot 任务关注schedule_status(Scheduled/Queued)。询问是否轮询;轮询只展示 status、jobstatus、succeededpods/failed_pods。 - 错误时输出
code+message;资源类错误尝试 OnDemand 降级前先征得用户同意(若用户未明确要求 OnDemand)。 - 查历史账单时向用户确认时间范围与粒度(
range);start_time/end_time用 RFC3339。 - 加签失败时建议用户换简易模式密钥,或提供私钥。
脚本
export SUANLI_TOKEN="<密钥>"
# GET
./scripts/call.sh GET /task/job/search "status=Running&page=1&page_size=10"
./scripts/call.sh GET /job/queue/group/search "queue_id=1&page=1&page_size=10"
./scripts/call.sh GET /job/queue/group/detail "group_id=1"
./scripts/call.sh GET /billing/get_billing_record "range=day&start_time=2026-01-01T00:00:00%2B08:00&end_time=2026-01-31T23:59:59%2B08:00&task_ids=123"
./scripts/call.sh GET /billing/get_task_billing_record "range=day&start_time=2026-01-01T00:00:00%2B08:00&end_time=2026-01-31T23:59:59%2B08:00"
# POST
./scripts/call.sh POST /task/job/stop '{"task_id":123}'
./scripts/call.sh POST /task/job/create @payload.json # @ 文件为 body