分析任务（Preview）

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

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

检索和读取已有数据请使用关键词与语义检索、读取内容与历史和增量同步数据。分析 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，可用读取内容与历史读取
`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 通常为空。

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。

下一步

需要持续同步原子数据时，先接入增量同步数据。需要先验证范围与内容时，使用关键词与语义检索和读取内容与历史。