面向人文数据的可视化分析系统 | 基于 Story Ribbons
HumanViz 是一个面向人文领域（文学、历史、哲学、艺术）的可视化分析系统。通过定制化的可视化视图和 AI 辅助分析，帮助用户深入理解人文数据中的模式、关系和演变规律。基于 Story Ribbons 开源项目演进，保留其核心叙事可视化能力（Narrative Ribbon），并计划扩展支持更多可视化类型以应对不同的人文数据场景。
- 系统定位：面向定制的可视化分析系统（非通用平台）
- 核心能力：LLM 驱动的数据解析 + 多维度可视化分析
- 技术亮点：D3.js 深度定制 + React 组件化 + Python LLM 服务
- 论文 📄: Story Ribbons: Reimagining Storyline Visualizations with Large Language Models
- 演示 🌐: Story Ribbons Demo
- 文档 📚: Story Ribbons Docs
- 原始仓库 🐙: GitHub - catherinesyeh/story-viz
- 框架: React 18 + TypeScript
- 构建工具: Vite 5
- UI 组件库: Mantine 7
- 数据可视化: D3.js + Chroma.js
- 状态管理: Zustand
- 样式: Sass
- 语言: Python 3.12
- 框架: Flask + Flask-CORS
- 包管理: UV (极速 Python 包管理器)
- AI 集成: LangChain OpenAI (兼容 OpenAI、智谱、DeepSeek 等厂商)
- 数据验证: Pydantic
- 容器化: Docker 🐳
- 云原生: CNB (Cloud Native Build) ☁️
- 代码编辑: code-server（VS Code 浏览器版）💻
- AI 编程: CodeX + ChatGPT 🤖
本项目使用 OpenAI 兼容格式，支持多种大模型厂商：
| 厂商 | 模型示例 | Base URL |
|---|---|---|
| 智谱 AI | glm-4 | https://open.bigmodel.cn/api/paas/v4 |
| OpenAI | gpt-4o-mini | https://api.openai.com/v1 |
| DeepSeek | deepseek-chat | https://api.deepseek.com/v1 |
| Moonshot | moonshot-v1-8k | https://api.moonshot.cn/v1 |
| 通义千问 | qwen-turbo | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| MiMo | mimo-v2.5-pro | https://token-plan-cn.xiaomimimo.com/v1 |
编辑 start.sh 文件顶部的配置区域：
# ==================== LLM API 配置 ====================
API_KEY="your-api-key-here"
MODEL="glm-4"
BASE_URL="https://open.bigmodel.cn/api/paas/v4"
PROVIDER="zhipu"
# ==================== 配置结束 ====================
** MiMo 配置示例**：
# ==================== LLM API 配置 ====================
API_KEY="tp-your-api-key"
MODEL="mimo-v2.5-pro"
BASE_URL="https://token-plan-cn.xiaomimimo.com/v1"
PROVIDER="xiaomi"
# ==================== 配置结束 ====================
配置说明：
API_KEY: 你的 API 密钥MODEL: 模型名称BASE_URL: API 基础地址（OpenAI 兼容格式）PROVIDER: 厂商标识（仅用于日志显示）
启动时会自动生成 story-viz/secrets.json 配置文件。
项目提供了 test_api.py 脚本用于测试 LLM API 连接：
# 测试 API 连通性
python test_api.py
该脚本会测试：
- 查询可用模型列表
- 基本 API 调用
- 流式响应
注意：小米 MiMo 模型名称需使用小写格式，如 mimo-v2.5-pro。
/workspace/ ├── .cnb.yml # 云原生构建配置文件（CNB 平台配置） ├── Dockerfile # Docker 镜像构建配置 ├── README.md # 项目说明文档 ├── settings.json # VS Code/code-server 编辑器配置 ├── start.sh # 一键启动脚本（自动检查环境、安装依赖、启动服务） ├── stop.sh # 停止服务脚本 ├── test_api.py # LLM API 测试脚本 ├── file/ # 项目文档 │ ├── FULL-STACK.md # 全栈技术栈参考 │ ├── OPERATION.md # 项目运维指南 │ └── OUTLINE.md # 项目规划大纲 ├── script/ # 脚本工具 │ └── init-codex.sh # CodeX CLI 配置初始化脚本 └── story-viz/ # Story Ribbons 核心源代码 ├── backend/ # 后端 Python 服务 │ ├── helpers.py # 辅助函数 │ ├── prompts.py # LLM 提示词模板 │ ├── server.py # Flask 服务器入口 │ └── test.py # 测试脚本 ├── notebooks/ # Jupyter 数据解析笔记本 │ └── parsing-data.ipynb # 主要数据解析流程 ├── public/ # 静态资源 │ ├── chapters/ # 小说章节文本文件（按故事分子文件夹） │ ├── characters/ # 角色图片资源 │ │ └── placeholder.png │ ├── covers/ # 书籍封面图片 │ ├── fav.svg # 网站图标 │ └── fav2.svg ├── src/ # 前端 React 源代码 │ ├── components/ # React 组件 │ │ ├── Header/ # 顶部导航栏组件 │ │ ├── Legend/ # 图例组件 │ │ ├── Misc/ # 杂项组件 │ │ ├── Modals/ # 弹窗组件 │ │ ├── Overlays/ # 覆盖层组件 │ │ ├── Vis/ # 可视化核心组件 │ │ ├── XAxis/ # X 轴组件 │ │ └── YAxis/ # Y 轴组件 │ ├── data/ # 数据文件（JSON 格式） │ ├── stores/ # Zustand 状态管理 │ ├── utils/ # 工具函数 │ ├── App.scss # 主样式文件 │ ├── App.tsx # 主应用组件 │ └── main.tsx # 应用入口 ├── .eslintrc.cjs # ESLint 配置 ├── .gitignore # Git 忽略配置 ├── index.html # HTML 入口 ├── package.json # 前端依赖配置 ├── Pipfile # Python 依赖配置 ├── README.md # story-viz 子项目说明 ├── secrets_example.json # API 密钥配置示例 ├── tsconfig.json # TypeScript 配置 ├── vite.config.ts # Vite 构建配置 └── yarn.lock # Yarn 锁定文件
本项目的详细文档位于 file/ 目录，建议按以下顺序阅读：
-
OUTLINE.md - 项目规划大纲
- 整体技术选型与架构设计
- 现有组件详细分析
- 可视化技术选型参考
-
OPERATION.md - 项目运维指南
- 部署与配置说明
- 故障排查方法
- 性能优化建议
-
FULL-STACK.md - 全栈技术栈参考
- 技术栈选型背景
- 学习路径参考
- 操作系统: Linux / macOS / Windows（支持 Docker）
- 内存: 建议 4GB 及以上
- 磁盘空间: 建议 10GB 及以上
- Node.js: 22.x 或更高版本
- Python: 3.12 或更高版本
- UV: 极速 Python 包管理器
- Yarn: npm 包管理工具
- Docker（可选，用于容器化部署）
项目已配置智能启动脚本，自动完成环境检查、依赖安装和服务启动：
# 1. 配置 LLM API（编辑 start.sh 顶部配置）
# start.sh
# 修改以下配置项：
# API_KEY="your-api-key"
# MODEL="glm-4" # 或其他模型如 gpt-4o-mini
# BASE_URL="https://open.bigmodel.cn/api/paas/v4" # 或其他厂商地址
# PROVIDER="zhipu" # 厂商标识（仅用于日志）
# 2. 一键启动前后端服务
./start.sh
启动脚本会自动完成：
- ✅ 环境检查（Node.js、Yarn、Python、UV）
- ✅ 端口占用清理
- ✅ Python 虚拟环境激活（使用 Dockerfile 预装的
/opt/venv） - ✅ 依赖检查与自动安装
- ✅ 前端依赖检查与自动安装
- ✅ 生成 API 配置文件
- ✅ 启动后端服务（Flask）
- ✅ 启动前端服务（Vite）
| 服务 | 地址 |
|---|---|
| 前端页面 | http://localhost:5200 |
| 后端 API | http://localhost:5000 |
| 后端状态 | http://localhost:5000/status |
启动服务后，通过以下方式访问：
| 服务 | 访问地址 |
|---|---|
| 前端页面 | https://${WORKSPACE_ID}-5200.preview.myide.io |
| 后端 API | https://${WORKSPACE_ID}-5000.preview.myide.io |
获取访问链接方法：
- 启动服务后，在终端查看输出日志中的绿色 URL
- 或点击 IDE 顶部「网络」面板，找到对应端口的「打开链接」按钮
- 将链接复制到浏览器新建标签页即可访问（支持 PC/手机端）
./stop.sh
如果你在研究或项目中使用了 Story Ribbons，请引用原始论文：
@article{yeh2025story, title={Story Ribbons: Reimagining Storyline Visualizations with Large Language Models}, author={Yeh, Catherine and Menon, Tara and Arya, Robin Singh and He, Helen and Weigel, Moira and Vi{\'e}gas, Fernanda and Wattenberg, Martin}, journal={IEEE Transactions on Visualization and Computer Graphics}, year={2025}, publisher={IEEE} }
本项目基于 Story Ribbons 开源项目。原始项目的许可证信息请参考原始仓库。
⚠️ 重要提示：
- 本项目仅供学习和研究使用
- 使用本项目时请遵守原始项目的许可证条款
- 商业用途请先获得原始项目作者的授权
感谢原始 Story Ribbons 项目的作者和贡献者！
原始作者：
- Catherine Yeh
- Tara Menon
- Robin Singh Arya
- Helen He
- Moira Weigel
- Fernanda Viégas
- Martin Wattenberg
🎭 感谢使用 HumanVIZ！
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
