> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 手动干预运行中的训练任务

> 向运行中的任务发送手动干预，以停止训练或在线更新超参数。仅运行中的任务可被干预。

使用此接口手动干预运行中的训练任务。你可以立即停止任务，或在不重启容器的情况下热更部分超参数（学习率、epochs、beta、group size）。

## 方法与路径

```http theme={null}
POST /v1/jobs/:id/intervene
```

## 认证

在 `Authorization` 头中以 Bearer 令牌的形式携带你的 PIN API 令牌或 JWT。

```http theme={null}
Authorization: Bearer <token>
```

## 路径参数

<ParamField path="id" type="string" required>
  任务标识符（例如 `jb_abc123def456`）。
</ParamField>

## 请求体

<ParamField body="action" type="string" required>
  干预动作。必须为 `stop` 或 `update_hyperparams`。
</ParamField>

<ParamField body="reason" type="string" optional>
  可读的干预原因（记入审计日志）。
</ParamField>

<ParamField body="hyperparams" type="object" optional>
  当动作为 `update_hyperparams` 时的新超参数。仅以下字段可被热更：`lr`、`epochs`、`beta`、`group_size`。
</ParamField>

### 请求体示例

```json theme={null}
{
  "action": "update_hyperparams",
  "reason": "Reduce LR after spike",
  "hyperparams": {
    "lr": 0.00001,
    "epochs": 5
  }
}
```

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/intervene" \
    -H "Authorization: Bearer $PIN_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "update_hyperparams",
      "reason": "Reduce LR after spike",
      "hyperparams": {
        "lr": 0.00001,
        "epochs": 5
      }
    }'
  ```
</CodeGroup>

## 响应

返回标准的 PIN 成功信封，包含干预记录。

<ResponseField name="code" type="integer" required>
  成功为 `0`，出错为非零值。
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="属性">
    <ResponseField name="job_id" type="string">
      任务标识符。
    </ResponseField>

    <ResponseField name="action" type="string">
      所请求的动作。
    </ResponseField>

    <ResponseField name="status" type="string">
      干预状态：`pending`、`applied` 或 `failed`。
    </ResponseField>

    <ResponseField name="intervention_id" type="string">
      本次干预的唯一标识符。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  可读消息（成功时为空）。
</ResponseField>

### 响应示例

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "jb_abc123def456",
    "action": "update_hyperparams",
    "status": "pending",
    "intervention_id": "iv_7a8b9c0d1e2f"
  },
  "message": ""
}
```

## 错误

| Code | HTTP | 含义                   |
| ---- | ---- | -------------------- |
| 401  | 401  | 缺失或无效的 Bearer 令牌。    |
| 404  | 404  | 任务不存在、不属于你，或干预已被禁用。  |
| 409  | 409  | 任务未在运行（仅运行中的任务可被干预）。 |
| 422  | 422  | 无效的动作，或超参数包含不可热更的字段。 |