离线多模态算子目录：视频、音频、图片、文档、文本与行业数据处理算子-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

离线算子基于 Ray Data 在 AnalyticDB Ray 上分布式执行，用于大规模多模态数据集的批量加工。本文介绍离线算子的使用前提、调用约定、模型服务配置和完整算子目录。

前提条件

已创建 Ray Cluster 资源组。具体操作，请参见托管Ray服务。
Ray 运行环境中已安装 mmops SDK，且 Driver 与所有 Worker 节点使用相同的依赖环境。SDK 的获取、安装、运行与作业提交方法，请参见mmops SDK 使用指南。
输入素材和输出产物位于所有 Worker 节点均可读写的位置，例如集群共享挂载目录或对象存储。
如需使用依赖模型服务的算子（如内容理解、语音识别、向量化和行业领域算子），已在所有执行节点配置模型服务环境变量。详细信息，请参见下文的模型服务配置。

调用方式

在 Driver 中初始化 Ray 并调用 enable_accessor() 后，即可在 Ray Dataset 上调用离线算子。在 Driver 中初始化 Ray 并启用算子入口的代码如下：

import ray
from mmops.ray import enable_accessor

ray.init()
enable_accessor()

不同类型算子的调用入口如下：

算子类型	调用入口
通用多模态算子（视频、音频、图片、文档、文本、公共处理）	`ds.mmops.<算子>()`
行业领域算子	目录中的 `domain.<领域>.<算子>` 对应调用入口 `ds.mmops.<领域>.<算子>()`，领域包括 game、product 和 embodied。

调用示例如下，参数仅作示意，具体参数请参见各算子的接口文档：

ds.mmops.probe_video(...)
ds.mmops.game.normalize_game_name(...)

商品场景中的商品图片描述和商品描述结构化直接复用通用算子 caption_image 和 extract_fields，通过商品场景的 Prompt 配置实现。

每个算子接收一个 Ray Dataset 并返回新的 Ray Dataset，因此可以与 Ray Data 原生算子、自定义离线算子（UDF）以及其他内置算子串联。各算子的输入列、参数、返回列和完整示例，请参见对应的接口文档；端到端的使用方法请参见mmops SDK 使用指南。

通用约定

列与参数：*_column 参数指定从每行读取数据的列名；其他参数是本次调用的全局常量。
返回列：算子默认仅返回声明的结果列，输入列不会自动透传，列表列也不会自动展开。如需保留来源 ID 等业务字段，请通过 keep_columns 显式指定；指定的列与标准结果列重名时会报错，需先用 Ray Data 原生的 rename_columns 改名。您可以使用 select_columns() 裁剪结果列。
产物与结果表：写文件的算子通过 output_dir 指定媒体产物的共享目录或对象存储前缀，SDK 为每行自动生成互不冲突的文件名；结果表通过 write_parquet() 单独保存。两者是独立位置，请勿让产物覆盖输入文件。
错误处理：读取、解码、超时或模型调用失败时，算子直接报错，不会以空结果代替成功结果。
结果顺序：多行结果不保证跨分区的顺序。关联多个 Dataset 的结果时，请使用业务标识，不要依赖行位置一一对应。

各算子支持以下通用调度参数，这些参数不改变单行输入与输出的对应关系：

参数	类型	默认值	说明
`batch_size`	int	1	Ray 批处理行数，取值为正整数。
`concurrency`	int	`1`	Ray 执行并发度，取值为正整数。不等同于单行内部的模型请求数。
`num_cpus`	float	`1`	每个执行任务申请的 Ray CPU 资源，取值须大于 0。

模型服务配置

内容理解、语音识别、向量化以及行业领域等算子需要调用远端模型服务，例如阿里云百炼提供的模型服务。模型服务的地址、模型名称和 API Key 从您使用的模型服务获取，并通过执行节点上的环境变量传给算子：

环境变量	说明
`MMOPS_MODEL_BASE_URL`	模型服务的默认地址。下列各类 `*_BASE_URL` 未配置时，均使用该地址。
`MMOPS_MODEL_API_KEY`	调用模型服务使用的 API Key。
`MMOPS_TEXT_MODEL`	文本模型名称。
`MMOPS_TEXT_BASE_URL`	文本模型服务地址。
`MMOPS_VISION_MODEL`	视觉模型名称。
`MMOPS_VISION_BASE_URL`	视觉模型服务地址。
`MMOPS_ASR_MODEL`	语音识别模型名称。
`MMOPS_ASR_BASE_URL`	语音识别模型服务地址。
`MMOPS_EMBEDDING_MODEL`	文本向量模型名称。文本向量默认使用 OpenAI 兼容的向量接口协议。
`MMOPS_EMBEDDING_BASE_URL`	文本向量模型服务地址。
`MMOPS_IMAGE_EMBEDDING_MODEL`	图片向量模型名称。图片向量默认使用 DashScope（阿里云百炼的模型服务接口）多模态协议。
`MMOPS_IMAGE_EMBEDDING_BASE_URL`	图片向量模型服务地址。

部分算子支持通过 config 或 model_config 参数按任务覆盖模型名称、服务地址和协议，具体请参见各算子的接口文档。

重要

请在所有执行节点的运行环境中安全注入 API Key，不要将密钥写入 Dataset 或代码。

算子目录

离线算子目录按处理对象分为通用多模态算子、行业领域算子，其中商品场景的 2 项复用通用算子。

视频算子（11 项）

详细说明请参见视频算子概述。

视频基础处理

算子	处理能力	核心输入输出
convert_video_to_mp4 视频转 MP4	统一视频容器与编码	视频 → MP4、尺寸与时长
resize_video 视频分辨率调整	保持比例缩放	视频、目标尺寸 → 新视频及实际尺寸
clip_video 视频按时间截取	按明确时间区间截取	视频、起止秒数 → 片段、来源 URI 与媒体属性
probe_video 视频元数据提取	读取媒体技术信息	视频 → 时长、分辨率、编码、帧率及音轨、字幕轨状态
detect_video_scenes 视频场景边界检测	定位镜头切换	视频 → 镜头切换候选时间点
sample_video_frames 视频帧采样	按预算抽取采样帧	视频、采样配置 → 图片及时间戳
extract_video_subtitles 视频字幕轨提取	读取独立字幕轨	视频 → 字幕文本与时间段；画面内字幕需视觉识别

视频理解与证据生成

算子	处理能力	核心输入输出
describe_video_frames 视频帧视觉理解	识别画面主体、场景与文字	采样帧 → 逐帧描述、文字与汇总
describe_video_motion 跨帧动作理解	理解相邻帧中的动作	采样帧 → 带观察时间窗口的动作事件；不代表精确动作边界
describe_video 视频结构化描述	汇总多路证据	视频元信息、视觉证据与字段 Schema → 结构化描述；可组合动作、语音与字幕
build_video_timeline 视频时间证据生成	整理带时间的内容证据	画面、动作、语音、字幕 → 时间证据列表

音频算子（7 项）

详细说明请参见音频算子概述。

算子	处理能力	核心输入输出
probe_audio 音频元数据提取	读取音频技术信息	音频或视频 → 音轨、采样率、声道与编码
extract_audio 音轨提取与标准化	为语音转写准备音频	音频或视频 → 16 kHz 单声道 WAV 与来源偏移
convert_audio 音频格式转换	转换 WAV、MP3、FLAC	音频对象 → 目标格式音频对象
resample_audio 音频重采样	调整采样率与声道数	音频对象、目标采样率 → PCM16 WAV
clip_audio 音频按时间截取	按明确时间区间截取	音频对象、起止秒数 → 片段与累计来源偏移
split_audio 音频按时长切段	按固定时长拆分	PCM WAV → 保留来源的片段列表
transcribe_audio 语音转文字	识别语音并聚合长音频	音频对象 → 全文、可用分段与来源时间

图片算子（8 项）

详细说明请参见图片算子概述。

算子	处理能力	核心输入输出
normalize_image 图片输入标准化	生成模型可读图片对象	图片 URI → PNG 或 JPEG 格式的 Base64 对象
probe_image 图片元数据探测	读取可见尺寸与格式	图片 → 尺寸、模式、透明度及帧数
convert_image 图片格式转换	转换 PNG、JPEG、WebP	图片 → 目标格式 ImageRef
resize_image 图片等比缩放	保持比例适配目标尺寸	图片、目标边界 → 新尺寸 ImageRef
crop_image 图片区域裁剪	按明确矩形框裁剪	图片、坐标与坐标系 → 裁剪结果与当前输入范围
ocr 图片与扫描 PDF 文字识别	按阅读顺序识别文字	图片或 PDF → 全文及逐图、逐页文本
caption_image 图片内容描述	根据提示描述可见内容	图片 → 文本描述
embed_image 图片多模态向量化	编码为检索向量	图片 → 数值向量

文档算子（14 项）

详细说明请参见文档算子概述。

格式读取与转换

算子	处理能力	核心输入输出
convert_doc_to_docx 旧版 Word 转换	转换旧版 Word 文档	DOC → DOCX；需 LibreOffice
extract_pdf_text PDF 文字层抽取	提取已有文字层	PDF → 全文及逐页文本
detect_scanned_pdf PDF 扫描件判定	识别是否需要 OCR	PDF 页文本 → 扫描件判定
extract_text Word、Markdown、TXT、RTF 文本抽取	提取段落与表格文本	DOCX、Markdown、TXT、RTF → 全文与文本页
extract_html HTML 静态文档抽取	提取静态网页内容	HTML → 正文、标题与表格；不执行脚本
extract_xml XML 路径与值抽取	读取结构化路径和值	XML → 路径与文本值
extract_slides PPTX 幻灯片抽取	按页提取演示内容	PPTX → 标题、正文、表格、备注与页码
read_spreadsheet Excel、CSV 行列读取	读取工作表与行列	XLSX、XLS、CSV → 工作表与行列数据
read_parquet_rows Parquet 行与媒体读取	读取列式数据及媒体引用	Parquet、列映射 → 行记录、媒体与来源定位

文档结构与内嵌图片

算子	处理能力	核心输入输出
detect_table_regions 表格区域与表头定位	定位表格与表头	工作表 → 数据区域、表头与列名
parse_table_rows 表格行级结构化解析	将表格解析为业务记录	工作表、字段配置 → 行级结构化记录及来源
extract_embedded_images 文档内嵌图片提取	提取文档中的图片	XLSX 或 DOCX → 图片及可用锚点
bind_spreadsheet_images Excel 图片与数据行关联	将图片绑定到数据行	XLSX 图片锚点、行坐标 → 行引用与匹配状态
extract_toc 文档目录提取	提取书签或标题目录	PDF 书签或 Markdown 标题 → 层级目录

文本算子（3 项）

详细说明请参见文本算子概述。

算子	处理能力	核心输入输出
extract_fields 文本结构化字段提取	按固定 Schema 提取字段	文本、字段定义 → properties 中各属性的具名结果列
split_text 文本分块	将长文本拆成片段	文本、分块配置 → 片段及来源位置
embed_text 文本向量化	生成文本语义向量	文本列表 → 顺序对应的向量列表

公共处理算子（2 项）

详细说明请参见公共处理算子概述。

算子

处理能力

核心输入输出

fetch_file

多来源文件获取

读取或下载源文件

本地路径、OSS、HTTP(S) → 本地文件

file_fingerprint

文件指纹与大小计算

计算文件指纹

文件 → SHA-256 与字节大小，用于判断内容是否相同

行业领域算子（16 项）

按行业对象处理原始资料与记录，输出规范字段、内容标签和关联数据。

游戏领域算子（4 项）：详细说明请参见游戏领域算子概述。

算子	处理能力	核心输入输出
domain.game.normalize_game_name 游戏名称归一	归一游戏名称与实体标识	原始游戏名称、游戏别名目录 → 规范名称、游戏标识与匹配状态
domain.game.extract_license_fields 游戏授权资料字段提取	按游戏授权字段整理资料	授权正文 → 游戏、授权双方、期限、凭证等字段及原文依据
domain.game.classify_game_content 游戏素材内容分类	固定识别素材类型与界面特征	已有画面、语音、字幕证据 → 固定内容类型、游戏 UI、商店标记及依据
domain.game.identify_target_region 游戏素材适用地区识别	推断游戏素材适用市场	语言、界面、商店标记证据 → 国内、海外或通用的判断结果、判断状态与依据；通用包含无法判断，不代表实际投放地区

商品场景算子（4 项）：详细说明请参见商品场景算子概述。

算子	处理能力	核心输入输出
caption_image 商品图片描述	复用通用算子，配置商品 Prompt	商品图片、商品 Prompt（示例提供模板）→ 描述文本
extract_fields 商品描述结构化	复用通用算子，配置商品 Prompt	描述文本、字段 Schema、商品 Prompt → 结构化属性
domain.product.localize_product_image 召回参考图定位与裁剪	参考图先定位，结果供意图识别与下游使用	查询参考图、目标说明 → 参考主体框、裁剪图或原图及状态
domain.product.parse_product_intent 商品意图识别	商品文字与参考图联合意图识别	需求文本、字段目录、可选参考图定位结果 → 四类硬条件与软偏好及未解析项

具身智能算子（8 项）：详细说明请参见具身智能算子概述。

以下 8 项用于机器人多传感器、状态、动作与训练数据加工。

算子	处理能力	核心输入输出
domain.embodied.align_sensor_streams 多传感器时间对齐	对齐多路传感器时序	相机、状态、动作与时钟配置 → 对齐样本及偏差标记
domain.embodied.segment_episodes 任务与轨迹切分	划分完整任务轨迹	采集会话、边界事件或规则 → Episode 清单、边界与源数据引用
domain.embodied.normalize_state 机器人状态标准化	统一机器人观测表示	状态、机器人配置 → 统一字段、单位与坐标
domain.embodied.normalize_actions 动作表示标准化	统一控制动作表示	控制指令、动作配置 → 规范动作序列与有效标记
domain.embodied.annotate_tasks 任务与操作阶段标注	标注任务与操作阶段	Episode、任务记录或观测证据 → 任务指令、阶段、时间范围与标注来源
domain.embodied.build_temporal_samples 时序训练样本构建	生成时序训练窗口	Episode、窗口配置 → 历史观测与目标动作
domain.embodied.validate_trajectories 轨迹质量校验	检查轨迹数据质量	轨迹、质量规则 → 缺帧、错位、越界等问题与位置
domain.embodied.export_dataset 具身训练数据导出	导出训练数据集	已校验的 Episode 清单、目标格式与版本 → 训练数据集及完整性报告；支持 LeRobot 和 RLDS 格式