使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/suanleme/gongji-skills --skill suanli-job开始前需了解
- 安装不包含模型订阅、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`,避免重复生成请求代码。
计费与价格
平台按秒计费,内部计量单位为点(与 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