视频理解技能
此技能使用 z-ai-web-dev-sdk 包提供专门的视频理解功能,使 AI 模型能够分析、描述和提取视频内容中的信息,包括动作、时间序列和场景变化。
技能路径
技能位置:{project_path}/skills/video-understand
此技能位于你项目中的上述路径。
参考脚本:示例测试脚本可在 {技能位置}/scripts/ 目录中找到,用于快速测试和参考。请参阅 {技能位置}/scripts/video-understand.ts 获取工作示例。
概述
视频理解专注于视频内容分析,提供以下功能:
- 视频场景理解与描述
- 动作与运动检测
- 时间序列分析
- 视频中的事件检测
- 视频内容摘要
- 场景变化检测
- 跨帧的人物与物体跟踪
- 视听内容分析(如适用)
重要提示:z-ai-web-dev-sdk 仅能在后端代码中使用。切勿在客户端代码中使用。
前提条件
z-ai-web-dev-sdk 包已安装。按照以下示例所示导入即可。
CLI 用法(适用于简单任务)
对于快速的视频分析任务,你可以使用 z-ai CLI 而不是编写代码。这非常适合简单的视频描述、测试或自动化。
基本视频分析
# 分析来自 URL 的视频
z-ai vision --prompt "总结这个视频中发生的事情" --image "https://example.com/video.mp4"
# 注意:视频 URL 也使用 --image 参数
z-ai vision -p "描述关键事件" -i "https://example.com/presentation.mp4"
分析本地视频
# 分析本地视频文件
z-ai vision -p "这个视频中展示了哪些活动?" -i "./recording.mp4"
# 将响应保存到文件
z-ai vision -p "提供详细摘要" -i "./meeting.mp4" -o summary.json
高级视频分析
# 复杂场景理解与思考
z-ai vision \
-p "分析此视频并识别:1) 主要事件,2) 人物及其动作,3) 关键时刻的时间线" \
-i "./event.mp4" \
--thinking \
-o analysis.json
# 动作检测
z-ai vision \
-p "识别此视频中人物执行的所有动作" \
-i "./sports.mp4" \
--thinking
流式输出
# 流式传输视频分析
z-ai vision -p "描述此视频内容" -i "./video.mp4" --stream
CLI 参数
--prompt, -p <文本>:必需 - 关于视频的问题或指令--image, -i <URL 或路径>:可选 - 视频 URL 或本地文件路径(尽管名称如此,它也适用于视频)--thinking, -t:可选 - 启用链式思维推理以进行复杂分析(默认:禁用)--output, -o <路径>:可选 - 输出文件路径(JSON 格式)--stream:可选 - 实时流式传输响应
支持的视频格式
- MP4 (.mp4) - 最广泛支持的格式
- AVI (.avi) - 音频视频交错
- MOV (.mov) - QuickTime 格式
- WebM (.webm) - Web 优化格式
- MKV (.mkv) - Matroska 格式
- FLV (.flv) - Flash 视频格式
何时使用 CLI 与 SDK
使用 CLI 的场景:
- 快速视频摘要
- 一次性视频分析
- 测试视频理解能力
- 简单的自动化脚本
- 生成视频描述
使用 SDK 的场景:
- 关于视频的多轮对话
- 复杂的视频处理流水线
- 带有错误处理的生产应用程序
- 使用视频处理逻辑进行自定义集成
- 带有自定义工作流的批量视频处理
推荐方法
为了获得更好的本地视频性能和可靠性,请考虑:
- 将视频上传到 CDN 并使用 URL
- 对于较短的视频,将关键帧转换为图像以加快分析速度
- 对于长视频,考虑分块或按间隔采样
基本视频理解实现
单一视频分析
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeVideo(videoUrl, prompt) {
const zai = await ZAI.create();
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: prompt
},
{
type: 'video_url',
video_url: {
url: videoUrl
}
}
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
// 使用示例
const summary = await analyzeVideo(
'https://example.com/presentation.mp4',
'总结此视频中呈现的要点'
);
const actionDetection = await analyzeVideo(
'https://example.com/sports.mp4',
'识别并描述此视频中执行的所有运动动作'
);
视频场景理解
import ZAI from 'z-ai-web-dev-sdk';
async function understandVideoScenes(videoUrl) {
const zai = await ZAI.create();
const prompt = `分析此视频并提供:
1. 视频内容的总体摘要
2. 主要场景或片段(如果可能,附上大致时间戳)
3. 关键人物或角色及其作用
4. 按时间顺序排列的重要动作或事件
5. 场景和环境描述
6. 整体情绪或基调`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' } // 启用详细分析
});
return response.choices[0]?.message?.content;
}
// 用法
const sceneAnalysis = await understandVideoScenes(
'https://example.com/documentary.mp4'
);
运动和动作检测
import ZAI from 'z-ai-web-dev-sdk';
async function detectActions(videoUrl, specificAction = null) {
const zai = await ZAI.create();
const prompt = specificAction
? `识别此视频中所有"${specificAction}"的实例。对于每个实例,描述其发生的时间并提供其执行方式的详细信息。`
: '识别并描述此视频中所有重要的动作和运动。包括执行者及发生时间。';
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
// 用法
const runningActions = await detectActions(
'https://example.com/sports.mp4',
'running'
);
const allActions = await detectActions(
'https://example.com/activity.mp4'
);
事件时间线提取
import ZAI from 'z-ai-web-dev-sdk';
async function extractTimeline(videoUrl) {
const zai = await ZAI.create();
const prompt = `创建此视频中事件的详细时间线:
- 识别关键时刻和过渡
- 注意大致时间(开始、中间、结束或可见的具体时间戳)
- 描述每个关键点发生的事件
- 识别事件之间的任何因果关系
格式化为按时间顺序排列的列表。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
视频内容分类
import ZAI from 'z-ai-web-dev-sdk';
async function classifyVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `分类此视频内容:
1. 主要类别(例如:教育、娱乐、体育、新闻、教程)
2. 子类别或类型
3. 目标受众
4. 内容风格(专业、休闲、纪录片等)
5. 关键主题或话题
6. 建议标签(10-15 个关键词)
将回答格式化为结构化 JSON。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
const content = response.choices[0]?.message?.content;
try {
return JSON.parse(content);
} catch (e) {
return { rawResponse: content };
}
}
高级用例
多轮视频对话
import ZAI from 'z-ai-web-dev-sdk';
class VideoConversation {
constructor() {
this.messages = [];
}
async initialize() {
this.zai = await ZAI.create();
}
async loadVideo(videoUrl, initialQuestion) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: initialQuestion },
{ type: 'video_url', video_url: { url: videoUrl } }
]
});
return this.getResponse();
}
async askFollowUp(question) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: question }
]
});
return this.getResponse();
}
async getResponse() {
const response = await this.zai.chat.completions.createVision({
messages: this.messages,
thinking: { type: 'disabled' }
});
const assistantMessage = response.choices[0]?.message?.content;
this.messages.push({
role: 'assistant',
content: assistantMessage
});
return assistantMessage;
}
}
// 用法
const conversation = new VideoConversation();
await conversation.initialize();
const initial = await conversation.loadVideo(
'https://example.com/lecture.mp4',
'这次讲座的主要主题是什么?'
);
const followup1 = await conversation.askFollowUp(
'你能解释一下提到的关键概念吗?'
);
const followup2 = await conversation.askFollowUp(
'使用了哪些例子来说明这些概念?'
);
视频质量评估
import ZAI from 'z-ai-web-dev-sdk';
async function assessVideoQuality(videoUrl) {
const zai = await ZAI.create();
const prompt = `评估此视频的质量:
1. 视觉质量(分辨率、清晰度、光照)- 评分 1-10
2. 音频质量(如果存在音频)- 评分 1-10
3. 摄像工作(稳定性、构图、画面布局)- 评分 1-10
4. 制作价值(剪辑、过渡、特效)- 评分 1-10
5. 内容清晰度(信息是否明确?)- 评分 1-10
6. 节奏(太快、太慢、恰到好处)
7. 技术问题(伪影、模糊、音画不同步等)
8. 总体评分 - 1-10
9. 具体改进建议
为每个标准提供详细的反馈。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
视频内容审核
import ZAI from 'z-ai-web-dev-sdk';
async function moderateVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `审核此视频的内容:
1. 检查任何不恰当或敏感内容
2. 识别任何潜在的安全问题
3. 注意任何可能违反常见社区准则的内容
4. 评估适龄性
5. 识别任何可见的受版权保护材料(标志、品牌、音乐)
6. 总体安全评级:安全 / 谨慎 / 需要审查
对于识别的任何问题,提供具体示例。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
视频转录生成(视觉描述)
import ZAI from 'z-ai-web-dev-sdk';
async function generateVisualTranscript(videoUrl) {
const zai = await ZAI.create();
const prompt = `生成此视频的详细视觉转录:
- 描述每个场景中发生了什么
- 注意屏幕上出现的任何文本
- 描述重要的视觉元素
- 提及任何场景变化或过渡
- 包括人物动作和表情的描述
格式化为基于时间的叙述(例如:"开始时…","然后…","最后…")。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
体育视频分析
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeSportsVideo(videoUrl, sport = null) {
const zai = await ZAI.create();
const prompt = sport
? `详细分析此${sport}视频:
1. 识别球员及其位置
2. 描述关键打法和策略
3. 注意得分事件或重要时刻
4. 评估球员表现
5. 识别任何规则违规或犯规
6. 描述比赛的节奏和流程`
: `分析此体育视频:
1. 识别正在进行的运动
2. 描述关键动作和比赛
3. 注意任何得分或重大事件
4. 描述球员移动和策略
5. 比赛或对局的总体评估`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
批量视频处理
import ZAI from 'z-ai-web-dev-sdk';
async function batchAnalyzeVideos(videoUrls) {
const zai = await ZAI.create();
const results = [];
for (const videoUrl of videoUrls) {
try {
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: '提供此视频的简要摘要' },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
results.push({
url: videoUrl,
summary: response.choices[0]?.message?.content,
status: 'success'
});
} catch (error) {
results.push({
url: videoUrl,
error: error.message,
status: 'failed'
});
}
}
return results;
}
// 用法
const batchResults = await batchAnalyzeVideos([
'https://example.com/video1.mp4',
'https://example.com/video2.mp4',
'https://example.com/video3.mp4'
]);
常见问题
支持哪些视频格式?
支持的格式包括:.mp4、.avi、.mov、.webm、.mkv、.flv。视频的最大文件大小取决于你的提供商限制(通常为 100MB - 1GB)。
如何处理长视频?
对于长视频(超过 10 分钟),请考虑:
- 以固定间隔采样关键帧
- 将视频分成较短的片段
- 使用
--thinking标志进行更详细的处理 - 首先关注特定部分或时间范围
视频理解支持音频吗?
视频理解主要关注视觉内容分析。虽然 z-ai-web-dev-sdk 在适用时会尝试处理音频,但音频分析并非主要功能。对于纯音频分析,请使用专门的语音转文本工具。
我可以分析实时视频流吗?
当前的实现针对预先录制的视频进行了优化。对于实时流,你需要捕获帧并定期发送进行分析。这不直接支持,但可以在你的实现中构建。
隐私请注意
上传到 AI 服务进行分析的视频将根据服务提供商的隐私政策进行处理。处理敏感或机密视频内容时请考虑这一点。
故障排除
常见错误
- "视频文件太大" - 将视频压缩到较小尺寸或采样关键帧
- "不支持的格式" - 转换为支持的格式(推荐 .mp4)
- "分析超时" - 对于长视频,增加超时时间或使用
--thinking标志 - "URL 无效" - 确保视频 URL 可公开访问或使用本地文件路径
- "文件未找到" - 检查本地文件路径是否正确以及文件是否存在
性能提示
- 对于本地视频,在分析前转换为基于 URL 的访问
- 分析前将视频压缩到合理的分辨率(例如 720p)
- 对于简单任务,使用 CLI 以获得更快的初始结果
- 复杂的多步分析启用
thinking模式 - 对于大型项目,使用 SDK 进行更强大的错误处理
下一步
- 探索
{技能位置}/scripts/中的参考脚本以了解实际情况 - 尝试不同的提示以优化特定用例的分析
- 考虑将视频理解与其他 AI 功能结合用于多模态应用程序
- 为你的领域自定义提示模板(例如,医疗、教育、安全)
- 构建视频分析管道以进行大规模处理