# Video Search & Vector Recall API 接口文档

> 项目: video-vector-server  
> 文档版本: 2026-05-07  
> 适用 Controller: `VideoSearchController`、`VectorRecallTestController`

---

## 通用约定

### 基础路径

| Controller | 前缀 |
|---|---|
| VideoSearchController | `/videoSearch` |
| VectorRecallTestController | `/recallTest` |

### 统一响应格式 `CommonResponse<T>`

所有接口均返回以下 JSON 结构:

```json
{
  "code": 0,
  "msg": "success",
  "data": <T>
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `int` | 业务状态码。`0` 表示成功 |
| `msg` | `String` | 状态消息。成功时为 `"success"` |
| `data` | `T` (泛型) | 业务数据,具体结构见各接口定义。失败时可能为 `null` |

### 全局行为

- **CORS**: 由全局拦截器 `CrosDomainAllowInterceptor` 统一处理,前端无需额外配置
- **鉴权**: MVP 阶段不校验鉴权,所有接口均可直接调用

---

## 一、VideoSearchController (`/videoSearch`)

视频解构与相似视频匹配。

### 1.1 触发内容解构

```
POST /videoSearch/deconstruct
```

**用途**: 对指定内容(长文/图文/视频)发起 AI 解构任务,提取选题、灵感点、关键点、目的点等结构化信息。

**Request Body** (`application/json`):

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `bizType` | `Integer` | 否 | 业务类型。`0` = 投流 |
| `contentType` | `Integer` | 否 | 内容类型: `1` = 长文, `2` = 图文, `3` = 视频 |
| `channelContentId` | `String` | 否 | 业务内容ID(帖子ID/视频ID) |
| `title` | `String` | 否 | 标题 |
| `bodyText` | `String` | 否 | 正文内容 |
| `videoUrl` | `String` | 否 | 视频地址 |
| `imageList` | `List<String>` | 否 | 图片URL列表 |
| `channelAccountId` | `String` | 否 | 作者ID |
| `channelAccountName` | `String` | 否 | 作者名称 |

**Request 示例**:

```json
{
  "bizType": 0,
  "contentType": 3,
  "channelContentId": "abc123",
  "title": "产品种草视频",
  "bodyText": "这是一款非常好用的护肤品...",
  "videoUrl": "https://example.com/video.mp4",
  "imageList": ["https://example.com/img1.jpg"],
  "channelAccountId": "account_001",
  "channelAccountName": "美妆达人小A"
}
```

**Response**:

```json
{
  "code": 0,
  "msg": "success",
  "data": "<taskId>"
}
```

`data` 为 `String` 类型,返回解构任务的唯一标识 `taskId`,可用于后续调用 `getDeconstructResult` 查询结果。

---

### 1.2 查询解构结果

```
POST /videoSearch/getDeconstructResult
```

**用途**: 根据任务ID或业务内容ID查询解构任务的处理结果。

**Request Body** (`application/json`):

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `taskId` | `String` | 否 | 解构任务ID(由 `deconstruct` 接口返回) |
| `bizType` | `Integer` | 否 | 业务类型: `0` = 选题, `1` = 创作, `2` = 制作 |
| `contentType` | `Integer` | 否 | 内容类型: `1` = 长文, `2` = 图文, `3` = 视频 |
| `channelContentId` | `String` | 否 | 业务内容ID(帖子ID/视频ID) |
| `forceRefresh` | `Boolean` | 否 | 是否强制从远程API重新拉取,不走Redis缓存 |

> **查询逻辑**: 至少提供 `taskId` 或 `channelContentId` 之一。若提供 `taskId` 则按任务ID查询;若提供 `channelContentId` 则按内容ID查询最新结果。

**Request 示例**:

```json
{
  "taskId": "task_20260507_001",
  "bizType": 0,
  "contentType": 3,
  "channelContentId": "abc123",
  "forceRefresh": false
}
```

**Response**: `data` 为 `JSONObject`,结构为解构引擎返回的原始结果JSON,包含但不限于:

- 选题(topic)
- 灵感点(inspiration points)
- 关键点(key points)
- 目的点(purpose points)
- 各点的实质词汇及贡献度分数(0~1)

---

### 1.3 按内容ID获取解构结果

```
GET /videoSearch/getDeconstructResultByChannelContentId
```

**用途**: 通过业务内容ID直接获取解构结果(简化版,仅需 channelContentId)。

**Query Parameters**:

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `channelContentId` | `String` | 是 | 业务内容ID(帖子ID/视频ID) |

**示例请求**:

```
GET /videoSearch/getDeconstructResultByChannelContentId?channelContentId=abc123
```

**Response**: `data` 为 `JSONObject`,与接口 1.2 返回结构一致。

---

### 1.4 相似视频匹配(Top-N 召回)

```
POST /videoSearch/matchTopNVideo
```

**用途**: 基于内容解构结果,在向量库中检索最相似的 Top-N 个视频。

**Request Body** (`application/json`):

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `channelContentId` | `String` | 否 | 参考内容的业务ID,用于自动获取该内容的解构向量 |
| `configCode` | `String` | 否 | 向量配置编码,指定搜索维度。不传使用默认配置 |
| `queryText` | `String` | 否 | 查询文本,将被向量化后检索 |
| `queryVector` | `List<Float>` | 否 | 直接传入查询向量,优先级高于 `queryText` |
| `topN` | `Integer` | 否 | 返回结果数量,默认 `10` |

> **检索逻辑**: `queryVector` > `queryText` > `channelContentId`。即若传入 `queryVector` 直接用于检索;否则若有 `queryText` 则将其向量化;否则使用 `channelContentId` 的解构向量进行检索。

**Request 示例**:

```json
{
  "channelContentId": "abc123",
  "configCode": "VIDEO_TOPIC",
  "topN": 10
}
```

按文本查询:

```json
{
  "configCode": "VIDEO_INSPIRATION",
  "queryText": "如何做美妆教程",
  "topN": 20
}
```

**Response**: `data` 为 `List<VideoMatchResult>`:

```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "configCode": "VIDEO_TOPIC",
      "videoId": 10001,
      "score": 0.9523,
      "videoDetail": {
        "topic": "美妆护肤",
        "灵感点": "产品成分解读",
        "灵感点-实质": [
          { "word": "成分", "score": 0.92 },
          { "word": "安全", "score": 0.88 }
        ],
        "关键点": "使用时需注意过敏",
        "关键点-实质": [
          { "word": "过敏", "score": 0.85 }
        ],
        "目的点": "种草转化",
        "目的点-实质": [
          { "word": "购买", "score": 0.91 }
        ]
      }
    }
  ]
}
```

**VideoMatchResult 字段说明**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `configCode` | `String` | 命中时使用的向量配置编码 |
| `videoId` | `Long` | 匹配到的视频ID |
| `score` | `Double` | 余弦相似度分值(0~1,越大越相似) |
| `videoDetail` | `Map<String, Object>` | 视频解构详情,来源 Redis `recall:vid_decode:{vid}`。包含 topic、灵感点、关键点、目的点及其"实质"分词信息 |

---

### 1.5 获取所有配置编码

```
GET /videoSearch/getAllConfigCodes
```

**用途**: 查询系统支持的所有向量配置编码及对应描述,供前端下拉选择。

**请求参数**: 无。

**示例请求**:

```
GET /videoSearch/getAllConfigCodes
```

**Response**: `data` 为 `Map<String, String>`,key 为 configCode,value 为中文描述:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "VIDEO_TOPIC": "选题维度",
    "VIDEO_INSPIRATION": "灵感点维度",
    "VIDEO_KEYPOINT": "关键点维度",
    "VIDEO_PURPOSE": "目的点维度"
  }
}
```

---

## 二、VectorRecallTestController (`/recallTest`)

向量召回前端测试页面专用接口。MVP 阶段不加鉴权。

### 支持的 configCode

| configCode | 说明 |
|---|---|
| `VIDEO_TOPIC` | 选题维度检索(默认) |
| `VIDEO_INSPIRATION` | 灵感点维度检索 |

> 不传 `configCode` 时默认使用 `VIDEO_TOPIC`。

---

### 2.1 获取视频基础详情 (Tab1)

```
GET /recallTest/videoDetail
```

**用途**: 查询单个视频的基础信息,用于测试页面 Tab1 展示。

**Query Parameters**:

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `videoId` | `Long` | 是 | 视频ID |

**示例请求**:

```
GET /recallTest/videoDetail?videoId=10086
```

**Response**: `data` 为 `VideoBasicVO`:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "videoId": 10086,
    "title": "2025春季妆容教程",
    "videoUrl": "https://example.com/video/10086.mp4",
    "cover": "https://example.com/cover/10086.jpg",
    "playCount": "--"
  }
}
```

**VideoBasicVO 字段说明**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `videoId` | `Long` | 视频ID |
| `title` | `String` | 视频标题 |
| `videoUrl` | `String` | 视频播放地址 |
| `cover` | `String` | 封面图URL |
| `playCount` | `String` | 播放量。长视频API当前不返回播放量,值为 `"--"` |

---

### 2.2 文本召回 (Tab2)

```
POST /recallTest/matchByText
```

**用途**: 输入自由文本,在向量库中检索语义最相似的 Top-N 个视频/素材/长文。

**Request Body** (`application/json`):

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `queryText` | `String` | 是 | 查询文本,将向量化后在指定维度检索 |
| `configCode` | `String` | 否 | 向量配置编码,不传默认 `VIDEO_TOPIC`。支持: `VIDEO_TOPIC` / `VIDEO_INSPIRATION` |
| `topN` | `Integer` | 否 | 返回 Top-N 结果,默认 `10` |

**Request 示例**:

```json
{
  "queryText": "美妆护肤教程",
  "configCode": "VIDEO_TOPIC",
  "topN": 20
}
```

**Response**: `data` 为 `RecallResultVO`:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 10001,
        "modality": "VIDEO",
        "configCode": "VIDEO_TOPIC",
        "score": 0.9523,
        "title": "春季护肤全攻略",
        "cover": "https://example.com/cover/10001.jpg",
        "videoUrl": "https://example.com/video/10001.mp4",
        "imageList": null,
        "bodyText": null,
        "playCount": "--",
        "exposure": "--",
        "ctr": "--",
        "readCount": "--",
        "rov": "--",
        "videoDetail": {
          "topic": "护肤教程",
          "灵感点": "产品成分解析",
          "灵感点-实质": [
            { "word": "成分", "score": 0.92 }
          ],
          "关键点": "敏感肌适用",
          "关键点-实质": [
            { "word": "敏感肌", "score": 0.89 }
          ],
          "目的点": "提升转化",
          "目的点-实质": [
            { "word": "购买", "score": 0.87 }
          ]
        }
      },
      {
        "id": 20005,
        "modality": "MATERIAL",
        "configCode": "VIDEO_TOPIC",
        "score": 0.8912,
        "title": "护肤品种草图文",
        "cover": "https://example.com/cover/20005.jpg",
        "videoUrl": null,
        "imageList": ["https://example.com/material/20005_1.jpg", "https://example.com/material/20005_2.jpg"],
        "bodyText": null,
        "playCount": "--",
        "exposure": "--",
        "ctr": "--",
        "readCount": "--",
        "rov": "--",
        "videoDetail": { }
      }
    ],
    "videoCount": 1,
    "materialCount": 1,
    "articleCount": 0,
    "total": 2
  }
}
```

**RecallResultVO 字段说明**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `items` | `List<VideoMatchEnrichedVO>` | 召回结果列表(已 enrich,含模态信息) |
| `videoCount` | `int` | 命中视频数量 |
| `materialCount` | `int` | 命中素材(图文)数量 |
| `articleCount` | `int` | 命中长文数量 |
| `total` | `int` | 总召回条数 |

**VideoMatchEnrichedVO 单条结果字段说明**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `Long` | 业务ID。视频时 = `wx_video.id`,素材时 = `channelContentId` 数值化 |
| `modality` | `Modality` 枚举 | 模态类型: `VIDEO` / `MATERIAL` / `ARTICLE` |
| `configCode` | `String` | 命中的向量配置编码 |
| `score` | `Double` | 余弦相似度分值(0~1) |
| `title` | `String` | 标题 |
| `cover` | `String` | 封面/缩略图URL |
| `videoUrl` | `String` | 视频播放地址(仅 `modality=VIDEO` 时有值,其余为 `null`) |
| `imageList` | `List<String>` | 图片列表(仅 `modality=MATERIAL` 时有值,其余为 `null`) |
| `bodyText` | `String` | 正文(仅 `modality=ARTICLE` 时有值,其余为 `null`) |
| `playCount` | `String` | 播放量,默认 `"--"` |
| `exposure` | `String` | 曝光量,默认 `"--"` |
| `ctr` | `String` | CTR,默认 `"--"` |
| `readCount` | `String` | 阅读数,默认 `"--"` |
| `rov` | `String` | ROV,默认 `"--"` |
| `videoDetail` | `Map<String, Object>` | 视频解构详情 KV(来源 Redis `recall:vid_decode:{vid}`),含 topic、灵感点、关键点、目的点及其"实质-分词" |

**Modality 枚举映射**:

| 枚举值 | 对应 content_type | 说明 |
|---|---|---|
| `VIDEO` | `3` | 视频 |
| `MATERIAL` | `2` | 图文素材 |
| `ARTICLE` | `1` | 长文 |

> `content_type` 缺省或未知时默认按 `VIDEO` 处理。

---

### 2.3 获取视频解构层级 (Tab1 解构树)

```
GET /recallTest/deconstructPoints
```

**用途**: 获取视频的解构层级数据(选题 + 高价值点),用于前端解构树组件递归渲染。数据来源: Singapore RDS → Python 解析筛选 → 国内 Redis。

**Query Parameters**:

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `videoId` | `Long` | 是 | 视频ID/素材ID |

**示例请求**:

```
GET /recallTest/deconstructPoints?videoId=10086
```

**Response**: `data` 为 `DeconstructPointsVO`:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "vid": 10086,
    "title": "2025春季妆容教程",
    "videoUrl": "https://example.com/video/10086.mp4",
    "htmlUrl": "https://example.com/viz/10086.html",
    "topic": "美妆教程-春季妆容",
    "highValuePoints": [
      {
        "id": "inspiration_1",
        "type": "灵感点",
        "name": "春季流行色系运用",
        "essences": [
          { "word": "春季", "score": 0.95 },
          { "word": "色系", "score": 0.91 },
          { "word": "流行", "score": 0.86 }
        ]
      },
      {
        "id": "kp_abc123",
        "type": "关键点",
        "name": "底妆持久度关键步骤",
        "essences": [
          { "word": "持久", "score": 0.93 },
          { "word": "底妆", "score": 0.88 }
        ]
      },
      {
        "id": "purpose_1",
        "type": "目的点",
        "name": "提升完播率与互动",
        "essences": [
          { "word": "完播", "score": 0.82 },
          { "word": "互动", "score": 0.80 }
        ]
      }
    ]
  }
}
```

**DeconstructPointsVO 字段说明**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `vid` | `Long` | 视频ID |
| `title` | `String` | 视频标题 |
| `videoUrl` | `String` | 视频播放地址 |
| `htmlUrl` | `String` | 带权重的可视化页面URL |
| `topic` | `String` | 最终选题(格式: `最终选题.选题`) |
| `highValuePoints` | `List<HighValuePoint>` | 实质≥0.8 的高价值解构点列表 |

**HighValuePoint 子结构**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `String` | 业务侧ID,格式如 `inspiration_1` / `purpose_1` / `kp_xxxxxx` |
| `type` | `String` | 点类型: `灵感点` / `目的点` / `关键点` |
| `name` | `String` | 该点的描述名称 |
| `essences` | `List<EssenceWord>` | 拆解出的"实质"分词列表(score ≥ 0.8) |

**EssenceWord 子结构**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `word` | `String` | 实质词 |
| `score` | `Double` | 词级贡献度(0~1,越大越重要) |

---

### 2.4 按视频ID召回相似内容 (Tab1 解构节点点击触发)

```
POST /recallTest/matchByVideoId
```

**用途**: 以指定视频/素材为参考,召回与之在指定维度(选题/灵感点)上最相似的内容。典型场景: 用户在解构树上看到某个节点,点击后查询与该节点对应的高价值点相似的内容。

**Request Body** (`application/json`):

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `videoId` | `Long` | 是 | 视频ID 或 `channelContentId` 数值化后的值 |
| `configCode` | `String` | 否 | 向量配置编码,不传默认 `VIDEO_TOPIC`。支持: `VIDEO_TOPIC` / `VIDEO_INSPIRATION` |
| `topN` | `Integer` | 否 | 返回 Top-N 结果,默认 `10` |

**Request 示例**:

```json
{
  "videoId": 10086,
  "configCode": "VIDEO_INSPIRATION",
  "topN": 15
}
```

**Response**: `data` 为 `RecallResultVO`,结构与 2.2 接口完全一致。

---

### 2.5 获取视频AI理解结果 (Tab1)

```
GET /recallTest/aiUnderstanding
```

**用途**: 获取视频的 AI 理解结果(选题、主题、关键词、口播文案等)。数据来源: ODPS `loghubods.result_log` → DataWorks 同步 Job → 本地表 `video_ai_understanding`。

> **重要**: MVP 阶段本地表可能为空,此时 `data` 的 field 全部为 `null`,前端需展示"AI理解数据未就绪,等待同步Job"。**严禁后端伪造任何字段返回值。**

**Query Parameters**:

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `videoId` | `Long` | 是 | 视频ID |

**示例请求**:

```
GET /recallTest/aiUnderstanding?videoId=10086
```

**Response (数据就绪时)**: `data` 为 `AIUnderstandingVO`:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "videoId": 10086,
    "contentTopic": "美妆护肤",
    "videoTheme": "春季妆容教程",
    "videoKeywords": "春季,妆容,护肤,教程",
    "videoNarration": "大家好,今天我们来分享一款春季日常妆容...",
    "dt": "2026050712"
  }
}
```

**Response (数据未就绪时)**:

```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

> 前端在收到 `data == null` 时应展示"AI理解数据未就绪"占位状态,不可报错。

**AIUnderstandingVO 字段说明**:

| 字段 | 类型 | 说明 |
|---|---|---|
| `videoId` | `Long` | 视频ID |
| `contentTopic` | `String` | 内容选题(AI识别) |
| `videoTheme` | `String` | 视频主题 |
| `videoKeywords` | `String` | 视频关键词(逗号分隔) |
| `videoNarration` | `String` | 视频口播文案(ASR识别文本) |
| `dt` | `String` | 数据所属分区,格式 `yyyyMMddHH`(如 `2026050712` 表示 2026-05-07 12时) |

---

## 三、数据流与架构说明

### 解构数据管线的来源链路

```
Singapore RDS (aigc_topic_decode_task_result)
  → Python 解析脚本(筛选实质 ≥ 0.8 的高价值点)
    → 国内 Redis (key: recall:vid_decode:{vid})
      → Java 后端 (DeconstructPointsVO / VideoMatchResult)
        → 前端渲染
```

### 向量召回流程

```
输入(queryText / videoId / channelContentId)
  → 获取或计算查询向量
    → Milvus/ES 向量检索 (按 configCode 指定维度)
      → 返回 Top-N 候选 vid
        → enrich: 从 Redis recall:vid_decode:{vid} 读取解构详情
          → 组装 RecallResultVO / VideoMatchResult 返回
```

### AI理解数据链路

```
ODPS (loghubods.result_log)
  → DataWorks 同步 Job
    → 本地 MySQL (video_ai_understanding 表)
      → Java 后端查询
        → 前端渲染
```

---

## 四、接口总览表

| 接口 | Method | 路径 | 说明 |
|---|---|---|---|
| 触发内容解构 | `POST` | `/videoSearch/deconstruct` | 发起AI解构任务,返回 taskId |
| 查询解构结果 | `POST` | `/videoSearch/getDeconstructResult` | 按 taskId/channelContentId 查结果 |
| 按内容ID查解构 | `GET` | `/videoSearch/getDeconstructResultByChannelContentId` | 简化查询,仅需 channelContentId |
| 相似视频匹配 | `POST` | `/videoSearch/matchTopNVideo` | Top-N 向量召回相似视频 |
| 获取所有配置码 | `GET` | `/videoSearch/getAllConfigCodes` | 查询支持的向量配置维度 |
| 视频基础详情 | `GET` | `/recallTest/videoDetail` | 查单视频基础信息(Tab1) |
| 文本召回 | `POST` | `/recallTest/matchByText` | 自由文本语义检索(Tab2) |
| 解构层级 | `GET` | `/recallTest/deconstructPoints` | 视频解构树数据(Tab1) |
| 按视频ID召回 | `POST` | `/recallTest/matchByVideoId` | 相似视频召回(Tab1节点触发) |
| AI理解结果 | `GET` | `/recallTest/aiUnderstanding` | 视频AI理解数据(Tab1) |

---

## 五、错误状态码

| code | 含义 | 典型场景 |
|---|---|---|
| `0` | 成功 | — |
| 非 `0` | 业务异常 | 参数校验失败、向量库不可用、查询超时等,具体 `msg` 字段会描述原因 |