按需查阅，不是必读接入步骤。接入路线：[查询取数接入路线](/docs)

# 分析任务（Preview）

分析 API 把你已授权的数据范围固化为异步分析任务，或保存为持续分析订阅，适合需要复用 Whale 数据与向量能力的分析平台。

> 当前为 Preview：`knn_graph` 已可对已注册的 chunk 向量 profile 执行；`clustering`、`feature_rollup`、`deduplication` 可以创建，但执行时会标记为 `failed`。订阅调度尚未上线，暂不要依赖订阅做持续分析。

检索和读取已有数据请使用[关键词与语义检索](/docs/search)、[读取内容与历史](/docs/documents)和[增量同步数据](/docs/change-feed)。分析 API 不替代这些原子数据接口。

## 使用前提

使用 Consumer API Key 调用，不需要内部管理员 Token。你的应用需要具备目标数据集、平台、语言和地域的 entitlement，并且 Whale 平台需要在你的应用访问策略中开启：


```json
{
  "analysis_enabled": true
}
```


向量相关任务还需要一个已注册且 active 的 `embedding_profile_id`。当前生产搜索向量以文本 chunk 为粒度，不能直接当作商品、listing 或应用级向量使用。

## 创建一次性任务


```bash
run_response="$(curl -sS --fail-with-body -X POST "$WHALE_BASE_URL/v1/analysis/runs" \
  -H "Authorization: Bearer $WHALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_type": "knn_graph",
    "embedding_profile_id": "search_chunk_bge_m3_v1",
    "input_scope": {
      "dataset_ids": ["social_media_raw"],
      "source_platforms": ["xianyu"],
      "subject_types": ["chunk"],
      "published_from": "2026-10-01T00:00:00Z"
    },
    "parameters": {"k": 30, "min_similarity": 0.72},
    "retention_days": 14
  }')"
printf '%s' "$run_response" | jq .
RUN_ID="$(printf '%s' "$run_response" | jq -er '.run_id')"
```


| 字段 | 必填 | 说明 |
| --- | ---: | --- |
| `analysis_type` | 是 | `knn_graph`、`clustering`、`feature_rollup` 或 `deduplication`；当前只有 `knn_graph` 会实际执行 |
| `input_scope.dataset_ids` | 是 | 至少一个已授权数据集 |
| `input_scope.source_platforms` / `languages` / `regions` / `content_types` / `subject_types` | 否 | 只能缩小已有授权，不能扩大 |
| `input_scope.published_from` / `published_to` / `created_from` / `created_to` | 否 | RFC 3339 时间，按发布时间或入库时间限定范围 |
| `embedding_profile_id` | 条件 | 向量相关类型必填，必须是 active profile |
| `parameters.k` | 否 | `knn_graph` 每个节点的近邻数，1–100，默认 30 |
| `parameters.min_similarity` | 否 | `knn_graph` 的最小余弦相似度，-1 到 1，默认不过滤 |
| `input_cutoff_at` | 否 | 输入截止时间；省略时使用创建时刻，之后入库的数据不参与本次计算 |
| `retention_days` | 否 | 任务与产物保留天数，1–365，默认 30 |

单次任务的输入规模有上限（默认 5000 个 chunk）。超过时任务会以 `failed` 结束，请缩小 `input_scope`。

请求成功返回 `202`，任务处于 `queued`：


```json
{
  "run_id": "arun_01K...",
  "analysis_type": "knn_graph",
  "embedding_profile_id": "search_chunk_bge_m3_v1",
  "input_scope": {"dataset_ids": ["social_media_raw"], "source_platforms": ["xianyu"], "subject_types": ["chunk"]},
  "input_cutoff_at": "2026-10-14T08:00:00Z",
  "status": "queued",
  "created_at": "2026-10-14T08:00:00Z",
  "expires_at": "2026-10-28T08:00:00Z"
}
```


## 跟踪任务与读取结果


```bash
curl -sS --fail-with-body "$WHALE_BASE_URL/v1/analysis/runs/$RUN_ID" \
  -H "Authorization: Bearer $WHALE_API_KEY" | jq '{status, error, started_at, completed_at}'
```


`status` 依次为 `queued`、`validating`、`running`，最终为 `succeeded`、`failed`、`cancelled` 或 `expired`。`failed` 时 `error` 说明原因。从 5 秒间隔开始轮询并逐步退避。

任务成功后列出产物并下载：


```bash
curl -sS --fail-with-body "$WHALE_BASE_URL/v1/analysis/runs/$RUN_ID/artifacts" \
  -H "Authorization: Bearer $WHALE_API_KEY" | jq .

curl -sS --fail-with-body -o knn-graph.parquet \
  "$WHALE_BASE_URL/v1/analysis/runs/$RUN_ID/artifacts/$ARTIFACT_ID/file" \
  -H "Authorization: Bearer $WHALE_API_KEY"
```


每个产物包含 `artifact_id`、`format`（`parquet`）、`rows`、`bytes`、`checksum` 和 `expires_at`。`knn_graph` 产物是一张 ZSTD 压缩的 Parquet 边表：

| 列 | 说明 |
| --- | --- |
| `source_subject_id` / `target_subject_id` | 源与近邻的 chunk ID |
| `source_document_id` / `target_document_id` | 所属文档 ID，可用[读取内容与历史](/docs/documents)读取 |
| `source_version_id` / `target_version_id` | 计算时使用的文档版本 |
| `rank` | 近邻排名，从 1 开始 |
| `similarity` | 余弦相似度 |

计算按 `input_cutoff_at` 选定当前已索引的 chunk，并做精确余弦 Top-K，不是近似检索。产物不包含正文或原始向量。

取消尚未完成的任务：


```bash
curl -sS --fail-with-body -X POST "$WHALE_BASE_URL/v1/analysis/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $WHALE_API_KEY"
```


## 创建持续分析订阅

订阅保存固定的范围、profile、参数和执行策略。调度上线后，每次成功计算会产生独立 run；你通过轮询 run 游标读取，不使用 Webhook。


```bash
curl -sS --fail-with-body -X POST "$WHALE_BASE_URL/v1/analysis/subscriptions" \
  -H "Authorization: Bearer $WHALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "xianyu-semantic-watch",
    "analysis_type": "knn_graph",
    "embedding_profile_id": "search_chunk_bge_m3_v1",
    "input_scope": {
      "dataset_ids": ["social_media_raw"],
      "source_platforms": ["xianyu"],
      "subject_types": ["chunk"]
    },
    "execution_mode": "hybrid",
    "interval_seconds": 900,
    "artifact_retention_days": 30
  }'
```


`name`、`analysis_type`、`input_scope` 和 `execution_mode` 必填。`execution_mode` 可以是 `on_change`、`scheduled` 或 `hybrid`；`interval_seconds` 最小 60。订阅状态为 `active`、`paused`、`disabled` 或 `reconciliation_required`。当前调度尚未上线，订阅不会自动创建 run，`runs` 和 `checkpoint` 通常为空。


```text
GET  /v1/analysis/subscriptions
POST /v1/analysis/subscriptions/{subscription_id}/pause
POST /v1/analysis/subscriptions/{subscription_id}/resume
GET  /v1/analysis/subscriptions/{subscription_id}/runs?after={cursor}
GET  /v1/analysis/subscriptions/{subscription_id}/checkpoint
```


## 错误

| HTTP | code | 含义与处理 |
| --- | --- | --- |
| 400 | `invalid_analysis_request` / `invalid_analysis_subscription` | 请求体字段缺失或不合法，按 `message` 修正 |
| 400 | `analysis_request_failed` | 业务校验失败，例如 profile 不存在或不是 active |
| 401 | `unauthorized` | Consumer API Key 无效 |
| 403 | `analysis_forbidden` | 应用未开启 `analysis_enabled`，或 `input_scope` 超出授权 |
| 404 | `analysis_not_found` / `analysis_artifact_not_found` | 任务、订阅或产物不存在，或不属于你的应用 |
| 429 | `rate_limit_exceeded` | 超过限流，按 `Retry-After` 退避 |

## 保留与数据边界

一次性任务默认保留 30 天，可通过 `retention_days` 设置 1 至 365 天。订阅使用 `artifact_retention_days` 设置结果的保留期，范围同样为 1 至 365 天。

到期清理只作用于分析运行和派生产物，不会删除文档、正文、事实、指标快照或向量。当前不处理源对象的删除、不可访问或下架：分析结论代表 `input_cutoff_at` 时刻已观测、且在授权范围内的输入。

完整字段见[公开 API Reference](/public-api-reference)。

## 下一步

需要持续同步原子数据时，先接入[增量同步数据](/docs/change-feed)。需要先验证范围与内容时，使用[关键词与语义检索](/docs/search)和[读取内容与历史](/docs/documents)。

## 继续当前任务

[返回接入路线](/docs)；查完所需信息后，回到正在执行的步骤。