# DYVA **Repository Path**: StarsPython/dyva ## Basic Information - **Project Name**: DYVA - **Description**: DYVA：基于GLM VLLM的抖音视频分析工具，使用ffmpeg、大模型对视频进行理解、分析提取结构化字段，批量生成标准化文本数据文件， - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-10-29 - **Last Updated**: 2025-10-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DYVA 系统说明书（抖音视频批量分析与结构化数据生成） DYVA 面向抖音（Douyin）短视频的批量分析与结构化数据生成，统一完成 Excel 元数据读取、音频转写（ASR）与清洗、文本与视觉分类，并导出 TXT 与 CSV。系统以研究类应用为核心目标，强调统一的分类标准、可复现的处理流程与可扩展的模块化架构。 --- ## 1. 系统概述与目标 - 目标：批量处理抖音视频，生成结构化 TXT 与汇总 CSV；分类标准统一、可复现、可扩展。 - 原则：单一职责、配置驱动、并行高效、错误隔离、日志完备、隐私安全。 - 产物： - TXT：清洗后的脚本及元数据摘要（每视频一个）。 - CSV：全量结构化汇总（严格列顺序）。 - 使用人群：传播/媒介研究者、内容分析员、行业从业者（尤其研究“三农”“返乡创业”等主题）。 --- ## 2. 应用场景 - 学术研究：内容分析、情感与风格分类、主题分布统计、时长与互动指标的关联研究。 - 媒体监测：监控特定主题、话题（如 #我的乡村生活），输出定期报告。 - 运营分析：面向电商助农、乡村振兴传播的素材分类与质检、复盘与选题。 - 归档整理：将大量视频转化为可搜可统计的文本与表格，便于后续再利用与扩展分析。 --- ## 3. 核心功能 - Excel→模型映射：从样本 Excel 读取，标准化字段与单位（中文“万”等），生成 `VideoMetadata`。 - 视频定位与副本名：以 `video_id`/作者+日期匹配 `S:/` 或配置目录下的 MP4；规范副本名 `VID_{video_id}.mp4`。 - ASR 转写与清洗： - 抽取音频（FFmpeg），调用 Whisper（GPU 优先）转写，统一简体中文并去冗余。 - 支持并发、超时、重试与失败回退（返回处理后的标题代替）。 - 文本分析（DeepSeek）： - 基于 `config/categories.yaml` 类目字典，提示词要求“仅返回 JSON，不做解释”。 - 对主题、情感、语言风格、标题情感表达、标题平台话题分类，失败回退关键词匹配。 - 视觉分析（VLM）： - 按时长分档的帧采样策略，分析 `actor/symbols`，统计频次取最高项。 - 失败回退 `NA`，不阻塞整批处理。 - 导出： - TXT：`data/result/txt_files/{video_id或author+date}.txt`，包含元数据摘要与清洗脚本。 - CSV：`data/result/result.csv`，列顺序严格对齐规范。 - 并发与重试：默认 `max_workers=4`；单视频超时 `180s`；指数退避重试；单任务失败不影响整批。 - 日志与错误隔离：统一写入 `data/logs/processing.log`，记录开始/结束/耗时/错误堆栈/告警。 --- ## 4. 预期效果与衡量指标 - 数据完整性：所有输出列均填充，如缺失用 `NA` 并在日志记录；副本名与 `video_id` 关联一致。 - 处理效率：在默认并发下，典型短视频批量（10–50个）可在数分钟到十几分钟内完成（视 ASR/VLM 耗时与硬件）。 - 分类一致性：统一类目字典与提示词，确保不同批次可复现；失败回退策略避免断档。 - 日志可追溯：完整记录每视频耗时、错误类型与处理策略；便于复盘与性能优化。 --- ## 5. 技术架构 - 入口模块：`main.py`（命令行）负责加载环境、初始化日志/目录、解析参数、调用导出管线。 - 处理器模块：`src/processors/` 包含 Excel→模型映射、ASR、文本分析、视觉分析。 - 模型模块：`src/models/` 定义 `VideoMetadata` 及单位/时长等工具映射逻辑。 - 工具模块：`src/utils/` 提供配置加载、路径与目录确保、日志初始化、媒体工具（FFmpeg 检查/抽音频/视频匹配）、文本清洗等。 - 配置模块：`config/config.yaml`（主配置：路径/并发/重试/ASR/VLM/DeepSeek）、`config/categories.yaml`（统一类目字典）。 - 测试模块：`tests/` 覆盖 utils/processors/models 与集成导出，基于 `unittest`。 - 文档与数据：`docs/` 提示词设计与流程说明；`data/` 放置 Excel 样本；`DiVoMiner/` 提供类目表与效果示例。 - 备用实现：`V2/` 提供早期 GLM-4V 管线（独立入口与模块），不与当前主入口耦合。 --- ## 6. 处理流程详解 - 环境与日志： - 加载 `.env`；初始化日志（级别可由 `DYVA_LOG_LEVEL` 覆盖）；确保输出与临时目录存在。 - Excel→模型： - 读取 Excel（默认 `data/研究样本表.xlsx`），映射为 `VideoMetadata`；抑制 openpyxl 特定告警。 - 字段清洗与标准化（见“数据类型与字段”）。 - 视频定位与副本名： - 根目录默认 `S:/`（可在 `config/config.yaml` 的 `paths.input_videos` 调整；当前示例配置为 `temp_input_videos` 便于本地调试）。 - 以 `video_id` 优先匹配文件名一致项；否则按作者+日期策略匹配/人工映射；副本名规范 `VID_{video_id}.mp4`。 - 批量 ASR： - 抽取音频（FFmpeg）；Whisper 本地 GPU（`cuda` 优先，显存不足回退 `cpu`）；语言中文优先；统一标点与冗余清洗。 - 并发执行（默认 4），设置单视频超时（180s），失败重试（指数退避，最多 3 次）。 - 失败安全回退：返回 `processed_title`，保证整批流程不中断。 - 文本分析（DeepSeek）： - 根据 `categories.yaml` 构建提示词，请求“仅返回 JSON，不做解释”；超时与重试按配置；失败关键词回退（中文不区分大小写）。 - 输出字段：`theme, sentiment, style, title_emotion, title_topic`。 - 视觉分析（VLM）： - 帧采样：`duration_weighted` 策略，按时长分档设置帧上限（如 ≤60秒：最多10帧；全局上限40）。 - 输出字段：`actor, symbols`；统计频次取最高项；失败填充 `NA`。 - 导出与校验： - TXT 输出清洗脚本与元数据摘要到 `paths.output_txt`；CSV 汇总到 `paths.output_csv`；列顺序与 `config.yaml` 对齐。 - 完整性检查：缺失项 `NA`；副本名与 `video_id` 关联一致；记录告警与错误类型。 --- ## 7. 数据类型与字段说明 - 数据模型 `VideoMetadata`（核心字段与类型）： - `author: str`（博主名称） - `publish_time: str`（标准化为 `YYYY-MM-DD HH:MM:SS`） - `original_title: str`（原始标题） - `processed_title: str`（移除话题与冗余符号，保留自然语言） - `topics: List[str]`（从标题中提取的 `#` 话题，去重保序） - `video_url: str`（清洗后的 URL，仅接受 `douyin.com` 域） - `video_id: str`（从 `https://www.douyin.com/video/{id}` 解析，失败置 `NA`） - `duration_seconds: int`（`MM:SS` 转秒） - `duration_category: str`（≤15秒/≤1分钟/≤5分钟/＞5分钟） - `engagement: Dict[str,int]`（`likes, comments, favorites, shares`，中文单位“万”标准化） - `copy_name: str`（视频副本名，规范 `VID_{video_id}` 或 `VID_{author+YYYY-MM-DD}`） - CSV 列（严格顺序）： - `author, publish_time, original_title, processed_title, topics, video_url, video_id, duration_seconds, duration_category, likes, comments, favorites, shares, copy_name, theme, sentiment, style, title_emotion, title_topic, actor, symbols` - TXT 内容（每视频）： - 元数据摘要（作者、发布时间、标题、话题、时长与分类结果） - 清洗后的文本脚本（ASR 输出经清洗） - 中间文件： - 临时音频：`data/result/audio_temp/VID_{video_id}.wav` - 日志文件：`data/logs/processing.log` --- ## 8. 配置详解（config/config.yaml 与 categories.yaml） - `paths`： - `input_videos`（默认设计为 `S:/`；示例配置 `temp_input_videos`） - `input_excel`（默认 `data/研究样本表.xlsx`） - `output_txt`、`output_csv`、`temp_audio`、`logs_dir` - `processing`： - `concurrency.max_workers`（默认 4） - `concurrency.timeout_per_video_seconds`（180） - `retry`（最多重试 3 次、指数退避） - `apis.deepseek/vlm`：`enabled`、`timeout_seconds`、`max_retries`；`vlm.frame_sampling` 采样策略与各时长档位帧上限（全局上限 40） - `asr`： - `model_size`（如 `small/medium/large`） - `device`（`cuda`/`cpu`） - `language`（中文优先） - `timeout_seconds`（180） - `csv.columns`：列顺序必须与导出一致。 - `security.api_keys_source=env`：仅从环境变量读取密钥。 - `logging.level=INFO`：可由环境变量覆盖。 - `categories.yaml`（统一类目字典，单选 `single_choice`）： - `duration`: 四档关键词（≤15秒/≤1分钟/≤5分钟/＞5分钟） - `theme`: 乡村生活/农村美食/农技展示/民间文化/农事劳作/电商助农/剧情情感等 - `actor`: 创业青年本人/家人/邻里乡亲/团队成员/宠物家禽/无明确人物 - `symbols`: 分组（场景/道具/语言/音乐）与关键词（如方言/背景音乐/农具等） - `sentiment`: 正面/中性/负面 - `style`: 煽情/幽默/亲切/欢快/平淡/无明显风格 - `title_emotion`: 有情感化表达/无情感化表达 - `title_topic`: 添加话题/未添加话题 --- ## 9. 使用方法（Windows，uv 环境） - 环境准备： - 依赖：`uv venv` → `.venv\Scripts\activate`（Python ≥3.12）；FFmpeg 安装并加入 `PATH`（`ffmpeg -version` 验证）。 - 环境变量： - `DEEPSEEK_API_KEY`（文本分析），`VLM_ACCESS_KEY`/`VLM_SECRET_KEY`（视觉分析）；严禁写入仓库或日志。 - 运行主流程： - `uv run main.py`（可选参数：`--max-rows N`、`--sheet-name `） - 运行测试： - `uv run python -m unittest discover -s tests -p "test_*.py"` - 配置调整： - 若需要扫描 `S:/`，请将 `paths.input_videos` 改为 `"S:/"`；其余路径按需调整。 --- ## 10. 项目结构与文件资源（关键路径） - 根目录： - `main.py`（主入口） - `pyproject.toml`（依赖管理；使用 uv） - `.python-version`（解释器版本约束） - `README.md`（系统说明书） - `LICENSE`（开源许可） - 配置：`config/` - `config.yaml`（主配置，含路径/并发/ASR/API/日志/安全） - `categories.yaml`（类目字典，统一提示词与关键词匹配依据） - 源码：`src/` - `processors/`（`excel_processor.py`、`asr_processor.py`、`text_analyzer.py`、`visual_analyzer.py`） - `models/`（`video_metadata.py`） - `utils/`（`config_loader.py`、`logger.py`、`media_utils.py`、`path_utils.py`、`text_cleaner.py`） - 数据与文档： - `data/研究样本表.xlsx`、`data/样本研究表简要.xlsx`（示例数据） - `docs/类目表.txt`（原始类目文本；已转为 YAML） - `docs/抖音视频内容批量处理与结构化数据生成.md`（处理设计说明） - `DiVoMiner/`（类目表与编码效果分析文档、示例图与结果表等） - 输出与临时： - `data/result/txt_files/`（TXT 输出） - `data/result/audio_temp/`（临时音频） - `data/logs/processing.log`（日志） - `temp/`（测试用临时目录：`temp_audio`、`temp_input_videos` 等） - 备用实现：`V2/` - `main.py`（独立入口，线程池并发处理；使用 GLM-4V 与 ZhipuAI） - `dyva/`（备用管线模块：`batch_analyzer.py`、`video_processor.py`、`result_exporter.py`、`parallel_processor.py` 等） - `config/categories_example.txt`（示例类目文本） - `results/`（历史 TXT 结果样本） - 注意：`V2/.config` 不应包含密钥；请清理并改用环境变量。 - 测试：`tests/` - 覆盖：ASR 并发/超时/重试、Excel→模型映射、CSV/TXT 导出、FFmpeg 检查、日志初始化、文本清洗、视觉/文本分析器等。 --- ## 11. 关键问题与解决方案 - Excel 异构与清洗： - 标题话题抽取：`#话题` 去重保序；忽略空标签。 - URL 清洗与 `video_id` 解析：仅接受 `douyin.com` 域；解析失败置 `NA` 并日志记录。 - 单位标准化：支持中文“万”（含小数）；应用于 `likes/comments/favorites/shares`。 - 时间与时长：`YYYY/MM/DD` → `YYYY-MM-DD 00:00:00`；`MM:SS`→秒；时长四档与 YAML 对齐。 - 并行与超时： - 默认并发 4，单视频超时 180s，重试最多 3 次，指数退避；失败不阻塞整批。 - ASR 稳健性： - GPU 优先，显存不足回退 `cpu`；转写失败返回处理后的标题，保障流程闭环。 - 分类一致性： - 统一 `categories.yaml`；提示词 JSON-only；失败关键词回退，中文大小写不敏感。 - 日志与错误隔离： - 统一日志文件；错误类型标准化（`file_not_found, api_timeout, invalid_format, processing_failed`）。 --- ## 12. 系统优势与潜在缺陷 - 优势： - 规范化与可复现：统一类目字典与提示词，输出结构稳定。 - 模块化与扩展性：处理器与工具职责清晰，易于替换/增强。 - 稳健与高可用：并发、超时、重试与回退策略，单任务失败不影响整批。 - 安全合规：API Key 仅环境变量读取，日志不泄露敏感信息。 - 潜在缺陷： - ASR/VLM 成本与性能：GPU/API 资源受限时会影响耗时与质量。 - Excel 数据质量：异常格式与缺失项需人工回填或脚本增强。 - `video_id` 关联：文件名与 ID 不一致时的自动匹配可能失败，需人工映射。 - 类目字典覆盖：关键词字典需持续维护以适应新内容与语料。 --- ## 13. 安全与隐私 - 密钥仅从环境变量读取：`DEEPSEEK_API_KEY`、`VLM_ACCESS_KEY`、`VLM_SECRET_KEY`。 - 禁止将密钥或敏感 payload 写入仓库或日志；请清理历史敏感文件（如 `V2/.config`），并立即更换密钥。 - 输出不包含敏感个人信息；严格遵守平台与法律合规要求。 --- ## 14. 测试与验证 - 单元测试：覆盖 processors/utils/models 核心函数（路径确保、配置加载、日志初始化、ASR 并发/超时/重试、文本/视觉分析解析、文本清洗等）。 - 集成测试：小批量（3–5个视频）打通 Excel→ASR/VLM→TXT/CSV；验证列顺序与完整性。 - 性能测试：记录并行处理耗时与资源使用（GPU/CPU/内存）。 - 边界测试：无音频、无人物、无标签、超长视频、API 超时、格式错误等。 - 运行命令：`uv run python -m unittest discover -s tests -p "test_*.py"`。 --- ## 15. 运维与运行规范 - 统一入口：`.venv\\Scripts\\activate` 后执行 `uv run main.py`。 - FFmpeg：需在 `PATH`；首次运行前检查 `data/result/` 与子目录存在并可写。 - 日志管理：根据环境变量可调整日志级别；日志定期归档与容量监控。 - 配置变更：修改 `config.yaml` 前建议备份与变更记录；类目字典更新需同步测试与提示词。 --- ## 16. 常见问题（FAQ） - FFmpeg 未在 PATH：安装后在命令行执行 `ffmpeg -version` 验证；若不可用，ASR 抽音频会失败并触发回退。 - Whisper 显存不足：将 `asr.device=cpu` 或选择更小模型（如 `small`）。 - API 超时或配额：调整 `processing.apis.*.timeout_seconds` 与 `max_retries`；开启关键词回退；必要时降低并发。 - CSV 列错位：确保 `config.yaml` 中 `csv.columns` 与导出逻辑一致；运行集成测试验证。 - 视频未匹配：检查 `paths.input_videos` 与文件命名；必要时人工映射或下载补齐。 --- ## 17. 备用实现（V2）说明 - 入口：`V2/main.py`（独立线程池并发，默认 `workers=5`）。 - 模块：`V2/dyva/`（`batch_analyzer.py` 组织 GLM-4V 调用与并发；`video_preprocessor.py` FFmpeg 片段抽取；`result_exporter.py` 输出；`parallel_processor.py` 并行调度）。 - 配置：`V2/config/categories_example.txt`（文本类目示例）；`V2/.config`（不建议使用，避免硬编码密钥）。 - 输出样例：`V2/results/` 包含多条历史 TXT（视频主题、人物、符号、情感、风格、标题话题等）。 - 用途：对比与迁移参考；默认不参与当前主入口。 --- ## 18. 扩展方向与里程碑建议 - 多语言支持：扩展 Whisper/提示词以适配多语种内容。 - 更细粒度采样：VLM 帧采样策略按镜头边界与画面变化自适应。 - 半自动纠错：对 `video_id`/标题/话题提取失败提供交互式校正工具。 - 统计报表：自动生成分类分布与时长/互动指标统计图；联动 `DiVoMiner/` 研究输出。 - 数据库落地：将 CSV 导入 SQLite/PostgreSQL，支持更丰富查询与可视化。 --- ## 19. 快速上手清单（Checklist） - 安装 FFmpeg 并加入 PATH；`ffmpeg -version` 通过。 - 创建与激活环境：`uv venv` → `.venv\\Scripts\\activate`。 - 设置环境变量：`DEEPSEEK_API_KEY`、`VLM_ACCESS_KEY`、`VLM_SECRET_KEY`。 - 检查目录：`data/result/txt_files`、`data/result/audio_temp`、`data/logs` 均存在且可写。 - 调整配置：如需扫描 `S:/`，修改 `paths.input_videos`；根据硬件设置 `asr.device` 与模型大小。 - 运行：`uv run main.py`（可加 `--max-rows` 抽样试跑）。 - 验证：运行 `unittest`，检查日志与输出文件生成成功。 --- 如需加入更详细的配置片段示例、最小跑通样例（3–5 个视频）或双语版文档，请提出需求，我将继续扩展本说明书并同步完善测试用例。