Gemma 4 视频分析

代码架构

gemma4-video-analysis/
├── .env                   # 环境变量（base_url、key、model）
├── .env.example           # 所需环境变量的模板
├── scripts/
│   └── analyze_video.py   # 独立 CLI 入口
└── SKILL.md               # 本技能参考文档

Scripts 目录 — 可执行工具隔离在 scripts/ 中
单文件工具 — 所有逻辑都在 scripts/analyze_video.py 中
函数式分解 — readVideoAsDataUri、createClient、analyzeVideo、main
类型注解 — 所有公共函数都带类型注解（遵循项目 Python 约定）
边界校验 — 在 CLI 边界进行输入检查（环境变量、文件存在性）
不修改全局状态 — 环境在导入后只读

工作流

通过 video_url 分析本地视频

digraph video_analysis_workflow {
    "从 .env.example 创建 .env" [shape=box];
    "运行 python scripts/analyze_video.py [路径]" [shape=box];
    "load_dotenv 读取 GEMMA4_*" [shape=box];
    "校验环境变量 + 文件" [shape=box];
    "Base64 编码视频" [shape=box];
    "发送 video_url + 提示词" [shape=box];
    "打印模型响应" [shape=doublecircle];
    "显示错误并退出 1" [shape=box];

    "从 .env.example 创建 .env" -> "运行 python scripts/analyze_video.py [路径]";
    "运行 python scripts/analyze_video.py [路径]" -> "load_dotenv 读取 GEMMA4_*";
    "load_dotenv 读取 GEMMA4_*" -> "校验环境变量 + 文件";
    "校验环境变量 + 文件" -> "Base64 编码视频" [label="通过"];
    "校验环境变量 + 文件" -> "显示错误并退出 1" [label="失败"];
    "Base64 编码视频" -> "发送 video_url + 提示词";
    "发送 video_url + 提示词" -> "打印模型响应" [label="通过"];
    "发送 video_url + 提示词" -> "显示错误并退出 1" [label="失败"];
}

复制 .env.example 到 .env，并填写 GEMMA4_BASE_URL、GEMMA4_API_KEY、GEMMA4_MODEL
（可选）在 .env 中设置 GEMMA4_DEFAULT_VIDEO 作为默认视频路径
运行 python scripts/analyze_video.py [ 可选的视频路径 ]
脚本通过 load_dotenv 加载 .env，校验环境变量和文件存在性，然后对视频进行 base64 编码
通过 OpenAI 兼容接口 /v1/chat/completions 发送 video_url + 文本提示词
打印模型响应

回退方案：当 video_url 不受支持时提取帧

如果后端服务不支持 video_url：

以 1 FPS 提取帧（60 秒上限内最多 60 帧）
将每帧编码为 base64 image_url
将所有帧与提示词一起放在单个 messages[0].content 数组中发送

错误处理模式

缺少环境变量 → 打印缺失变量名和示例 export 命令，以代码 1 退出
文件缺失 → 打印绝对路径，以代码 1 退出
API 调用失败 → 在 try/except 中捕获，打印异常信息，以代码 1 退出
不静默吞错 — 所有错误都会输出到终端

配置约定

| 约定 | 值 | 说明 | |------|-------|-----------| | 配置文件 | 项目根目录下的 .env | 标准做法，通过 .env.example 友好地纳入版本控制 | | 环境变量前缀 | GEMMA4_ | 防止与其他 OpenAI 兼容工具冲突 | | 超时时间 | 300.0 秒 | 大体积 base64 负载（>80 MB）需要比默认 60 秒更充裕的时间 | | 默认提示词 | 用中文描述视频 | 与项目面向用户的语言偏好保持一致 | | 最大 Token 数 | 2048 | 足以生成详细的场景描述 | | Top K | 64 | 通过 extra_body 传递给后端，控制采样多样性 |

测试模式

目前这个最小化工具还没有自动化测试套件。手动验证清单：

不带 .env 运行 → 预期会友好地提示缺失变量
文件不存在时运行 → 预期会友好地报错
使用有效的 30 秒 MP4 运行 → 预期会输出中文描述

反模式

| 模式 | 失败原因 | 正确做法 | |---------|--------------|----------------| | 在源码中硬编码 base_url 或 api_key | 无法跨环境复用；存在密钥泄露风险 | 使用 .env + python-dotenv | | 将 .env 提交到 git | 泄露密钥和环境专属 URL | 只提交 .env.example；将 .env 加入 .gitignore | | 向 31B Dense 模型传入含音频的期望 | Gemma 4 31B 不处理音频；只有 E2B/E4B 才支持 | 如需处理音频，请单独转录 | | 上传 5 分钟视频 | 超过 60 秒的帧预算；可能导致 OOM 或被截断 | 分析前裁剪到 60 秒 | | 后端不支持 video_url 时未配置回退 | 部分服务可能只接受图片帧 | 提供帧提取回退逻辑 |

速查参考

# 1. 安装依赖
pip install openai python-dotenv

# 2. 准备环境
cp .env.example .env
# 编辑 .env，填入你的端点地址和凭据

# 3. 运行
python scripts/analyze_video.py              # 默认视频
python scripts/analyze_video.py my_video.mp4 # 指定视频