视频算子概述：视频转码、抽帧、字幕提取与视频内容理解-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

算子列表

基础处理

算子	用途	默认顶层结果列
probe_video	读取视频与轨道信息。	video_uri、duration_s、width、height、fps、codec、frame_count、file_size_bytes、has_audio、has_subtitle、audio_codec、subtitle_codec
convert_video_to_mp4	转为 MP4。	video_uri、source_uri、duration_s、width、height、has_audio
resize_video	等比缩放并输出 MP4。	video_uri、source_uri、duration_s、width、height、has_audio
clip_video	按固定时间范围截取并输出 MP4。	video_uri、source_uri、duration_s、width、height、has_audio
detect_video_scenes	检测视觉切换候选点。	video_uri、status、duration_s、threshold、boundaries_s、scene_count
sample_video_frames	按概览、均匀、定时或动作帧对策略抽帧。	video_uri、frames
extract_video_subtitles	提取独立的文本字幕轨。	video_uri、has_subtitle、track_index、language、codec、text、segments
build_video_timeline	汇集带有时间和来源的证据。	evidence

内容理解

算子	用途	默认顶层结果列
describe_video_frames	理解画面、文字与主体。	video_uri、frames、summary、profile、model
describe_video_motion	比较相邻帧中的动作。	events；`return_report=True` 时另有 video_uri、compared_pairs、skipped_pairs、skip_reasons、model
describe_video	按 Schema 综合生成内容。	Schema 顶层属性，以及 model、schema_version、provided_sources、missing_sources

describe_video 遍历固定的 schema.properties 生成业务结果列：可选字段缺省时补 null，缺少必填字段或出现额外字段时报错。显式的 null 必须由字段 Schema 允许；每层 object 需显式设置 additionalProperties=False，嵌套 struct 同样处理，不会新增 extra 列。

输入与执行规则

不同视频算子使用的输入列如下。并不要求每个 Dataset 都包含全部列，各算子的精确参数、输入条件和全部输出字段请参见对应的接口文档。

输入列	类型	使用方式
`video_uri`	str	URI 类算子默认通过 `video_column="video_uri"` 读取。
`frames`	list[struct]	画面理解和动作理解算子通过 `frames_column="frames"` 读取。
`metadata`	struct	综合描述算子通过 `metadata_column="metadata"` 读取。
`vision`	struct	综合描述或时间线算子使用的完整画面结果。
`motion`	list[struct] 或 struct	动作 events 列或完整报告。
`asr`	struct	已恢复至视频来源时间轴的完整语音识别结果。
`subtitles`	struct	完整的文本字幕结果。

*_column 参数指定从每行读取数据的列名；start_s、end_s、strategy 等普通参数是本次调用的全局常量。视频算子的通用参数如下：

通用参数	类型	默认值	说明
`output_dir`	str	写文件的算子必填	媒体产物的共享目录或对象存储前缀。SDK 自动为每行生成互不冲突的文件名。
`keep_columns`	list[str] \| None	None	需要保留的原输入列。与标准输出列重名时报错，需先用原生 `rename_columns` 改名。
`batch_size`	int	1	Ray 批处理行数，不改变单行输出的基数。
`concurrency`	int	`1`	Ray 执行并发度，取值为正整数。
`num_cpus`	float	`1`	每个执行任务申请的 Ray CPU 资源，取值须大于 0。

默认仅返回各接口文档中声明的结果列。组合多路证据时，可以通过 keep_columns 保留业务标识，再按标识关联，不能假设两个 Dataset 的行位置天然一一对应。需要完整 struct 输入时，请使用原生 map 在调用边界显式打包。write_parquet() 保存结果元数据，output_dir 保存媒体文件；纯文本和证据整理类算子不需要 output_dir。

完整示例：从视频到动作报告

说明

示例中的 /shared 是集群所有 Worker 节点均可读写的共享挂载目录，需预先放置输入视频，并在执行节点配置 MMOPS_VISION_MODEL、MMOPS_VISION_BASE_URL 和 MMOPS_MODEL_API_KEY 环境变量。环境变量说明，请参见离线算子概述。

import ray
from mmops.ray import enable_accessor

ray.init()
enable_accessor()

ds = ray.data.from_items([{
    "asset_id": "demo-001", "video_uri": "/shared/input/sample.mp4",
}])
frames = ds.mmops.sample_video_frames(
    video_column="video_uri", output_dir="/shared/output/video_frames",
    strategy="motion", motion_gap_s=1.0, max_frames=12,
    keep_columns=["asset_id"],
)
result = frames.mmops.describe_video_motion(
    frames_column="frames", max_gap_s=3.0, return_report=True,
    keep_columns=["asset_id"],
)
result.select_columns([
    "asset_id", "video_uri", "events", "compared_pairs", "skip_reasons"
]).write_parquet("/shared/metadata/video_motion")

示例返回结果

以下为与上述调用对应的返回结构示例，媒体内容、模型结果和生成的文件名以实际输入及配置为准。算子返回 Dataset，take() 仅取少量行到本地查看；多行结果不保证跨分区的顺序。

假设上游采集到两个相邻帧，model 为当前配置的模型名称。

import json

rows = result.take(1)
print(json.dumps(rows, ensure_ascii=False, indent=2))

[
  {
    "events": [
      {
        "video_uri": "/shared/input/sample.mp4",
        "event_id": "motion_000000",
        "start_s": 0.0,
        "end_s": 1.0,
        "frame_ids": ["frame_000000", "frame_000001"],
        "subject": "杯子",
        "action": "移动",
        "path": "向右",
        "description": "杯子从桌面左侧移动到右侧。",
        "confidence": 0.9
      }
    ],
    "video_uri": "/shared/input/sample.mp4",
    "compared_pairs": 1,
    "skipped_pairs": 0,
    "skip_reasons": [],
    "model": "<配置的模型名称>",
    "asset_id": "demo-001"
  }
]

帧结构与时间语义

抽帧结果中的每一帧为 FrameRef 结构：

FrameRef 字段	类型	说明
`frame_id`	str	同一行内唯一的帧编号。
`video_uri`	str	来源视频。
`frame_uri`	str	后续 Worker 节点可读取的图片地址。
`timestamp_s`	float	实际帧相对视频起点的秒数，按时间严格递增。
`requested_timestamp_s`	float，可选	请求的采样时间。抽帧结果包含该字段，外部帧可省略。
`role`	str，可选	采样角色。抽帧结果包含该字段。
`width`	int，可选	图片宽度，单位为像素。
`height`	int，可选	图片高度，单位为像素。
`scene_id`	str，可选	外部提供的镜头编号。动作分析可据此跳过跨镜头的帧对。

使用时请注意以下时间语义：

概览抽帧不保证帧间距适合动作观察。请查看 compared_pairs，以区分“已比较但未发现动作”与“没有可比较的帧对”。
动作时间表示观察窗口，语音识别结果中切片（chunk）的时间表示切片范围，二者都不是精确的事件边界。
从视频中提取语音时，请依次使用 extract_audio 和 transcribe_audio，并保留完整音频对象（AudioRef）的来源和偏移。
clip_video 默认严格返回六列，片段从零开始计时。如需记录截取范围，请在后续原生 map 中记录全局 start_s，并另行维护多级来源关系。
读取失败、解码失败、模型失败不能当作正常的空证据传入综合描述。