진윈원차이 Sovena

English | 简体中文

Zotero → Markdown 의미 문헌 패키지 → 벡터 검색: 각 학문 분야의 학술 연구를 위한 로컬 문헌 처리 시스템(인문, 사회, 이공, 의학 등 스캔/복사 자료가 많은 분야에서 특히 유용)이며, MCP(Model Context Protocol) 서비스 형태로 모든 로컬/원격 AI 클라이언트에 노출됩니다.

「진윈(缙云)」은 베이베이(北碚) 진윈산(缙云山)——서남대학 소재지에서 따왔습니다. 「원차이(文采)」는 두 가지 뜻을 담고 있습니다: 문헌의 정수를 **채집(采撷)**한다는 뜻과, 문장의 화려한 **문채(文采)**라는 뜻입니다. 「먼 옛날의 꽃을 채집하여, 우리의 꿀을 양조하리라.」——우미(吴宓, 서남대학에서 28년간 교편을 잡음)

활용 시나리오

• 문헌 종합 및 집필: Zotero의 문헌(영인 고서, 스캔 PDF 포함)을 일괄적으로 책 페이지 번호가 포함된 Markdown으로 변환하여, AI 클라이언트가 인용 시 페이지까지 정확하게 출처를 추적할 수 있음

• 교차 라이브러리 의미 검색: 수백 편의 문헌에 자연어로 질문(예: 「음색의 음향 측정 방법에는 어떤 것이 있나」)하여, 한 편씩 키워드를 찾지 않아도 됨

• 고서/영인본 디지털화: 스캔 PDF는 자동으로 OCR 채널을 거쳐 제목, 표, 2단 레이아웃을 구조화된 텍스트로 복원

• 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, 또는 Bailian / OpenRouter 등 원격 플랫폼) + LanceDB 로컬 벡터 라이브러리

OCR 엔진 및 모델 배포

sovena의 OCR 채널은 Unlimited-OCR(바이두 오픈소스, MIT 라이선스, 모델 가중치는 HuggingFace baidu/Unlimited-OCR)을 사용합니다: DeepSeek-V2 MoE 디코더 + SAM/CLIP 이중 비전 타워의 문서 OCR 모델로, 다중 페이지 스캔 문서를 전체 인식하고 제목/표/레이아웃을 복원할 수 있습니다.

두 가지 백엔드를 지원하며, 출력은 동일한 구조화 형식이므로 다운스트림 변환에는 차이가 없습니다:

백엔드 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(임의 컴퓨터, 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 설정)

• 원격 상용 플랫폼(로컬에서 모델 실행을 원하지 않을 때): 알리바바 클라우드 Bailian / 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 백엔드 사용(위 「백엔드 2」 참조). 전체 과정은 복사-붙여넣기 명령만 하면 됩니다.

1단계: uv 설치(Python 패키지 관리자, 1회)

「터미널」을 열고(런치패드에서 「터미널」 또는 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 호환 솔루션도 동일

• 원격 플랫폼(로컬에서 모델 실행 안 함): 알리바바 클라우드 Bailian / OpenRouter 등, 프로젝트 루트에 .env를 만들어 주소와 키 입력(위 「Embedding 서비스」 예시 참조)

OCR 모델(스캔 문서만 필요, Apple Silicon): HuggingFace에서 Unlimited-OCR-MLX를 ~/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 문서 변환, 검색 등 핵심 기능과 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 기여자들, 서남대학교·예술인류학연구소, 서남대학교·중국음악심리건강연구소; 저자: 스펑카이(sfklc@hotmail.com)