okforge-webui

# okforge-webui okforge 的局域网网页界面及任务运行器 知识库：放入收件箱的扫描书籍，通过 VLM OCR、可选的翻译以及摄入 LLM 综合的维基 - 然后浏览、查询和发布结果。构建用于本地优先设置，其中 LLM 是您自己的 llama.cpp/vLLM 盒子，而不是云 API。 该管道有五个屏幕：**probe**（检查 PDF：文本层？语言？页数？）→ **pilot**（OCR 一页或三页，在提交前检查转录和图像裁剪）→ **project**（选择或命名收集输出的项目）→ **run**（分段 OCR → 翻译 → 带有实时进度的 markdown）→ **verify & use**（查看 markdown，将其摄入项目的知识库，然后查询和发布）。OCR 和摄入始终是单独的步骤，因此同一个工具既可以用作纯 PDF→markdown 转换器 - 跳过摄入并从 `md-out/` 中获取文件。 输入：PDF、页面扫描图像（jpg/png/tif/bmp - 上传时包装成 PDF，以便 OCR 管道处理它们）和您自己的 markdown/text 文档（直接添加到项目中，无需 OCR）。一次选择多个 PDF/图像会将它们合并成一个 PDF 文件，按自然文件名顺序排列 - 上传会显示确切的顺序和组合名称，然后再进行任何操作。其他格式（docx、pptx、html ...）应首先转换为 markdown。  ## 工具列表 - **串行作业队列**（sqlite + 一个 worker，刻意为之）：一次一个 `add` 或 OCR 运行，保护单槽 LLM 主机和引擎的每个知识库摄入锁。作业在后端重启时存活；每个已完成的作业都会保留其日志。单击 **resume/retry**，一个 **stall watchdog**（标志，永不杀死），每个块的 **ETA** 来自真实历史记录，以及在每次添加之前对知识库的 git **pre-ingest snapshot**。 - **Markdown优先，摄入其次**：每次运行都将 OCR 转换为项目的 `md-out/<name>/` 文件夹（分段 `.md` + 页面映射 + 图像裁剪）；可以从 UI 中将手工制作的 markdown/text 文件添加到同一个文件夹中（“添加 markdown ...” - 不涉及 OCR）；将该 markdown 摄入知识库是一个单独的步骤 - 验证阶段的单击按钮（知识库统计信息逐块更新）或运行上的自动摄入开关。知识库在首次摄入时创建 - 或者如果您只想要 markdown，则永远不会创建。 - **存档优先删除**：删除上传的 PDF、项目的 markdown、已发布的站点或整个项目会将其 **移动** 到 `trash/`（知识库退休到 `kbs-retired/`）- UI 中没有任何内容是破坏性的，恢复是一个 `mv` 回复。 - **OCR + 图像提取** 通过 [okforge-vision-ocr](https://github.com/okforge/okforge-vision-ocr) （每个页面一个 VLM 调用：markdown 转录 + 照片边界框一起），具有针对快速路径损坏的页面的表格模式和每个页面重新 OCR + 重新摄入修复循环。 - **翻译** 工作流，用于非英语扫描：首先忠实地转录，然后逐页翻译 - 两个语言版本共享一个图像目录，页面引用存活。 - **维基浏览器**，具有词汇搜索（源命中带有真实页码）、图像灯箱和 markdown 渲染。 - **MCP 服务器** 在 `/mcp`（可流式 HTTP）：`list_projects`、`project_status`、`ask`、`search`、`read_wiki_page`。连接任何 MCP 客户端，例如 `claude mcp add --transport http okforge http://<host>/mcp`。 - **静态站点发布**，每个知识库通过 [Quartz](https://quartz.jzhao.xyz/) - 全文搜索、图形视图、反向链接 - 一个按钮，然后是一个打印的 rsync 命令，使其公开。 ## 先决条件 - **兼容 OpenAI 的 LLM 端点** - 整个管道的大脑（llama.cpp 或 vLLM 在您自己的硬件上，或托管服务；参见配置）。对于 OCR 路径，端点的模型必须是 **视觉能力**（Qwen-VL 家族或类似）- 它读取页面图像。文本层提取、摄入和查询适用于任何具有能力的聊天模型。 - **Python 3.10+** - **Git** - 用于克隆；在 Windows 上，它还提供引擎的查询代理使用的 `grep` 二进制文件。 - **Node.js 18+** - 仅用于可选的静态站点发布（Quartz）；其他所有功能无需它即可运行。Quartz 是一次性、每台机器一次安装到共享的 quartz 目录中（`<base>/quartz` 或 `OKFORGE_WEBUI_QUARTZ_DIR`）- 克隆它，检出 v5，`npm ci`，然后 **`npx quartz plugin install`**；确切的步骤在 [OPERATIONS](docs/OPERATIONS.md#publishing-a-kb-as-a-website-quartz) 中。 ## 目录布局 ``` <base>/ 例如 /opt/okforge/ 或 C:\okforge\ okforge-webui/ ← 此仓库；.venv/ 在其中 kbs/<Subject>/ ← 每个主题一个自包含的知识库 inbox/ ← 网页界面放置 PDF 的目录 md-out/<Project>/ ← 每个项目 OCR 的 markdown（按需创建） kbs-retired/ ← 退休的知识库（存档优先“删除”） trash/ ← 网页界面删除时将事物移动到此处，永不擦除 quartz/ ← 共享的 Quartz 安装（站点发布，可选） sites/<Subject>/ ← 已发布的静态站点（可选） ``` 基准目录可以是任意位置 - 所有默认值相对于此仓库的位置（每个都可以覆盖为环境变量，参见配置）。每个知识库都是自包含的（源、维基、引擎状态、`.env`、其自己的 git 历史记录）- 复制目录，您就复制了知识库。UI 通过扫描知识库根目录发现知识库；其他地方不注册任何内容。 ## 安装 Linux/macOS： ```bash cd /opt/okforge # 或任意基准目录 git clone https://github.com/okforge/okforge-webui cd okforge-webui python3 -m venv .venv .venv/bin/pip install -r requirements.txt mkdir -p ../kbs ../inbox ``` Windows（PowerShell）： ```powershell cd C:\okforge # 或任意基准目录 git clone https://github.com/okforge/okforge-webui cd okforge-webui python -m venv .venv .venv\Scripts\pip install -r requirements.txt md ..\kbs, ..\inbox ``` （PowerShell 注意：当前目录中的任何内容都需要 `.\` 前缀才能运行 - `.\script.ps1`，而不是 `script.ps1`。上述 `.venv\Scripts\…` 表格已经合格。） `requirements.txt` 固定了 PyPI 的两个 okforge 包 - [okforge 引擎](https://github.com/okforge/okforge)（摄入、维基编译、查询；参见其 [GETTING_STARTED](https://github.com/okforge/okforge/blob/main/GETTING_STARTED.md)）和 [okforge-vision-ocr](https://github.com/okforge/okforge-vision-ocr) （预转换控制台脚本）- 以及 FastAPI 后端的依赖项。 ## 运行 一个进程为前端、API 和 MCP 服务器提供服务。从此仓库的目录运行它 - `python -m webui` 解析相对于当前目录的 `webui` 包，因此从其他地方运行 Python 会以 `No module named webui` 退出： ```bash cd <base>/okforge-webui .venv/bin/python -m webui # Linux/macOS .venv\Scripts\python -m webui # Windows # 浏览 http://<host>:8500/ ``` `OKFORGE_WEBUI_HOST` / `OKFORGE_WEBUI_PORT` 更改绑定（默认为 `0.0.0.0:8500` - 对局域网可见；使用 `127.0.0.1` 保持本地）。所有模式下的信任模型相同：仅限局域网，无身份验证 - 不要将其暴露到您信任的网络之外。 第一次？在指向一本书之前，请遵循 [小型测试演练](#first-run--start-with-a-small-test) 演练。 ## 文档 - **首次运行**：上面的 [小型测试演练](#first-run--start-with-a-small-test) 是预期的入口。 - [`docs/INSTALL_PROMPT.md`](docs/INSTALL_PROMPT.md) - 一个提示，交给编码代理，以便它与您交互式地安装和配置，包含 Quartz。 - [`docs/OPERATIONS.md`](docs/OPERATIONS.md) - 日常操作知识库：解剖学、在机器之间复制、重新摄入语义（当您两次添加同一个文档时会发生什么）、Obsidian 编辑安全性、Quartz 发布、故障排除。 - [`docs/MCP_CLIENT_PROMPT.md`](docs/MCP_CLIENT_PROMPT.md) - 将此提示粘贴到不显示服务器自己的 `instructions` 的 MCP 客户端中（Open WebUI 和大多数 OpenAPI 桥接客户端）；也从服务器作为 MCP 提示 `kb-search-guide` 提供。 - [`webui/PLAN.md`](webui/PLAN.md) - 架构和 API 设计笔记。 ## License MIT - 参见 [LICENSE](LICENSE)。