byted-las-long-video-understand

Files (10)

• LICENSE
• SKILL.md
• checklist.md
• evals.json · evals/
• api.md · references/
• prices.md · references/
• check_format.sh · scripts/
• env_init.sh · scripts/
• generate_result.md.sh · scripts/
• poll_background.sh · scripts/

SKILL.md (first lines)

# LAS 视频精细理解（`las_long_video_understand`）

基于大模型提供多维度、精细化的视频结构化理解。支持小时级（最大 3h）视频的全局理解、事件与行为识别、视频问答、高效摘要及结构化输出。

## 设计模式

本 skill 主要采用：
- **Tool Wrapper**：封装 `lasutil` CLI 调用
- **Pipeline**：包含 Step 0 → Step N 的顺序工作流

## 核心 API 与配置

- **算子 ID**: `las_long_video_understand`
- **API**: 异步（`submit` → `poll`）
- **环境变量**: `LAS_API_KEY` (必填)
- **支持时长**: 最大支持 3h (10G) 视频。

> 详细参数与接口定义见 [references/api.md](references/api.md)。

## Gotchas

- **不可精确预估**：按 Token 计费，受视频时长和复杂度影响极大。
- **密钥安全**：若聊天框屏蔽密钥，让用户在当前目录创建 `env.sh` 并写入 `export LAS_API_KEY="..."`，SDK 会自动读取。
- **免责声明**：最终回复结果时必须包含："本方式的计费均为预估计费，与实际费用有差距，实际费用以运行后火山产生的账单为准。计费说明请参考 [Volcengine LAS 定价](https://www.volcengine.com/docs/6492/1544808)。"，且禁止使用"实际费用"字眼描述预估价。

## 工作流（严格按步骤执行）

复制此清单并跟踪进度：

```text
执行进度：
- [ ] Step 0: 前置检查
- [ ] Step 1: 初始化与准备
- [ ] Step 2: 预估价格
- [ ] Step 3: 提交异步任务
- [ ] Step 4: 轮询任务状态
- [ ] Step 5: 结果呈现
```

### Step 0: 前置检查（⚠️ 必须在第一轮对话中完成）

在接受用户的任务后，**不要立即开始执行**，必须首先进行以下环境检查：
1. **检查 `LAS_API_KEY` 与 `LAS_REGION`**：确认环境变量或 `.env` 中是否已配置。
   - 若无，必须立即向用户索要（提示：`LAS_REGION` 常见为 `cn-beijing`）。
   - **注意**：`LAS_REGION` 必须与您的 API Key 及 TOS Bucket 所在的地域完全一致。如果用户中途切换了 Region，必须提醒用户其 TOS Bucket 也需对应更换，否则会导致权限异常或上传失败。
2. **检查输入路径**：
   - 如果用户要求处理的是**本地文件**，则需要先通过 File API 上传至 TOS（只需 `LAS_API_KEY`，无需额外 TOS 凭证）。
   - 如果算子的**输出结果**存放在 TOS 上，且用户需要下载回本地，则需要 `VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY`。对于**仅需要上传输入文件**的场景，TOS 凭证**不再必须**。
3. **确认无误后**：才能进入下一步。

### Step 1: 初始化与准备

**环境初始化（Agent 必做）**：

```bash
# 执行统一的环境初始化与更新脚本（会自动创建/激活虚拟环境，并检查更新）
source "$(dirname "$0")/scripts/env_init.sh" las_long_video_understand
workdir=$LAS_WORKDIR
```

> 如果网络问题导致更新失败，脚本会跳过检查，使用本地已安装的 SDK 继续执行。

- **处理本地文件时**：先本地检查格式和时长，预估价格，用户确认后再上传：
  ```bash
  # 提前检查视频格式（避免参数错误）
  ./scripts/check_format.sh <local_path>
  # 本地使用 ffprobe 获取时长（无需上传即可预估价格）
  duration_sec=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:noprint_section=1 <local_path>)
  ```
  计算预估价格并等待用户确认后，再执行上传：
  ```bash
  # 用户确认后，上传到 TOS
  lasutil file-upload <local_path>
  ```
  上传成功后返回 JSON，取其中的 `tos_uri`（格式 `tos://bucket/key`）传给算子作为输入路径。

### Step 2: 预估价格（⚠️ 必须获得用户确认）

本 skill 按 token 计费，由于视频长且分析复杂，提交前无法精确预估费用。

1. 查阅 [references/prices.md](references/prices.md) 的说明。
2. 说明此任务产生的 token 量可能会非常大（特别是对于长视频）。
3. **将计费单价告知用户并强制暂停执行**，明确等待用户回复确认。在用户明确回复"继续"、"确认"等同意指令前，**绝对禁止**进入下一步（执行/提交任务）。提示：预估仅供参考，实际以火山账单为准。计费说明请参考 [Volcengine LAS 定价](https://www.volcengine.com/docs/6492/1544808)。

### Step 3: 提交异步任务 (Submit)

构造 `data.json`：
```json
{
  "video_url": "<url>",
  "query": "请总结这个视频的主要内容",
  "fps": 1.0,
  "model_name": "doubao-seed-2-0-lite-260215"
}
```

执行命令：
```bash
data=$(cat "$workdir/data.json")
lasutil submit las_long_video_understand "$data" > "$workdir/submit.json"
task_id=$(cat "$workdir/submit.json" | jq -r '.metadata.task_id')
echo "Task ID: $task_id"
```

### Step 4: 轮询任务状态 (Poll)

```bash
# 获取任务状态
lasutil poll las_long_video_understand "$task_id" > "$workdir/poll.json"
cat "$workdir/poll.json" | jq -r '.metadata.task_status'
```

- 如果状态是 `PENDING` 或 `RUNNING`，等待一段时间后再次执行上述命令。由于是长视频理解，耗时可能较长。
- 如果状态是 `COMPLETED`，继续 Step 5。
- 如果状态是 `FAILED`，向用户报告错误 `error_msg`。

### Step 4: 异步查询 (Poll)

⚠️ **异步任务与后台轮询约束**：

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples