MiyakoKB 处理的对象是漫画的图片页,产出的是结构化的知识:
导入(Venera 库 / 本地目录)
→ 逐页多模态分析(概要、关键事件、连续性、实体)
→ 跨章节实体对齐(别名合并与消歧)
→ 分层聚合 → 概览 / 压缩上下文 / 剧情时间线 / 知识图谱 / 向量索引
→ 检索问答(带页码引用)· 角色 Skill 蒸馏(含人格层)
- 本地优先:默认单用户本地模式,数据库、页面图片、日志都留在你自己的机器上,不必把漫画上传给第三方。
- 模型自带:视觉(VLM)、语言(LLM)、嵌入、重排全部按 OpenAI 兼容协议接入,Base URL 与 API Key 由你在设置里填写——仓库不内置任何默认凭据、内网地址或模型文件。
| 模块 | 说明 |
|---|---|
| 漫画导入 | 从 Venera 本地库导入,或从本地目录导入(先预览再确认);按章落库为页与页面资产;Venera 数据目录可在设置里改 |
| 逐页结构化分析 | 视觉模型逐页抽取页面概要、关键事件、连续性备注,以及角色 / 地点 / 物品 / 能力 / 概念五类实体 |
| 实体对齐 | 跨章节消歧与别名合并:硬性规则(泛词与从属过滤、简称包含、同音与异体字、日期与编号区分)+ 按候选图分批的语义裁决 |
| 分层聚合 | 页 → 分组 → 章 → 全书的多层汇总,可按范围触发(全书 / 增量 / 指定章节 / 指定页);聚合粒度与每批页数可分别配置 |
| 概述与压缩上下文 | 无剧透概览、剧情总结、压缩上下文,作为问答的全库资料 |
| 剧情时间线 | 由分析结果生成事件与角色时间线 |
| 知识图谱 | 实体共现关系图,支持类别筛选、最小共现权重、搜索与节点详情 |
| 智能问答 | 单一「通用」检索:页面向量 + 全库产物 + 实体知识网络自动融合,回答带「第 X 话 第 Y 页」引用可溯源;检索降级会显式提示而不是静默兜底 |
| 向量检索 | ChromaDB 持久化索引 + 嵌入模型,可随时重建;索引过期或不可用会提示重建 |
| 角色 Skill 蒸馏 | 从实体知识网络与页面证据蒸馏单个角色的档案:事实层(身份、关系、出场)+人格层(性格、说话方式、逐字台词),人格层由视觉模型查看原画提炼;可在线查看或导出 .zip |
| 世界书蒸馏 | 按「最少出场页数」筛选后蒸馏世界书条目,同样可导出 .zip |
| 书架与阅读器 | 书架、书籍详情、章节列表、阅读器(翻页 / 连续滚动 / 沉浸模式)、问答笔记 |
| 设置中心 | 模型通道总览 + VLM / LLM / 嵌入 / 重排 / 分析 / 提示词分页,含连接测试、每域恢复默认、整库导入导出(备份不含密钥)、设置搜索与字段级错误定位 |
| 任务中心 | 持久任务队列:进度、暂停 / 继续 / 取消、失败项补跑(retry-failed) |
矢量版:architecture.svg
受管启动器(saber_v2.py --role launcher)
├── 存储准备:版本检查 / 等待升级 / 健康确认(storage-migrator)
├── API 进程(Flask + Waitress)──── Web 前端(Vue 3 构建产物,同源托管)
└── Worker 进程 ──────────────────── 持久任务队列(分析 / 衍生构建 / 向量 / 导入)
- 存储契约:SQLite 结构由
src/storage_migrator/schemas/<版本>.sql冻结契约 + 迁移脚本管理,启动时自动校验;结构不匹配会拒绝启动,而不是带着脏结构运行。当前版本见version.json。 - 任务模型:所有重活都是持久任务(job / item / step),支持中断续跑与失败项补跑;进程崩溃后由启动器重启并回收在途工作。
- 前端:构建产物随包分发(
src/backend_v2/static/vue),由 API 直接托管;开发时用 Vite 热更新。 - 模型:分析用的模型配置在任务启动时冻结,运行中改设置只影响下一个任务。
数据库、页面资产、日志与向量索引都在数据根下(默认是程序目录旁的 data-v2/):
data-v2/
├── saber.sqlite3 # 主库(书籍 / 页面 / 分析结果 / 产物 / 任务)
├── objects/ # 页面图片与封面等二进制资产
├── chroma/ # 向量索引(ChromaDB 持久化目录)
├── logs/ # API / Worker 日志(含诊断日志)
├── plugins/ runtime/ # 插件与运行期状态
└── temp/ # 导入暂存与中间文件(可安全清理)
公网 profile 必须显式指定 --data-dir,不会与本地实例共用数据根。
- 发行包:到 Releases 下载
MiyakoKB-<版本>.7z(单个文件,不再分卷,也不区分 CPU / GPU),用 7-Zip 或 Bandizip 解压后运行MiyakoKB.exe(Windows 内置解压与 WinRAR 无法正确识别 7z)。 - 源码运行:见下方源码开发。
- 发行包不含本地模型运行时:视觉 / 语言 / 嵌入 / 重排全部通过 API 接入,首次启动后在「设置」中填写。
启动后进入「设置」,先在模型通道总览里看清四条通道的状态,再逐个配置:
- 凭据:填写各家服务的 API Key。落库后只以密文保存,界面回读时只给出指纹与「已保存」标记,永不回传明文;输入框留空表示沿用已保存的密钥。
- 视觉模型(VLM):逐页分析用,必须支持图片输入;「批内并发数」与「最大图片边长」在这里配。
- 语言模型(LLM):实体对齐的语义裁决、概览等衍生步骤用,可与 VLM 复用同一提供商(「与视觉模型相同」开关)。
- 嵌入 / 重排:问答检索用;填好后点「连接测试」验证。
内置的 OpenAI 兼容提供商档案:SiliconFlow、DeepSeek、火山引擎、Google Gemini、通义千问、OpenAI、Ollama(本地)、自定义(任意兼容端点);重排另有 Jina AI、Cohere。
提示:Base URL 填到兼容层(通常以
/v1结尾)即可。多数服务对图片体积敏感,建议把「最大图片边长」压到 1024 再送模型,既稳又快。视觉连接测试会真实发一次单图请求,而不是查供应商能力清单——清单是快照,会把实际可用的模型误判成不支持。
- 导入:书架页 → 导入 → 选择 Venera 本地库或本地目录(先预览,再确认)。
- 分析:书籍详情页 → 选择范围(全书 / 增量 / 指定章节 / 指定页)→ 启动分析,进度在任务中心查看。
- 看结果:分析完成后查看概览、时间线、知识图谱、实体浏览、角色 Skill 与世界书。
- 提问:问答页选书提问,回答会给出「第 X 话 第 Y 页」的引用,可点开原图核对。
升级前请自行备份整个数据根目录。存储结构变更由启动器按 src/storage_migrator/schemas/ 下的契约自动迁移;跨版本升级细节见 docs/storage-migrations.md。
环境:Python 3.11+(CI 使用 3.12)、Node 22+。
# 后端
python -m venv .venv
.venv\Scripts\activate # Windows(Linux/macOS: source .venv/bin/activate)
pip install -r requirements.txt
# 前端
cd vue-frontend
npm ci
npm run build # 产物写入 ../src/backend_v2/static/vue启动:
# 开发栈:API + Worker(不做存储准备)
python run.py --no-browser
# 正式栈:受管启动器(存储准备 + API + Worker 监督,推荐)
python saber_v2.py --role launcher
# 公网部署:必须显式指定数据根
python saber_v2.py --role launcher --profile public --data-dir <目录>
# 也可单独起某个角色
python saber_v2.py --role api
python saber_v2.py --role worker
python saber_v2.py --role storage-migrator --data-dir <目录>公网(
publicprofile)已内置强制安全头:Content-Security-Policy、X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Referrer-Policy: no-referrer、Permissions-Policy、HSTS 等。若在前面加反向代理,请保留后端下发的这些响应头,不要覆盖。
测试与门禁:
python -m pytest tests_backend -q # 后端全量
cd vue-frontend
npm test # vitest(含 property 用例)
npm run typecheck # vue-tsc
npm run lint && npm run lint:css # eslint / stylelint
npm run lint:ui && npm run lint:ui:audit # UI 架构检查与审计(token、裸控件、层级、媒体查询)
npm run check:api # 契约与生成类型是否一致跑后端全量前先停掉开发栈(它占用 5000 端口,会让启动器与端口类用例超时),也别设
PYTHONIOENCODING=utf-8(会被角色子进程继承,导致按 locale 解码的探针用例假失败)。若
vue-frontend下出现.vite-tmp/,那是构建/架构检查用的临时目录:vite build与check-ui-architecture.mjs都会在里面写中间文件,它已在.gitignore与 eslint 的ignores里排除,不要提交。
打包与发布:
python -m PyInstaller app.spec --clean # 产物在 dist/MiyakoKB/
python .github/scripts/probe_package.py dist/MiyakoKB/MiyakoKB.exe # 逐角色启动探测推送 v* tag 或手动触发 .github/workflows/release.yml:工作流会跑后端测试 + 前端门禁(含 check:api)+ 打包探测,再产出单一发行包的单个 7z 资产(MiyakoKB-<version>.7z,不分卷)。version.json 的 version 必须与 tag 一致。
- 全新目录启动后 API 起不来? 先看同目录的
miyako-api-diagnostic.log(产品日志是miyako-api.log,只记摘要);启动器只在受管模式下做存储准备,run.py不做,所以开发栈不适合验证全新安装。 - 分析或衍生构建报 502 / 超时? 多半是模型服务侧的限流或网关故障。失败项不会丢:到任务中心用「重跑失败项」补跑即可。
- 问答按钮是灰的? 页面提示会给出缺失项(没有分析结果 / 向量索引过期 / 全库产物过期),点提示里的按钮重建即可。
- 问答回答里出现「语义索引读取失败」之类的告警? 说明向量索引不可用、本次只用了关键词与实体证据;按提示重建向量索引即可恢复。
- 想换模型提供商? 任务的模型配置在启动时冻结,改设置只影响下一个任务;换完请重新触发分析(已发布的页结果可用「增量」范围复用)。
- 实体对齐很慢? 它是把整张候选图分批送模型裁决,规模取决于书的大小与概念类实体数量;
INSIGHT_ALIGN_*环境变量可调批大小、并发、候选面与概念最小页数,INSIGHT_ANALYZE_PARALLEL控制页分析的批内并发。 - 设置里某页签「恢复默认」会动到密钥吗? 不会,只恢复该页签的非凭据字段;换机器搬配置用「导出备份 / 导入备份」,备份不含密钥,导入后需重新填写。
- 打包产物(
MiyakoKB.exe)双击能开,但--version/--probe报No usable temporary directory found? 这是无控制台(windowed)发行包的已知行为:只要它的工作目录或TEMP落在系统临时目录之内,Pythontempfile就无法证明候选目录可写。修法是让工作目录与TEMP/TMP都待在系统临时根目录之外(三者缺一不可)。控制台版不受影响;CI 侧probe_package.py已规避,发行流程细节见.github/scripts/probe_package.py。 - 存储版本升级? 见
docs/storage-migrations.md。
- 问题反馈 / 功能建议:Issues
- 提交前请确保后端
pytest与前端test / typecheck / lint / lint:css / lint:ui:audit / check:api全绿,且重建后的前端产物(src/backend_v2/static/vue)已一并提交。 - 第三方组件与字体许可清单见
THIRD_PARTY_LICENSES.md;本版本变更见RELEASE_NOTES.md。
本项目仅用于学习与技术交流。请在遵守当地法律法规与版权政策的前提下使用,严禁用于非法用途;漫画内容版权归原作者与出版方所有,请勿传播未授权内容。
MiyakoKB 派生自 Saber-Translator(原作者 MashiroSaber03,GPL-3.0),最初是作为漫画翻译工具开始的。
本项目在其基础上做了大规模改造:移除全部翻译专属的表、配置、提示词与代码目录,把管线从「翻译」改写为「漫画知识库」——逐页多模态结构化分析、跨章节实体对齐、分层聚合、概览与压缩上下文、剧情时间线、共现知识图谱、向量检索问答、角色 Skill 与世界书蒸馏;同时重做了前端(Vue 3 + 设计令牌)与发布链路。
因为这些改动,本仓库与原项目在功能、数据库结构与接口上均已不兼容;原项目的翻译功能在本项目中不存在。原始版权与 GPL-3.0 许可保持不变,上游的历史贡献应归其作者所有。
如果你要的是「把漫画翻成中文」,请使用上游的 Saber-Translator。








