Video Search & Vector Recall API 接口文档

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

通用约定

基础路径

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

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

所有接口均返回以下 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 示例:

{
  "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:

{
  "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 示例:

{
  "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 示例:

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

按文本查询:

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

Response: data 为 List<VideoMatchResult>:

{
  "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 为中文描述:

{
  "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:

{
  "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 示例:

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

Response: data 为 RecallResultVO:

{
  "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:

{
  "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 示例:

{
  "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:

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

Response (数据未就绪时):

{
  "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` 字段会描述原因

api_server.md 20 KB History Raw

Video Search & Vector Recall API 接口文档

通用约定

基础路径

统一响应格式 CommonResponse<T>

全局行为

一、VideoSearchController (/videoSearch)

1.1 触发内容解构

1.2 查询解构结果

1.3 按内容ID获取解构结果

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

1.5 获取所有配置编码

二、VectorRecallTestController (/recallTest)

支持的 configCode

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

2.2 文本召回 (Tab2)

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

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

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

三、数据流与架构说明

解构数据管线的来源链路

向量召回流程

AI理解数据链路

四、接口总览表

五、错误状态码

api_server.md 20 KB

History Raw

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

一、VideoSearchController (`/videoSearch`)

二、VectorRecallTestController (`/recallTest`)