V2 独立版愿景

任务接口

HeteroFlow 是本站的异构算力与大模型调度产品。任务接口。任务接口 HeteroFlow V2 的任务接口提供完整的任务生命周期管理 API，包括任务的创建、查询、更新、删除，以及任务状态控制（睡眠、唤醒、停止）。 接口概览 方法 路径 说明 认证 ------ ------ ------ ------ POST 创建任务 Bearer…

任务接口

HeteroFlow V2 的任务接口提供完整的任务生命周期管理 API，包括任务的创建、查询、更新、删除，以及任务状态控制（睡眠、唤醒、停止）。

接口概览

方法路径说明认证
POST/api/v1/tasks创建任务Bearer Token
GET/api/v1/tasks获取任务列表Bearer Token
GET/api/v1/tasks/:id获取任务详情Bearer Token
PUT/api/v1/tasks/:id更新任务Bearer Token
DELETE/api/v1/tasks/:id删除任务Bearer Token
POST/api/v1/tasks/:id/sleep睡眠任务Bearer Token
POST/api/v1/tasks/:id/wake唤醒任务Bearer Token
POST/api/v1/tasks/:id/stop停止任务Bearer Token
GET/api/v1/tasks/:id/logs获取任务日志Bearer Token
GET/api/v1/tasks/:id/retries获取重试历史Bearer Token

任务状态流转

                    ┌──────────┐
                    │ PENDING  │ ← 创建任务
                    └────┬─────┘
                         │ 调度成功
                         ▼
                    ┌──────────┐    sleep     ┌──────────┐
              ┌────→│ RUNNING  │────────────→│ SLEEPING │
              │     └────┬─────┘             └────┬─────┘
              │          │                        │ wake
              │          │ stop            ┌──────┘
              │          ▼                 ▼
              │     ┌──────────┐    ┌──────────┐
              │     │ STOPPED  │    │ RUNNING  │ ← 唤醒
              │     └──────────┘    └──────────┘
              │
     重试      │
              │
              └────────────────────────────────→ RUNNING（新节点/原节点）

                    ┌──────────┐
                    │ SUCCESS  │ ← 任务完成
                    └──────────┘

                    ┌──────────┐
                    │ FAILED   │ ← 任务失败（重试次数用尽）
                    └──────────┘
状态说明
PENDING等待调度
RUNNING正在运行
SLEEPING休眠中（容器暂停）
STOPPED已停止（可重新启动）
SUCCESS执行成功
FAILED执行失败

---

创建任务

请求

POST /api/v1/tasks
Authorization: Bearer <token>
Content-Type: application/json
{
  "name": "gpu-training-job",
  "image": "pytorch/pytorch:2.0-cuda11.7",
  "command": "python train.py --epochs 100 --lr 0.001",
  "gpu_count": 2,
  "gpu_type": "NVIDIA",
  "memory_mb": 8192,
  "cpu_cores": 4,
  "env": {
    "CUDA_VISIBLE_DEVICES": "0,1",
    "BATCH_SIZE": "32"
  },
  "volumes": [
    {
      "host_path": "/data/models",
      "container_path": "/workspace/models",
      "read_only": true
    }
  ],
  "retry_strategy": "retry_new_node",
  "max_retries": 3,
  "priority": 1,
  "labels": {
    "team": "ml-team",
    "project": "image-classification"
  }
}
字段类型必填默认值说明
namestring是-任务名称
imagestring是-Docker 镜像
commandstring否-执行命令
gpu_countint否0GPU 数量
gpu_typestring否""GPU 类型偏好
memory_mbint否2048内存限制（MB）
cpu_coresint否1CPU 核心数
envmap否{}环境变量
volumesarray否[]挂载卷
retry_strategystring否retry_new_node重试策略
max_retriesint否3最大重试次数
priorityint否0优先级（数字越大优先级越高）
labelsmap否{}自定义标签

响应

成功 (201):

{
  "id": "task-abc123",
  "name": "gpu-training-job",
  "status": "PENDING",
  "image": "pytorch/pytorch:2.0-cuda11.7",
  "gpu_count": 2,
  "memory_mb": 8192,
  "node_id": null,
  "created_at": "2026-05-20T10:30:00Z",
  "updated_at": "2026-05-20T10:30:00Z"
}

---

获取任务列表

请求

GET /api/v1/tasks?page=1&per_page=20&status=RUNNING&sort=created_at&order=desc
Authorization: Bearer <token>
参数类型说明
pageint页码（默认 1）
per_pageint每页条数（默认 20）
statusstring按状态过滤
node_idstring按节点过滤
namestring按名称搜索
sortstring排序字段（created_at/updated_at/priority）
orderstring排序方向（asc/desc）
labelsstring按标签过滤（key=value 格式）

响应

成功 (200):

{
  "tasks": [
    {
      "id": "task-abc123",
      "name": "gpu-training-job",
      "status": "RUNNING",
      "image": "pytorch/pytorch:2.0-cuda11.7",
      "gpu_count": 2,
      "memory_mb": 8192,
      "node_id": "node-1",
      "node_name": "GPU-Server-A",
      "retry_count": 0,
      "priority": 1,
      "created_at": "2026-05-20T10:30:00Z",
      "updated_at": "2026-05-20T10:31:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

---

获取任务详情

请求

GET /api/v1/tasks/task-abc123
Authorization: Bearer <token>

响应

成功 (200):

{
  "id": "task-abc123",
  "name": "gpu-training-job",
  "status": "RUNNING",
  "image": "pytorch/pytorch:2.0-cuda11.7",
  "command": "python train.py --epochs 100 --lr 0.001",
  "gpu_count": 2,
  "gpu_type": "NVIDIA",
  "memory_mb": 8192,
  "cpu_cores": 4,
  "env": {
    "CUDA_VISIBLE_DEVICES": "0,1",
    "BATCH_SIZE": "32"
  },
  "node_id": "node-1",
  "node_name": "GPU-Server-A",
  "container_id": "abc123def456",
  "retry_count": 0,
  "retry_strategy": "retry_new_node",
  "max_retries": 3,
  "priority": 1,
  "labels": {
    "team": "ml-team"
  },
  "started_at": "2026-05-20T10:31:00Z",
  "created_at": "2026-05-20T10:30:00Z",
  "updated_at": "2026-05-20T10:31:00Z"
}

失败 - 任务不存在 (404):

{
  "error": "task not found",
  "code": 40401
}

---

更新任务

仅允许更新 PENDING 状态的任务。

请求

PUT /api/v1/tasks/task-abc123
Authorization: Bearer <token>
Content-Type: application/json
{
  "memory_mb": 16384,
  "command": "python train.py --epochs 200 --lr 0.0005"
}

响应

成功 (200):

{
  "id": "task-abc123",
  "status": "PENDING",
  "memory_mb": 16384,
  "command": "python train.py --epochs 200 --lr 0.0005",
  "updated_at": "2026-05-20T11:00:00Z"
}

失败 - 任务已在运行 (400):

{
  "error": "cannot update a running task",
  "code": 40020
}

---

删除任务

删除任务及其关联数据。运行中的任务会先被停止。

请求

DELETE /api/v1/tasks/task-abc123
Authorization: Bearer <token>

响应

成功 (200):

{
  "message": "task deleted successfully",
  "id": "task-abc123"
}

---

睡眠任务

暂停正在运行的任务（发送 SIGSTOP 到容器），释放 GPU 资源但保留内存状态。

请求

POST /api/v1/tasks/task-abc123/sleep
Authorization: Bearer <token>

响应

成功 (200):

{
  "id": "task-abc123",
  "status": "SLEEPING",
  "message": "task put to sleep, GPU resources released"
}

失败 - 任务状态不正确 (400):

{
  "error": "task is not running, current status: PENDING",
  "code": 40030
}

---

唤醒任务

唤醒处于 SLEEPING 状态的任务（发送 SIGCONT 到容器），重新分配 GPU 资源。

请求

POST /api/v1/tasks/task-abc123/wake
Authorization: Bearer <token>

响应

成功 (200):

{
  "id": "task-abc123",
  "status": "RUNNING",
  "message": "task woke up, GPU resources reassigned"
}

---

停止任务

强制停止运行中的任务。

请求

POST /api/v1/tasks/task-abc123/stop
Authorization: Bearer <token>

响应

成功 (200):

{
  "id": "task-abc123",
  "status": "STOPPED",
  "message": "task stopped successfully"
}

---

获取任务日志

获取任务的实时日志输出。

请求

GET /api/v1/tasks/task-abc123/logs?lines=100&follow=false
Authorization: Bearer <token>
参数类型说明
linesint获取最后 N 行（默认 100）
followbool是否持续获取（SSE 流式）

响应

成功 (200):

{
  "task_id": "task-abc123",
  "logs": [
    "[2026-05-20 10:31:00] Starting training...",
    "[2026-05-20 10:31:05] Loading model weights...",
    "[2026-05-20 10:31:10] Epoch 1/100 - Loss: 2.3456"
  ]
}

---

获取重试历史

查看任务的所有重试记录。

请求

GET /api/v1/tasks/task-abc123/retries
Authorization: Bearer <token>

响应

成功 (200):

{
  "task_id": "task-abc123",
  "total_retries": 2,
  "retries": [
    {
      "attempt": 1,
      "node_id": "node-1",
      "status": "failed",
      "error": "OOM Killed",
      "memory_mb": 4096,
      "started_at": "2026-05-20T10:30:00Z",
      "finished_at": "2026-05-20T10:30:45Z"
    },
    {
      "attempt": 2,
      "node_id": "node-2",
      "status": "running",
      "error": null,
      "memory_mb": 8192,
      "started_at": "2026-05-20T10:32:00Z",
      "finished_at": null
    }
  ]
}

错误码汇总

HTTP 状态码错误码说明
40040020无法更新运行中的任务
40040030任务状态不正确
40440401任务不存在
50050001调度失败
50050002节点不可达