Jinyun Wencai Sovena

English | 简体中文

Zotero → Paquete de literatura semántica en Markdown → Búsqueda vectorial: un sistema local de procesamiento de flujo de documentos para la investigación académica en todas las disciplinas (las áreas con gran cantidad de material escaneado/facsímil, como humanidades, ciencias sociales, ingeniería y medicina, se benefician especialmente), expuesto a cualquier cliente de IA local/remoto a través de un servicio MCP (Model Context Protocol).

«Jinyun» proviene del monte Jinyun en Beibei, donde se encuentra la Universidad del Suroeste; «Wencai» tiene un doble significado: tanto recoger la esencia de la literatura como el esplendor de los escritos. «Recojo las flores de tiempos remotos para elaborar nuestra miel.» — Wu Mi (profesor en la Universidad del Suroeste durante veintiocho años)

Casos de uso

• Revisión de literatura y redacción: convierte en lote los documentos de Zotero (incluidos facsímiles de libros antiguos y PDF escaneados) a Markdown con números de página del libro; los clientes de IA pueden citar con precisión la página al referenciar

• Búsqueda semántica entre bibliotecas: formula preguntas en lenguaje natural sobre cientos de documentos (por ejemplo, «¿cuáles son los métodos de medición acústica del timbre?») en lugar de buscar palabra por palabra

• Digitalización de libros antiguos/facsímiles: los PDF escaneados pasan automáticamente por el canal OCR, restaurando títulos, tablas y maquetación de doble columna como texto estructurado

• Materiales fuera de Zotero: bibliotecas de libros electrónicos, PDF sueltos, apuntes y cualquier otra carpeta, convertidos en paquetes de material temporal igualmente buscables (adhoc)

• Cerebro externo de lectura profunda con IA: clientes como Claude Desktop / Cherry Studio / Trae consultan directamente tu biblioteca de documentos a través de MCP, con respuestas que incluyen la fuente

• Colaboración remota: el servidor se despliega en cualquier ordenador que cumpla los requisitos (en casa, en el laboratorio o en la nube), y otros ordenadores solo necesitan introducir la URL del servidor en el cliente de IA

Related MCP server: zotero-mcp-lite

Capacidades principales

Arquitectura

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 客户端)

• Ruta L1 de texto: PDF con capa de texto → extracción con pymupdf; la anotación de página prioriza PDF Page Labels (número de página del libro, no el orden físico de páginas)

• Ruta L2 de OCR: escaneos/facsímiles → reconocimiento estructurado Unlimited-OCR (doble backend MLX / GGUF); prioridad de página: page_number reconocido por OCR > PDF Page Label > orden físico de páginas

• No PDF: docx / epub / html / txt / md / xlsx / pptx, etc. → anydoc / trafilatura

• Búsqueda: cualquier servicio de embedding compatible con OpenAI (mlx-lm / Ollama local, o plataformas remotas como Bailian / OpenRouter) + base de datos vectorial local LanceDB

Motor OCR y despliegue de modelos

El canal OCR de sovena utiliza Unlimited-OCR (código abierto de Baidu, licencia MIT, pesos del modelo en HuggingFace baidu/Unlimited-OCR): un modelo OCR de documentos con decodificador MoE DeepSeek-V2 + doble torre visual SAM/CLIP, capaz de reconocer escaneos multipágina completos y restaurar títulos/tablas/maquetación.

Se admiten dos backends, ambos con salida en formato estructurado; la conversión posterior no nota la diferencia:

Backend uno: MLX (Apple Silicon, predeterminado)

Descarga los pesos MLX desde HuggingFace (LoJexLLM/Unlimited-OCR-MLX):

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

Por defecto se colocan en la ruta predeterminada de sovena (~/models/Unlimited-OCR-MLX), sin necesidad de configuración. Si se colocan en otra ubicación, especifícala en .env:

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

Backend dos: GGUF (cualquier ordenador, incluidos Windows/Linux sin GPU)

Unlimited-OCR tiene una versión cuantizada GGUF comunitaria (HuggingFace sahilchachra/Unlimited-OCR-GGUF; hay que descargar el modelo principal como Unlimited-OCR-Q4_K_M.gguf (aprox. 3,2 GB) + el proyector visual mmproj-Unlimited-OCR-F16.gguf), y se puede iniciar un servicio local con llama-server de 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

También se puede usar vLLM o cualquier otro servicio compatible con OpenAI que pueda ejecutar ese GGUF (si el nombre del modelo difiere, añade SOVENA_OCR_MODEL_NAME=...; si hay autenticación, añade SOVENA_OCR_API_KEY=...). El servicio OCR incluso puede desplegarse en otra máquina con GPU; sovena solo necesita su dirección.

Consejo: la cuantización Q4 ocupa unos 3 GB; un ordenador normal con 16 GB de RAM puede ejecutarla. sovena la invoca bajo demanda (solicitudes página a página), sin ocupar memoria dentro del proceso de sovena.

Servicio de embedding (necesario para la búsqueda) — cualquier interfaz /embeddings compatible con OpenAI, elige una de dos:

• Local (recomendado, gratuito y privado): usa mlx-lm (servicio de inferencia del ecosistema MLX oficial de 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 y otras soluciones locales compatibles con OpenAI funcionan igual (si la dirección difiere, configura SOVENA_EMBED_API)

• Plataforma comercial remota (si no quieres ejecutar modelos localmente): Alibaba Cloud Bailian / OpenRouter / SiliconFlow, etc.; solo hay que rellenar la dirección API y la clave en .env:

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

Nota: al cambiar el servicio/modelo de embedding, la dimensión vectorial y el espacio semántico cambian; los índices existentes deben reconstruirse (sovena lo avisará claramente al detectar la discrepancia de dimensiones; elimina el directorio _lancedb y vuelve a «preparar» cada colección, o marca «Reconstrucción completa»).

Inicio rápido

Requisitos: se puede desplegar en cualquier ordenador; el flujo principal solo necesita Python ≥ 3.12 (compatible con Windows / macOS / Linux). Canal OCR, elige uno de dos: Apple Silicon usa el backend MLX predeterminado (configuración cero); otras plataformas (o si quieres usar un servidor GPU para OCR) usan el backend GGUF (ver sección «Backend dos» arriba). Todo el proceso solo requiere copiar y pegar comandos.

Paso 1: instalar uv (gestor de paquetes de Python, una sola vez)

Abre «Terminal» (busca «Terminal» en Launchpad o Terminal), y pega:

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

Después de instalar, cierra la terminal y vuelve a abrirla (para que el comando surta efecto). Verificación: uv --version debe mostrar el número de versión.

Paso 2: instalar Zotero y mantenerlo en ejecución

• Descarga e instala Zotero 7+ desde zotero.org e importa tu bibliografía

• sovena lee a través de la API local de Zotero (con Zotero abierto, está disponible automáticamente, sin necesidad de configuración)

• Los archivos adjuntos pueden ser «archivos adjuntos importados» o «archivos adjuntos vinculados»; ambos son compatibles

Paso 3: preparar los servicios de modelo (embedding obligatorio + OCR opcional)

Servicio de embedding (obligatorio para la búsqueda), elige una de dos:

• Local (recomendado): mlx-lm (ecosistema MLX oficial de Apple, MIT) — uv tool install mlx-lm, descarga el modelo y ejecuta mlx_lm.server --model <directorio del modelo> --port 8080 para iniciar el servicio (comando completo en la sección «Servicio de embedding» arriba). Ollama / vLLM y otras soluciones compatibles con OpenAI funcionan igual

• Plataforma remota (sin ejecutar modelos localmente): Alibaba Cloud Bailian / OpenRouter, etc.; crea un .env en la raíz del proyecto con la dirección y la clave (ver el ejemplo en la sección «Servicio de embedding» arriba)

Modelo OCR (solo para escaneos, Apple Silicon): descarga Unlimited-OCR-MLX desde HuggingFace a ~/models/Unlimited-OCR-MLX (comando en la sección «Backend uno» arriba; sovena lo carga/libera automáticamente cuando lo necesita)

Ordenadores sin Apple Silicon para OCR: usa el «backend GGUF» — descarga Unlimited-OCR-GGUF + ejecuta llama-server; configuración en la sección «Backend dos» arriba. ¿Solo quieres probar rápido y no buscar por ahora? El servicio de modelos puede añadirse después; salta a los pasos 4-5.

Paso 4: obtener sovena e instalar dependencias

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

Ordenadores sin Apple Silicon (Windows / Linux / Intel Mac): las dependencias relacionadas con MLX solo se usan en el backend OCR MLX; uv sync las omite automáticamente en estas plataformas o las instala con versiones compatibles con CPU; las funciones principales como conversión de PDF de texto, conversión de documentos no PDF, búsqueda, y OCR con backend GGUF funcionan con normalidad.

Paso 5: inicio con un clic

uv run sovena

Al ver Uvicorn running on http://0.0.0.0:8765, el inicio fue exitoso. Abre en el navegador **<http://localhost:8765**:

• El punto en la página «Monitor de rendimiento» está en verde → el servicio funciona

• El menú desplegable «Flujo de literatura de Zotero» muestra tus colecciones → Zotero está conectado

Cuando termines, pulsa Control + C en la terminal para detener. El servicio no reside permanentemente ni se inicia con el sistema; las operaciones pesadas se programan internamente en serie (concurrencia OCR=1, guardia de memoria), no satura el ordenador.

Paso 6 (opcional): configuración de rutas personales

Los datos predeterminados se guardan en ~/sovena_data. Si quieres otra ubicación (por ejemplo, un disco duro externo), crea un archivo .env en la raíz del proyecto:

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

.env está ignorado por git; las rutas personales no entran en el repositorio.

Paso 7: ejecutar la primera tarea

En la consola web, «Flujo de literatura de Zotero» → selecciona una colección pequeña (por ejemplo, 5 entradas) → «Iniciar preparación» → cambia a «Monitor de rendimiento» para ver el progreso. Cuando termine, ve a «Búsqueda semántica» y haz una pregunta de prueba.

Preguntas frecuentes

Paso 8 (opcional): conexión de clientes de IA (también válido para otros ordenadores)

Cualquier cliente compatible con MCP streamable-http (Claude Desktop, Cherry Studio, Trae, etc.) introduce:

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

Despliegue remoto (otros ordenadores): inicia el servidor con SOVENA_HOST=0.0.0.0 (predeterminado), y el cliente cambia la URL a http://<IP del servidor o nombre de host Tailscale>:8765/mcp. La página «Configuración» de la consola web permite copiar/descargar el JSON de configuración del despliegue actual con un clic.

Plugin de Zotero (opcional)

dist/sovena-plugin-<version>.xpi es un plugin de cliente instalable en Zotero 7+ (incluidos 9/10) que permite acceder a sovena directamente desde Zotero:

• Clic derecho en colección → «sovena: preparar/actualizar paquete semántico (incremental)»

• Clic derecho en entrada → «sovena: añadir archivos adjuntos al paquete semántico temporal» (los archivos adjuntos locales de las entradas seleccionadas pasan por el flujo adhoc)

• Menú Herramientas → sovena → abrir consola de supervisión / configuración de dirección del servidor / copiar configuración del cliente MCP / comprobación de conexión

Instalación: Zotero → Herramientas → Complementos → engranaje en la esquina superior derecha → Install Plugin From File… → selecciona dist/sovena-plugin-0.1.0.xpi. Por defecto se conecta a http://localhost:8765; en otros ordenadores, introduce la dirección del servidor sovena en «Herramientas → sovena → Dirección del servidor…».

Para reempaquetar el plugin (después de modificar zotero-plugin/):

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

Variables de entorno

Toda la configuración puede establecerse con variables de entorno; se recomienda crear un archivo .env en la raíz del proyecto (ignorado por .gitignore, adecuado para rutas personales), que se carga automáticamente al iniciar el servicio:

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

Uso

Flujo de literatura de Zotero (incremental)

Selecciona una colección en la consola web → «Iniciar preparación»; o haz que el cliente de IA llame a la herramienta MCP sovena_prepare. La ejecución repetida es automáticamente incremental: solo procesa entradas nuevas/modificadas (cambio de version de Zotero o cambio de mtime del archivo adjunto), y el índice se añade/elimina a nivel de entrada. Marcar «Reconstrucción completa» fuerza a rehacerlo.

Material temporal adhoc (cualquier archivo/carpeta)

Convierte bibliotecas de libros electrónicos, PDF sueltos, apuntes, etc., en paquetes semánticos buscables:

• Consola web: en la tarjeta «Paquete de material temporal», introduce las rutas (varias separadas por saltos de línea o ;) → enviar; a partir de ahí se pueden buscar semánticamente junto con las colecciones de Zotero

• MCP: sovena_adhoc_process(paths=["/path/to/E_book/algún subdirectorio"], name="Mi biblioteca")

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

Admite pdf/epub/docx/html/txt/md/xlsx/pptx, etc.; los PDF escaneados pasan automáticamente por OCR; también admite incrementos (si el mtime del archivo fuente no cambia, se omite).

Resumen de herramientas MCP

Nota: la API local de Zotero es de solo lectura, por lo que no se ofrecen herramientas de escritura.

Estructura de directorios del paquete semántico

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

Resumen de la API REST

Estructura del proyecto

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

Agradecimientos

sovena se apoya en los hombros de los siguientes proyectos, muchas gracias:

• Unlimited-OCR (Baidu, MIT) — El modelo OCR de documentos en sí; el código ocr_port/ se portó de la implementación MLX de la comunidad mlx-vlm; los pesos MLX (formato organizado por LoJexLLM) y la versión cuantizada GGUF (sahilchachra) provienen de la comunidad HuggingFace; el backend http se ejecuta a través de llama-server de llama.cpp (MIT)

• cookjohn/zotero-mcp — Una de las fuentes de inspiración del proyecto

• Zotero (AGPL) — El gestor de referencias en sí y su API local

• PyMuPDF (AGPL) — Extracción de texto PDF y etiquetas de número de página

• LanceDB (Apache-2.0) — Base de datos vectorial local

• FastMCP (MIT) — Marco de servicios MCP

• anydoc (firecrawl-anydoc) — Conversión de documentos no PDF como docx/epub

• trafilatura (Apache-2.0) — Extracción de contenido de páginas web

• mlx-lm (Apple ml-explore, MIT) — Servicio de inferencia de embeddings local (mlx_lm.server, API compatible con OpenAI)

• uv (Astral, MIT) — Gestión de paquetes de Python

Licencia

MIT © Sovena contributors, Instituto de Antropología del Arte de la Universidad del Suroeste, Instituto de Salud Mental Musical de China de la Universidad del Suroeste; autor: Shi Fengkai (sfklc@hotmail.com)