docs: 更新 README 反映当前架构
- 补充 detect-best-and-search、detect-best、rerank 命令 - 更新鉴权架构说明（auth-rt 统一鉴权） - 补充 sessionId 和 Langfuse 追踪说明 - 更新环境变量表 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
d497e92626
commit
a235c519ac
112
README.md
112
README.md
|
|
@ -1,19 +1,22 @@
|
||||||
# video-product-snapshot — 视频商品截图
|
# video-product-snapshot — 视频商品以图搜图
|
||||||
|
|
||||||
检测视频中的电商商品，提取最佳商品画面，并通过图片搜索在 1688 找同款。
|
从视频中提取最佳商品帧，以图搜图在 1688 找同款。
|
||||||
|
|
||||||
## 工作原理
|
## 工作原理
|
||||||
|
|
||||||
1. 使用 `ffmpeg` 按配置间隔从视频抽帧
|
1. `ffmpeg` 按 0.5s 间隔抽帧（最多 60 帧）
|
||||||
2. 将每帧发给视觉模型，检测是否有商品并评分
|
2. 视觉质量预过滤（亮度/方差剔除模糊帧）
|
||||||
3. 选出置信度最高的帧作为最佳商品截图
|
3. 容器/架子类产品检测 → 自动选择空载帧
|
||||||
4. 可选：用这张截图调用图片搜索 API 找同款商品
|
4. 视觉模型多帧对比排序，选出最佳商品帧
|
||||||
|
5. 裁剪商品区域 → 上传 → 1688 图搜
|
||||||
|
6. 后置过滤（视觉模型判断结果是否同款）→ rerank 排序
|
||||||
|
|
||||||
## 安装
|
## 安装
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
./install.sh # 安装 auth-rt + 依赖
|
||||||
bun install
|
bun install
|
||||||
bun run build # 输出到 dist/run.js
|
bun run build # 输出到 dist/run.js
|
||||||
```
|
```
|
||||||
|
|
||||||
## 使用方法
|
## 使用方法
|
||||||
|
|
@ -26,77 +29,74 @@ bun dist/run.js <command> [options]
|
||||||
|
|
||||||
| 命令 | 说明 |
|
| 命令 | 说明 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| `detect <video>` | 抽帧并检测商品画面 |
|
| `detect-best-and-search <video>` | **推荐。** 最佳帧 → 图搜 → rerank |
|
||||||
| `search <image>` | 用图片搜同款 |
|
| `detect-best <video>` | 只提取最佳商品帧，不搜图 |
|
||||||
| `detect-and-search <video>` | 完整流程：检测最佳画面 → 搜图 |
|
| `detect-and-search <video>` | 两阶段过滤后图搜（较慢） |
|
||||||
| `session` | 打印当前认证 session token |
|
| `detect <video>` | 抽帧并逐帧检测商品 |
|
||||||
|
| `search <image>` | 用已有图片搜同款 |
|
||||||
|
| `rerank` | 关键词对图搜结果交叉过滤 |
|
||||||
|
| `session` | 获取当前认证会话 token |
|
||||||
|
|
||||||
### 选项（`detect` / `detect-and-search`）
|
### 选项（`detect-best` / `detect-best-and-search`）
|
||||||
|
|
||||||
| 参数 | 默认值 | 说明 |
|
| 参数 | 默认值 | 说明 |
|
||||||
|------|--------|------|
|
|------|--------|------|
|
||||||
| `--interval=<秒>` | `1` | 抽帧间隔（秒） |
|
| `--interval=<秒>` | `0.5` | 帧采样间隔 |
|
||||||
| `--max-frames=<数量>` | `60` | 最多分析帧数 |
|
| `--max-frames=<n>` | `60` | 最大分析帧数 |
|
||||||
| `--output-dir=<目录>` | 视频所在目录 | 抽帧图片保存目录 |
|
| `--output-dir=<目录>` | 视频同目录 | 截图保存目录 |
|
||||||
| `--min-confidence=<0-1>` | `0.7` | 最低检测置信度 |
|
| `--session-id=<id>` | 自动生成 | Langfuse session ID |
|
||||||
| `--dry-run` | — | 解析参数并打印配置，不实际执行 |
|
| `--dry-run` | — | 解析参数，不实际执行 |
|
||||||
|
|
||||||
### 示例
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 检测商品，每 3 秒抽一帧
|
|
||||||
bun dist/run.js detect ./demo.mp4 --interval=3
|
|
||||||
|
|
||||||
# 完整流程 + 更高置信度门槛
|
|
||||||
bun dist/run.js detect-and-search ./demo.mp4 --interval=5 --min-confidence=0.85
|
|
||||||
|
|
||||||
# 用已有截图搜同款
|
|
||||||
bun dist/run.js search ./snapshot.jpg
|
|
||||||
```
|
|
||||||
|
|
||||||
## 输出
|
## 输出
|
||||||
|
|
||||||
所有命令输出 JSON 到 stdout。
|
所有命令输出 JSON 到 stdout，包含 `sessionId` 字段用于 Langfuse 追踪。
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
"sessionId": "skill-20260426-184345-lb06",
|
||||||
|
"status": "success",
|
||||||
|
"command": "detect-best-and-search",
|
||||||
"bestSnapshot": {
|
"bestSnapshot": {
|
||||||
"frameIndex": 4,
|
"frameIndex": 7,
|
||||||
"timestampSeconds": 9,
|
"timestampSeconds": 3,
|
||||||
"imagePath": "/path/to/frame_0004.jpg",
|
"imagePath": "/path/to/frame_0007.jpg",
|
||||||
"confidence": 0.92,
|
"croppedImagePath": "/path/to/frame_0007_cropped.jpg",
|
||||||
"description": "White sneaker with blue logo, left side view",
|
"description": "黑色金属床底鞋架 可折叠移动"
|
||||||
"boundingHint": "centered"
|
|
||||||
},
|
},
|
||||||
"productFrames": [...],
|
"rerank": {
|
||||||
"searchBody": { ... }
|
"keyword": "床底鞋架",
|
||||||
|
"results": [
|
||||||
|
{ "num_iid": 123, "title": "...", "price": "44.00", "sales": 87, "detail_url": "..." }
|
||||||
|
]
|
||||||
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `productFrames` — 所有检测到的画面，按置信度排序（最高在前）
|
## 鉴权架构
|
||||||
- `bestSnapshot` — 排名第一的画面
|
|
||||||
- `searchBody` — 图片搜索 API 的返回（仅 `search` / `detect-and-search`）
|
```
|
||||||
|
~/.openclaw/.env
|
||||||
|
CLIENT_KEY ──→ auth-rt ──→ 业务系统
|
||||||
|
├── /session → access_token
|
||||||
|
└── /client-config → provider.api_key
|
||||||
|
provider.base_url
|
||||||
|
provider.model
|
||||||
|
```
|
||||||
|
|
||||||
|
仅需配置 `CLIENT_KEY`，LLM 凭据和端点均由业务系统下发。
|
||||||
|
|
||||||
## 环境变量
|
## 环境变量
|
||||||
|
|
||||||
唯一必需配置是 `~/.openclaw/.env` 中的 `CLIENT_KEY`：
|
|
||||||
|
|
||||||
```
|
|
||||||
CLIENT_KEY=sk_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx
|
|
||||||
```
|
|
||||||
|
|
||||||
所有凭据和接口地址通过 `auth-rt` 从客户端配置自动获取，无需额外配置。
|
|
||||||
|
|
||||||
### 可选覆盖
|
|
||||||
|
|
||||||
| 变量 | 说明 |
|
| 变量 | 说明 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| `VISION_MODEL` | 覆盖模型名称（默认：`aliyun-cp-multimodal`） |
|
| `CLIENT_KEY` | **必需。** 在 `~/.openclaw/.env` 中配置 |
|
||||||
|
| `VISION_MODEL` | 覆盖模型名称（默认来自 client config） |
|
||||||
|
| `SKILL_SESSION_ID` | Langfuse session ID（自动生成，格式 `skill-YYYYMMDD-HHMMSS-xxxx`） |
|
||||||
| `AUTH_RT_BIN` | 覆盖 `auth-rt` 二进制路径 |
|
| `AUTH_RT_BIN` | 覆盖 `auth-rt` 二进制路径 |
|
||||||
| `TELEMETRY_ENDPOINT` | 上报执行结果到遥测接口 |
|
| `TELEMETRY_ENDPOINT` | 遥测上报接口 |
|
||||||
|
|
||||||
## 前置依赖
|
## 前置依赖
|
||||||
|
|
||||||
- [Bun](https://bun.sh) 运行时
|
- [Bun](https://bun.sh) 运行时
|
||||||
- 系统 PATH 中包含 `ffmpeg` 和 `ffprobe`
|
- 系统 PATH 中包含 `ffmpeg` / `ffprobe`（帧提取）
|
||||||
- 系统 PATH 中包含 `auth-rt` CLI（`search` / `detect-and-search` 需要）
|
- 系统 PATH 中包含 `auth-rt` CLI（鉴权/API 调用）
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue