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="失败"];
}

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

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

如果后端服务不支持 video_url：

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

错误处理模式

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

配置约定

测试模式

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

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

反模式

速查参考

# 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 # 指定视频