|
|
@@ -0,0 +1,1375 @@
|
|
|
+# Video Search & Vector Recall API 接口文档
|
|
|
+
|
|
|
+> 项目: video-vector-server
|
|
|
+> 文档版本: 2026-05-09
|
|
|
+> 适用 Controller: `VideoSearchController`、`VectorRecallTestController`、`MaterialController`、`FileController`、`HealthController`、`XxlJobController`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 通用约定
|
|
|
+
|
|
|
+### 基础路径
|
|
|
+
|
|
|
+| Controller | 前缀 |
|
|
|
+|---|---|
|
|
|
+| VideoSearchController | `/videoSearch` |
|
|
|
+| VectorRecallTestController | `/recallTest` |
|
|
|
+| MaterialController | `/material` |
|
|
|
+| FileController | `/file` |
|
|
|
+| HealthController | `/` |
|
|
|
+| XxlJobController | `/job` |
|
|
|
+
|
|
|
+### 统一响应格式 `CommonResponse<T>`
|
|
|
+
|
|
|
+所有接口均返回以下 JSON 结构:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": <T>
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `code` | `int` | 业务状态码。`0` 表示成功 |
|
|
|
+| `msg` | `String` | 状态消息。成功时为 `"success"` |
|
|
|
+| `data` | `T` (泛型) | 业务数据,具体结构见各接口定义。失败时可能为 `null` |
|
|
|
+
|
|
|
+### 全局行为
|
|
|
+
|
|
|
+- **CORS**: 由全局拦截器 `CrosDomainAllowInterceptor` 统一处理,前端无需额外配置。`FileController` 额外加了 `@CrossOrigin(origins = "*")`
|
|
|
+- **鉴权**: 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 查询解构结果(精简版)
|
|
|
+
|
|
|
+```
|
|
|
+POST /videoSearch/getDeconstructResultMini
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 查询解构结果的精简版,参数与 `getDeconstructResult` 一致,返回裁剪后的解构结果。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `taskId` | `String` | 否 | 解构任务ID |
|
|
|
+| `bizType` | `Integer` | 否 | 业务类型: `0` = 选题, `1` = 创作, `2` = 制作 |
|
|
|
+| `contentType` | `Integer` | 否 | 内容类型: `1` = 长文, `2` = 图文, `3` = 视频 |
|
|
|
+| `channelContentId` | `String` | 否 | 业务内容ID(帖子ID/视频ID) |
|
|
|
+| `forceRefresh` | `Boolean` | 否 | 是否强制从远程API重新拉取 |
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "taskId": "task_20260507_001",
|
|
|
+ "bizType": 0,
|
|
|
+ "contentType": 3,
|
|
|
+ "channelContentId": "abc123",
|
|
|
+ "forceRefresh": false
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `JSONObject`,返回精简后的解构结果JSON。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 1.5 相似视频匹配(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,
|
|
|
+ "text": "美妆护肤教程 春季妆容",
|
|
|
+ "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,越大越相似) |
|
|
|
+| `text` | `String` | 向量化原文 |
|
|
|
+| `videoDetail` | `Map<String, Object>` | 视频解构详情,来源 Redis `recall:vid_decode:{vid}`。包含 topic、灵感点、关键点、目的点及其"实质"分词信息 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 1.6 召回视频并按综合评分排序
|
|
|
+
|
|
|
+```
|
|
|
+POST /videoSearch/recallWithScore
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 召回视频后按综合评分排序返回。综合分 = `alpha * sim_norm + (1-alpha) * rov_norm`,同时考虑相似度和效率分。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `channelContentId` | `String` | 否 | 业务内容ID(帖子ID/视频ID) |
|
|
|
+| `configCode` | `String` | 否 | 向量配置编码 |
|
|
|
+| `queryText` | `String` | 否 | 查询文本,将被向量化后检索 |
|
|
|
+| `queryVector` | `List<Float>` | 否 | 直接传入查询向量,优先级高于 `queryText` |
|
|
|
+| `topN` | `Integer` | 否 | 返回 Top-N 结果数量,默认 `10` |
|
|
|
+| `alpha` | `Double` | 否 | 相关性权重,取值 0~1,默认 `0.6`。越大越看重相关性(sim) |
|
|
|
+| `rovP95` | `Double` | 否 | ROV 全局历史 P95,默认 `0.05` |
|
|
|
+| `rovP5` | `Double` | 否 | ROV 全局历史 P5,默认 `0.005` |
|
|
|
+| `simMin` | `Double` | 否 | 相似度下界(粗筛阈值),默认 `0.7` |
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "configCode": "VIDEO_TOPIC",
|
|
|
+ "queryText": "美妆护肤教程",
|
|
|
+ "topN": 20,
|
|
|
+ "alpha": 0.6,
|
|
|
+ "simMin": 0.7
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `RecallVideoScoreVO`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "items": [
|
|
|
+ {
|
|
|
+ "videoId": 10001,
|
|
|
+ "configCode": "VIDEO_TOPIC",
|
|
|
+ "sim": 0.9523,
|
|
|
+ "simNorm": 0.87,
|
|
|
+ "rov": 0.032,
|
|
|
+ "rovNorm": 0.65,
|
|
|
+ "score": 0.782,
|
|
|
+ "text": "美妆护肤教程 春季妆容",
|
|
|
+ "videoDetail": { }
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "total": 1,
|
|
|
+ "scoreParams": {
|
|
|
+ "alpha": 0.6,
|
|
|
+ "rovP95": 0.05,
|
|
|
+ "rovP5": 0.005,
|
|
|
+ "simMin": 0.7,
|
|
|
+ "simMax": 0.98
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**RecallVideoScoreVO 字段说明**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `items` | `List<ScoredVideoItem>` | 按综合分降序排列的结果列表 |
|
|
|
+| `total` | `int` | 总条数 |
|
|
|
+| `scoreParams` | `ScoreParams` | 本次使用的评分参数 |
|
|
|
+
|
|
|
+**ScoredVideoItem 子结构**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `videoId` | `Long` | 匹配到的视频ID |
|
|
|
+| `configCode` | `String` | 命中的配置编码 |
|
|
|
+| `sim` | `Double` | 原始相似度分数 |
|
|
|
+| `simNorm` | `Double` | 归一化后的相似度 |
|
|
|
+| `rov` | `Double` | 效率分(来自视频维度表) |
|
|
|
+| `rovNorm` | `Double` | 归一化后的效率分 |
|
|
|
+| `score` | `Double` | 综合得分 = alpha * sim_norm + (1-alpha) * rov_norm |
|
|
|
+| `text` | `String` | 向量化原文 |
|
|
|
+| `videoDetail` | `Map<String, Object>` | 视频基础信息及解构子对象 |
|
|
|
+
|
|
|
+**ScoreParams 子结构**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `alpha` | `Double` | 相关性权重 |
|
|
|
+| `rovP95` | `Double` | ROV P95 |
|
|
|
+| `rovP5` | `Double` | ROV P5 |
|
|
|
+| `simMin` | `Double` | 相似度下界 |
|
|
|
+| `simMax` | `Double` | 相似度上界 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 1.7 查询渠道需求匹配结果
|
|
|
+
|
|
|
+```
|
|
|
+POST /videoSearch/queryDemandMatchResult
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 查询渠道需求匹配结果,按日期、渠道、人群、维度查询匹配到的视频ID及分数。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `dt` | `String` | 是 | 数据日期,格式 `yyyyMMdd` |
|
|
|
+| `channelName` | `String` | 是 | 渠道类名称 |
|
|
|
+| `crowdSegment` | `String` | 否 | 人群细分 |
|
|
|
+| `dimension` | `String` | 否 | 维度(如"传播的分发") |
|
|
|
+| `pointType` | `String` | 否 | 点类型(关键点/灵感点/目的点) |
|
|
|
+| `standardElement` | `String` | 否 | 标准化元素(搜索词) |
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "dt": "20260509",
|
|
|
+ "channelName": "美妆类",
|
|
|
+ "crowdSegment": "年轻女性",
|
|
|
+ "dimension": "传播的分发",
|
|
|
+ "pointType": "灵感点",
|
|
|
+ "standardElement": "成分安全"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `List<ChannelDemandMatchVO>`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "dt": "20260509",
|
|
|
+ "channelName": "美妆类",
|
|
|
+ "crowdSegment": "年轻女性",
|
|
|
+ "dimension": "传播的分发",
|
|
|
+ "pointType": "灵感点",
|
|
|
+ "standardElement": "成分安全",
|
|
|
+ "categoryName": "护肤品",
|
|
|
+ "visitUv": 12345,
|
|
|
+ "totalRov": 0.052,
|
|
|
+ "matchedVideos": [
|
|
|
+ {
|
|
|
+ "videoId": 10001,
|
|
|
+ "configCode": "VIDEO_INSPIRATION",
|
|
|
+ "score": 0.852,
|
|
|
+ "sim": 0.92,
|
|
|
+ "rov": 0.035,
|
|
|
+ "text": "护肤品成分安全解析"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**ChannelDemandMatchVO 字段说明**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `dt` | `String` | 数据日期 |
|
|
|
+| `channelName` | `String` | 渠道类名称 |
|
|
|
+| `crowdSegment` | `String` | 人群细分 |
|
|
|
+| `dimension` | `String` | 维度 |
|
|
|
+| `pointType` | `String` | 点类型 |
|
|
|
+| `standardElement` | `String` | 标准化元素(搜索词) |
|
|
|
+| `categoryName` | `String` | 分类名称 |
|
|
|
+| `visitUv` | `Long` | 访问 UV |
|
|
|
+| `totalRov` | `Double` | 总 ROV |
|
|
|
+| `matchedVideos` | `List<MatchedVideo>` | 匹配到的视频列表 |
|
|
|
+
|
|
|
+**MatchedVideo 子结构**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `videoId` | `Long` | 匹配视频ID |
|
|
|
+| `configCode` | `String` | 匹配使用的向量配置编码 |
|
|
|
+| `score` | `Double` | 综合评分 |
|
|
|
+| `sim` | `Double` | 相似度分数 |
|
|
|
+| `rov` | `Double` | 匹配视频 ROV |
|
|
|
+| `text` | `String` | 匹配命中的向量原文 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 1.8 获取所有配置编码
|
|
|
+
|
|
|
+```
|
|
|
+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": "--",
|
|
|
+ "text": "美妆护肤教程 春季妆容",
|
|
|
+ "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": "--",
|
|
|
+ "text": "护肤品种草推荐",
|
|
|
+ "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,默认 `"--"` |
|
|
|
+| `text` | `String` | 向量化原文 |
|
|
|
+| `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时) |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 三、MaterialController (`/material`)
|
|
|
+
|
|
|
+素材向量化搜索接口。支持素材入库(解构 + 异步向量化)和相似素材搜索。
|
|
|
+
|
|
|
+### 3.1 素材入库
|
|
|
+
|
|
|
+```
|
|
|
+POST /material/submit
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 提交素材进行解构和异步向量化入库。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `channelContentId` | `String` | 否 | 素材业务ID |
|
|
|
+| `contentType` | `Integer` | 否 | 内容类型: `1` = 长文, `2` = 图文, `3` = 视频 |
|
|
|
+| `title` | `String` | 否 | 素材标题 |
|
|
|
+| `bodyText` | `String` | 否 | 素材正文/描述 |
|
|
|
+| `videoUrl` | `String` | 否 | 视频地址(可选) |
|
|
|
+| `imageList` | `List<String>` | 否 | 图片列表(可选) |
|
|
|
+| `channelAccountId` | `String` | 否 | 作者ID(可选) |
|
|
|
+| `channelAccountName` | `String` | 否 | 作者名称(可选) |
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "channelContentId": "mat_001",
|
|
|
+ "contentType": 2,
|
|
|
+ "title": "护肤品图文种草素材",
|
|
|
+ "bodyText": "这款精华液含有烟酰胺成分...",
|
|
|
+ "imageList": ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
|
|
|
+ "channelAccountId": "author_001",
|
|
|
+ "channelAccountName": "护肤小达人"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `String`,返回任务唯一标识:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": "<taskId>"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 3.2 素材相似搜索
|
|
|
+
|
|
|
+```
|
|
|
+POST /material/matchTopN
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 在素材向量库中检索语义最相似的 Top-N 个素材。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `queryText` | `String` | 否 | 查询文本,将被向量化后检索 |
|
|
|
+| `queryVector` | `List<Float>` | 否 | 直接传入查询向量,优先级高于 `queryText` |
|
|
|
+| `channelContentId` | `String` | 否 | 业务内容ID,用于复用历史向量(可选) |
|
|
|
+| `configCode` | `String` | 否 | 配置编码。传 `ALL` 可搜索所有启用的配置维度 |
|
|
|
+| `topN` | `Integer` | 否 | 返回 Top-N 结果,默认 `10` |
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "queryText": "烟酰胺精华液功效",
|
|
|
+ "configCode": "ALL",
|
|
|
+ "topN": 10
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `List<MaterialMatchResult>`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "configCode": "VIDEO_TOPIC",
|
|
|
+ "contentId": 20001,
|
|
|
+ "channelContentId": "mat_005",
|
|
|
+ "score": 0.9213,
|
|
|
+ "title": "烟酰胺美白精华种草",
|
|
|
+ "sourceText": "烟酰胺是一种高效美白成分..."
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**MaterialMatchResult 字段说明**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `configCode` | `String` | 命中的配置编码 |
|
|
|
+| `contentId` | `Long` | deconstruct_content.id |
|
|
|
+| `channelContentId` | `String` | 素材业务ID |
|
|
|
+| `score` | `Double` | 余弦相似度分值(0~1) |
|
|
|
+| `title` | `String` | 素材标题 |
|
|
|
+| `sourceText` | `String` | 命中的向量原文 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 四、FileController (`/file`)
|
|
|
+
|
|
|
+OSS 文件上传与签名接口。所有端点均配置 `@CrossOrigin(origins = "*")`。
|
|
|
+
|
|
|
+### 4.1 文件上传
|
|
|
+
|
|
|
+```
|
|
|
+POST /file/upload
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 上传文件到阿里云 OSS。
|
|
|
+
|
|
|
+**Request**: `multipart/form-data`
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `file` | `MultipartFile` | 是 | 上传的文件 |
|
|
|
+| `fileUri` | `String` | 否 | 文件存储路径。不传则自动生成 `video-vector/{timestamp}_{random}.{ext}` |
|
|
|
+| `fileType` | `EnumFileType` | 是 | 文件类型枚举 |
|
|
|
+
|
|
|
+**Response**: `data` 为 `FileInfo`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "fileName": "example.jpg",
|
|
|
+ "fileUrl": "https://bucket.oss-cn-hangzhou.aliyuncs.com/video-vector/123456_abc.jpg",
|
|
|
+ "fileSize": 102400.0
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**FileInfo 字段说明**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `fileName` | `String` | 文件名 |
|
|
|
+| `fileUrl` | `String` | 文件访问URL |
|
|
|
+| `fileSize` | `Double` | 文件大小(字节) |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 4.2 获取OSS上传签名
|
|
|
+
|
|
|
+```
|
|
|
+POST /file/signature
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 获取阿里云 OSS 上传策略签名,供前端直传 OSS 使用。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `fileType` | `Integer` | 是 | 文件类型: `1` = 图片, `2` = 视频, `3` = 音频, `4` = 文件, `5` = GIF, `6` = 字幕 |
|
|
|
+
|
|
|
+> 该参数继承自 `VideoApiBaseParam`,包含大量通用参数(laginUid, token, versionCode 等),此处仅列出必填的 `fileType`。
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "fileType": 1
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `SignatureVO`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "accessId": "LTAI5xxx",
|
|
|
+ "policy": "eyJleHBpcmF0aW9uIjo...",
|
|
|
+ "signature": "abc123...",
|
|
|
+ "fileName": "video-vector/abc.jpg",
|
|
|
+ "host": "https://bucket.oss-cn-hangzhou.aliyuncs.com",
|
|
|
+ "expire": "2026-05-09T12:00:00Z"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**SignatureVO 字段说明**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `accessId` | `String` | OSS AccessKeyId |
|
|
|
+| `policy` | `String` | Base64 编码的上传策略 |
|
|
|
+| `signature` | `String` | 策略签名 |
|
|
|
+| `fileName` | `String` | 随机生成的文件名 |
|
|
|
+| `host` | `String` | OSS Bucket 域名 |
|
|
|
+| `expire` | `String` | 签名过期时间 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 4.3 获取STS临时令牌
|
|
|
+
|
|
|
+```
|
|
|
+POST /file/getTempStsToken
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 获取阿里云 STS 临时访问令牌,有效期为 15 分钟。用于前端安全直传 OSS,降低安全风险。
|
|
|
+
|
|
|
+**Request Body** (`application/json`):
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+|---|---|---|---|
|
|
|
+| `fileType` | `Integer` | 是 | 文件类型: `1` = 图片, `2` = 视频, `3` = 音频, `4` = 文件, `5` = GIF, `6` = 字幕 |
|
|
|
+| `uploadId` | `String` | 否 | 上传ID |
|
|
|
+
|
|
|
+> 该参数继承自 `VideoApiBaseParam`,包含大量通用参数,此处仅列出业务参数。
|
|
|
+
|
|
|
+**Request 示例**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "fileType": 2,
|
|
|
+ "uploadId": "upload_001"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: `data` 为 `StsTokenVO`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 0,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "Expiration": "2026-05-09T10:15:00Z",
|
|
|
+ "AccessKeyId": "STS.xxx",
|
|
|
+ "AccessKeySecret": "yyy",
|
|
|
+ "SecurityToken": "zzz",
|
|
|
+ "RequestId": "req-001",
|
|
|
+ "FileName": "video-vector/123456_abc.mp4",
|
|
|
+ "Host": "https://bucket.oss-cn-hangzhou.aliyuncs.com",
|
|
|
+ "Hosts": ["https://bucket.oss-cn-hangzhou.aliyuncs.com"],
|
|
|
+ "Bucket": "bucket-name",
|
|
|
+ "Region": "oss-cn-hangzhou",
|
|
|
+ "Cname": false,
|
|
|
+ "serverTimestamp": 1746782100000
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**StsTokenVO 字段说明**:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `Expiration` | `String` | 令牌过期时间 |
|
|
|
+| `AccessKeyId` | `String` | STS AccessKeyId |
|
|
|
+| `AccessKeySecret` | `String` | STS AccessKeySecret |
|
|
|
+| `SecurityToken` | `String` | STS 安全令牌 |
|
|
|
+| `RequestId` | `String` | 请求ID |
|
|
|
+| `FileName` | `String` | 随机生成的文件名 |
|
|
|
+| `Host` | `String` | OSS Bucket 域名 |
|
|
|
+| `Hosts` | `String[]` | OSS Bucket 域名列表 |
|
|
|
+| `Bucket` | `String` | OSS Bucket 名称 |
|
|
|
+| `Region` | `String` | OSS 区域 |
|
|
|
+| `Cname` | `Boolean` | 是否使用 CNAME |
|
|
|
+| `serverTimestamp` | `Long` | 服务器时间戳(毫秒) |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 五、HealthController (`/`)
|
|
|
+
|
|
|
+### 5.1 健康检查
|
|
|
+
|
|
|
+```
|
|
|
+GET /healthcheck
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 服务探活端点,用于负载均衡/容器编排的健康检查。
|
|
|
+
|
|
|
+**请求参数**: 无。
|
|
|
+
|
|
|
+**示例请求**:
|
|
|
+
|
|
|
+```
|
|
|
+GET /healthcheck
|
|
|
+```
|
|
|
+
|
|
|
+**Response**: 返回纯文本 `ok` (非 `CommonResponse` 包装):
|
|
|
+
|
|
|
+```
|
|
|
+ok
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 六、XxlJobController (`/job`)
|
|
|
+
|
|
|
+定时任务触发器,供 XXL-Job 调度中心回调。所有接口无请求参数,返回 `CommonResponse<Void>`。
|
|
|
+
|
|
|
+### 6.1 视频向量化任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/vectorVideoJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发视频向量化任务。
|
|
|
+
|
|
|
+### 6.2 AIGC视频向量化任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/aigcVideoVectorJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发 AIGC 视频向量化任务。
|
|
|
+
|
|
|
+### 6.3 结果日志视频向量化任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/resultLogVideoVectorJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发结果日志视频向量化任务。
|
|
|
+
|
|
|
+### 6.4 全量视频向量化任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/allVideoVectorJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发全量视频向量化任务。
|
|
|
+
|
|
|
+### 6.5 重试解构任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/retryDeconstructJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 重试失败的解构任务。
|
|
|
+
|
|
|
+### 6.6 检查素材解构任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/checkMaterialDeconstructJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发素材解构状态检查。
|
|
|
+
|
|
|
+### 6.7 素材向量化任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/vectorMaterialJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发素材向量化任务。
|
|
|
+
|
|
|
+### 6.8 同步视频详情任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/syncVideoDetailJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发视频详情同步任务(从外部数据源同步至本地)。
|
|
|
+
|
|
|
+### 6.9 视频标题向量化任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/videoTitleVectorJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发视频标题向量化任务。
|
|
|
+
|
|
|
+### 6.10 同步AI理解数据任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/syncAiUnderstandingJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发 AI 理解数据同步任务(从 ODPS → DataWorks → 本地表)。
|
|
|
+
|
|
|
+### 6.11 渠道需求匹配任务
|
|
|
+
|
|
|
+```
|
|
|
+GET /job/channelDemandMatchJob
|
|
|
+```
|
|
|
+
|
|
|
+**用途**: 触发渠道需求匹配计算任务。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、数据流与架构说明
|
|
|
+
|
|
|
+### 解构数据管线的来源链路
|
|
|
+
|
|
|
+```
|
|
|
+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/getDeconstructResultMini` | 返回精简后的解构结果 |
|
|
|
+| 相似视频匹配 | `POST` | `/videoSearch/matchTopNVideo` | Top-N 向量召回相似视频 |
|
|
|
+| 召回并综合评分 | `POST` | `/videoSearch/recallWithScore` | 召回后按 sim + rov 综合分排序 |
|
|
|
+| 查询渠道需求匹配 | `POST` | `/videoSearch/queryDemandMatchResult` | 按日期/渠道/维度查询匹配视频 |
|
|
|
+| 获取所有配置码 | `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) |
|
|
|
+| 素材入库 | `POST` | `/material/submit` | 提交素材进行解构+向量化 |
|
|
|
+| 素材相似搜索 | `POST` | `/material/matchTopN` | 检索相似素材 |
|
|
|
+| 文件上传 | `POST` | `/file/upload` | 上传文件至阿里云OSS |
|
|
|
+| 获取OSS签名 | `POST` | `/file/signature` | 获取OSS上传策略签名 |
|
|
|
+| 获取STS令牌 | `POST` | `/file/getTempStsToken` | 获取STS临时访问令牌(15min) |
|
|
|
+| 健康检查 | `GET` | `/healthcheck` | 服务探活,返回 "ok" |
|
|
|
+| 视频向量化Job | `GET` | `/job/vectorVideoJob` | 触发视频向量化任务 |
|
|
|
+| AIGC视频向量化Job | `GET` | `/job/aigcVideoVectorJob` | 触发AIGC视频向量化 |
|
|
|
+| 结果日志向量化Job | `GET` | `/job/resultLogVideoVectorJob` | 触发结果日志向量化 |
|
|
|
+| 全量向量化Job | `GET` | `/job/allVideoVectorJob` | 触发全量视频向量化 |
|
|
|
+| 重试解构Job | `GET` | `/job/retryDeconstructJob` | 重试失败解构任务 |
|
|
|
+| 素材解构检查Job | `GET` | `/job/checkMaterialDeconstructJob` | 检查素材解构状态 |
|
|
|
+| 素材向量化Job | `GET` | `/job/vectorMaterialJob` | 触发素材向量化 |
|
|
|
+| 同步视频详情Job | `GET` | `/job/syncVideoDetailJob` | 同步视频详情数据 |
|
|
|
+| 标题向量化Job | `GET` | `/job/videoTitleVectorJob` | 触发标题向量化 |
|
|
|
+| 同步AI理解Job | `GET` | `/job/syncAiUnderstandingJob` | 同步AI理解数据 |
|
|
|
+| 渠道需求匹配Job | `GET` | `/job/channelDemandMatchJob` | 触发渠道需求匹配计算 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 九、错误状态码
|
|
|
+
|
|
|
+| code | 含义 | 典型场景 |
|
|
|
+|---|---|---|
|
|
|
+| `0` | 成功 | — |
|
|
|
+| 非 `0` | 业务异常 | 参数校验失败、向量库不可用、查询超时等,具体 `msg` 字段会描述原因 |
|
luojunhui