缙云文采 Sovena

English | 简体中文

Zotero → Markdown-Semantik-Literaturpaket → Vektor-Retrieval: Ein lokales Literaturverarbeitungssystem für akademische Forschung aller Disziplinen (besonders vorteilhaft für Bereiche mit vielen gescannten/fotokopierten Materialien in Geistes-, Sozial-, Natur- und Medizinwissenschaften), das über MCP (Model Context Protocol) als Dienst für beliebige lokale/Remote-KI-Clients bereitgestellt wird.

„Jinyun" stammt vom Jinyun-Berg in Beibei – dem Standort der Southwest University; „Wencai" hat eine doppelte Bedeutung: sowohl das Sammeln der Essenz von Literatur als auch den literarischen Glanz der Texte. „Pflücke die Blumen der fernen Vergangenheit, um daraus unseren Honig zu brauen." – Wu Mi (lehrte 28 Jahre an der Southwest University)

Anwendungsszenarien

• Literaturübersicht und Schreiben: Literatur aus Zotero (einschließlich gescannter alter Bücher, gescannter PDFs) wird in großen Mengen in Markdown mit Seitenzahlen umgewandelt; KI-Clients können beim Zitieren präzise auf die Seite zurückverfolgen

• Semantische Suche über Datenbanken hinweg: Natürliche Sprachfragen an mehrere hundert Literaturstellen (z. B. „Welche akustischen Messmethoden für Klangfarbe gibt es?"), statt mühsam nach Stichwörtern zu suchen

• Digitalisierung alter Bücher/Scans: Gescannte PDFs werden automatisch über den OCR-Kanal verarbeitet; Titel, Tabellen und zweispaltige Layouts werden in strukturierten Text zurückgeführt

• Materialien außerhalb von Zotero: E-Book-Bibliotheken, lose PDFs, Vorlesungsunterlagen und beliebige Ordner werden zu gleichermaßen durchsuchbaren temporären Materialpaketen (adhoc)

• KI-Deep-Reading-Externes Gehirn: Clients wie Claude Desktop / Cherry Studio / Trae greifen über MCP direkt auf Ihre Literaturdatenbank zu; Antworten enthalten Quellenangaben

• Remote-Zusammenarbeit: Der Server kann auf jedem geeigneten Computer bereitgestellt werden (zu Hause/Labor/Cloud); andere Computer nutzen ihn, indem sie die Server-URL im KI-Client eintragen

Related MCP server: scientific-papers-mcp

Kernfunktionen

Architektur

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-Textpfad: PDFs mit Textebene → Extraktion mit pymupdf; Seitenzahlmarkierung bevorzugt über PDF Page Labels (Buchseitenzahlen, nicht physische Seitenreihenfolge)

• L2-OCR-Pfad: Scans/Fotokopien → Unlimited-OCR-Strukturerkennung (duale Backends MLX / GGUF); Seitenzahlpriorität: von OCR erkannte page_number > PDF Page Label > physische Seitenreihenfolge

• Nicht-PDF: docx / epub / html / txt / md / xlsx / pptx usw. → anydoc / trafilatura

• Retrieval: beliebiger OpenAI-kompatibler Embedding-Dienst (lokal mlx-lm / Ollama, oder Remote-Plattformen wie Bailian / OpenRouter) + LanceDB lokale Vektordatenbank

OCR-Engine und Modellbereitstellung

Der OCR-Kanal von sovena verwendet Unlimited-OCR (Open-Source von Baidu, MIT-Lizenz, Modellgewichte auf HuggingFace baidu/Unlimited-OCR): Ein Dokument-OCR-Modell mit DeepSeek-V2-MoE-Decoder + dualem SAM/CLIP-Vision-Turm, das mehrseitige Scans als Ganzes erkennen und Titel/Tabellen/Layouts rekonstruieren kann.

Es werden zwei Backends unterstützt, beide mit identischer strukturierter Ausgabe – die nachgelagerte Konvertierung merkt keinen Unterschied:

Backend 1: MLX (Apple Silicon, Standard)

MLX-Gewichte von HuggingFace herunterladen (LoJexLLM/Unlimited-OCR-MLX):

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

Standardmäßig landen sie im Standardpfad von sovena (~/models/Unlimited-OCR-MLX) – keinerlei Konfiguration erforderlich. Für andere Speicherorte in .env angeben:

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

Backend 2: GGUF (beliebiger Computer, einschließlich Windows/Linux ohne GPU)

Unlimited-OCR hat eine Community-GGUF-Quantisierung (HuggingFace sahilchachra/Unlimited-OCR-GGUF; Hauptmodell wie Unlimited-OCR-Q4_K_M.gguf (ca. 3,2 GB) + visueller Projektor mmproj-Unlimited-OCR-F16.gguf herunterladen) – mit llama.cpp's llama-server einen lokalen Dienst starten:

# 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

Alternativ kann jeder OpenAI-kompatible Dienst, der dieses GGUF ausführen kann (z. B. vLLM), verwendet werden (bei anderem Modellnamen SOVENA_OCR_MODEL_NAME=... hinzufügen; bei Authentifizierung SOVENA_OCR_API_KEY=... hinzufügen). Der OCR-Dienst kann sogar auf einem anderen Rechner mit GPU bereitgestellt werden; sovena trägt einfach dessen Adresse ein.

Hinweis: Q4-Quantisierung ca. 3 GB – ein normaler Computer mit 16 GB RAM reicht aus. sovena ruft bei Bedarf auf (seitenweise Anfragen) und belegt keinen Speicher im sovena-Prozess.

Embedding-Dienst (für Retrieval erforderlich) – jede beliebige OpenAI-kompatible /embeddings-Schnittstelle, eine von zwei Optionen:

• Lokal (empfohlen, kostenlos und privat): mlx-lm (Inferenzdienst aus Apples offiziellem MLX-Ökosystem, 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 und andere OpenAI-kompatible lokale Lösungen funktionieren analog (bei anderer Adresse SOVENA_EMBED_API setzen)

• Remote-Kommerzplattform (keine lokalen Modelle gewünscht): Alibaba Cloud Bailian / OpenRouter / SiliconFlow usw. – einfach API-Adresse und Schlüssel in .env eintragen:

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

Hinweis: Nach einem Wechsel des Embedding-Dienstes/Modells ändern sich Vektordimension und semantischer Raum; bestehende Indizes müssen neu aufgebaut werden (sovena weist bei Dimensionsabweichung deutlich darauf hin; _lancedb-Verzeichnis löschen und die Sammlungen neu „vorbereiten", oder „Vollständigen Neuaufbau" anhaken).

Schnellstart

Anforderungen: Auf jedem Computer bereitstellbar; der Kernprozess benötigt nur Python ≥ 3.12 (Windows / macOS / Linux universell). OCR-Kanal: eine von zwei Optionen: Apple Silicon verwendet das Standard-MLX-Backend (Null-Konfiguration); andere Plattformen (oder wenn ein GPU-Server für OCR gewünscht ist) verwenden das GGUF-Backend (siehe Abschnitt „Backend 2" oben). Der gesamte Ablauf besteht nur aus Kopieren-und-Einfügen von Befehlen.

Schritt 1: uv installieren (Python-Paketmanager, einmalig)

„Terminal" öffnen (im Launchpad nach „Terminal" suchen), einfügen:

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

Nach der Installation das Terminal schließen und neu öffnen (damit der Befehl wirksam wird). Verifizieren: uv --version sollte eine Versionsnummer ausgeben.

Schritt 2: Zotero installieren und laufen lassen

• Zotero 7+ von zotero.org herunterladen und installieren, Ihre Literatur importieren

• sovena liest über die lokale API von Zotero (sobald Zotero geöffnet ist, automatisch verfügbar – keine Einstellungen erforderlich)

• Anhänge können „importierte Anhänge" oder „verlinkte Anhänge" sein – beide werden unterstützt

Schritt 3: Modelldienste vorbereiten (Retrieval erforderlich + OCR optional)

Embedding-Dienst (für Retrieval erforderlich), eine von zwei Optionen:

• Lokal (empfohlen): mlx-lm (aus Apples offiziellem MLX-Ökosystem, MIT) – uv tool install mlx-lm, Modell herunterladen und mlx_lm.server --model <Modellverzeichnis> --port 8080 starten (vollständige Befehle siehe Abschnitt „Embedding-Dienst" oben). Ollama / vLLM und andere OpenAI-kompatible Lösungen funktionieren analog

• Remote-Plattform (keine lokalen Modelle): Alibaba Cloud Bailian / OpenRouter usw. – im Projektstammverzeichnis eine .env-Datei mit Adresse und Schlüssel anlegen (siehe Beispiel im Abschnitt „Embedding-Dienst" oben)

OCR-Modell (nur für Scans erforderlich, Apple Silicon): Unlimited-OCR-MLX von HuggingFace nach ~/models/Unlimited-OCR-MLX herunterladen (Befehle siehe Abschnitt „Backend 1" oben; sovena lädt/entlädt es bei Bedarf selbst)

Nicht-Apple-Silicon-Computer für OCR: „GGUF-Backend" verwenden – Unlimited-OCR-GGUF herunterladen + llama-server starten, Konfiguration siehe Abschnitt „Backend 2" oben. Nur schnell ausprobieren, Retrieval vorerst nicht nötig? Der Modelldienst kann später nachgerüstet werden – überspringen Sie ihn und machen Sie Schritte 4–5.

Schritt 4: sovena holen und Abhängigkeiten installieren

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

Nicht-Apple-Silicon-Computer (Windows / Linux / Intel Mac): MLX-bezogene Abhängigkeiten werden nur im MLX-OCR-Backend verwendet; uv sync überspringt sie auf diesen Plattformen automatisch oder installiert CPU-kompatible Versionen; Text-PDFs, Nicht-PDF-Dokumentkonvertierung, Retrieval und andere Kernfunktionen sowie OCR mit dem GGUF-Backend funktionieren normal.

Schritt 5: Ein-Klick-Start

uv run sovena

Wenn Uvicorn running on http://0.0.0.0:8765 erscheint, ist der Start erfolgreich. Im Browser **<http://localhost:8765** öffnen:>

• Der Punkt auf der Seite „Leistungsüberwachung" ist grün → Dienst läuft normal

• Im Dropdown „Zotero-Literaturstrom" sind Ihre Sammlungen sichtbar → Zotero ist verbunden

Zum Beenden im Terminal Control + C drücken. Der Dienst läuft nicht dauerhaft und startet nicht automatisch; schwere Operationen werden intern seriell geplant (OCR-Konkurrenz=1, Speicherwächter) – der Computer läuft nicht in den Tod.

Schritt 6 (optional): Persönliche Pfadkonfiguration

Standarddaten liegen in ~/sovena_data. Für einen anderen Speicherort (z. B. externe Festplatte) im Projektstammverzeichnis eine .env-Datei anlegen:

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

.env ist von git ignoriert; persönliche Pfade gelangen nicht ins Repository.

Schritt 7: Erste Aufgabe ausführen

In der Web-Konsole „Zotero-Literaturstrom" → eine kleine Sammlung wählen (z. B. 5 Einträge) → „Vorbereitung starten" → zur „Leistungsüberwachung" wechseln und den Fortschritt beobachten. Danach in „Semantische Suche" eine Frage stellen und testen.

Häufige Fragen

Schritt 8 (optional): KI-Client-Anbindung (auch für andere Computer)

Jeder Client mit MCP-streamable-http-Unterstützung (Claude Desktop, Cherry Studio, Trae usw.) trägt ein:

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

Remote-Bereitstellung (andere Computer): Server mit SOVENA_HOST=0.0.0.0 starten (Standard); der Client ersetzt die URL durch http://<Server-IP-oder-Tailscale-Hostname>:8765/mcp. Auf der Seite „Einstellungen" der Web-Überwachungskonsole kann die Konfigurations-JSON der aktuellen Bereitstellung mit einem Klick kopiert/heruntergeladen werden.

Zotero-Plugin (optional)

dist/sovena-plugin-<version>.xpi ist ein Client-Plugin, das in Zotero 7+ (einschließlich 9/10) installiert werden kann und direkten Zugriff auf sovena aus Zotero heraus ermöglicht:

• Rechtsklick auf Sammlung → „sovena: Semantikpaket vorbereiten/aktualisieren (inkrementell)"

• Rechtsklick auf Eintrag → „sovena: Anhänge zum temporären Semantikpaket hinzufügen" (lokale Dateianhänge der ausgewählten Einträge durchlaufen den adhoc-Prozess)

• Menü Extras → sovena → Überwachungskonsole öffnen / Serveradresse einstellen / MCP-Client-Konfiguration kopieren / Verbindungsprüfung

Installation: Zotero → Extras → Plugins → Zahnrad oben rechts → Install Plugin From File… → dist/sovena-plugin-0.1.0.xpi auswählen. Standardmäßig verbindet es sich mit http://localhost:8765; auf anderen Computern unter „Extras → sovena → Serveradresse…" die sovena-Serveradresse eintragen.

Plugin neu packen (nach Änderungen an zotero-plugin/):

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

Umgebungsvariablen

Alle Konfigurationen können über Umgebungsvariablen gesetzt werden; empfohlen ist eine .env-Datei im Projektstammverzeichnis (von .gitignore ignoriert, geeignet für persönliche Pfade), die beim Dienststart automatisch geladen wird:

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

Verwendung

Zotero-Literaturstrom (inkrementell)

In der Web-Konsole eine Sammlung wählen → „Vorbereitung starten"; oder den KI-Client das MCP-Tool sovena_prepare aufrufen lassen. Wiederholte Ausführung ist automatisch inkrementell: Es werden nur neue/geänderte Einträge verarbeitet (Änderung der Zotero-Version oder der Anhang-mtime); der Index wird eintragsbezogen hinzugefügt/entfernt. Mit „Vollständiger Neuaufbau" kann ein erzwungener Neustart erfolgen.

adhoc temporäre Materialien (beliebige Dateien/Ordner)

E-Book-Bibliotheken, lose PDFs, Vorlesungsunterlagen usw. zu durchsuchbaren Semantikpaketen machen:

• Web-Konsole: Auf der Karte „Temporäre Materialpakete" Pfade eintragen (mehrere durch Zeilenumbruch oder ; getrennt) → absenden; danach zusammen mit Zotero-Sammlungen semantisch durchsuchbar

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

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

Unterstützt pdf/epub/docx/html/txt/md/xlsx/pptx usw.; gescannte PDFs durchlaufen automatisch OCR; ebenfalls inkrementell (Quelldatei wird übersprungen, wenn mtime unverändert).

MCP-Tool-Übersicht

Hinweis: Die lokale Zotero-API ist schreibgeschützt, daher werden keine Schreibwerkzeuge angeboten.

Verzeichnisstruktur der Semantikpakete

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

REST-API-Übersicht

Projektstruktur

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                     # 本地个人配置（可选，不入库）

Danksagung

sovena steht auf den Schultern der folgenden Projekte, vielen Dank:

• Unlimited-OCR（Baidu，MIT）— das Dokument-OCR-Modell selbst；Der ocr_port/-Code wurde aus der MLX-Implementierung der mlx-vlm-Community portiert；Die MLX-Gewichte (im LoJexLLM-Format) und die GGUF-quantisierte Version (sahilchachra) stammen beide aus der HuggingFace-Community；Der HTTP-Backend läuft über den llama-server von llama.cpp (MIT)

• cookjohn/zotero-mcp — eine der Projektinspirationen

• Zotero（AGPL）— Literaturverwaltung selbst und lokale API

• PyMuPDF（AGPL）— PDF-Textextraktion und Seitenzahl-Labels

• LanceDB（Apache-2.0）— lokale Vektordatenbank

• FastMCP（MIT）— MCP-Service-Framework

• anydoc（firecrawl-anydoc）— Konvertierung von Nicht-PDF-Dokumenten wie docx/epub

• trafilatura（Apache-2.0）— Webseiten-Text-Extraktion

• mlx-lm（Apple ml-explore，MIT）— lokaler Embedding-Inferenzdienst（mlx_lm.server，OpenAI-kompatible API）

• uv（Astral，MIT）— Python-Paketverwaltung

License

MIT © Sovena-Mitwirkende、Südwest-Universität · Institut für Kunstanthropologie、Südwest-Universität · Institut für Musikpsychische Gesundheit；Autor：Shi Fengkai（sfklc@hotmail.com）