跳到主要内容

数据集健康度（Health）

健康度接口是一个聚合仪表盘，将画像（Profile）和入库统计（Ingestion）合并为单一响应，供前端健康度面板展示。

数据聚合模型​

响应结构​

GET /api/v1/datasets/{dataset_id}/health 返回 DatasetHealthResponse：

字段类型说明
dataset_idUUID数据集 ID
generated_atdatetime生成时间
profileDatasetProfileSummary画像摘要（含 token 分布、findings 等）
ingestionDatasetHealthIngestionSummary入库统计

DatasetHealthIngestionSummary​

字段类型说明
total_documentsint文档总数
by_statusdict按状态分布（key=status, value=count）
pendingint等待处理
processingint处理中
completedint已完成
failedint失败
quarantinedint已隔离
cancelledint已取消

API 示例​

curl "http://localhost:8000/api/v1/datasets/$DATASET_ID/health" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Authorization: Bearer $TOKEN"

响应示例：

{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "generated_at": "2026-04-02T10:30:00Z",
  "profile": {
    "total_documents": 156,
    "total_chunks": 4320,
    "token_percentiles": {"p25": 180, "p50": 320, "p75": 510, "p90": 720, "p99": 1100},
    "findings": [
      {"key": "short_chunks", "label": "短 chunk 比例偏高", "severity": "warning", "count": 42}
    ]
  },
  "ingestion": {
    "total_documents": 156,
    "completed": 150,
    "failed": 4,
    "processing": 2,
    "pending": 0,
    "quarantined": 0,
    "cancelled": 0
  }
}
健康度解读
  • ingestion.failed > 0：有文档处理失败，需检查错误原因并重试
  • profile.findings 中有 severity=error：存在严重质量问题，可能影响检索效果
  • processing 长时间不为 0：可能有文档卡在处理中，参见 排障

相关链接​