# data_analysis_visualization_practice

**Repository Path**: zhu-fengkai/data_analysis_visualization_practice

## Basic Information

- **Project Name**: data_analysis_visualization_practice
- **Description**: 数据分析与可视化实践——基于大模型的数据视频生成
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-09-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM-Powered Data Video Generation

## Project Overview
AI 故事创作助手旨在将“文本整理 → 多模态生成 → 视频合成”整合为一条轻量、可配置且可本地运行的流水线。核心聚焦自研 Summary Agent、多模态并行调度、结构化数据可视化以及本地视频合成，力求在外部 API 受限的环境下，仍能稳定输出故事、配图、语音与视频等完整素材。

### Quickstart
1. **创建并激活虚拟环境（可选）**
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   ```
2. **安装依赖**
   ```bash
   pip install -U pip
   pip install -r requirements.txt
   ```
3. **配置环境变量**
   ```bash
   # 编辑 setup_env.local.sh，填入各类密钥
   source setup_env.local.sh
   ```
4. **准备字体与系统工具（推荐）**
   - 安装 `ffmpeg` 以支持动画与视频合成。
   - 在 `resources/font/` 放置中文字体文件（默认使用 `msyh.ttf`）。
5. **启动 Web 应用**
   ```bash
   python web_app.py --config configs/mm_story_agent.yaml --host 0.0.0.0 --port 5000
   ```
   打开浏览器访问 `http://localhost:5000`，即可在前端侧边栏上传文档、切换功能开关并通过聊天面板与 Agent 互动。
6. **命令行快速体验（可选）**
   ```bash
   python run.py -c configs/mm_story_agent.yaml
   python scripts/quick_compose_demo.py
   ```

## Core Features

### 1. Frontend Interface
- 单页应用基于 `templates/index.html`，整合侧边栏功能开关、上传区、快捷卡片与聊天窗口，实现端到端的故事创作交互。
- “快速摘要”改为模态框操作：支持直接输入文本、复用当前故事内容以及上传纯文本文件，前端会自动调用 `/summary` 指令并在聊天区域展示结果。
- 功能开关与后端 `featureFlags` 实时同步，包含故事生成、视频合成、数据分析、并行优化等；按钮状态、toast 提示与故事预览会依据目前的创作流程动态更新。
- 上传文档后自动渲染故事预览、数据图表与提示信息，为后续编辑、导出或直接合成视频提供上下文。

### 2. Parallel Inference Optimization
- `mm_story_agent/parallel/pipeline.py` 中的 `ParallelSingleRequestRunner` 使用线程池并行调度图像与语音生成，显著缩短单次请求耗时；通过 `pipeline.parallel_single_request` 与 `pipeline.parallel_max_workers` 调整开关和并行度。
- `parallel/batch.py` 实现通用批处理执行器，支持限流与有序结果聚合，便于在 YAML 中配置 `batch_parallel_enabled`、`batch_max_workers`、`batch_throttle_seconds` 等参数进行批量创作。
- 并行模式对故事生成、数据可视化与视频合成流程保持兼容，并在异常聚合后统一抛出，确保问题可观测且易于排查。

### 3. Long-text Processing
- 自研 `LongTextProcessor` 在摘要与故事扩写前进行章节/标题识别，再依据长度阈值回退，减少跨章节内容混排的问题。
- 数据分析开关开启时，会先调用 `_summarize_to_pages` 对长文本分页处理，再交给 Story Agent 或数据可视化模块，保障每页内容语义自洽。
- 相关阈值（最大章节数、最小段落长度等）可在配置文件中调整，以适配不同体量的文档。

### 4. Custom Styling
- 前端设置面板提供“创作风格”“故事长度”等偏好项，通过 `localStorage` 持久化并在每次请求中注入 `story_preferences`。
- 后端 `_resolve_story_preferences` 同时支持 token 与“页”字样的长度设定；填写“5页”“8 页”等格式即可直接影响故事长度与摘要页数。
- 视频合成部分可在 YAML 中自定义字幕字体、镜头运动、转场样式等，确保不同场景下的成片风格一致。

### 5. Summary Agent
- 位于 `mm_story_agent/modality_agents/summary_agent.py`，统一处理摘要模式与语义分析模式，支持 `max_sentences`、`enable_semantic_tags`、`analysis_fields` 等参数。
- 后端新增 `_handle_summary_command`，允许 `/summary use=current` 直接复用当前故事，也支持传入自由文本；返回结果包含摘要、关键词、主题、情感等结构化字段。
- Summary Agent 输出可被数据可视化、故事预览以及前端模态框复用，实现多处链路的信息一致。

### 6. Data Visualization
- `data_viz_agent.py` 结合 LLM 规划与正则回退，在故事或上传文本中自动识别数据段落并生成柱状图、折线图、饼图、散点图等，可选输出动画（mp4/gif）。
- 结果会附带 `summary.txt` 以及结构化 `summary_agent_output.json`，前端故事预览支持展示要点摘要与图表缩略图。
- 运行时可通过命令行参数 `--enable-data-viz`、`--data-viz-animation` 或 YAML 配置启用/禁用相关能力。

### 7. Direct-to-Video Support
- `video_compose_agent.py` 负责本地素材合成：优化字幕切分、提供 zoom/pan/tilt/rotate 等镜头运动，以及 slide/dissolve/flash 转场；字幕渲染失败时会回退，确保流程连续。
- `modality_agents/video_model_agent.py` 提供第三方视频模型直出方案，通过配置 `video_generation.enabled`、`cfg`、`params` 等项即可接入 Runway、Pika 类 API。
- `benchmark/recompose_video.py` 可在不重新生成图像/语音的情况下复用既有素材，按照新的字幕策略重新合成视频，验证不同配置组合的效果。

## Project Structure Overview

- `web_app.py`：Flask 后端主入口，负责聊天接口、文件上传、摘要指令、特性开关同步与日志记录。
- `run.py`：命令行批处理入口，按照配置执行故事生成、数据可视化与视频合成工作流。
- `templates/index.html`：前端单页应用模板与脚本，涵盖侧边栏、功能卡片、摘要模态框、消息流与交互逻辑。
- `assets/`：静态资源与示例素材（图标、占位图片等）。
- `configs/`：核心 YAML 配置文件，如 `mm_story_agent.yaml`、`mm_story_agent_min.yaml`，用于定义工具参数、并行策略与生成开关。
- `mm_story_agent/`：多模态代理实现总目录
   - `base.py`、`mm_story_agent.py`：故事创作主流程、工具调度与产物落盘。
   - `modality_agents/`：各模态工具（故事、图像、语音、摘要、数据可视化、视频模型等）。
   - `parallel/`：单请求并行与批处理执行器。
   - `utils/`：长文本处理、LLM 输出校验、文件路径工具等。
- `benchmark/`
   - `bench_parallel.py`：评估并行开关对生成耗时的影响。
   - `produce_estimate_plots.py`：生成吞吐与延迟估算图表，辅助容量规划。
   - `quick_compose_demo.py`：以最小样例快速合成故事与视频，验证端到端流程。
   - `recompose_video.py`：复用既有 `generated_stories/<case>/` 素材，应用新字幕策略重新合成视频。
- `generated_stories/`
   - `example/`：示例输出，含 `script_data.json`、`summary_agent_output.json`、`captions.srt`、`image/`、`speech/` 与合成视频（如 `output.mp4`）。
   - `test_data_viz/`：数据可视化测试产物，包含图表 PNG/GIF、摘要文本等。
   - 运行流程会在此目录下为每次故事生成创建独立子目录，方便回溯与调试。
- `experiments/`：并行与批处理实验记录（如 `parallel_batch_experiments.md`），整理性能数据与调优心得。
- `story_eval/`：故事评估提示词、评分规则等辅助脚本。
- `resources/`
   - `font/`：字幕渲染所需字体（例如 `msyh.ttf`）。
   - `test_samples/`：测试输入样例（如 `data_viz_story.txt`）。
- `setup_env.sh`、`setup_env.local.sh`：环境变量配置脚本模板与示例，用于加载所需 API 密钥与路径设置。
- `README.md`、`README_rewrite.md`：项目说明文档；本文件用于重构后的结构化描述。

## Project Journey & Issue Resolution

- **2025-10-27 · Subtitle Segmentation Refresh**：原策略按定长切块导致同一条字幕混入上下句内容，阅读割裂。我们改用句子优先切分（按中英文标点优先分段、再用弱停顿回退）并基于字符数分配字幕时长，同时新增 `benchmark/recompose_video.py` 以复用既有素材验证新策略。
- **2025-10-13 · Data Visualization Rollout**：完成“LLM 规划 + 正则回退”的图表生成流程，并让 Summary Agent 输出摘要与语义标签协同写入 `summary_agent_output.json`。同日还接入视频大模型直出、扩展并行管线与批处理执行器、加强长文本分段以及镜头/转场效果。
- **2025-10-13 · JSON 序列化修复**：数据可视化结果中的 `Path` 对象在 Flask 返回时引发 `TypeError`。在 `web_app.py` 中统一转换为字符串后，`script_data.json` 与前端读取流程恢复正常。
- **2025-10-10 · Subtitle Rendering Failure**：字幕缺失源于 ImageMagick 安全策略阻断 TextClip 读写。修改 `/etc/ImageMagick-6/policy.xml` 中的 `@*` 限制并补充字体资源提示后，字幕渲染恢复；同时强化 `quick_compose_demo.py` 与 `test_video_caption.py` 的验证能力。
- **2025-10 · Summary & Parallel Enhancements**：为 Summary Agent 引入情感、话题、关键词等字段，构建 `/summary` 指令与前端模态框链路；并完成单请求/批处理并行的调试，为未来本地推理迁移打好基础。

## Future Directions

- **Local Inference Stack**：计划将 Summary、Story 等关键 Agent 迁移到自托管推理（如 vLLM、sglang）。在实现路径上，优先给 `mm_story_agent/modality_agents/llm.py` 增加 OpenAI 兼容的本地端点，使现有工具注册无缝切换；批处理与单请求并行流程可在同一进程内共享模型权重，减少重复加载；结合 `batch_throttle_seconds`、`parallel_max_workers` 调优吞吐；同时保留 DashScope 作为降级路径，确保在本地推理资源不足时可以切回云端。
- **Richer Summary Inputs**：扩展 `/summary` 指令和前端模态框支持 docx/pdf 等富文本解析，输出更细粒度的语义标签并将结果与数据可视化、故事预览深度联动。
- **Frontend Insight Surfacing**：在聊天气泡中以卡片形式展示关键摘要、关键词与图表缩略图，并附带并行状态或耗时提示，降低来回滚动的成本。
- **Observability & Resilience**：补充任务级指标采集、失败回退与重试策略，对长耗时任务提供前端进度反馈并优化错误提示。