縉雲文采 Sovena

English | 简体中文

Zotero → Markdown 意味文献パック → ベクトル検索：各学問分野の学術研究向けローカル文献フロー処理システム（人文・社会科学・理工・医学など、影印・スキャン資料が多い分野で特に有用）。MCP（Model Context Protocol）サービスとして任意のローカル／リモート AI クライアントに公開します。

「縉雲」は北碚縉雲山——西南大学の所在地——に由来します。「文采」には二つの意味があります：文献の精髄を採撷（採り集める）こと、そして文章の華采（あや）。 「采撷遠古之花兮，以醸造吾人之蜜。」——呉宓（西南大学で二十八年教鞭を執る）

応用シーン

• 文献レビューと執筆：Zotero 内の文献（影印古籍、スキャン版 PDF を含む）をページ番号付き Markdown に一括変換。AI クライアントが引用する際にページまで正確に遡れます

• クロスライブラリ意味検索：数百篇の文献に対して自然言語で質問（例：「音色の音響学的測定方法には何があるか」）。1 篇ずつキーワードを探す必要はありません

• 古籍・影印本のデジタル化：スキャン版 PDF は自動で OCR チャネルを通り、タイトル・表・二段組レイアウトを構造化テキストに復元

• Zotero 以外の資料：電子書籍ライブラリ、バラ PDF、講義資料など任意のフォルダを、同じく検索可能な一時資料パック（adhoc）に

• AI 深層読書の外部脳：Claude Desktop / Cherry Studio / Trae などのクライアントが MCP 経由で直接文献ライブラリを照会、回答に出典付き

• リモート協働：サーバーを任意の実行条件を満たす PC（自宅／研究室／クラウドいずれでも）にデプロイし、他の PC は 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 モデルで、複数ページのスキャン文書を全体認識し、タイトル・表・レイアウトを復元できます。

2 種類のバックエンドをサポートし、出力は同じ構造化形式のため、下流の変換は差異を意識しません：

バックエンド 1：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

バックエンド 2：GGUF（任意の PC、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 メモリの一般的な PC で実行可能です。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 ディレクトリを削除して各分類を再「準備」するか、「全量再構築」にチェックを入れてください）。

クイックスタート

要件：任意の PC にデプロイ可能。コアフローは Python ≥ 3.12 のみ必要（Windows / macOS / Linux 共通）。OCR チャネルはどちらかを選択：Apple Silicon はデフォルトの MLX バックエンド（ゼロ設定）。その他のプラットフォーム（または GPU サーバーで OCR を実行したい場合）は GGUF バックエンド（前節「バックエンド 2」参照）。すべてコピー＆ペーストで実行できます。

ステップ 1：uv をインストール（Python パッケージマネージャー、一度だけ）

「ターミナル」を開き（Launchpad で「ターミナル」または Terminal を検索）、貼り付け：

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

インストール後、ターミナルを閉じて開き直します（コマンドを有効にするため）。確認：uv --version でバージョンが表示されれば OK。

ステップ 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 にダウンロード（コマンドは前節「バックエンド 1」参照。sovena が必要時に自動でロード・リリース）

非 Apple Silicon PC で OCR を行う場合：「GGUF バックエンド」を使用——Unlimited-OCR-GGUF をダウンロード + llama-server を実行。設定は前節「バックエンド 2」参照。 すぐに体験したいだけで、検索はまだ不要？モデルサービスは後から追加できます。先にステップ 4〜5 をスキップして進めてください。

ステップ 4：sovena を取得して依存関係をインストール

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

非 Apple Silicon PC（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、メモリガード）されるため、PC をフリーズさせることはありません。

ステップ 6（任意）：個人パス設定

デフォルトデータは ~/sovena_data に保存されます。別の場所（外付けハードディスクなど）に置きたい場合は、プロジェクトルートに .env ファイルを作成：

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

.env は git で無視されているため、個人パスを書いてもリポジトリに入りません。

ステップ 7：最初のタスクを実行

Web コンソール「Zotero 文献フロー」→ 小さな分類（例：5 件の文献）を選択 →「準備開始」→「性能監視」に切り替えて進捗を確認。完了後、「意味検索」で質問してみてください。

よくある質問

ステップ 8（任意）：AI クライアント接続（他の PC でも同様に適用）

MCP streamable-http をサポートする任意のクライアント（Claude Desktop、Cherry Studio、Trae など）に以下を入力：

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

リモート（他の PC）デプロイ：サーバー側は 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 に接続。他の PC では「ツール → 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 パッケージ管理

ライセンス

MIT © Sovena contributors、西南大学・芸術人類学研究所、西南大学・中国音楽心理健康研究所；著者：石丰恺（sfklc@hotmail.com）