Flipbook Local

本项目是一个本地运行的“无限翻翻书”视觉浏览器。

用户输入任意主题后，系统生成第一页总览图；点击图中的任意区域后，系统不会简单放大该区域，而是把这次点击理解成一次“继续追问”，生成下一页知识解读页面，沿着同一主题继续做结构剖析、机制解释和逻辑递进。

当前实现受 flipbook.page 启发，但不是其官方项目，也不依赖 ComfyUI。

项目目标

• 支持任意主题的可探索视觉总览页
• 点击任意区域后，生成与该区域直接相关的知识讲解页
• 页面关系遵循稳定的 flipbook 递进逻辑，而不是随机扩展
• 默认本地部署，可接本机或局域网内 OpenAI-compatible / vLLM / Ollama 兼容模型服务

核心页面链路：

overview -> detail_explainer -> mechanism -> evidence

典型示例：

泰坦尼克号总览
  -> 水密隔舱失效
  -> 隔舱壁设计缺陷与连锁进水机制
  -> 更细的结构证据或子部件

当前特性

• 前端：React + Vite，浏览器窗口式界面、路径栏、点击扩展、水波纹反馈、基础分享按钮
• 主后端：FastAPI + SQLite + SSE
• 图像服务：独立 FastAPI 推理服务，支持 placeholder 和 diffusers
• 规划器：LLM planner 负责把点击行为转成“下一页该讲什么”
• 出图模式：
  • 根页：总览页
  • 子页：默认使用父图点击区域做视觉锚点，生成局部知识解读页
  • 如果 img2img 失败，自动降级为 text2img
• 元数据：节点会记录 page_kind、question_answered、knowledge_points、next_targets

技术架构

frontend (React + Vite)
  -> backend (FastAPI)
    -> page planner (OpenAI-compatible / vLLM / Ollama compatible)
    -> image provider
      -> LightX2V adapter (FastAPI)
        -> LightLLM + LightX2V
          -> SenseNova-U1

请求流程：

1. 用户输入主题，后端生成 overview 页规划。
2. 图像模型生成第一页总览图。
3. 用户点击图中区域。
4. planner 结合根主题、父页、路径、点击坐标、父图，输出结构化页面规划：
   • page_kind
   • question_answered
   • selected_region
   • knowledge_points
   • visual_elements
   • next_targets
5. 后端按固定 flipbook 模板拼接图像 prompt。
6. 图像服务生成下一页知识解读图。

仓库结构

backend/                 主后端
frontend/                前端
inference/image_service/ 独立图像推理服务
scripts/                 安装、启动、模型下载脚本
data/                    本地数据目录（图片、数据库等）
docs/                    补充文档

关键文件：

• frontend/src/App.tsx
• frontend/src/api.ts
• backend/app/api/generation.py
• backend/app/services/generation_service.py
• backend/app/services/page_planner.py
• backend/app/providers/image/native.py
• inference/image_service/app/engines/lightx2v.py

运行环境

当前脚本以 Windows + PowerShell 为主，已在本机 NVIDIA GPU 环境上验证。

建议环境：

• Windows 11
• Python 3.11
• Node.js 18+
• NVIDIA GPU
• PowerShell

快速开始

以下命令默认在仓库根目录执行。

如果当前 PowerShell 禁止脚本执行，先运行：

Set-ExecutionPolicy -Scope Process Bypass

1. 安装依赖

后端：

.\scripts\install-backend-deps-aliyun.ps1

推理服务基础依赖：

.\scripts\install-inference-base-deps-aliyun.ps1

推理服务 GPU 依赖：

.\scripts\install-inference-gpu-deps-aliyun.ps1 -InstallTorch

前端：

.\scripts\install-frontend-deps-npmmirror.ps1

2. 下载模型

默认主模型是 SenseNova/SenseNova-U1-8B-MoT，通过 LightLLM + LightX2V 容器提供服务。

.\scripts\download-model-modelscope.ps1 -ModelId "SenseNova/SenseNova-U1-8B-MoT"

默认会下载到：

models/modelscope

3. 启动服务

推荐一键启动并打开网页：

.\start-flipbook.bat

一键关闭项目并释放显存：

.\stop-flipbook.bat

也可以手动分步启动：

启动 U1 容器和 Flipbook 适配服务：

.\scripts\start-lightllm-lightx2v-wsl.ps1
.\scripts\start-image-service-lightx2v.ps1

启动主后端：

.\scripts\start-backend-native.ps1

启动前端：

.\scripts\start-frontend.ps1

打开：

http://127.0.0.1:5173

配置说明

示例环境变量见 .env.example。

关键变量：

• FLIPBOOK_IMAGE_PROVIDER
  • mock 或 native
  • start-backend-native.ps1 会强制使用 native
• FLIPBOOK_LIGHTX2V_IMAGE_BASE_URL
  • 默认 http://127.0.0.1:8793
• FLIPBOOK_DEFAULT_IMAGE_BACKEND
  • 默认 lightx2v
• FLIPBOOK_USE_PARENT_IMAGE_FOR_LOCAL
  • true 时，子页默认使用父图点击区域作为视觉锚点
• FLIPBOOK_LLM_BASE_URL
  • OpenAI-compatible 接口地址，例如 http://127.0.0.1:8000/v1
• FLIPBOOK_LLM_MODEL
  • planner 使用的模型名
• FLIPBOOK_LLM_SEND_PARENT_IMAGE
  • true 时，若 planner 支持视觉输入，会附带父图

planner 配置

如果你希望点击后的页面真正“理解点击区域”，而不是只走 fallback 规则，需要配置 planner：

$env:FLIPBOOK_LLM_BASE_URL="http://127.0.0.1:8000/v1"
$env:FLIPBOOK_LLM_MODEL="your-vision-or-text-model"
$env:FLIPBOOK_LLM_API_KEY=""
$env:FLIPBOOK_LLM_SEND_PARENT_IMAGE="true"
$env:FLIPBOOK_USE_PARENT_IMAGE_FOR_LOCAL="true"

说明：

• 支持视觉输入的 planner 效果最好
• 不支持视觉输入时，会自动退回纯文本规划
• 完全未配置 planner 时，系统仍可运行，但只能按固定 flipbook 规则 fallback

Flipbook 逻辑

本项目的重点不是“图像局部放大”，而是“点击后的知识递进”。

当前规则：

• overview
  • 总览页
  • 目标：建立整体结构、主流程、主要区域
• detail_explainer
  • 第一层点击页
  • 目标：解释点击区域是什么、发生了什么、为什么重要
• mechanism
  • 第二层点击页
  • 目标：解释更深层的结构、原理、设计缺陷、连锁机制
• evidence
  • 更深层点击页
  • 目标：展示证据、子部件、测量点、对照关系

这套规则由 backend/app/services/page_planner.py 控制，并由后端模板统一生成图像 prompt。

API

主要接口：

• POST /api/generate
  • 主生成接口，返回 text/event-stream
• POST /api/iteratively-generate-next-page
  • 同上，兼容旧命名
• GET /api/nodes
  • 最近节点
• GET /api/nodes/{node_id}
  • 单节点详情
• GET /health
  • 主后端健康检查

SSE 事件：

• start
• planning
• planned
• generating
• complete
• error

验证

健康检查：

Invoke-RestMethod http://127.0.0.1:8001/v1/models
Invoke-RestMethod http://127.0.0.1:8793/health
Invoke-RestMethod http://127.0.0.1:8788/health

生成根节点：

$body = @{
  query = "Titanic sinking explainer"
  image_backend = "lightx2v"
  width = 1920
  height = 1088
  steps = 50
  guidance_scale = 4.0
  strength = 0.6
} | ConvertTo-Json

Invoke-WebRequest http://127.0.0.1:8788/api/generate `
  -Method Post `
  -ContentType "application/json" `
  -Body $body `
  -TimeoutSec 1200

本地静态验证：

python -m compileall -q backend inference

cd frontend
npm run build

当前状态

当前版本已经完成：

• 本地前后端闭环
• LightLLM + LightX2V 图像服务接入
• SenseNova-U1 模型接入
• 点击后结构化 planner 逻辑
• overview -> detail_explainer -> mechanism 链路验证
• 子页默认 img2img 视觉锚点

当前仍属于实验性原型，重点在于：

• planner 质量高度依赖外部/本地大模型
• 图中文字默认要求简体中文，实际可读性仍取决于图像模型
• 当前没有生产级队列、权限控制、多用户隔离

文档

补充文档：

• docs/PROJECT_RECORD.md
• docs/INFERENCE_SERVICE.md
• docs/MODELS.md
• docs/DEPLOYMENT_DECISION.md

路线图

• 更稳定的视觉 planner
• 更强的节点缓存与历史管理
• draft / final 两阶段生成
• 更好的分享页和导出能力
• 更强的页面布局控制，让翻翻书知识页更稳定
• 可选视频或动态过渡页

公开仓库建议

上传到 GitHub 前建议确认：

• 不提交 models/
• 不提交 .venv/ 和 .venv-inference/
• 不提交 frontend/node_modules/ 和 frontend/dist/
• 不提交本机私有 .env
• 如需公开演示图，建议使用你自己生成的项目截图

许可证

当前仓库未附带许可证文件。

如果你准备公开发布，建议补充明确的 LICENSE，并确认所使用模型与第三方资源的许可证是否允许你的预期用途。