多媒体 / CV / 语音任务模板

本篇汇总多媒体、计算机视觉与语音方向的 pipeline 任务模板：

video-audio（Ray 分布式视频/多媒体处理）

同一目录下 3 个模板，均基于 Ray 在 K8s 拉起多 Worker 并行执行，共用镜像 ccr.ccs.tencentyun.com/cube-studio/video-audio:20260301，靠「名称 + 启动命令 + 参数」区分（核对 start_download.py、start_video_img.py、start_video_audio.py）：

公共机制：

• 用 Ray 创建集群（Worker 数由 --num_worker 指定，默认 3），从 --input_file 逐行读任务，按行轮询划分到约 1000 个「任务盒」再作为 Ray 远程任务下发到各 Worker。
• 账号：kubeflow-pipeline；gitpath 统一为 /job-template/job/video-audio。

各模板要点：

• media-download：每行 $url $local_path，Worker 内 requests.get 下载；local_path 已存在则跳过，父目录自动创建。参数另有 --download_type（当前仅 url）。
• video-img：每行 $local_video_path $des_img_dir $frame_rate，Worker 内用 ffmpeg 执行 ffmpeg -i <视频> -r <帧率> -f image2 <输出目录>/%5d.jpg，自动建目录（生成 00001.jpg...）。
• video-audio：每行 $local_video_path $des_audio_path，目标 .mp3 直接导出；目标 .wav 先导 mp3 再转 16kHz 单声道 pcm_s16le（常用于语音识别）后删中间 mp3；des_audio_path 已存在则跳过。

依赖：video-img / video-audio 依赖容器内 ffmpeg（镜像已含）。可先用 media-download 下载到本地，再用 video-img/video-audio 处理；保证同一流水线内挂载与路径一致即可。

vision-process（图像处理 + 图片质量评估）

同一目录承载两类能力（两份 README 合并）。

图像批处理（launcher.py）

镜像：ccr.ccs.tencentyun.com/cube-studio/vision-process:20240601。对 --input_dir 下图像批量处理后存到 --save_dir。

图片质量评估（image-data-check.py）

镜像：ccr.ccs.tencentyun.com/cube-studio/vision-process:20260101（与图像处理 README 标注的 20240601 不同——质量评估能力在较新版本镜像）。支持无参考与全参考图像质量评估。

• 基础指标（始终计算）：分辨率、亮度、清晰度（Laplacian 方差）、对比度、过曝/欠曝比例、图像熵、RGB 通道均值、边缘密度、近似重复检测（aHash，需 --hash-dup）。
• 无参考指标：BRISQUE、NIQE。
• 全参考指标（需 --reference）：PSNR、SSIM、MS-SSIM、LPIPS、CLIP 余弦/欧氏距离。

输出：quality_report.json（含 duplicates 分组）、quality_metrics.csv（每图明细：image,img_w,img_h,aspect,brightness_mean,blur_metric,contrast,overexposed_ratio,underexposed_ratio,entropy,r_mean,g_mean,b_mean,edge_density 及可选无参考/全参考列）、plots/（每指标直方图+箱线图，中英文各一份，约 32 张）。

voice-process（音频数据集清洗/增强/评估）

目录无主 README；3 个独立模板，共用镜像 ccr.ccs.tencentyun.com/cube-studio/voice-process:20260101（核对 clean-audio-dataset.py、augment-audio-dataset.py、audio-dataset-eval.py）。

音频清洗（clean-audio-dataset.py）

批量清洗标准化：转单声道、重采样、降噪（频谱减法）、VAD 去非语音、去直流偏移、带通滤波、静音裁剪、RMS 响度归一化（防削波）、质量检查（时长/削波率/静音比例/信噪比）。输出统一 16 位 PCM WAV，保持原目录结构，并写 output_dir/metadata_clean.csv（UTF-8 带 BOM）。

metadata_clean.csv 字段：rel_path,out_path,sr,duration,peak,rms,clipping_ratio,silence_ratio,snr_db,status,message。

音频增强（augment-audio-dataset.py）

随机数据增强生成变体（随机增益±6dB、时间平移±0.2s、高斯噪声 SNR10-25dB、混响 RT60 0.15-0.6s、时间拉伸 0.9-1.1x、音高±2 半音、动态压缩、频谱遮蔽 SpecAugment、带宽限制、背景噪声、随机削波）。输出 16 位 PCM WAV（扁平化到同一目录），命名 {原始路径}_aug{序号}.wav，并写 output_dir/metadata_aug.csv。

metadata_aug.csv 字段：rel_path,out_path,sr,duration,aug_id,status,message。

音频质量评估（audio-dataset-eval.py）

递归扫描目录评估音频质量，生成报告与可视化图表。注意参数名用连字符风格（--scan-dir 等）。

统计分组含：duration_stats（num_clips/total_duration_s/mean_s/std_s/min_s/max_s/p50_s/p90_s/p95_s 等）、audio_quality_stats（peak_mean/peak_max/rms_mean/clip_ratio_mean）、snr_dynamics_stats（snr_db_mean/snr_db_std/dynamic_range_db_mean/silence_ratio_mean/crest_factor_mean/loudness_lufs_mean）、spectral_stats（频谱质心/带宽/滚降/平坦度/对比度）、audio_features_stats（过零率/MFCC 方差/色度偏差）。

yolo26（YOLO26 目标检测：训练/评估/服务）

镜像：ccr.ccs.tencentyun.com/cube-studio/yolo26:20260331（核对 train.py、eval-yolo.py、server.py、app.py；含 Dockerfile-npu 的 ARM64/NPU 变体）。

训练（train.py）

ENTRYPOINT/启动命令为 python train.py，训练完成后把 best 权重拷到 --save_model_path，并把指标写入 /metric.json（供平台展示）。

注意：界面模板里轮数参数写作 --epoch，而 train.py:65 argparse 定义的是 --epochs、默认 300（界面默认却是 1，已核对 README JSON）。argparse 默认允许唯一前缀缩写，--epoch 能匹配到 --epochs，故一般可正常工作；如关闭 allow_abbrev 则会出错。建议注册模板时统一用 --epochs。train.py:66 的 --batch_size 代码默认 16、界面默认 1。

评估（eval-yolo.py，README-eval-yolo）

对 YOLO 检测模型自动算 mAP / Precision / Recall / F1。--root 自动发现 images/ 与 labels/，或用 --images_dir + --labels_dir 显式指定（二选一，--root 支持逗号分隔多目录）。

输出：evaluation_results.csv、evaluation_results.json、evaluation_charts.png、/metric.json（平台元数据）。指标含 mAP@IoU、Precision、Recall、F1-score、各类别 AP（VOC 2010+ 插值）。

推理服务（server.py + app.py）

FastAPI 服务，监听端口 8080（uvicorn.run(host="0.0.0.0", port=8080)，server.py:563）。常规接口（API 详见 yolo26_api.md）：

请求/响应示例：

import requests, base64, json
url = "http://xx.xx.xx.xx/v1/models/MODEL_NAME/versions/MODEL_VERSION/predict"
data = {"image": base64.b64encode(open("a.jpg","rb").read()).decode()}
r = requests.post(url, headers={'Content-Type':'application/json'}, data=json.dumps(data))
print(r.json())   # {"labels":[],"scores":[],"xywhs":[],"orig_shape":[w,h]}

RTSP/RTMP 多路实时流推理（--rtsp / RTSP_URLS）

传 --rtsp 参数或环境变量 RTSP_URLS 即启用；不传则完全退化为 Gradio 图片推理（零影响）。RTSP 相关代码在 rtsp.py。

• 启动：python server.py --rtsp demo（内置两路示例流，容器内自动拉起 MediaMTX + ffmpeg 循环推流）；--rtsp rtsp://a,rtsp://b,rtmp://c/live/x（外部多路，逗号分隔）；RTSP_URLS=demo python server.py 等价。
• token demo（大小写不敏感）展开成两条内置 RTSP 地址并自动去重；其它 token 为任意 cv2.VideoCapture 可识别 URL。
• 启用后额外端点：/（网格 HTML 页）、/rtsp/stream/{idx}（multipart/x-mixed-replace MJPEG 流）、/rtsp/health（JSON 健康检查）；原有接口不变。
• demo 模式额外占用端口：8554(RTSP)、1935(RTMP)、8888(HLS)、8889(WebRTC)；非 demo 模式只占 8080。
• 关键设计：每路流独立子进程各自加载 YOLO（规避 GIL/CUDA 冲突）；reader 线程丢旧帧防解码缓冲堆积；JPEG 只编码一次共享缓存；MJPEG over <img> 取代 Gradio streaming（720p 实测从 ~0.1fps 提到 15fps+）；mp.set_start_method('spawn') 须在 torch/cv2 之前。
• 排障：白屏→curl http://<host>:8080/rtsp/health 看 has_frame；corrupted macroblock→降采样 max_side=720。

yolov8（旧版，建议优先用 yolo26）

job-template/job/yolov8 目录无独立 README，仅含 Dockerfile、build.sh、install-cube-studio.sh、npu/。从这些文件推断：

• 镜像 ccr.ccs.tencentyun.com/cube-studio/yolov8:20250901（build.sh；Dockerfile 顶部注释与 manifest 命令里用带架构后缀的 :20250901-amd64 / -npu），基础镜像 ubuntu-gpu:cuda11.8.0-cudnn8-python3.9，装 torch==2.5.1 torchvision==0.20.1 ultralytics==8.2.55 gradio==4.43.0，预下载 yolov8{n,s,m,l,x}.pt（来自 ultralytics assets v8.2.0）。
• Dockerfile 的 ENTRYPOINT ["python","train.py"] 指向 train.py，但该目录下并无 train.py/server.py/app.py 等源码（仅构建脚本与 npu 目录）。

注意（旧产物）：yolov8 目录功能等价代码已缺失（仅余 Dockerfile/build.sh/install-cube-studio.sh/npu/，已核对），已被 yolo26 取代（yolo26 目录完整含 train/eval/server）。本节仅作存档说明，新项目建议直接用 yolo26；是否删除 yolov8 目录由维护者决定。

paddleocr-vl（文档/图片转 Markdown）

基于 PaddleOCR-VL，把 PDF/图片/DOCX/HTML 识别为文本并输出 Markdown（含版面/表格/公式）。镜像 ccr.ccs.tencentyun.com/cube-studio/paddleocr-vl:20251126，工作目录 /app，启动命令 python start.py（核对 start.py）。

支持格式与流程

输入方式与输出

• 单文件：--input_file_or_path 填文件路径，结果写到 {output_path}/paddleocr-vl-result/ 下 {原文件名}.md。
• 多文件/多目录：英文逗号 , 分隔（中文逗号自动替换），目录递归处理 docx/pdf/png/jpg/jpeg/html，忽略隐藏文件与名为 paddleocr-vl-result 的目录，输出在 {output_path}/paddleocr-vl-result/{输入目录名}/ 保持相对结构。

参数（防 OOM）

防 OOM 策略：预缩放（按上限缩放后再推理）→ 若仍 OOM 只清显存不重建模型、按比例（默认每次 90%）缩小重试，最多 10 次；该逻辑（_predict_image_with_auto_resize()）仅对图片类生效，PDF/DOCX/HTML 由 PaddleOCR-VL 内部按页处理。

python start.py --input_file_or_path /path/a.pdf,/path/images/ --output_path /mnt/{{creator}}/pipeline/example/paddleocr

可与下游「Markdown 转 QA」类模板串联，把 paddleocr-vl-result 作为后续清洗/检索/训练的输入。

本篇为知识库导航/核对稿，具体参数与行为以各算子源码（job-template/job/...）为准。