> ## 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.

# 为训练任务配置自动干预护栏

> 获取或更新运行中任务的自动干预规则。当指标在可配置窗口内越过阈值时触发规则。

自动干预允许你定义护栏规则，在训练指标偏离基线时触发。你可以为 reward 突增、KL 散度爆炸、回复长度激增与重复率上升配置规则。仅运行中的任务可更新其自动干预配置。

## 方法与路径

```http theme={null}
GET /v1/jobs/:id/auto-intervention
PUT /v1/jobs/:id/auto-intervention
```

## 认证

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

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

## 路径参数

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

## GET 响应

在标准 PIN 信封中返回该任务当前的自动干预配置。

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

<ResponseField name="data" type="object" required>
  <Expandable title="属性">
    <ResponseField name="enabled" type="boolean">
      自动干预是否启用。
    </ResponseField>

    <ResponseField name="rules" type="array">
      规则列表。

      <Expandable title="规则对象">
        <ResponseField name="id" type="string">
          唯一的规则标识符。
        </ResponseField>

        <ResponseField name="metric" type="string">
          监听的指标：`reward`、`kl`、`response_len`、`repeat`。
        </ResponseField>

        <ResponseField name="condition" type="string">
          条件类型：`spike`、`drop`、`kl_explode`、`len_surge`、`repeat_up`。
        </ResponseField>

        <ResponseField name="window_steps" type="integer">
          长期窗口大小（以步为单位，10 到 100000）。
        </ResponseField>

        <ResponseField name="threshold" type="number">
          触发所需的比率阈值（必须大于 0）。
        </ResponseField>

        <ResponseField name="min_consecutive" type="integer">
          触发前所需的连续命中次数（1 到 window\_steps）。
        </ResponseField>

        <ResponseField name="action" type="string">
          采取的动作：`stop` 或 `update_hyperparams`。
        </ResponseField>

        <ResponseField name="hyperparams" type="object">
          当动作为 `update_hyperparams` 时的新超参数。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cooldown_seconds" type="integer">
      同一规则重复触发之间的冷却时间。
    </ResponseField>
  </Expandable>
</ResponseField>

### GET 响应示例

```json theme={null}
{
  "code": 0,
  "data": {
    "enabled": true,
    "rules": [
      {
        "id": "reward_spike",
        "metric": "reward",
        "condition": "spike",
        "window_steps": 100,
        "threshold": 2.0,
        "min_consecutive": 3,
        "action": "stop"
      }
    ],
    "cooldown_seconds": 300
  },
  "message": ""
}
```

## PUT 请求体

<ParamField body="enabled" type="boolean" required>
  开启或关闭自动干预。
</ParamField>

<ParamField body="rules" type="array" required>
  规则对象列表（见上述结构）。
</ParamField>

<ParamField body="cooldown_seconds" type="integer" required>
  同一规则重复触发之间的最小秒数（不得为负）。
</ParamField>

### 请求体示例

```json theme={null}
{
  "enabled": true,
  "rules": [
    {
      "id": "reward_spike",
      "metric": "reward",
      "condition": "spike",
      "window_steps": 100,
      "threshold": 2.0,
      "min_consecutive": 3,
      "action": "stop"
    },
    {
      "id": "kl_explode",
      "metric": "kl",
      "condition": "kl_explode",
      "window_steps": 50,
      "threshold": 3.0,
      "min_consecutive": 2,
      "action": "update_hyperparams",
      "hyperparams": {
        "lr": 0.000005,
        "group_size": 2
      }
    }
  ],
  "cooldown_seconds": 300
}
```

## PUT 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X PUT "https://api.ariacompute.com/v1/jobs/jb_abc123def456/auto-intervention" \
    -H "Authorization: Bearer $PIN_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "rules": [
        {
          "id": "reward_spike",
          "metric": "reward",
          "condition": "spike",
          "window_steps": 100,
          "threshold": 2.0,
          "min_consecutive": 3,
          "action": "stop"
        }
      ],
      "cooldown_seconds": 300
    }'
  ```
</CodeGroup>

## PUT 响应

在标准 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="auto_intervention" type="object">
      更新后的配置。
    </ResponseField>
  </Expandable>
</ResponseField>

### PUT 响应示例

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "jb_abc123def456",
    "auto_intervention": {
      "enabled": true,
      "rules": [
        {
          "id": "reward_spike",
          "metric": "reward",
          "condition": "spike",
          "window_steps": 100,
          "threshold": 2.0,
          "min_consecutive": 3,
          "action": "stop"
        }
      ],
      "cooldown_seconds": 300
    }
  },
  "message": ""
}
```

## 错误

| Code | HTTP | 含义                                               |
| ---- | ---- | ------------------------------------------------ |
| 401  | 401  | 缺失或无效的 Bearer 令牌。                                |
| 404  | 404  | 任务不存在、不属于你，或自动干预已被全局禁用。                          |
| 409  | 409  | 任务未在运行（仅运行中的任务可被更新）。                             |
| 422  | 422  | 无效的规则配置（重复 ID、无效的 metric/condition/action、数值越界）。 |