面向人文数据的可视化分析系统 | 基于 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

该脚本会测试：

1. 查询可用模型列表
2. 基本 API 调用
3. 流式响应

注意：小米 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/ 目录，建议按以下顺序阅读：

1. OUTLINE.md - 项目规划大纲

   • 整体技术选型与架构设计
   • 现有组件详细分析
   • 可视化技术选型参考

2. OPERATION.md - 项目运维指南

   • 部署与配置说明
   • 故障排查方法
   • 性能优化建议

3. 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

获取访问链接方法：

1. 启动服务后，在终端查看输出日志中的绿色 URL
2. 或点击 IDE 顶部「网络」面板，找到对应端口的「打开链接」按钮
3. 将链接复制到浏览器新建标签页即可访问（支持 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

---