Цзиюнь Вэньцай Sovena

English | 简体中文

Zotero → Markdown семантический пакет документов → векторный поиск: локальная система обработки потока документов для академических исследований в различных дисциплинах (особенно полезна в областях с большим количеством сканированных/факсимильных материалов — гуманитарные, социальные, естественные и технические науки, медицина), предоставляемая любому локальному/удалённому AI-клиенту в виде сервиса MCP (Model Context Protocol).

«Цзиюнь» — от горы Цзиюньшань в Бэйбэе, где расположен Юго-Западный университет; «Вэньцай» имеет два значения: и собирание (采撷) сути документов, и литературный блеск (华采). «Срывая цветы древности, чтобы сотворить мёд наш.» — У Ми (преподавал в Юго-Западном университете двадцать восемь лет)

Сценарии применения

• Литературные обзоры и написание: массовое преобразование документов из Zotero (включая факсимильные издания древних книг, сканированные PDF) в Markdown с номерами страниц книг; AI-клиент может точно ссылаться на страницы при цитировании

• Семантический поиск по нескольким базам: задавайте вопросы на естественном языке по сотням документов (например, «какие существуют методы акустического измерения тембра»), вместо поиска по ключевым словам в каждом документе

• Оцифровка древних книг/факсимильных изданий: сканированные PDF автоматически проходят через OCR-канал, восстанавливая заголовки, таблицы, двухколоночную вёрстку в структурированный текст

• Материалы вне Zotero: электронные библиотеки, разрозненные PDF, учебные материалы и любые другие папки — создаются как временные семантические пакеты (adhoc) с возможностью поиска

• Внешний мозг для глубокого чтения AI: клиенты Claude Desktop / Cherry Studio / Trae и др. напрямую обращаются к вашей библиотеке через MCP, ответы с указанием источников

• Удалённая совместная работа: сервер разворачивается на любом подходящем компьютере (дома/в лаборатории/в облаке), другие компьютеры указывают URL сервера в AI-клиенте

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, или удалённые платформы Bailian / OpenRouter и др.) + локальная векторная база LanceDB

OCR-движок и развёртывание моделей

OCR-канал sovena использует Unlimited-OCR (открытый исходный код Baidu, лицензия MIT, веса моделей на HuggingFace baidu/Unlimited-OCR): документная OCR-модель с декодером DeepSeek-V2 MoE + двойной визуальной башней SAM/CLIP, способная распознавать многостраничные сканы целиком и восстанавливать заголовки/таблицы/вёрстку.

Поддерживаются два бэкенда, вывод в обоих — структурированный формат, нижестоящая конвертация не замечает разницы:

Бэкенд 1: MLX (Apple Silicon, по умолчанию)

Скачайте MLX-веса с HuggingFace (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 (любой компьютер, включая Windows/Linux без GPU)

У Unlimited-OCR есть GGUF-квантованная версия сообщества (HuggingFace sahilchachra/Unlimited-OCR-GGUF, нужно скачать основную модель, например Unlimited-OCR-Q4_K_M.gguf (около 3,2 ГБ) + визуальный проектор mmproj-Unlimited-OCR-F16.gguf), запустите локальный сервис через llama-server из llama.cpp:

# 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 или любой другой OpenAI-совместимый сервис, способный запустить этот GGUF (при другом имени модели добавьте SOVENA_OCR_MODEL_NAME=...; при наличии аутентификации — SOVENA_OCR_API_KEY=...). OCR-сервис можно даже развернуть на другой машине с GPU, sovena просто укажет её адрес.

Подсказка: Q4-квантование около 3 ГБ, обычный компьютер с 16 ГБ памяти справится. sovena вызывает по требованию (запрос постранично), не занимает память внутри процесса sovena.

Сервис Embedding (для поиска, обязателен) — любой OpenAI-совместимый интерфейс /embeddings, на выбор:

• Локальный (рекомендуется, бесплатно и приватно): используйте mlx-lm (инференс-сервис из официальной экосистемы MLX от Apple, 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)

• Удалённая коммерческая платформа (не хотите запускать модели локально): Alibaba Cloud Bailian / OpenRouter / SiliconFlow и др., достаточно заполнить адрес API и ключ в .env:

# 示例：阿里云百炼（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 по умолчанию (нулевая настройка); на других платформах (или если хотите запускать OCR на GPU-сервере) — бэкенд GGUF (см. выше раздел «Бэкенд 2»). Весь процесс — только копирование и вставка команд.

Шаг 1: установите uv (менеджер пакетов Python, однократно)

Откройте «Терминал» (поиск «Терминал» в Launchpad или Terminal), вставьте:

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

После установки закройте терминал и откройте заново (чтобы команда заработала). Проверка: uv --version должен вывести номер версии.

Шаг 2: установите Zotero и держите его запущенным

• Скачайте и установите Zotero 7+ с zotero.org, импортируйте свои документы

• sovena читает через локальный API Zotero (автоматически доступен, пока Zotero открыт, никаких настроек не нужно)

• Вложения могут быть «импортированными вложениями» или «связанными вложениями», поддерживаются оба типа

Шаг 3: подготовьте сервисы моделей (embedding обязателен + OCR по желанию)

Сервис embedding (обязателен для поиска), на выбор:

• Локальный (рекомендуется): mlx-lm (официальная экосистема MLX от Apple, MIT) — uv tool install mlx-lm, скачайте модель и запустите mlx_lm.server --model <каталог модели> --port 8080 (полные команды см. выше в разделе «Сервис Embedding»). Ollama / vLLM и другие OpenAI-совместимые решения аналогично

• Удалённая платформа (без запуска моделей локально): Alibaba Cloud Bailian / OpenRouter и др., создайте .env в корне проекта и заполните адрес и ключ (см. пример в разделе «Сервис Embedding» выше)

OCR-модель (только для сканов, Apple Silicon): скачайте Unlimited-OCR-MLX с HuggingFace в ~/models/Unlimited-OCR-MLX (команды см. выше в разделе «Бэкенд 1», sovena загрузит/выгрузит её по мере необходимости)

На компьютерах не с Apple Silicon для 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 (Windows / Linux / Intel Mac): зависимости, связанные с MLX, используются только в MLX OCR-бэкенде; uv sync на этих платформах автоматически пропустит их или установит CPU-совместимые версии; текстовые PDF, конвертация не-PDF документов, поиск и другие ключевые функции, а также OCR через бэкенд GGUF — всё работает нормально.

Шаг 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), обеспечивающий прямой доступ к sovena из Zotero:

• Правый клик по коллекции → «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-консоли выберите коллекцию → «Запустить подготовку»; или вызовите MCP-инструмент sovena_prepare из AI-клиента. Повторное выполнение автоматически инкрементально: обрабатываются только новые/изменённые записи (изменение version в Zotero или изменение 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-инструментов

Примечание: локальный API Zotero доступен только для чтения, поэтому инструменты записи не предоставляются.

Структура каталога семантического пакета

$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 (Baidu, MIT) — сама модель OCR для документов; код ocr_port/ портирован из реализации MLX сообщества mlx-vlm; MLX-веса (формат LoJexLLM) и GGUF-квантованная версия (sahilchachra) взяты из сообщества HuggingFace; http-бэкенд работает через llama-server от llama.cpp (MIT)

• cookjohn/zotero-mcp — один из источников вдохновения проекта

• Zotero (AGPL) — основа управления литературой и локальный API

• PyMuPDF (AGPL) — извлечение текста из PDF и метки страниц

• LanceDB (Apache-2.0) — локальная векторная база данных

• FastMCP (MIT) — фреймворк MCP-сервисов

• anydoc (firecrawl-anydoc) — конвертация документов, отличных от PDF (docx/epub и др.)

• trafilatura (Apache-2.0) — извлечение основного текста веб-страниц

• mlx-lm (Apple ml-explore, MIT) — локальный сервис инференса embedding (mlx_lm.server, OpenAI-совместимый API)

• uv (Astral, MIT) — управление Python-пакетами

Лицензия

MIT © участники Sovena, Институт антропологии искусства Юго-Западного университета, Китайский институт музыкального психологического здоровья Юго-Западного университета; автор: Ши Фэнкай (sfklc@hotmail.com)