最近处理了一批视频素材发现一个问题同一个视频被不同工具转码、裁剪、加字幕之后散落在好几个目录里硬盘占了两份三份空间。人工一个个看缩略图去重效率太低了。第一反应是想接一个大模型 API用多模态模型判断“视频语义是否相同”但盘算了一下成本又犹豫了。原因很直接大模型 API 按 token 计费视频去重这种任务要反复传帧和文本描述token 用量会非常高。而且用 API 方案还会遇到 token 失效、额度不足、403、登录失败、批量任务中断这些问题几十万条素材跑起来光是重试和补额度就够折腾。所以这次我们来看一种**“零 token 视频去重”**思路不调用任何大模型 API完全用本地图像特征、音频特征和视频指纹做重复检测。没有 token 用量没有额度限制没有网络请求失败适合批量和离线场景。这篇文章会从原理、环境、实现、批量任务、接口、效果测试到排查完整跑一遍这个方案。如果你是要处理个人素材库、团队内容资产或者平台自查这篇文章可以直接收藏。1. 零token视频去重核心能力速览能力项说明项目类型本地离线视频去重方案依赖开源图像/音频处理库核心功能重复视频检测、相似视频分组、批量扫描、HTTP接口token 开销0不调用大模型 API不按 token 计费硬件要求CPU 内存即可可选 GPU 加速显存占用接近 0支持平台Windows / Linux / macOS前提是能安装 Python 和 FFmpeg启动方式命令行脚本 / FastAPI 服务是否支持 API支持可提供 HTTP 接口供其他系统调用是否支持批量任务支持按目录批量扫描输出分组结果适合场景素材库整理、二次创作素材管理、平台内容自查、团队资产去重这套方案的关键点不是“模型多强”而是把重复检测转化成可计算的哈希和特征相似度问题从而绕开大模型 API 的高成本和不确定性。2. 适用场景与使用边界先说明这个方案适合哪些场景。如果你面对的是这些情况零 token 视频去重非常合适同一段源视频被人用不同码率、不同分辨率、不同容器格式重新导出过多次需要清掉冗余副本。二创过程中同一段原始素材被剪辑成多个近似版本需要找出内容重复或高度相似的片段。内容平台运营人员需要对大量离线视频做自查判断是否存在未经授权的重复发布。团队素材库里有大量下载、转码、压缩后的重复文件需要批量清理并释放存储空间。它不适合的场景是“语义级去重”。比如一个视频换掉了全部画面只保留了相同主题和文案或者把横屏改成竖屏、重新拍摄了同场景内容这种“看起来主题一样但画面完全不同”的情况仅靠帧级特征和哈希是无法判断的。要做语义判定通常需要引入 CLIP 之类的多模态向量模型而那是另一套方案且会引入模型推理资源开销不再属于“零 token”范畴。合规边界也要讲清楚。视频去重技术本身是中性工具适合用于自己拥有版权的素材库、获得授权的素材、以及平台要求的内容自查。如果把它用于批量搬运他人视频、逃避原创审核、规避版权保护是不被允许的。文章后续所有实现和测试都以自有素材和测试视频为准。3. 环境准备与前置条件零 token 视频去重的核心依赖是三块Python 环境、FFmpeg、图像/音频特征计算库。建议系统满足以下条件Python 3.9 或更高版本推荐 3.10 或 3.11。FFmpeg用来抽取视频帧和音频流。Windows 下可以把 ffmpeg.exe 放到 PATH 里Linux 下通过 apt 或 yum 安装即可。如果是纯 CPU 方案4 核以上的 CPU、8GB 内存起步处理速度和视频分辨率强相关。磁盘空间按素材规模准备因为抽帧和特征缓存会占用一部分临时空间。创建一个独立的工作目录结构可以这样设计zero-token-video-dedup/ ├── input/ # 待去重的视频目录 ├── cache/ # 特征缓存目录 ├── output/ # 去重结果输出目录 ├── requirements.txt └── dedup.pyrequirements.txt 内容如下opencv-python imagehash Pillow numpy ffmpeg-python fastapi uvicorn pydantic tqdm安装依赖pip install -r requirements.txt注意imagehash 库依赖 Pillowopencv-python 负责视频帧读取ffmpeg-python 只是封装真正干活的是系统里的 FFmpeg。启动正式批量任务之前先用下面的命令确认 FFmpeg 可用ffmpeg -version如果提示找不到命令需要先安装 FFmpeg 并配置 PATH。4. 视频特征提取核心实现零 token 去重的核心思路可以拆成四步抽帧、算图像哈希、算音频特征、做相似度比对。下面逐个实现。4.1 均匀抽帧重复视频可能帧率不同直接逐帧比对代价太高所以采用“均匀抽帧”策略从视频里均匀抽取固定数量的帧比如 16 帧或 24 帧再对每一帧计算感知哈希。用 OpenCV 实现抽帧import cv2 import os def extract_frames(video_path, target_count16): 从视频中均匀抽取 target_count 帧返回图像列表 cap cv2.VideoCapture(video_path) frame_count int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) if frame_count 0: cap.release() return [] indices [int(i * frame_count / target_count) for i in range(target_count)] frames [] current 0 for idx in indices: cap.set(cv2.CAP_PROP_POS_FRAMES, idx) ok, frame cap.read() if ok: frames.append(frame) cap.release() return frames抽帧数量不是越多越好。16 帧对大部分 10 秒到 10 分钟的视频都够用24 帧会更稳但耗时和内存都会上涨。先小样本测试再决定上限。4.2 图像感知哈希图像感知哈希会把一张图片压缩成一个固定长度的哈希值内容越相似哈希值越接近。这里用 average_hash 和 perceptual_hash 两种结合。import imagehash from PIL import Image import numpy as np def frame_to_hash(frame, hash_size16): 将 OpenCV 的 BGR 帧转成感知哈希 rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) pil_img Image.fromarray(rgb) ahash imagehash.average_hash(pil_img, hash_sizehash_size) phash imagehash.phash(pil_img, hash_sizehash_size) return ahash, phash为什么要用两种哈希average_hash 对亮度变化敏感phash 对频域特征更敏感两者组合可以降低误判率。单个哈希只能判断“缩略图级别相似”组合起来更接近“画面内容级别相似”。4.3 哈希差异归一化imagehash 返回的哈希对象可以直接用汉明距离比较。为了方便后续设定阈值把差异归一化到 0 到 1 之间def hash_distance(h1, h2): 返回归一化汉明距离0 表示完全一致1 表示完全不同 max_dist h1.hash.size dist h1 - h2 return dist / max_dist两个 16x16 的 average_hash哈希位数是 256 位除以 256 之后就能得到一个 0 到 1 的相似度差异值。阈值可以先用 0.25 作为基准后面调优。4.4 音频指纹简化版画面完全一致的视频音频也可能一样但也存在画面无变化、音频不同的情况。为了降低误杀可以在抽帧哈希之外增加一个简化的音频特征。先用 FFmpeg 把视频转成 16kHz 单声道 WAVffmpeg -i input.mp4 -ac 1 -ar 16000 -f wav tmp.wav -y然后用 numpy 读取 WAV 数据计算能量包络并降采样成一个固定长度的向量import wave import numpy as np def parse_wav_to_mono(wav_path, target_len128): 读取 wav 文件并计算能量包络特征 with wave.open(wav_path, rb) as wf: n_channels wf.getnchannels() sample_width wf.getsampwidth() sample_rate wf.getframerate() n_frames wf.getnframes() raw wf.readframes(n_frames) audio np.frombuffer(raw, dtypenp.int16) if n_channels 1: audio audio.reshape(-1, n_channels).mean(axis1) # 分块计算 RMS 能量 block_size max(1, len(audio) // target_len) features [] for i in range(0, len(audio) - block_size, block_size): block audio[i:i block_size] rms np.sqrt(np.mean(block.astype(np.float32) ** 2)) features.append(rms) if len(features) target_len: break # 长度不足时补零 if len(features) target_len: features.extend([0.0] * (target_len - len(features))) # 做一次归一化抵消音量大小差异 arr np.array(features, dtypenp.float32) norm np.linalg.norm(arr) if norm 0: arr arr / norm return arr def audio_similarity(feat_a, feat_b): 余弦相似度越接近 1 表示越相似 dot np.dot(feat_a, feat_b) return float(dot)音频特征这一步不是必须的。如果只是清理纯转码副本画面哈希就足够。如果视频夹杂了不同背景音乐版本建议加上音频特征用余弦相似度辅助判断。4.5 视频相似度判定把帧哈希差异和音频相似度合成一个评分再决定是否判重。def video_features(video_path, frame_count16): 提取视频的完整特征包括画面哈希和音频特征并缓存到本地 frames extract_frames(video_path, target_countframe_count) if not frames: return None avg_dist_sum 0.0 phase_dist_sum 0.0 count 0 for frame in frames: ahash, phash frame_to_hash(frame) count 1 # 当前帧不参与自比较这里返回哈希序列 return frames, [frame_to_hash(frame) for frame in frames]实际上更常见的做法是保存整个视频的哈希序列然后用两个序列做逐位对齐比较def compare_video_hashes(hash_seq_a, hash_seq_b): 比较两个视频的哈希序列返回 0 到 1 的相似度1 表示完全一致 if not hash_seq_a or not hash_seq_b: return 0.0 min_len min(len(hash_seq_a), len(hash_seq_b)) if min_len 0: return 0.0 total_diff 0 for i in range(min_len): ahash_a, phash_a hash_seq_a[i] ahash_b, phash_b hash_seq_b[i] diff_a hash_distance(ahash_a, ahash_b) diff_b hash_distance(phash_a, phash_b) total_diff (diff_a diff_b) / 2 avg_diff total_diff / min_len return 1.0 - avg_diff相似度在 0.85 以上可以认为高度相似0.75 到 0.85 之间的建议放到待人工确认列表。音频相似度如果大于 0.98说明音频也几乎一致可以进一步确认判重。5. 批量去重任务与启动方式单文件比对没有意义批量目录扫描才是零 token 方案的价值所在。5.1 目录扫描与特征缓存给每个视频生成特征后先保存一份特征缓存。这样第二次扫描时不需要重新抽帧速度会快很多。这里用一个简单的 JSON 缓存来演示import json import os import hashlib def file_md5(path): 计算文件 MD5用于精确去重 h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(65536), b): h.update(chunk) return h.hexdigest() def scan_video_dir(input_dir): 扫描目录下所有视频文件返回路径列表 exts (.mp4, .mkv, .mov, .avi, .flv, .wmv, .ts) video_list [] for root, dirs, files in os.walk(input_dir): for name in files: if name.lower().endswith(exts): video_list.append(os.path.join(root, name)) return video_list文件 MD5 适合做精确去重特征哈希适合做相似去重两者配合可以分两轮处理先清掉 MD5 完全一致的冗余副本再用特征相似度找出转码裁剪后的相似版本。5.2 批量比较与分组去重分组的逻辑是提前设置阈值把相似度超过阈值的视频放进同一个组。def group_similar_videos(video_paths, threshold0.85): 基于两两相似度对视频分组 groups [] used set() for i in range(len(video_paths)): if i in used: continue group [video_paths[i]] used.add(i) for j in range(i 1, len(video_paths)): if j in used: continue sim compare_video_files(video_paths[i], video_paths[j]) if sim threshold: group.append(video_paths[j]) used.add(j) groups.append(group) return groups两两比较的时间复杂度是 O(n^2)素材少时没问题素材量大了之后建议引入 FAISS 做向量索引这一步后续可以优化。5.3 命令行启动写一个简单的入口脚本if __name__ __main__: input_dir ./input output_json ./output/duplicated_groups.json videos scan_video_dir(input_dir) print(f扫描到 {len(videos)} 个视频) groups group_similar_videos(videos, threshold0.85) result [] for idx, group in enumerate(groups): if len(group) 1: result.append({ group_id: idx, videos: group, count: len(group) }) os.makedirs(./output, exist_okTrue) with open(output_json, w, encodingutf-8) as f: json.dump(result, f, ensure_asciiFalse, indent2) print(f找到 {len(result)} 组重复视频结果已写入 {output_json})启动python dedup.py5.4 服务化启动如果要把去重能力接入内容管理后台需要提供 HTTP 接口。这里用 FastAPI 起一个轻量服务from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class CompareRequest(BaseModel): video_a: str video_b: str class ScanRequest(BaseModel): input_dir: str threshold: float 0.85 app.post(/api/compare) def compare_videos(req: CompareRequest): sim compare_video_files(req.video_a, req.video_b) return {similarity: sim} app.post(/api/scan) def scan_videos(req: ScanRequest): videos scan_video_dir(req.input_dir) groups group_similar_videos(videos, thresholdreq.threshold) valid_groups [g for g in groups if len(g) 1] return {total: len(valid_groups), groups: valid_groups}启动服务uvicorn dedup_service:app --host 0.0.0.0 --port 8000注意接口服务不要直接暴露到公网限制在内网或者加访问认证。6. 功能测试与效果验证去重功能到底准不准必须用一组可控测试视频来验证。准备几类测试样本测试样本说明期望结果original.mp4原始视频作为基准copy_same.mp4原视频直接复制精确重复MD5 一致reencode.mp4原视频重新转码、改码率高度相似相似度高于 0.9resize.mp4分辨率从 1920x1080 改成 1280x720高度相似crop.mp4裁剪掉上下黑边后重新导出相似度较高但可能受裁切区域影响subtitle.mp4原视频加了硬字幕画面内容变化较小相似度仍较高different.mp4完全不同的视频素材相似度低于 0.7测试步骤python scan.py --input ./test_input --output ./test_output.json然后检查 output JSON 中的分组结果看哪些视频被分到了同一组。判定标准同一视频的转码、改分辨率、加字幕版本应该分到同一组。不同内容视频不应出现在同一组。相似度落在 0.75 到 0.85 之间时应进入疑似列表而不要直接判重。如果出现“不同视频被分到同一组”优先降低抽帧数或者提高分类阈值。如果出现“同视频转码后没有进入同一组”优先检查抽帧是否成功尤其是黑场片头、快速切换场景的视频可能需要增加抽帧数到 24 或 32。7. 接口 API 调用示例与批量任务设计服务化之后其他系统可以通过 HTTP 调用去重能力。7.1 单视频相似度比对接口请求示例curl -X POST http://127.0.0.1:8000/api/compare \ -H Content-Type: application/json \ -d {video_a: /data/videos/a.mp4, video_b: /data/videos/b.mp4}返回示例{ similarity: 0.93 }7.2 批量扫描接口请求示例curl -X POST http://127.0.0.1:8000/api/scan \ -H Content-Type: application/json \ -d {input_dir: /data/input, threshold: 0.85}返回示例{ total: 2, groups: [ { group_id: 0, videos: [/data/input/a.mp4, /data/input/reencode_a.mp4] } ] }Python 调用示例import requests url http://127.0.0.1:8000/api/compare payload { video_a: /data/videos/a.mp4, video_b: /data/videos/b.mp4 } response requests.post(url, jsonpayload, timeout300) print(response.json())7.3 批量任务与失败重试批量任务设计上要避免两个坑一是视频文件本身损坏导致抽帧失败二是部分视频编码格式特殊导致 FFmpeg 报错。建议每个视频独立 try/except失败时记录日志不影响后续视频处理。def safe_scan(input_dir): videos scan_video_dir(input_dir) results [] errors [] for video in videos: try: feature build_feature(video) results.append({video: video, feature_ok: True}) except Exception as e: errors.append({video: video, error: str(e)}) continue return results, errors然后把 errors 写入单独的 error.log二次扫描时只重试失败文件。8. 资源占用与性能观察零 token 方案最大的优势是不消耗大模型 token资源占用集中在 CPU、内存和磁盘 I/O 上显存占用基本为 0。性能观察要点抽帧阶段CPU 占用会比较高尤其是高分辨率视频。如果是多核机器建议多进程并行每个进程处理不同视频。内存占用主要取决于同时读取多少帧。单视频 16 帧、1080p 分辨率内存占用在几百 MB 级别。批量处理时不要一次性把所有视频帧读进内存最好流式处理。特征缓存建议把特征哈希保存到磁盘第二次扫描时直接读取缓存避免重新抽帧。GPU 是否必要这套方案没有使用任何深度模型GPU 不是必须的。如果后续引入 FAISS 向量索引或 CLIP 语义模型才需要考虑 GPU 加速。用 psutil 在 Python 里观察进程资源占用import psutil def print_process_info(): process psutil.Process() mem_info process.memory_info() print(f内存占用: {mem_info.rss / 1024 / 1024:.2f} MB) print(fCPU 占用: {process.cpu_percent(interval1):.2f}%)性能优化方向是降低抽帧数量、限制最大并发数、优先用缓存特征做二次扫描。9. 常见问题与排查方法问题现象可能原因排查方式解决方案扫描时提示 ffmpeg 找不到FFmpeg 未安装或未加入 PATH执行ffmpeg -version安装 FFmpeg 并加入 PATH视频抽帧后得到空列表视频文件损坏或编码格式不支持用 OpenCV 单独打开视频打印帧数换用 VLC 或其他工具尝试转码或跳过该视频两个相同视频相似度只有 0.6抽帧数量太少头尾黑场帧占比较高检查抽帧结果看是否抽到黑帧增加抽帧数量或先做黑帧过滤不同视频被分到同一组两个视频有大量相同静态画面或相同片头片尾查看分组内视频的实际帧提高阈值或加上音频特征辅助判断处理大量视频时内存持续上涨一次性加载了太多帧或特征查看任务管理器确认内存曲线改为流式处理限制并发数接口超时视频比较大抽帧耗时太长检查日志确认耗时点增加超时时间前端先用异步任务轮询结果结果 JSON 中 group_id 不稳定分组顺序依赖扫描顺序规范化排序后再输出按视频路径排序后分配 group_idtoken 失效或接口报 403使用大模型 API 方案时的常见问题检查 API key、额度、地区限制零 token 方案不涉及远程 API直接绕开10. 最佳实践与使用建议从工程落地角度看有几点值得注意。第一次跑批量任务时不要直接删视频。默认输出的是“可疑重复分组”报告人工看一眼再决定是否删除。可以给每个分组生成一张对比缩略图把两个视频的同帧位置并排放一起人工确认速度会快很多。所有视频的特征结果和分组结果都要保存下来。这样第二次扫描时不需要重新抽帧直接加载缓存特征做比较效率能提升不少。涉及大目录时建议按子目录分批处理避免一次性加载太多文件。输出结果也按批次命名比如 output_20250101_01.json。涉及人脸、声音、肖像或版权素材时务必确认是否有合法授权。视频去重工具可以用来管理自有素材和获得授权的内容不能用来规避版权保护或平台审核机制。接口服务要加访问控制和日志记录。如果服务部署在服务器上不要直接绑定 0.0.0.0 暴露到公网建议绑定内网 IP 或者加 token 认证。11. 总结与下一步零 token 视频去重的核心价值是把视频重复检测从“调用大模型 API”降级为“本地特征计算”省掉了 token 用量、额度管理和网络请求异常这些麻烦事。它尤其适合大批量、离线、高重复度的素材清理任务。最先要验证的功能是抽帧和感知哈希能否稳定区分“转码副本”和“完全不同的视频”。如果这一步通过整个方案基本就成立。最容易踩的坑是黑场帧和片头片尾干扰。很多视频有统一片头会导致不同视频被误判为相似。解决办法是过滤黑帧、增加抽帧数量或者把片头片尾区域单独排除。后续如果素材量继续涨可以考虑两个扩展方向一是引入 FAISS 索引解决 O(n^2) 的两两比较问题二是接入 CLIP 这类多模态向量模型做语义去重。但要注意引入模型推理之后就不再是“零 token”方案会变成“本地模型推理”方案成本和复杂度都会上升。对大部分素材库清理和重复检测需求来说先跑通这套零 token 方案成本更低也更可控。建议收藏备用直接在本地素材上跑一轮测试看看效果。