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 结构:

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

{
  "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 查询解构结果(精简版)

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

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

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

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

Response: data 为 RecallVideoScoreVO:

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

{
  "dt": "20260509",
  "channelName": "美妆类",
  "crowdSegment": "年轻女性",
  "dimension": "传播的分发",
  "pointType": "灵感点",
  "standardElement": "成分安全"
}

Response: data 为 List<ChannelDemandMatchVO>:

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

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

{
  "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时)

三、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 示例:

{
  "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,返回任务唯一标识:

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

{
  "queryText": "烟酰胺精华液功效",
  "configCode": "ALL",
  "topN": 10
}

Response: data 为 List<MaterialMatchResult>:

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

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

{
  "fileType": 1
}

Response: data 为 SignatureVO:

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

{
  "fileType": 2,
  "uploadId": "upload_001"
}

Response: data 为 StsTokenVO:

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

api-documentation.md 37 KB История Исходник

Video Search & Vector Recall API 接口文档

通用约定

基础路径

统一响应格式 CommonResponse<T>

全局行为

一、VideoSearchController (/videoSearch)

1.1 触发内容解构

1.2 查询解构结果

1.3 按内容ID获取解构结果

1.4 查询解构结果(精简版)

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

1.6 召回视频并按综合评分排序

1.7 查询渠道需求匹配结果

1.8 获取所有配置编码

二、VectorRecallTestController (/recallTest)

支持的 configCode

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

2.2 文本召回 (Tab2)

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

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

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

三、MaterialController (/material)

3.1 素材入库

3.2 素材相似搜索

四、FileController (/file)

4.1 文件上传

4.2 获取OSS上传签名

4.3 获取STS临时令牌

五、HealthController (/)

5.1 健康检查

六、XxlJobController (/job)

6.1 视频向量化任务

6.2 AIGC视频向量化任务

6.3 结果日志视频向量化任务

6.4 全量视频向量化任务

6.5 重试解构任务

6.6 检查素材解构任务

6.7 素材向量化任务

6.8 同步视频详情任务

6.9 视频标题向量化任务

6.10 同步AI理解数据任务

6.11 渠道需求匹配任务

七、数据流与架构说明

解构数据管线的来源链路

向量召回流程

AI理解数据链路

八、接口总览表

九、错误状态码

api-documentation.md 37 KB

История Исходник

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

一、VideoSearchController (`/videoSearch`)

二、VectorRecallTestController (`/recallTest`)

三、MaterialController (`/material`)

四、FileController (`/file`)

五、HealthController (`/`)

六、XxlJobController (`/job`)