1. VSR 字幕检测为什么必须升级到 PP-OCRv5VSRvideo-subtitle-remover是一套基于 AI 的硬字幕、文本水印去除工具它的工作链路可以拆成三段先用 OCR 把每一帧里的字幕框找出来再根据这些框生成掩码最后交给 LAMA、STTN 这类修复模型把字幕区域抹掉。很多人以为去不干净是修复模型的问题其实我排查下来绝大多数「字幕时而被消除、时而残留」的锅都在第一段——检测环节。原作者内置的 PaddleOCR 检测模型放在backend/models/V4/ch_det这个 V4 版本已经两年没动过。两年前的检测模型面对现在的视频素材问题很集中艺术字、描边字、半透明字幕、复杂背景上的小字检测框要么漏、要么框歪。框漏了掩码就盖不住字幕修复模型自然无能为力框歪了掩码会误伤正常画面修复后出现糊块。所以你会看到同一段视频里有的帧字幕被干净抹掉有的帧还留着半截。PP-OCRv5 是 PaddleOCR 在 2025 年 8 月随 3.2.0 版本一起放出的新一代检测模型官方模型列表里PP-OCRv5_server_det在复杂背景和小目标上的召回明显比 V4 强。把它换进 VSR 的SubtitleDetect类是性价比最高的一次升级改动只集中在一个类里不用动修复模块也不用重写整个 pipeline。这篇面向的是已经在跑 VSR、想提升字幕检测召回的人以及想把 PaddleOCR 检测服务接到统一 API 通道上做批量验证的人。我会给出可复制的模型加载配置、检测脚本改动、置信度过滤逻辑以及怎么通过 TaoToken 的 API 通道统一调用最后把升级前后效果对比和常见报错一起讲清楚。你跟着做基本能在一个下午完成从 V4 到 V5 的切换验证。需要先明确一点VSR 项目里用的paddleocr版本是 2.10.0而 PP-OCRv5 的TextDetection接口是 3.x 才有的。所以升级不是单纯换个模型文件而是「模型 依赖版本 调用方式」三件套一起动。下面按顺序来。2. TaoToken 前置统一 API 通道与依赖准备在动手改代码之前先把两件事准备好一是 PaddleOCR 3.x 的依赖环境二是通过 TaoToken 统一 API 通道调用检测服务的入口。为什么要走 TaoToken因为 VSR 的字幕检测经常要跑批量视频本地单机推理慢而且不同机器上 CUDA 版本、paddle 编译版本对不齐很容易出现「这台能跑那台报错」。用统一 API 通道把检测请求发出去本地只负责抽帧和拼掩码环境问题就收敛到一处。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接用它做 Base URL 就行。你需要先在控制台生成一个 Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后先复制保存后面配置里要用。依赖这块PaddleOCR 3.x 要求paddlepaddle3.x。官方安装文档在 PaddleOCR 仓库的docs/version3.x/installation.md。如果你有 GPU 且 CUDA 是 12.6可以直接装 GPU 版# GPU 版本需显卡驱动版本 550.54.14 python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/我自己的机器是 Linux驱动 570.124.06nvcc --version显示 CUDA 12.8。但 PaddleOCR 当时还没提供 cu128 的 GPU 包去https://www.paddlepaddle.org.cn/packages/stable/cu128/看只有 CPU 版的 whl。这种情况只能先用 CPU 推理或者把 CUDA 降到 12.6 再装 GPU 版。CPU 版安装pip install paddlepaddle-3.2.0-cp312-cp312-linux_x86_64.whl如果你要离线部署去https://www.paddlepaddle.org.cn/packages/stable/cu126/paddlepaddle-gpu/目录里挑对应 Python 版本和系统的 whl比如paddlepaddle_gpu-3.2.0-cp312-cp312-linux_x86_64.whl下载后本地pip install即可。然后是 PaddleOCR 本身。VSR 原来锁的是paddleocr2.10.0必须升到 3.x 才能用TextDetectionpip install paddleocr3.3.1模型文件方面PP-OCRv5 的检测模型PP-OCRv5_server_det可以从 PaddleOCR 的docs/version3.x/model_list.md里找到下载链接。下载解压后得到PP-OCRv5_server_det_infer目录把它放到 VSR 项目的backend/models/下。注意不要覆盖原来的V4/ch_det保留旧模型方便回滚对比。注意升级paddleocr到 3.x 后原来 2.x 的TextDetector类已经不可用所有调用点都要改成TextDetection。如果你项目里还有别的地方 import 了旧接口一并搜出来改掉否则会报ImportError。到这里前置就绪环境有 paddlepaddle 3.2.0 paddleocr 3.3.1模型有PP-OCRv5_server_det_infer通道有 TaoToken 的 Base URL 和 Key。接下来进入代码改动。3. 可复制配置SubtitleDetect 类改造与 settings 片段VSR 的文本检测核心逻辑集中在backend/main.py的SubtitleDetect类里。原来的流程是text_detector方法初始化TextDetectordetect_subtitle调用它拿到dt_boxesget_coordinates把框转成矩形区域。我们要改的就是这三处外加初始化参数。先看配置文件。VSR 在backend/config.py里定义了模型路径DET_MODEL_BASE os.path.join(BASE_DIR, models) DET_MODEL_PATH os.path.join(DET_MODEL_BASE, MODEL_VERSION, ch_det)其中MODEL_VERSION V4。升级后我们不走这个路径了直接在TextDetection里指定model_dir。但为了保持项目结构清晰建议在 config 里加一个新常量# backend/config.py MODEL_VERSION V4 # 保留旧版本用于回滚 DET_MODEL_V5_PATH os.path.join(BASE_DIR, models, PP-OCRv5_server_det_infer)然后是SubtitleDetect的__init__加上保存控制和置信度阈值参数def __init__(self, video_path, sub_areaNone, save_imgFalse, save_jsonFalse, conf_threshold0.5, output_dir./output): self.video_path video_path self.sub_area sub_area self.save_img save_img self.save_json save_json self.output_dir output_dir self.conf_threshold conf_threshold os.makedirs(self.output_dir, exist_okTrue)接着替换text_detector方法。原来用的是TextDetector现在换成TextDetection并指定 v5 模型cached_property def text_detector(self): import paddle paddle.disable_signal_handler() from paddleocr import TextDetection return TextDetection( model_namePP-OCRv5_server_det, devicegpu if paddle.is_compiled_with_cuda() else cpu, model_dirmodels/PP-OCRv5_server_det_infer )这里的model_dir是相对项目根目录的路径实际跑的时候按你的工作目录调整。device用paddle.is_compiled_with_cuda()自动判断装了 GPU 版就走 GPU否则走 CPU。如果你要把检测请求发到 TaoToken 统一通道可以在项目里加一个settings.json或.env把通道配置集中管理{ taotoken: { base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: PP-OCRv5_server_det, timeout: 60 }, detect: { conf_threshold: 0.5, save_img: false, save_json: true, output_dir: ./output } }注意base_url用https://taotoken.net/api不要带任何查询参数。api_key从控制台生成后填入不要提交到 git建议用环境变量覆盖。三件套对齐一下Base URL 是https://taotoken.net/apiKey 是控制台生成的sk-开头字符串Model ID 是PP-OCRv5_server_det。这三个值在本地推理和远程调用里要保持一致后面验证请求时直接复用。4. 验证请求检测脚本改动与成功结果配置改完接下来改detect_subtitle方法适配 v5 的返回格式。v5 的predict返回的是一个列表每个元素是 dict里面有dt_polys和dt_scores。原来的 2.x 返回的是dt_boxes结构不一样所以这里必须重写def detect_subtitle(self, img, frame_noNone): 检测文本框返回多边形坐标和置信度并根据参数保存结果 frame_no: 当前帧号用于保存文件命名 try: output self.text_detector.predict(img) except Exception as e: print(ferror: {str(e)}) return [], 0.0 res_dict output[0] if not res_dict: return [], 0.0 dt_polys res_dict[dt_polys] dt_scores res_dict[dt_scores] if dt_polys is None or dt_scores is None: return [], 0.0 filtered_polys [] elapse 0.0 for poly, score in zip(dt_polys, dt_scores): if score self.conf_threshold: filtered_polys.append(poly) if self.save_img or self.save_json: base_name fframe_{frame_no} if frame_no else result img_path os.path.join(self.output_dir, f{base_name}.png) json_path os.path.join(self.output_dir, f{base_name}.json) for res in output: if self.save_img: res.save_to_img(save_pathimg_path) if self.save_json: res.save_to_json(save_pathjson_path) return filtered_polys, elapse然后在find_subtitle_frame_no里调用时传入帧号并把get_coordinates的入参从dt_boxes.tolist()改成直接传列表dt_boxes, elapse self.detect_subtitle(frame, frame_nocurrent_frame_no) coordinate_list self.get_coordinates(dt_boxes)改完先做一次单帧验证确认模型能加载、能出框。写个最小脚本import cv2 from backend.main import SubtitleDetect detector SubtitleDetect( video_pathtest.mp4, save_imgTrue, save_jsonTrue, conf_threshold0.5, output_dir./output ) cap cv2.VideoCapture(test.mp4) ret, frame cap.read() if ret: polys, elapse detector.detect_subtitle(frame, frame_no0) print(f检测到 {len(polys)} 个文本框) for p in polys[:3]: print(p) cap.release()跑通的话终端会打印检测到的文本框数量./output/下会生成frame_0.png和frame_0.json。打开 json 能看到dt_polys和dt_scores字段说明 v5 返回格式解析正确。如果你走 TaoToken 通道做远程验证可以用 curl 先探一下服务是否可达curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: PP-OCRv5_server_det, messages: [{role: user, content: ping}] }返回 200 且 body 里有正常响应说明通道和 Key 都没问题。这一步只是验证连通性实际检测还是走本地TextDetection或你封装的服务接口。成功结果长这样单帧检测文本框数量从 V4 的个位数提升到十几甚至几十个艺术字和描边字的框明显更完整dt_scores里大部分分数在 0.8 以上低于conf_threshold的会被过滤掉减少误检。把save_imgTrue打开肉眼对比frame_0.png上画的框能直接看出 V5 比 V4 多框住了哪些字。5. 本篇常见错排查401、local proxy failed 与 reading choices升级过程中最容易撞的几类报错我按实际遇到的顺序列一下对照着排。第一类是401 Unauthorized。这个基本都出在 TaoToken 通道调用上原因无非三个Key 没填、Key 填错、或者请求头格式不对。检查Authorization头是不是Bearer sk-xxx格式中间有空格Key 是不是从控制台复制完整有没有多复制换行。如果本地推理报 401那多半是你把远程调用的配置误用到了本地本地TextDetection不需要 Key。第二类是local proxy failed或连接超时。这个通常出现在你通过通道发请求时本地网络到https://taotoken.net/api不通。先确认 Base URL 没写错不要带 UTM 参数再用 curl 单独测连通性。如果 curl 能通但代码不通检查代码里有没有设置proxies参数指向了错误的地址把代理配置清掉再试。第三类是reading choices或KeyError: choices。这个报错说明你拿到的响应结构和你解析的字段对不上。如果你用 TaoToken 的对话接口做连通性测试返回体里确实有choices但如果你把 PaddleOCR 的检测结果也按choices去解析就会报这个错。检测结果要按dt_polys/dt_scores解析两套结构不要混。第四类是ImportError: cannot import name TextDetector。这是paddleocr版本没升到位还是 2.10.0。执行pip show paddleocr确认版本是 3.3.1如果是 2.x重新pip install paddleocr3.3.1。升级后如果还有别的地方 import 旧类一并改掉。第五类是OAuth相关报错比如OAuth token expired。这个一般出现在你用了带鉴权的通道且 token 过期。重新去控制台生成 Key替换配置里的api_key重启进程即可。注意 Key 不要硬编码在代码里用环境变量或settings.json管理。第六类是模型加载失败报model_dir not found或inference.pdiparams missing。检查PP-OCRv5_server_det_infer目录是不是完整解压里面应该有inference.pdiparams、inference.pdmodel等文件。路径要和你TextDetection里写的model_dir一致相对路径是相对你运行脚本的工作目录不是相对main.py。第七类是检测结果为空len(polys) 0。先确认conf_threshold是不是设太高v5 的分数分布和 v4 不同0.5 起步比较稳再确认输入图像是不是 BGR 格式cv2.imread读进来是 BGRPaddleOCR 内部会处理但如果你手动转成 RGB 又转错检测会失效。最后确认帧本身有没有字幕拿一帧明确有字幕的图测。注意排障时把save_imgTrue和save_jsonTrue打开出错帧的图和 json 都留下来比看日志快得多。json 里能看到原始dt_scores判断是模型没检出还是被阈值过滤了。6. 语义一致 CTA把检测服务接到统一通道升级到 PP-OCRv5 之后本地单帧检测的召回上来了但批量视频跑起来还是慢尤其是 CPU 推理。这时候把检测服务接到 TaoToken 统一 API 通道本地只做抽帧和掩码生成检测请求发出去能省掉大量环境折腾。接入的入口在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL、鉴权方式和请求示例。Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。如果你只是想先验证模型效果可以去模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试如果是长期跑编码和 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更合适。实际接入时把settings.json里的base_url和api_key读进环境变量检测请求统一走https://taotoken.net/api。本地SubtitleDetect保留作为兜底通道不通时自动回退到本地TextDetection。这样既拿到了 v5 的检测精度又不会被单机环境卡住。最后留一个实用技巧升级后先别急着全量跑视频挑三段有代表性的素材——一段艺术字、一段半透明字幕、一段复杂背景小字——分别用 V4 和 V5 各跑一遍把save_img的框对比图存下来。确认 V5 在这三类上都更完整再切默认模型。回滚也简单把MODEL_VERSION改回V4text_detector换回旧实现就行。