tmp / HANDOVER.md

Add files using upload-large-folder tool

120e73b verified 7 days ago

12 kB

交接文档：Video Deep Research 视频优质度判别 Demo

负责人：高振坤（zhenkun / zhenkungao）文档用途：说明本 demo 的功能、运行环境、运行方式、配置与密钥、排错与待办，便于他人接手 / 迁移到新服务器 / 后续网页化。代码当前位置：/home/tione/notebook/gaozhenkun/demo/video_deep_research_demo/ 本目录已自包含全部源码，可整目录拷贝/建 git 后迁移。

一、这个 Demo 做什么

给定一个 YouTube 视频链接，自动判别该视频是否为「优质素材」（当前业务口径：是否含可抽取的高颜值男女（帅哥/美女）素材），输出结构化判定（approve / reject / undecided）+ 推理轨迹。

核心方法是 Video Deep Research：让一个 VLM（视频多模态大模型）以「多轮工具调用」的方式自己去研究视频——抽帧、锁定关键帧、放大、反向图搜、网页文搜，最后给出判定。

判别逻辑不是简单分类，而是：模型在每一轮自行决定调用 5 个工具中的哪一个，最终在 <answer> 里输出 JSON 判定，由脚本解析（parse_answer_json），本链路没有独立的 LLM-as-judge 打分环节（judge/summarizer 只在 image_search 摘要里用到）。

5 个工具（Video Deep Research 工具集）

工具	作用
`choose_frames`	选定一个时间/帧区间，返回均匀采样的若干帧
`find_frame`	锁定单个具体帧，细看
`zoom_in`	放大锁定帧的某个 bbox 区域
`image_search`	对锁定帧的某个区域做反向图搜（识别未知实体）
`web_search`	文本网页搜索（已知实体，查外部知识）。本 demo 走 Tavily 公网搜索

工具定义在 inference/attractive_leads_prompt.py 的 _TOOLS_BLOCK，与训练侧 config/tool_config/tools_video_train.yaml 的 5 个工具一一对应（名称/参数/required 一致）。bbox 文案一处是 0–1000、一处是 0.0–1.0，运行时自动识别坐标制式，无影响。

二、整体流程（脚本 `run_people_online_tavily.sh` 做了什么）

YouTube URL
   │
   ├─[第1步 抓取] inference/fetch_youtube_online.py
   │     yt-dlp 下载 mp4 + info.json(含评论) → 规范化 comments.json / metadata.json
   │     以 ---FETCH--- KEY=VALUE ---END--- 块把 VIDEO_ID/VIDEO_PATH/COMMENTS_FILE/... 回传 shell
   │
   ├─[第2步 推理] inference/run_people_quality_inference.py  (单条模式)
   │     调用 eval.py::evaluate_video_tool() 跑「5 工具多轮」推理
   │     ├─ 每轮请求外部 VLM 服务 (MODEL_BASE_URL, OpenAI 兼容)
   │     ├─ web_search → Tavily (公网)
   │     └─ image_search → 内网 gateway/Serper + summarizer (可选)
   │
   └─ 产出：判定 JSON + HTML 轨迹 + 决策表 CSV + 帧图

demo 本机不需要 GPU：它是「客户端」，模型在外部 MODEL_BASE_URL 上已部署。
两步之间用「临时文件 + KEY=VALUE 文本块」中转，不是函数直调（后续网页化时这里要改成 Python API）。

三、运行环境

1. 机器 / 硬件

无需 GPU（模型在远端服务上）。普通 CPU 机器即可。
需能访问：① 外部 VLM 推理服务；② 公网（yt-dlp 拉 YouTube、Tavily 搜索）；③（可选）内网图搜 gateway / MARS summarizer。

2. 系统依赖

ffmpeg（必需，yt-dlp 合并 mp4 用，要在 PATH）。
yt-dlp（pip 或系统包；脚本会在 CONDA_ENV/bin、CONDA_BASE/bin、PATH 里自动探测，也可用 YT_DLP 指定）。
playwright + chromium：eval.py 顶层 import playwright，必须装浏览器内核，否则 import 直接失败。

3. Python 环境

当前本地环境：conda env /home/tione/notebook/gaozhenkun/envs/sglang。

新机器自建：

/home/tione/notebook/gaozhenkun/envs/sglang/bin/python -m pip install -r requirements.txt
PLAYWRIGHT_BROWSERS_PATH=$PWD/.playwright-browsers \
  /home/tione/notebook/gaozhenkun/envs/sglang/bin/playwright install chromium          # 必做

requirements.txt 关键依赖（版本锁自 sglang9，可放宽）： aiohttp / openai / pillow / playwright / requests / beautifulsoup4 / PyYAML / numpy / yt-dlp。 google-*（Vertex/Gemini）仅 --model-client vertex 时需要，默认不用装。

4. 网络 / 外部依赖服务清单

依赖	用途	走代理?	在哪配
VLM 推理服务 `MODEL_BASE_URL`	多轮推理主模型	否（内网直连，加入 no_proxy）	脚本 `MODEL_BASE_URL`，默认 `http://100.102.37.219:8008`
Tavily	`web_search` 公网搜索	是	`TAVILY_API_KEY_FILE` / `TAVILY_API_KEY`
yt-dlp → YouTube	下载视频/评论	是	`HTTP_PROXY_URL`
内网 gateway 图搜	`image_search`（可选）	否（no_proxy）	`GATEWAY_URL` / `GATEWAY_TOKEN` 等环境变量
MARS summarizer	图搜结果摘要（可选）	否（no_proxy）	`MARS_SUMMARIZER_ADDRESS` / `MARS_SUMMARIZER_MODEL`

代理机制：脚本默认 HTTP_PROXY_URL=http://127.0.0.1:17890，公网流量走代理，内网服务进 no_proxy 直连。新机器若直连公网，设 HTTP_PROXY_URL="" 关掉代理。

四、如何运行

快速开始（当前本地环境）

cd /home/tione/notebook/gaozhenkun/demo/video_deep_research_demo
./run_people_online_tavily.sh https://www.youtube.com/shorts/ZHI5IkRfXAM

常用调用方式

# 用环境变量传 URL
VIDEO_URL=https://www.youtube.com/watch?v=XXXX ./run_people_online_tavily.sh

# 限制抓取评论数
MAX_COMMENTS=50 ./run_people_online_tavily.sh <url>

# `--` 之后的参数透传给推理脚本，例如改温度
./run_people_online_tavily.sh <url> --temperature 0.6

关键环境变量（迁移时覆盖默认值）

变量	作用	默认值	迁移必改
`CONDA_ENV`	要激活的 conda 环境路径/名	`/home/tione/notebook/gaozhenkun/envs/sglang`	视情况
`CONDA_BASE`	conda 安装根（`conda shell.bash hook`）	`/root/miniconda3`	视情况
`MODEL_BASE_URL`	VLM 服务（OpenAI 兼容 `/v1`）	`http://100.102.37.219:8008`	✅
`MODEL_NAME`	模型名	`qwen3-vl-video-dr`	视情况
`TAVILY_API_KEY_FILE`	Tavily key 文件（每行一个 key）	`demo/secrets/tavily_api_keys.txt`	视情况
`HTTP_PROXY_URL`	公网代理；直连设 `""`	`http://127.0.0.1:17890`	✅
`YT_DLP`	yt-dlp 路径	自动探测	视情况
`MAX_COMMENTS` / `MAX_TURNS` / `MAX_CONCURRENT`	评论数 / 最大轮数 / 并发	100 / 10 / 1	可选
`WORK_DIR`	复用已下载产物，避免重下	每次新建	可选
`YT_COOKIES` / `YT_COOKIES_FROM_BROWSER`	给 yt-dlp 传 cookie（应对 YouTube 风控）	无	视情况

迁移示例（新机直连公网、自建 conda）

export CONDA_ENV=/home/tione/notebook/gaozhenkun/envs/sglang
export CONDA_BASE=/root/miniconda3
export MODEL_BASE_URL=http://<your-vlm-host>:8000
export MODEL_NAME=<your-model-name>
export TAVILY_API_KEY=tvly-xxxxxxxx
export HTTP_PROXY_URL=""           # 直连，不走代理
./run_people_online_tavily.sh <youtube_url>

五、产物

抓取缓存 <work_dir>/（默认 inference/online_runs/<id>_<ts>/）： <id>.mp4、<id>.info.json、comments.json、metadata.json。
推理结果 <output_dir>/（默认 demo/lead_filter_runs/online_<id>_<ts>/）：
- results.jsonl — 结构化结果（含每轮工具调用）
- results.html — 可视化推理轨迹（逐轮工具/帧图，演示首选）
- summary.json、decision_table.csv — 判定汇总
- images/、frame_cache/ — 抽帧与裁剪图
日志 <output_dir>.log。

六、配置与密钥 ⚠️（迁移 / 建 git 必读）

video_dr_gen/config.py 已改为从环境变量读取凭证和内网地址，默认不再写死旧机器路径或明文 secret：

位置	内容
`config.py`	`SERPER_API_KEY`、`GATEWAY_URL/USERNAME/USERID/GATEWAY_TOKEN`、`MARS_RETRIEVAL_ADDRESS`、`MARS_SUMMARIZER_ADDRESS`、OSS 配置均读环境变量
`run_people_online_tavily.sh`	`TAVILY_API_KEY_FILE` 默认指向 `demo/secrets/tavily_api_keys.txt`；`MODEL_BASE_URL` 仍需按实际模型服务配置

因此：

不要把真实 GATEWAY_TOKEN、SERPER_API_KEY、Tavily key、OSS key 写回源码或提交。
MARS_SUMMARIZER_ADDRESS 默认空，自检会跳过；只有显式配置后才会探测。
若需要 image_search，需要额外配置 gateway/Serper 与 OSS 上传相关环境变量，否则该工具会返回配置缺失错误。

七、运行前自检

# 1) 模型服务可达？
curl "$MODEL_BASE_URL/v1/models"

# 2) 源码闭包可导入？应输出 IMPORT_OK
cd demo/inference && python -c "import fetch_youtube_online, run_people_quality_inference; print('IMPORT_OK')"

# 3) ffmpeg / yt-dlp / chromium 就绪？
ffmpeg -version | head -1; yt-dlp --version; python -c "from playwright.sync_api import sync_playwright; print('pw ok')"

八、常见问题排错

现象	原因 / 处理
import 阶段报 playwright 相关错	没装内核：`playwright install chromium`
yt-dlp 下载失败 / 被风控 / 403	YouTube 对云 IP 风控。配 `HTTP_PROXY_URL`，或用 `YT_COOKIES` / `YT_COOKIES_FROM_BROWSER` 传 cookie；必要时降频
启动卡在自检 / judge 连不上	`config.py` 的 `MARS_SUMMARIZER_ADDRESS` 内网不可达，按第六节设为 `""`
`web_search` 报缺 key	提供 `TAVILY_API_KEY` / `TAVILY_API_KEYS` / `TAVILY_API_KEY_FILE` 三选一
模型请求超时	检查 `MODEL_BASE_URL` 可达、模型名 `MODEL_NAME` 是否匹配；`curl $MODEL_BASE_URL/v1/models`
内网服务走了代理连不上	确认该地址在脚本 `no_proxy` 列表里（默认已含模型 host 与 MARS 地址）
ffmpeg 报错 / mp4 合并失败	装 ffmpeg 并加入 PATH

九、目录结构速查

demo/
├── run_people_online_tavily.sh        # 入口脚本（REPO_ROOT 自动取本目录）
├── requirements.txt                   # Python 依赖（锁自 sglang9）
├── README.md                          # 简版说明
├── HANDOVER.md                        # 本交接文档
├── inference/
│   ├── fetch_youtube_online.py        # 第1步：yt-dlp 抓视频/评论
│   ├── run_people_quality_inference.py# 第2步：单条筛选推理入口（含 health_check）
│   ├── attractive_leads_prompt.py     # ★工具定义 _TOOLS_BLOCK + 业务 system prompt
│   ├── eval.py                        # 核心引擎：5工具多轮 + Tavily/图搜 + HTML 轨迹
│   └── video_dr_bridge.py             # 桥接层：自动定位 video_dr_gen（VIDEO_DR_SOURCE_ROOT 可覆盖）
└── video_dr_gen/                      # 被 bridge 依赖的闭包（4 文件）
    ├── config.py                      # 本地默认配置，secret/内网地址从环境变量读取
    ├── utils.py                       # normalize_bbox / crop_frame / real_image_search ...
    ├── prompts.py
    └── assemble_sft_dataset.py

inference/ 与 video_dr_gen/ 必须保持现在的相对位置（同在 demo/ 下）。

十、已知问题 / 后续待办

网页化（GitHub / HuggingFace Space）需新增：
- Web 层（Gradio/FastAPI）包住现有两步 CLI；
- 把 shell+文件中转改成可调用、可流式吐进度的 Python API（推理耗时长，需进度条）；
- 系统依赖打包（ffmpeg / playwright chromium，Dockerfile 或 HF packages.txt）；
- 增加「本地视频上传」备选输入，规避云端拉 YouTube 被风控；
- 并发队列 / 超时 / 临时目录清理 / 限流。