企业官网建设流程全解析

最近做多模态应用时，碰到一个特别适合用来“考”视频理解模型的问题：给一段几十秒的鼓掌视频，让模型准确说出现场一共鼓了多少次掌。单独抽一帧看，模型很容易判断“画面里有人在鼓掌”；但要数清次数，却经常出现漏计、重复计、把连续掌声拆成多次的问题。Gemini 3.7 Flash 在这一类场景中表现出的能力，恰好可以引出“智能体视频理解”这个概念：它不再是单纯地把视频转成文字摘要，而是把“看视频”拆成观察、推理、校验多个步骤，最终输出更接近人工复核的结果。

这篇文章会结合“数清鼓掌次数”这个具体任务，拆解 Gemini 3.7 Flash 的视频理解链路，分析智能体机制在其中的作用，并给出可落地的 Python 演示代码、提示词设计思路和工程化建议。无论你是做视频内容分析、会议纪要，还是做行为识别类 AI 应用，都可以参考这套方法。

1. 任务内涵：为什么“数清鼓掌次数”比“识别鼓掌”更难

1.1 “识别”和“计数”是两类不同难度的问题

传统的图像分类模型，只要输入的某一帧中存在鼓掌动作，就可以输出“鼓掌”标签。这种方式解决的是“有没有”的问题，比如：

• 这一帧里有没有人举手；
• 这个画面是不是演唱会现场；
• 这个人是否在做鼓掌动作。

但“数清鼓掌次数”解决的是“有多少次”的问题。模型需要在连续的时间轴上判断动作的起止点，区分一次完整的鼓掌和另一次鼓掌。比如一个人连续拍了三下，中间没有明显停顿，如果只依靠单帧分类，很容易把三次拍手误判成一次长动作；反过来，如果掌声因为现场噪声等原因出现弱信号，又可能把一个连续鼓掌过程拆成多次。

从任务拆解来看，鼓掌计数至少包含以下几个子问题：

• 鼓掌动作的起始点在哪里；
• 一次鼓掌的结束点在哪里；
• 两次鼓掌之间是否满足“新一次”的判定条件；
• 多个人同时鼓掌时，是统计所有人总掌声次数，还是只统计某一个人的动作；
• 视频中是否存在误动作，比如击掌、拍桌子、挥手，可能会被模型误判成鼓掌。

这些问题，单靠“某一帧分类”解决不了，必须依赖时间序列上的推理能力。

1.2 什么是智能体视频理解

“智能体视频理解”可以从两个关键词来理解：智能体 + 视频理解。

先看视频理解。它指的是模型能接收连续的图像帧序列，并理解其中的时间变化信息，而不仅仅是把视频拆成一堆静止图片。典型的视频理解任务包括：

• 视频摘要，比如“这段视频里发生了什么”；
• 动作识别，比如“这段里的人在打球还是跳舞”；
• 视频问答，比如“这个人最后选择了什么颜色的箱子”；
• 事件计数，比如“全场一共鼓了多少次掌”。

再看智能体。这里并不是说模型突然变成了一个能自我思考的独立机器人，而是指模型在实际解决问题时，可以通过多步推理、调用不同工具、分工协作来完成任务。它可以先“看懂视频画面”，再结合音频信息或时间戳进行推断，最后返回结构化的结果。Gemini 3.7 Flash 在视频理解中具备的智能体能力，本质上是把复杂任务拆解成多个环节，并通过模型自身的多模态感知和推理能力来逐步完成。

1.3 数清鼓掌次数能检验模型的哪些能力

鼓掌是一个短促、重复、可能多人同步发生的动作，检验的是模型的综合能力：

所以在实际评估中，一个模型如果连“鼓掌次数”都能相对稳定地数出来，说明它在视频事件定位、动作边界判断、结构化输出方面都有不错的基础。这正是 Gemini 3.7 Flash 这类模型被讨论的原因。

2. 智能体视频理解的工作链路

2.1 从“直接回答”到“分步处理”

早期的多模态模型处理视频问题时，通常采用“一次问答”的方式：

用户：这段视频里鼓了多少次掌？ 模型：大约 6 次。

这种方式的问题在于，如果模型数错了，使用者完全不知道原因，也无法要求模型针对某个片段重新检查。尤其在会议纪要、赛事回放、行为分析等场景中，“大约”的结果无法直接用于业务判断。

智能体视频理解的做法，是把问题拆成多个可验证的小步骤：

第 1 步：观看视频全局，确定鼓掌发生的时间范围； 第 2 步：逐段分析掌声动作的起止点； 第 3 步：结合音频或画面细节确认每一次鼓掌； 第 4 步：汇总次数，并输出带时间戳的结构化结果。

每一步都可以单独检查，也可以让模型针对某一段重新推理。这个概念看起来并不复杂，但对模型的连续帧理解能力和推理稳定性要求很高。

2.2 三个核心模块

在实际实现中，可以把智能体视频理解拆成三个模块：

• 感知模块：负责将视频中的画面和声音信息转换为模型可以理解的上下文，例如从视频中抽取关键帧，或者接入视频片段的音频。
• 推理模块：负责对“鼓掌是否发生”“一次鼓掌何时结束”等判断进行时间维度上的推理。
• 校验模块：负责对模型给出的结果进行二次确认，例如发现“计数结果明显小于视频中出现的拍手动作数量”时，重新定位漏掉的部分。

Gemini 3.7 Flash 之所以能在类似“数清鼓掌次数”的任务中给出较准确的结果，本质上是因为它可以把这三个模块的职责结合起来，在同一个任务上下文中完成。开发者也可以利用这些模块思想，在业务系统中构造自己的 Agent 工作流。

2.3 一个可落地的工作链路示例

假设我们输入给模型一段 30 秒的鼓掌视频，希望模型输出鼓掌次数。推荐的 Agent 工作链路可以这样设计：

开始 ↓ 输入视频路径或视频 URL ↓ 让模型先做全局扫描： “请描述视频中出现了几次明显的鼓掌动作周期” ↓ 针对每个候选时间段再次确认： “第 1 次鼓掌大约从第几秒到第几秒” “是否有连续的多次拍击” ↓ 汇总所有候选时间段 ↓ 输出 JSON 格式结果，包含 total_count 和 clap_segments ↓ 结束

在这个流程里，模型不只是一次性输出答案，而是先找到“可能存在鼓掌动作”的区间，再对区间做精细判断。这种“先粗排、再精排”的方式，能避免很多由于视频过长、动作密集导致的计数遗漏。后续写代码时，我们可以用 Agent 状态管理的方式模拟这一流程。

3. 环境准备与模型接入思路

不同项目接入 Gemini 的方式不完全一样。下面以 Python 环境为例，介绍通用的接入思路。建议使用较新的google-genaiSDK，具体版本请以你的项目实际情况为准。如果当前环境安装的 SDK 版本较旧，可能需要调整导入语句和调用方法。

3.1 准备 Python 环境

建议使用 Python 3.9 及以上版本，并创建一个独立的虚拟环境：

python -m venv venv source venv/bin/activate

在 Windows 环境下，激活命令是：

venv\Scripts\activate

激活后，安装必要的依赖。

3.2 安装 SDK

你可以根据自己使用的云平台或 API 接入方式选择安装包。如果通过 Google AI Studio 提供的 API 接入，可以安装官方 Python SDK：

pip install google-genai

如果需要操作视频文件、切分片段、抽取音频，建议同时安装：

pip install opencv-python ffmpeg-python numpy

其中opencv-python用于视频帧读取，ffmpeg-python用于视频片段处理，numpy用于简单的数据分析。如果你的业务环境已经具备视频预处理服务，则不需要全部安装。

3.3 API Key 与基本配置

调用 Gemini 系列模型需要 API Key，或者使用云平台的服务账号认证。API Key 不要硬编码在代码中，也不要提交到 Git 仓库。推荐通过环境变量加载：

import os GEMINI_API_KEY = os.getenv("GEMINI_API_KEY") if not GEMINI_API_KEY: raise ValueError("请先设置环境变量 GEMINI_API_KEY")

在命令行中设置临时环境变量的方式如下：

export GEMINI_API_KEY="你的API Key"

Windows PowerShell 下可以写为：

$env:GEMINI_API_KEY="你的API Key"

3.4 模型名称的说明

本文示例中的模型名称统一用一个变量表示，比如MODEL_NAME。由于不同用户的项目在接入时间和可用模型列表上可能不同，你可以把它替换成你实际有权限访问的 Gemini Flash 模型名称。更推荐的做法是把它放到配置文件中：

MODEL_NAME = "gemini-3.7-flash"

如果你的账号当前没有该名称对应的模型，请到模型列表或官方接口中查询可用名称，并将该常量替换为实际值。下面的代码不影响整体流程。

4. 用 Python 实现一个鼓掌计数 Demo

4.1 示例视频的选择

为了便于验证效果，建议先准备一段 10 到 20 秒的短视频，画面中有人或多人鼓掌。最好满足以下条件：

• 视频中掌声清晰；
• 鼓掌次数在 3 到 10 次之间；
• 背景环境相对简单；
• 没有过多人物同时快速鼓掌。

这样的视频能帮助我们先验证工作链路是否正确。等流程跑通后，再逐步增加复杂视频。

4.2 入参封装

为了让后续 Agent 流程更容易扩展，我们可以先封装一个视频分析请求的数据结构。这里没有引入重型框架，只是用字典来传递上下文：

def build_video_task(video_path: str, task: str) -> dict: """ 构造视频分析任务的基础上下文。 video_path: 本地视频路径或可访问的视频 URL task: 任务描述，例如 "count_claps" """ return { "video_path": video_path, "task": task, "model_name": MODEL_NAME, "result": None, }

4.3 调用多模态模型的基础函数

接下来的核心是调用 Gemini 系列模型。不同版本的 SDK 调用方式会有区别，但整体思路是一样的：提交视频，并附带一个文本 prompt，让模型返回结构化结果。

下面这段代码为后续 Agent 流程提供了一个基础调用函数：

from google import genai from google.genai import types # 初始化客户端 client = genai.Client(api_key=GEMINI_API_KEY) def ask_model_with_video(video_path: str, prompt_text: str) -> str: """ 向模型传入视频和提示词，返回模型的文本回答。 这里使用 types.Part.from_uri 或本地上传，需要根据你的 SDK 能力选择。 示例代码重点是演示流程，实际 API 参数请以当前 SDK 文档为准。 """ # 如果是本地文件，通常可以先上传，得到一个可访问的 URI。 # 不同版本的 SDK 上传方法可能不同，这里保留一个概念性示例。 video_file = client.files.upload(file=video_path) response = client.models.generate_content( model=MODEL_NAME, contents=[ types.Content( role="user", parts=[ types.Part.from_uri( file_uri=video_file.uri, mime_type=video_file.mime_type, ), types.Part.from_text(text=prompt_text), ], ) ], ) return response.text

这里需要注意：client.files.upload的具体实现、上传后的文件 URI 获取方式，以及generate_content中的参数名，可能会因 SDK 版本不同而不同。如果运行报错，优先去查阅当前版本 SDK 的官方示例，而不是强行改参数名。

4.4 设计 Agent 步骤函数

围绕“先定位，再精查，最后汇总”的思路，我们构造三个步骤函数。

第一步，让模型对视频做全局定位：

def step_locate_clap_segments(video_path: str) -> str: prompt = """ 你是一个专业的视频行为分析助手。 请观看这段视频，找出其中所有可能出现鼓掌动作的时间段。 要求： 1. 按时间顺序列出时间段，格式为 [起止秒数] 2. 如果某段时间内可能有连续多次鼓掌，请单独列出 3. 不要忽略短暂但明显的鼓掌声 """ return ask_model_with_video(video_path, prompt)

第二步，让模型针对可疑时间段做精细确认：

def step_verify_segment(video_path: str, segment_index: int, segment_info: str) -> str: prompt = f""" 请针对视频中的第 {segment_index} 个候选鼓掌时间段进行复核。 候选时间段信息：{segment_info} 复核要求： 1. 判断这个时间段内确实存在鼓掌的次数 2. 如果是一次鼓掌，明确写 1 3. 如果是连续多次鼓掌，请分别写出每一次的起止时间 4. 说明判断依据，尤其要判断是否存在拍桌子、击掌等相似动作 """ return ask_model_with_video(video_path, prompt)

第三步，让模型汇总所有候选时间段的结果：

def step_summarize_count(verify_results: list[str]) -> str: joined = "\n\n".join(verify_results) prompt = f""" 下面是对多个候选鼓掌时间段的复核结果： {joined} 请对以上结果做最终汇总： 1. 输出总鼓掌次数 total_count 2. 排除被误判的非鼓掌动作 3. 用 JSON 格式返回，字段包括 total_count 和 clap_segments """ return ask_model_with_video("", prompt)

可以看到，第三步实际上不一定需要重新传视频，因为前面步骤已经拿到了模型对视频片段的判断文字。不过在真实实现中，也可以让模型再次观看视频，以获得更精确的时间轴信息。

4.5 组装简单 Agent 流程

下面把所有步骤串联起来，形成一个完整的 Agent 流程函数：

def run_clap_count_agent(video_path: str) -> dict: """ 使用“全局定位 -> 分段复核 -> 汇总计数”的智能体流程， 计算视频中出现的鼓掌次数。 """ # 第 1 步：全局定位 locate_result = step_locate_clap_segments(video_path) print("=== 第 1 步：全局定位结果 ===") print(locate_result) # 第 2 步：分段复核 # 实际项目中，这里需要解析 locate_result 中的时间段。 # 为了演示流程，这里假设模型已经返回了两个候选时间段， # 真实场景中可以通过正则或文本解析提取这些信息。 segments = extract_segments_from_text(locate_result) verify_results = [] for idx, seg in enumerate(segments[:5], start=1): verify_text = step_verify_segment(video_path, idx, seg) print(f"\n=== 第 {idx} 个候选时间段复核结果 ===") print(verify_text) verify_results.append(verify_text) # 第 3 步：汇总 summary_text = step_summarize_count(verify_results) print("\n=== 最终汇总结果 ===") print(summary_text) return { "video_path": video_path, "locate_result": locate_result, "verify_results": verify_results, "summary_text": summary_text, }

代码中提到了extract_segments_from_text函数，它用来从模型第一步返回的文本中解析时间段。这个函数可以采用简单的正则匹配实现，比如匹配[12.5-15.2]这样的表达式：

import re def extract_segments_from_text(text: str) -> list[str]: """ 从模型返回的定位结果中提取候选时间段。 这里默认模型会返回类似 [12.5-15.2] 的时间段格式。 实际的 prompt 输出格式需要提前约定好。 """ pattern = r"(\d+(?:\.\d+)?)\s*[-—~～]\s*(\d+(?:\.\d+)?)" matches = re.findall(pattern, text) segments = [] for start, end in matches: start = float(start) end = float(end) if end > start: segments.append(f"[{start}-{end}]") return segments

这段正则会把模型文本中的时间信息提取出来，并转成统一格式。注意，如果第二步返回的是描述性文本而非严格格式，提取效果会不稳定。因此在 prompt 中，一定要要求模型使用固定格式输出。

4.6 主程序入口

最后，写一个主程序入口，方便本地运行：

if __name__ == "__main__": # 这里换成你自己的视频路径 video_path = "./test_videos/clap_demo.mp4" task_context = build_video_task(video_path, "count_claps") print("任务上下文：", task_context) result = run_clap_count_agent(video_path) print("\n全部处理完成。")

为了便于演示，你可以先准备一个简单的视频，命名为clap_demo.mp4，放到项目目录下的test_videos文件夹中。

4.7 预期输出示例

如果视频中一共有 6 次明显鼓掌，理想的输出看起来像这样：

=== 第 1 步：全局定位结果 === 视频中出现了多个鼓掌时间段，可能集中在 1.2-3.5 秒、6.8-9.2 秒、12.0-15.6 秒、20.5-22.8 秒等区间。 === 第 1 个候选时间段复核结果 === 该时间段内出现了连续 3 次鼓掌，时间分别在 1.2-1.8 秒、2.0-2.7 秒、3.0-3.5 秒。 === 第 2 个候选时间段复核结果 === 该时间段内出现了 1 次鼓掌，时间范围为 7.0-7.9 秒。 === 最终汇总结果 === { "total_count": 6, "clap_segments": [ {"start": 1.2, "end": 1.8, "count": 1}, {"start": 2.0, "end": 2.7, "count": 1}, {"start": 3.0, "end": 3.5, "count": 1}, {"start": 7.0, "end": 7.9, "count": 1}, {"start": 12.3, "end": 13.1, "count": 1}, {"start": 21.0, "end": 21.9, "count": 1} ] }

这里需要特别说明：不同模型的输出格式会存在差异，如果你发现第一步返回的时间段并不规范，不要强行依赖正则，可以在 prompt 中明确要求模型“只输出 JSON 格式”，再做结构化解码。

5. 提示词设计的核心要点

在视频理解任务中，提示词对结果的影响非常大。围绕“数清鼓掌次数”这个 Demo，我总结出四个有效设计原则。

5.1 把目标定义清楚

不要只写“请数出鼓掌次数”，而要告诉模型“鼓掌次数”的标准是什么。以下提示词示例更容易让模型对齐目标：

请统计视频中明显的鼓掌次数。 规则： - 一次快速的双手拍击计为 1 次； - 同一人连续快速击掌，按实际次数计数； - 多人同时鼓掌时，只统计所有人产生的明显鼓掌声数量； - 拍桌子、敲击物体、击掌互动的动作不计入鼓掌。

5.2 要求模型给出时间戳

计数结果如果没有时间戳，就难以被人工复核。建议在一开始就要求模型输出每个计数的时间区间：

每个计数结果必须包含起止时间。 判断方法是：从双手开始靠近并接触的瞬间作为起始，到双手分开或动作结束作为结束。

5.3 让模型先判断再计数

为了避免模型在短时间内输出一个“猜测式”的数字，可以在提示词中加入推理链条。

请先描述你在视频中看到的鼓掌动作模式， 例如：是单人鼓掌还是多人鼓掌，掌声是否连续。 然后根据描述给出计数结果。

这种“先描述、后计数”的方式，在大多数情况下能降低重复计数和漏计的概率。

5.4 使用固定输出格式

对于需要进入业务系统的场景，强制模型返回 JSON 非常关键。可以在 prompt 末尾增加如下内容：

只输出 JSON，不要输出其他解释。 格式如下： { "total_count": 数字, "clap_segments": [ {"start": 秒数, "end": 秒数, "description": "描述"} ] }

这样后续代码可以直接用json.loads解析，减少格式混乱带来的问题。

6. 常见问题与排查思路

6.1 模型经常漏计快速连续的鼓掌声

排查建议： 优先把视频切分为 5 到 10 秒的片段，再逐段让模型计数。最后合并结果，而不是直接让模型看完整段长视频。

6.2 无法从结果中还原鼓掌发生的时间

6.3 背景音复杂，误把其他声音当成鼓掌声

如果视频里同时有音乐、人声、拍桌声，模型的计数准确性可能下降。此时建议不要把画面和音频混在一起做单一判断，而是分步骤提取信息：

• 先用音频工具检测明显的低频冲击声；
• 再把对应时间片段交给模型进行画面确认；
• 最后合并音频事件和视觉确认结果。

这样做可以大幅减少误判，不过实现复杂度比纯调用多模态模型要高一些。

6.4 视频太长导致结果不稳定

Gemini 系列的 Flash 模型定位是高效处理，但视频长度越长，计数任务的不确定性越高。如果视频超过几分钟，建议先抽帧或切段，再将多个 segment 输出合并。合并时要注意处理边界重复计数问题，避免两个片段交界处的一次鼓掌声被算了两次。

7. 工程化落地的实践建议

7.1 结果一致性设计

模型的输出天然带有随机性。同一个视频调用两次，结果可能不一致。工程落地时不能把模型输出直接当成“数据库里唯一的真相”，而是要做多层确认：

• 让模型对同一段视频执行两次分析，比较结果是否一致；
• 对存在大差异的片段，标记为“需要人工复核”；
• 保留每次分析的时间戳 prompt 版本，方便排查计数偏差来源。

7.2 视频预处理规范

不是所有视频都能直接送入模型进行分析。建议在进入 Agent 流程之前，先对视频做统一预处理：

• 统一分辨率，建议不超过模型限定的最大分辨率；
• 统一编码格式，推荐 MP4/H.264；
• 控制视频时长，超过阈值先切片；
• 如果场景包含大段无声画面，可以降低采样帧率或忽略静音片段。

通过合理的预处理，能够降低输入 token 消耗，并减少无效帧对模型的干扰。

7.3 业务上的权限与授权

如果你处理的视频涉及人物肖像、会议内容、隐私数据，务必在采集和处理前获得合法授权。尤其在内部系统试点时，不要直接使用真实用户视频进行无限制测试。建议先用脱敏数据或公开测试集验证效果，再逐步扩大到真实业务场景。

7.4 结合其他工具构建更强的 Agent

“数清鼓掌次数”虽然是一个偏展示性的任务，但它背后的思路可以用来扩展出许多生产级功能：

• 分析直播带货录屏中的“互动鼓掌”次数；
• 统计课堂中学生齐声回答的次数；
• 从演讲视频中统计观众欢呼或鼓掌频次；
• 在体育录像中计算特定动作的重复次数。

更强的 Agent 往往不是只靠一个模型函数，而是让模型具备调用切片工具、音频分析服务、规则校验脚本的能力。比如模型发现某段音频出现了强烈冲击波，但它不确定是否来自鼓掌声时，就可以调用一个音频频谱分析函数来判断。把“视觉判断”和“音频分析”结合，更符合人类复核动作事件的思路。

7.5 日志记录与可观测性

给模型发送的 prompt、返回结果、解析后的 JSON、调用耗时，都应该记录在日志中。建议每条分析记录包含：

video_id prompt_version model_name raw_model_output parsed_result warning_flag created_at

这样一旦业务上发现某些视频计数异常，可以快速定位是 prompt 问题、模型问题还是视频本身的问题。

7.6 成本控制

视频类 API 调用成本往往比纯文本高。工程化时可以设置如下策略：

• 先用低成本模型或规则做粗筛，只有粗筛发现鼓掌动作的视频，才调用更强的视频理解模型；
• 对视频进行切片，只分析包含可能动作的时间区间；
• 限制每次请求的视频时长和帧数，避免发送完全冗余的画面。

当然，不同模型的价格和计费方式相差很大，具体需要以下单前的计费说明为准。不要在代码里写死“某一固定价格”，那样一旦价格调整会给业务带来误导。

8. 最后想说的话

“数清鼓掌次数”本质上是一个典型的时间推理任务。Gemini 3.7 Flash 能很好地完成这类任务，说明模型已经不是简单地把画面中的人识别成“鼓掌的人”，而是能顺着时间轴理解动作的连续变化，并通过智能体化的多步流程输出更可用的结构化答案。

如果你也对视频理解类业务感兴趣，建议从这段 Demo 开始，先准备几段不同难度的视频，记录模型在每次实验中的输出，再逐步优化 prompt。不要一开始就追求完美的生产系统，先把“输入视频、输出次数”这条链路跑通，再考虑增加音频分析、多段合并、人工复核这些更复杂的模块。

当你能通过智能体流程稳定完成一个看似简单的计数任务后，再去迁移到更复杂的视频分析场景，就会发现多模态模型的能力比我们想象中更有延展性。希望这篇文章能给你一些思路，也欢迎在 CSDN 评论区交流你在视频理解项目中遇到的实际问题。