---
title: Search Access
description: 消费方通过 API key 查询授权数据。
---

# 消费方数据获取

消费方通过 API key 调用检索接口。授权范围由 data product 和 entitlement 控制，canonical data 仍属于数据中心。消费方不直接访问数据库、对象存储、索引或向量库。

当前验证环境使用 `http://20.169.21.11`。所有请求必须携带：

```http
Authorization: Bearer whale_consumer_xxx
```

## 本页目录

| 章节 | 内容 |
| --- | --- |
| 接入流程 | 从拿到 API key 到完成首个查询 |
| 检索模式 | keyword、vector、hybrid 的适用场景 |
| 请求过滤 | 平台、数据集、时间、内容类型、语言等 |
| 文档详情 | 当前版本、完整正文、历史版本、快照、片段和事实 |
| 统计维度 | 平台、数据集、内容类型、时间窗口和处理状态 |
| 错误处理 | 常见错误语义 |

## 接入流程

```mermaid
sequenceDiagram
  participant Client as Consumer Client
  participant API as Whale API
  participant Auth as Entitlement
  participant Search as Search Backend
  participant Store as Content Store

  Client->>API: POST /v1/contents/search
  API->>Auth: validate API key and scope
  API->>Search: retrieve authorized chunks
  Search-->>API: ranked hits
  API-->>Client: document_id + snippet + score
  Client->>API: POST /v1/documents/batch-get
  API->>Auth: validate document access
  API->>Store: load details and latest snapshot
  API-->>Client: document cards
```

生产接入建议先用小时间窗口和明确平台验证结果，再扩大查询范围。

## 检索模式

外部消费方优先使用统一入口 `POST /v1/contents/search`，通过 `mode` 选择检索模式。旧的 `/v1/search/keyword`、`/v1/search/vector`、`/v1/search/hybrid` 保留为兼容和专项调试接口。

| API | 适合场景 | 说明 |
| --- | --- | --- |
| `POST /v1/contents/search` | 推荐外部入口 | `mode` 可选 `keyword`、`vector`、`hybrid` |
| `POST /v1/search/keyword` | 精确词、品牌、人名、URL、话题 | 结果可解释，适合确定性召回 |
| `POST /v1/search/vector` | 语义相似、跨语言、表达不一致 | 可只传 `query`，由服务端生成 query embedding |
| `POST /v1/search/hybrid` | 默认推荐 | 融合词面召回、向量召回、质量分和时效分 |

`mode` 省略时，没有 `query_vector` 默认走 `keyword`；传了 `query_vector` 默认走 `hybrid`。

统一入口默认返回文档级结果，同一页同一个 `document_id` 只出现一次。`body` 是最佳命中分块摘要，不是完整正文；需要分块明细时传 `include_chunks=true`。

## 请求过滤

常用过滤维度：

| 过滤维度 | 示例 | 说明 |
| --- | --- | --- |
| `dataset_id` | `social_media_raw` | 数据产品或数据域 |
| `source_platform` | `youtube`, `weibo`, `xianyu` | 来源平台 |
| `content_type` | `video`, `article`, `product` | 内容类型 |
| `published_from/to` | `2026-08-01T00:00:00Z` | 平台发布时间窗口 |
| `language` | `zh`, `en` | 内容语言 |
| `region` | `CN`, `US` | 平台或内容区域 |
| `facts` | `price <= 100`, `company=Example` | 结构化事实筛选 |

示例请求：

```json
{
  "mode": "hybrid",
  "query": "AI 视频生成",
  "dataset_ids": ["social_media_raw"],
  "source_platforms": ["youtube", "bilibili", "xiaohongshu"],
  "published_from": "2026-08-01T00:00:00Z",
  "published_to": "2026-09-01T00:00:00Z",
  "languages": ["zh", "en"],
  "top_k": 20
}
```

## 文档详情

统一入口检索结果是文档级。需要完整文档时，先从检索结果取 `document_id`，再调用：

- `POST /v1/documents/batch-get`：批量读取文档元数据、当前版本、可选完整正文、最新快照、片段和事实
- `GET /v1/documents/{document_id}`：文档元数据和当前版本
- `GET /v1/documents/{document_id}/content`：当前版本完整正文
- `GET /v1/documents/{document_id}/content?version_id=ver_xxx`：指定版本完整正文
- `GET /v1/documents/{document_id}/versions`：正文版本历史
- `GET /v1/documents/{document_id}/snapshots`：指标、作者状态和平台状态快照历史
- `GET /v1/documents/{document_id}/parts`：字幕、OCR、规格、章节等多内容片段
- `GET /v1/documents/{document_id}/facts`：价格、公司、地点、技能等结构化事实

正文、标题、URL、字幕、规格等内容变化会生成新版本；点赞、评论、播放、粉丝数、价格、库存等随时间变化的数据应从 snapshots 读取趋势。`parts` 面向可读片段，`facts` 面向可筛选和可聚合的结构化字段。

外部响应不会返回 Blob/R2 的 raw、text、manifest 或 part object key；完整正文和片段内容必须通过授权 API 获取。

列表页建议先用 `batch-get` 读取轻量信息和最新快照，详情页或导出场景再开启 `include_content=true`。

## 版本、片段和快照

| 数据 | 什么时候读取 | 示例 |
| --- | --- | --- |
| 当前版本 | 只关心最新标题、正文、URL | 最新文章正文、最新视频描述 |
| 历史版本 | 需要知道正文是否变更 | 标题修改、商品描述修改 |
| `parts` | 一个内容有多个可读片段 | YouTube 字幕、音频转录、小红书 OCR、商品规格 |
| `facts` | 需要结构化筛选和聚合 | 价格、公司、地点、薪资、技能 |
| `snapshots` | 需要随时间变化的状态 | 播放量、点赞、价格、库存、作者粉丝 |

## 统计维度

对外统计通常按以下维度理解：

| 维度 | 说明 |
| --- | --- |
| 时间 | `published_at` 看业务发布时间，`snapshot_at` 看指标趋势，`created_at` 看系统入库时间 |
| 平台 | `source_platform` 表示来源平台 |
| 数据集 | `dataset_id` 表示数据产品或数据域 |
| 内容类型 | `content_type` 表示视频、文章、帖子、商品、职位等 |
| 指标 | 统一指标字段加平台扩展指标 |
| 处理状态 | 是否已可检索、已向量化、已分析 |

## 权限控制

consumer 不拥有数据，只拥有访问权。授权可以限制：

- dataset
- source platform
- language
- region
- published time range
- allowed fields

每日配额按 UTC 自然日、消费方和检索操作统计，并在进入检索后端前原子占用。已被平台接受但下游失败的请求仍计入请求用量；因达到配额而返回 `429` 的请求不计入。

实时限制由 entitlement 的 `requests_per_second`、`burst` 和 `max_concurrency` 控制。触发时返回 `429 rate_limit_exceeded` 和 `Retry-After: 1`，请求不会进入下游，也不计入 usage。当前该限制在单 Gateway 内执行；多 Gateway 部署需要在统一 API Gateway 层同步全局策略。

## 返回字段

默认返回文档、分块、标题、正文摘要和评分。服务会按每条结果实际命中的 entitlement 再次脱敏；未授权 `body` 时不会返回正文和高亮。请求中的 `fields` 只能缩小返回范围，不能扩大授权。文档详情接口同样受 entitlement 控制。

## 错误处理

| 错误 | 含义 | 处理建议 |
| --- | --- | --- |
| `401 unauthorized` | API key 缺失或无效 | 检查鉴权头 |
| `403 entitlement_denied` | API key 无权访问该 dataset、平台或字段 | 缩小查询范围或申请授权 |
| `400 invalid_query` | 请求字段格式错误或未知 mode | 按 API Reference 修正参数 |
| `429 quota_exceeded` | 触发配额或限流 | 降低并发，等待 `Retry-After` 指定的秒数后重试 |
| `429 rate_limit_exceeded` | 触发实时 RPS、突发或并发限制 | 等待 `Retry-After` 后重试并降低并发 |
| `503 search_backend_unavailable` | OpenSearch、Milvus、embedding 或 rerank 不可用 | 使用指数退避重试 |

完整接入步骤见[快速开始](/docs/quickstart)，密钥与错误语义见[鉴权与密钥](/docs/authentication)。