缙云文采 Sovena

English | 简体中文

Zotero → Markdown 语义文献包 → 向量检索：面向各学科学术研究的本地文献流处理系统（人文、社科、理工、医学等均有大量影印/扫描资料的领域尤其受益），并以 MCP（Model Context Protocol）服务的形式暴露给任意本地/远程 AI 客户端。

「缙云」取自北碚缙云山——西南大学所在地；「文采」兼含二义：既是采撷文献之精华，亦是文章之华采。 「采撷远古之花兮，以酿造吾人之蜜。」——吴宓（执教西南大学二十八年）

应用场景

• 文献综述与写作：把 Zotero 里的文献（含影印古籍、扫描版 PDF）批量转成带书页页码的 Markdown，AI 客户端引用时可精确溯源到页

• 跨库语义检索：对几百篇文献用自然语言提问（如「音色的声学测量方法有哪些」），而不是逐篇翻找关键词

• 古籍/影印本数字化：扫描版 PDF 自动走 OCR 通道，还原标题、表格、双栏版式为结构化文本

• Zotero 之外的资料：电子书库、散装 PDF、讲义等任意文件夹，做成同样可检索的临时资料包（adhoc）

• AI 深度阅读外脑：Claude Desktop / Cherry Studio / Trae 等客户端经 MCP 直接查你的文献库，回答带出处

• 远程协作：服务端部署在任意满足运行条件的电脑上（家中/实验室/云端均可），其他电脑在 AI 客户端里填服务端 URL 即可使用

Related MCP server: zotero-mcp-lite

核心能力

架构

Zotero(本地API) ─┐
                 ├─ Pipeline.prepare ─┬─ L1 文本路(pymupdf) ─┐
任意文件/文件夹 ─┘  (增量)             ├─ L2 OCR路(MLX/GGUF) ├─ 语义包(content.md+meta.json)
                                     └─ anydoc(非PDF)      ┘        │
                                                                 LanceDB 向量索引
                                                       （embedding: 本地/远程 OpenAI 兼容服务）
                                                                     │
                              ┌──────────────────────────────────────┤
                              │                                      │
                        Web 监管台(:8765)                      MCP 端点(/mcp)
                       (HTMX/原生JS)                    (本地 & Tailscale 远程 AI 客户端)

• L1 文本路：有文本层的 PDF → pymupdf 提取，页码标注优先用 PDF Page Labels（书页页码，非物理页序）

• L2 OCR 路：扫描/影印件 → Unlimited-OCR 结构化识别（MLX / GGUF 双后端），页码优先级：OCR 识别的 page_number > PDF Page Label > 物理页序

• 非 PDF：docx / epub / html / txt / md / xlsx / pptx 等 → anydoc / trafilatura

• 检索：任意 OpenAI 兼容 embedding 服务（本地 mlx-lm / Ollama，或百炼 / OpenRouter 等远程平台）+ LanceDB 本地向量库

OCR 引擎与模型部署

sovena 的 OCR 通道使用 Unlimited-OCR（百度开源，MIT 协议，模型权重在 HuggingFace baidu/Unlimited-OCR）：DeepSeek-V2 MoE 解码器 + SAM/CLIP 双视觉塔的文档 OCR 模型，能整篇识别多页扫描件并还原标题/表格/版式。

支持两种后端，输出同为结构化格式，下游转换无感知：

后端一：MLX（Apple Silicon，默认）

从 HuggingFace 下载 MLX 权重（LoJexLLM/Unlimited-OCR-MLX）：

huggingface-cli download LoJexLLM/Unlimited-OCR-MLX \
  --local-dir ~/models/Unlimited-OCR-MLX

默认就落在 sovena 的默认路径（~/models/Unlimited-OCR-MLX），无需任何配置。放到其他位置则在 .env 指定：

SOVENA_OCR_MODEL=/path/to/Unlimited-OCR-MLX

后端二：GGUF（任意电脑，含无 GPU 的 Windows/Linux）

Unlimited-OCR 有社区 GGUF 量化版（HuggingFace sahilchachra/Unlimited-OCR-GGUF，需下载主模型如 Unlimited-OCR-Q4_K_M.gguf（约 3.2GB）+ 视觉投影器 mmproj-Unlimited-OCR-F16.gguf），用 llama.cpp 的 llama-server 起一个本地服务即可：

# 1. 下载模型（二选一）
huggingface-cli download sahilchachra/Unlimited-OCR-GGUF \
  Unlimited-OCR-Q4_K_M.gguf mmproj-Unlimited-OCR-F16.gguf --local-dir ./ocr-models
# 国内可用 ModelScope 或镜像加速

# 2. 启动 OpenAI 兼容服务（8080 端口，任意平台；含 GPU 加速则加对应参数）
llama-server -m ocr-models/Unlimited-OCR-Q4_K_M.gguf \
  --mmproj ocr-models/mmproj-Unlimited-OCR-F16.gguf \
  --host 127.0.0.1 --port 8080

# 3. sovena 侧启用 http 后端（项目根目录 .env）
echo 'SOVENA_OCR_API=http://127.0.0.1:8080/v1' >> .env

也可用 vLLM 等任何能跑该 GGUF 的 OpenAI 兼容服务（模型名不同时加 SOVENA_OCR_MODEL_NAME=...；有鉴权加 SOVENA_OCR_API_KEY=...）。OCR 服务甚至可以部署在另一台有 GPU 的机器上，sovena 填它的地址即可。

提示：Q4 量化约 3GB，16GB 内存的普通电脑即可运行。sovena 按需调用（逐页请求），不在 sovena 进程内占内存。

Embedding 服务（检索用，必须）——任意 OpenAI 兼容 /embeddings 接口均可，二选一：

• 本地（推荐，免费私密）：用 mlx-lm（Apple 官方 MLX 生态的推理服务，MIT）：

uv tool install mlx-lm            # 或 pip install mlx-lm
huggingface-cli download Qwen/Qwen3-Embedding-4B --local-dir ~/models/Qwen3-Embedding-4B
mlx_lm.server --model ~/models/Qwen3-Embedding-4B --port 8080
# 起一个 OpenAI 兼容 /v1/embeddings 服务，即 sovena 的默认地址 http://localhost:8080/v1

Ollama / vLLM 等其他 OpenAI 兼容本地方案同理（地址不同时设 SOVENA_EMBED_API）

• 远程商用平台（不想本地跑模型）：阿里云百炼 / OpenRouter / SiliconFlow 等，只需在 .env 填 API 地址与密钥：

# 示例：阿里云百炼（OpenAI 兼容端点）
SOVENA_EMBED_API=https://dashscope.aliyuncs.com/compatible-mode/v1
SOVENA_EMBED_API_KEY=sk-你的密钥
SOVENA_EMBED_MODEL=text-embedding-v4

注意：更换 embedding 服务/模型后向量维度与语义空间会变化，已有索引需重建（sovena 检测到维度不匹配会明确提示；删除 _lancedb 目录后重新「准备」各分类，或勾选「全量重建」）。

快速开始

要求：任意电脑均可部署，核心流程只需 Python ≥ 3.12（Windows / macOS / Linux 通用）。OCR 通道二选一：Apple Silicon 用默认 MLX 后端（零配置）；其他平台（或想用 GPU 服务器跑 OCR）用 GGUF 后端（见上节「后端二」）。全程只需复制粘贴命令。

第 1 步：装 uv（Python 包管理器，一次性）

打开「终端」（启动台搜索「终端」或 Terminal），粘贴：

curl -LsSf https://astral.sh/uv/install.sh | sh

装完后关闭终端，重新打开（让命令生效）。验证：uv --version 能出版本号即可。

第 2 步：装 Zotero 并保持运行

• 到 zotero.org 下载安装 Zotero 7+，导入你的文献

• sovena 通过 Zotero 的本地 API 读取（Zotero 打开着就自动可用，无需任何设置）

• 附件可以是「导入的附件」或「链接附件」，两种都支持

第 3 步：准备模型服务（检索必需 + OCR 可选）

embedding 服务（检索必需），二选一：

• 本地（推荐）：mlx-lm（Apple 官方 MLX 生态，MIT）——uv tool install mlx-lm，下载模型并 mlx_lm.server --model <模型目录> --port 8080 起服务（完整命令见上节「Embedding 服务」）。Ollama / vLLM 等其他 OpenAI 兼容方案同理

• 远程平台（不在本地跑模型）：阿里云百炼 / OpenRouter 等，在项目根目录建 .env 填地址与密钥（见上节「Embedding 服务」的示例）

OCR 模型（仅扫描件需要，Apple Silicon）：从 HuggingFace 下载 Unlimited-OCR-MLX 到 ~/models/Unlimited-OCR-MLX（命令见上节「后端一」，sovena 需要时会自己加载/释放）

非 Apple Silicon 电脑做 OCR：改用「GGUF 后端」——下载 Unlimited-OCR-GGUF + 跑 llama-server，配置见上节「后端二」。 只想快速体验、暂时不检索？模型服务可以后补，先跳过做第 4-5 步。

第 4 步：获取 sovena 并安装依赖

git clone https://github.com/<you>/sovena.git
cd sovena
uv sync        # 自动下载全部依赖（首次约 1.3GB，需要几分钟）

非 Apple Silicon 电脑（Windows / Linux / Intel Mac）：MLX 相关依赖仅在 MLX OCR 后端用到，uv sync 在这些平台会自动跳过或用 CPU 兼容版本安装；文本 PDF、非 PDF 文档转换、检索等核心功能，以及 GGUF 后端的 OCR，均可正常使用。

第 5 步：一键启动

uv run sovena

看到 Uvicorn running on http://0.0.0.0:8765 即成功。浏览器打开 http://localhost:8765：

• 「性能监控」页的圆点是绿色 → 服务正常

• 「Zotero 文献流」下拉框能看到你的分类 → Zotero 连通

用完在终端按 Control + C 停止。服务不常驻、不开机自启，重操作内部串行调度（OCR 并发=1、内存守卫），不会把电脑跑死。

第 6 步（可选）：个人路径配置

默认数据存在 ~/sovena_data。想放别处（如移动硬盘），在项目根目录建 .env 文件：

echo 'SOVENA_ROOT=/Volumes/你的盘/sovena_data' > .env

.env 已被 git 忽略，写个人路径不会进仓库。

第 7 步：跑第一个任务

Web 台「Zotero 文献流」→ 选一个小分类（如 5 条文献）→「启动准备」→ 切到「性能监控」看进度。完成后去「语义检索」问个问题试试。

常见问题

第 8 步（可选）：AI 客户端接入（其他电脑同样适用）

任意支持 MCP streamable-http 的客户端（Claude Desktop、Cherry Studio、Trae 等）填入：

{
  "mcpServers": {
    "sovena": { "url": "http://localhost:8765/mcp" }
  }
}

远程（其他电脑）部署：服务端 SOVENA_HOST=0.0.0.0 启动（默认），客户端把 URL 换成 http://<服务器IP或Tailscale主机名>:8765/mcp 即可。Web 监管台「设置」页可一键复制/下载当前部署的配置 JSON。

Zotero 插件（可选）

dist/sovena-plugin-<version>.xpi 是可安装到 Zotero 7+（含 9/10） 的客户端插件，让 Zotero 内直达 sovena：

• 分类右键 → 「sovena：准备/更新语义包（增量）」

• 条目右键 → 「sovena：把附件加入临时语义包」（所选条目的本地文件附件走 adhoc 流程）

• 工具菜单 sovena → 打开监管台 / 服务端地址设置 / 复制 MCP 客户端配置 / 连接检查

安装：Zotero → 工具 → 插件 → 右上角齿轮 → Install Plugin From File… → 选择 dist/sovena-plugin-0.1.0.xpi。默认连 http://localhost:8765；其他电脑在「工具 → sovena → 服务端地址…」填 sovena 服务器地址即可。

重新打包插件（修改 zotero-plugin/ 后）：

bash zotero-plugin/build.sh    # 产出 dist/sovena-plugin-<version>.xpi

环境变量

所有配置均可用环境变量设置；推荐在项目根目录建一个 .env 文件（已被 .gitignore 忽略，适合放个人路径），服务启动时自动加载：

SOVENA_ROOT=/Volumes/your-disk/zotero_AI
SOVENA_ZOTERO_API=http://localhost:23119/api

使用

Zotero 文献流（增量）

Web 台选择分类 →「启动准备」；或让 AI 客户端调用 MCP 工具 sovena_prepare。重复执行自动增量：仅处理新增/变更条目（Zotero version 变化或附件 mtime 变化），索引按条目级增删。勾选「全量重建」可强制重来。

adhoc 临时资料（任意文件/文件夹）

把电子书库、散装 PDF、讲义等做成可检索语义包：

• Web 台：「临时资料包」卡片填路径（多个用换行或 ; 分隔）→ 提交，之后可与 Zotero 分类一起被语义检索

• MCP：sovena_adhoc_process(paths=["/path/to/E_book/某子目录"], name="我的书库")

• REST：POST /api/adhoc/submit {"paths": [...], "name": "..."}

支持 pdf/epub/docx/html/txt/md/xlsx/pptx 等；扫描版 PDF 自动走 OCR；同样支持增量（源文件 mtime 不变则跳过）。

MCP 工具一览

注：Zotero 本地 API 为只读，故不提供写操作工具。

语义包目录结构

$SOVENA_ROOT/
  <分类名>/
    _manifest.json                 # 分类级清单（增量依据）
    <作者>_<年份>_<标题>/
      meta.json                    # Zotero 元数据 + 转换统计
      content.md                   # AI 友好 markdown（含【书页页码】标注）
  adhoc/
    <资料包名>/
      _manifest.json
      <文件名slug>/
        meta.json
        content.md
  _lancedb/                        # 向量库

REST API 概览

项目结构

sovena/
  main.py                  # 一键启动入口
  sovena/
    server.py              # 服务总入口（Web + MCP 同进程，自动加载 .env）
    web.py / webui.html    # Web 监管台（分区 Tab + 路径选择器）
    mcp_server.py          # MCP 工具集
    zotero_collector.py    # Zotero 本地 API 采集（附件 4 路解析）
    pipeline.py            # prepare 流水线（增量）
    adhoc.py               # 任意资料临时处理
    converter.py           # L1/L2/anydoc 转换
    indexer.py             # 分块 + 向量化 + LanceDB
    packager.py            # 语义包落盘
    jobs.py                # 任务调度（内存守卫/OCR 并发=1）
  zotero-plugin/           # Zotero 客户端插件源码（bootstrap 结构）
  dist/                    # 构建产物（sovena-plugin-<version>.xpi）
  ocr_port/                # Unlimited-OCR-MLX（MLX OCR 引擎）
  .env                     # 本地个人配置（可选，不入库）

致谢

sovena 站在以下项目肩膀上，深表感谢：

• Unlimited-OCR（百度，MIT）— 文档 OCR 模型本体；ocr_port/ 代码移植自 mlx-vlm 社区的 MLX 实现；MLX 权重（LoJexLLM 整理格式）与 GGUF 量化版（sahilchachra）均来自 HuggingFace 社区；http 后端经 llama.cpp（MIT）的 llama-server 运行

• cookjohn/zotero-mcp — 项目灵感来源之一

• Zotero（AGPL）— 文献管理本体与本地 API

• PyMuPDF（AGPL）— PDF 文本提取与页码标签

• LanceDB（Apache-2.0）— 本地向量库

• FastMCP（MIT）— MCP 服务框架

• anydoc（firecrawl-anydoc）— docx/epub 等非 PDF 文档转换

• trafilatura（Apache-2.0）— 网页正文提取

• mlx-lm（Apple ml-explore，MIT）— 本地 embedding 推理服务（mlx_lm.server，OpenAI 兼容 API）

• uv（Astral，MIT）— Python 包管理

License

MIT © Sovena contributors、西南大学·艺术人类学研究所、西南大学·中国音乐心理健康研究所；作者：石丰恺（sfklc@hotmail.com）