README.md

# 在线人物筛选 Demo（YouTube + Tavily 文搜）

给定一个 YouTube 视频链接，自动：

1. 用 `yt-dlp` 抓取视频 + 顶层评论 + 元数据；
2. 跑“高颜值男女可抽取素材”筛选推理（多轮工具调用，`web_search` 走 Tavily 公网搜索）；
3. 产出结构化判定（approve / reject / undecided）、HTML 轨迹、决策表 CSV 等。

本目录已**自包含全部源码**，可整目录拷贝到其他服务器部署。

---

## 一、目录结构

```
demo/
├── run_people_online_tavily.sh     # 入口脚本（可迁移版，REPO_ROOT 自动取本目录）
├── requirements.txt                # Python 依赖（已清理为本地可安装格式）
├── README.md                       # 本文件
├── inference/
│   ├── fetch_youtube_online.py     # 第 1 步：yt-dlp 抓视频/评论 -> work_dir
│   ├── run_people_quality_inference.py  # 第 2 步：单条筛选推理入口
│   ├── attractive_leads_prompt.py  # system / user prompt 构造
│   ├── eval.py                     # 核心：五工具多轮推理 + Tavily/图搜 + HTML
│   └── video_dr_bridge.py          # 桥接层：复用 video_dr_gen 的帧处理/工具逻辑
└── video_dr_gen/                   # VideoDR SFT 构造代码（帧抽取、bbox、图搜/web搜实现）
    ├── assemble_sft_dataset.py     # NEW_SYSTEM_PROMPT 等
    ├── config.py                   # MARS / gateway / 默认帧参数等常量
    ├── prompts.py                  # PHASE1/PHASE2/BASE system prompts
    └── utils.py                    # normalize_bbox / crop_frame / image_search / mars_web_search ...
```

> **重要**：`inference/` 与 `video_dr_gen/` 必须保持现在的相对位置（同在 `demo/` 下）。
> `video_dr_bridge.py` 按 `本文件父目录的父目录 / video_dr_gen` 定位依赖；也可用环境变量
> `VIDEO_DR_SOURCE_ROOT` 显式指定其它路径。
>
> 本 demo 已把用到的 4 个 `video_dr_gen` 文件打包进来并改成相对/可配置定位，
> 迁移后无需依赖旧机器共享盘路径。

---

## 二、运行流程（脚本做了什么）

`run_people_online_tavily.sh <youtube_url>`：

1. 设置出网代理 + `no_proxy`（内网模型直连、公网走代理），激活 conda 环境。
2. **抓取**：调用 `inference/fetch_youtube_online.py`
   - `yt-dlp` 下载 mp4 + `info.json`（含评论），规范化后写出
     `comments.json` / `metadata.json`；
   - 以 `---FETCH--- KEY=VALUE ---END---` 块把 `VIDEO_ID/VIDEO_PATH/COMMENTS_FILE/
     TITLE/CHANNEL/DURATION/VIEW_COUNT/VIDEO_URL` 回传给 shell。
3. **推理**：shell 解析上述 KEY=VALUE，拼成单条参数喂给
   `inference/run_people_quality_inference.py`（`--web-search-backend tavily` + 一组
   `--tavily-*`），复用 `eval.py::evaluate_video_tool()` 的五工具多轮推理逻辑。
4. 标准输出/错误 `tee` 到日志文件。

### 产物
- 抓取缓存：`<work_dir>/<id>.mp4`、`<id>.info.json`、`comments.json`、`metadata.json`
  （默认 `inference/online_runs/<id>_<ts>/`，可用 `WORK_DIR` 复用避免重下）。
- 推理结果（默认 `demo/lead_filter_runs/online_<id>_<ts>/`）：
  `results.jsonl`、`results.html`、`summary.json`、`decision_table.csv`、
  `images/`、`frame_cache/`。
- 日志：`<output_dir>.log`。

---

## 三、用法

```bash
cd demo
./run_people_online_tavily.sh https://www.youtube.com/shorts/ZHI5IkRfXAM
# 或
VIDEO_URL=https://www.youtube.com/watch?v=XXXX ./run_people_online_tavily.sh
# 限制评论数
MAX_COMMENTS=50 ./run_people_online_tavily.sh <url>
```

`--` 之后透传给推理脚本，例如调温度：
```bash
./run_people_online_tavily.sh <url> --temperature 0.6
```

---

## 四、部署到新服务器

### 1. 系统依赖
- `ffmpeg`（yt-dlp 合并 mp4 必需，需在 PATH）。
- `yt-dlp`（pip 安装或系统包均可）。

### 2. Python 依赖
```bash
/home/tione/notebook/gaozhenkun/envs/sglang/bin/python -m pip install -r requirements.txt
# eval.py 顶层 import playwright，需要装浏览器内核：
PLAYWRIGHT_BROWSERS_PATH=$PWD/.playwright-browsers \
  /home/tione/notebook/gaozhenkun/envs/sglang/bin/playwright install chromium
```
> 说明：当前默认使用本机 `/home/tione/notebook/gaozhenkun/envs/sglang` 环境。
> `google-*`（Vertex/Gemini）仅在 `--model-client vertex` 时才需要，默认不装也能跑。

### 3. 必填环境变量 / 配置
| 变量 | 作用 | 默认值 | 迁移时是否要改 |
|------|------|--------|----------------|
| `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 列表文件（每行一个） | `demo/secrets/tavily_api_keys.txt` | 视情况 |
| `HTTP_PROXY_URL` | 公网代理（yt-dlp/Tavily 出网）；直连可设为空 `""` | `http://127.0.0.1:17890` | **是** |
| `YT_DLP` | yt-dlp 可执行路径 | 自动探测 | 视情况 |
| `VIDEO_DR_SOURCE_ROOT` | VideoDR 依赖目录 | 默认用打包的 `demo/video_dr_gen` | 一般不用改 |
| `VIDEO_DEEP_RESEARCH_DATA_ROOT` | 本地批量数据/评测数据根目录 | `demo/local_data` | 可选 |
| `VIDEO_DEEP_RESEARCH_SECRETS_DIR` | 本地 secret 文件目录 | `demo/secrets` | 可选 |
| `PLAYWRIGHT_BROWSERS_PATH` | Playwright 浏览器内核目录 | `demo/.playwright-browsers` | 可选 |

Tavily key 也可不用文件，直接 `export TAVILY_API_KEY=...` 或 `TAVILY_API_KEYS=k1,k2`。

示例（新机直连公网）：
```bash
export CONDA_ENV=/home/tione/notebook/gaozhenkun/envs/sglang
export CONDA_BASE=/root/miniconda3
export MODEL_BASE_URL=http://<your-vlm-host>:8000
export TAVILY_API_KEY=tvly-xxxxxxxx
export HTTP_PROXY_URL=""        # 直连，不走代理
./run_people_online_tavily.sh <youtube_url>
```

### 4. 可选服务（默认不写死旧机器路径）
`web_search` 在本 demo 中走 Tavily。`MARS_RETRIEVAL_ADDRESS` / `MARS_SUMMARIZER_ADDRESS`
默认空字符串，只有显式 `export` 后才会探测内网 MARS/summarizer。

`image_search` 默认读取 `GATEWAY_URL` / `GATEWAY_TOKEN` / `SERPER_API_KEY` /
`OSS_ACCESS_KEY_ID` 等环境变量；未配置时工具会返回配置缺失错误，但不会依赖旧机器明文路径。

---

## 五、运行前自检
```bash
# 模型服务可达？
curl "$MODEL_BASE_URL/v1/models"
# 源码闭包可导入？（应输出 IMPORT_OK）
cd demo/inference && python -c "import fetch_youtube_online, run_people_quality_inference; print('IMPORT_OK')"
```