Gemma 4 视频分析

要解决什么问题

本地 MP4 需要交给 Gemma 4 做多模态理解，但各家的 OpenAI 兼容网关对 video_url、payload 大小和超时的支持并不一致。把密钥写进脚本、错误被静默吞掉，或在不支持整段视频时硬传 base64，都会在联调阶段浪费大量时间。

技能如何工作

技能把可执行逻辑集中在 scripts/analyze_video.py，通过 函数式分解（读视频、建客户端、发起分析、CLI 入口）和类型注解，把边界校验放在命令行一侧：

• 用 python-dotenv 从项目根目录 .env 读取 GEMMA4_BASE_URL、GEMMA4_API_KEY、GEMMA4_MODEL 等变量
• 校验环境变量与视频文件是否存在，缺失时打印变量名或绝对路径并以退出码 1 结束
• 优先将本地视频编码为 data URI，经 /v1/chat/completions 以 video_url 加默认中文提示词请求模型（max_tokens 2048，超时 300 秒，较大负载场景）
• 回退方案：若后端不接受 video_url，则以约 1 FPS 抽帧（60 秒内最多 60 帧），每帧作为 image_url 与提示词一并放入 messages[0].content

API 异常在 try/except 中捕获并输出到终端，不修改全局只读环境状态。

适用边界与注意点

• Gemma 4 31B Dense 不处理音频；需要旁路转录，不要指望模型听懂音轨
• 帧回退有 60 秒 预算，长视频应先裁剪，避免 OOM 或被截断
• 大体积 base64 上传依赖 300 秒超时；仍须确认网关是否支持视频或多图消息
• 配置只提交 .env.example，勿将 .env 纳入版本控制