Obsidian2Vector

将 Obsidian 笔记库转换为向量数据库，支持 Milvus/Chroma，并提供 MCP Server 接口。

功能特性

• 📄 Obsidian 解析 - 解析 Vault 中的 Markdown 文件，提取 frontmatter、tags、wiki links
• 🔢 向量嵌入 - 支持多种嵌入模型 (BGE, Qwen3-Embedding)
• 🗄️ 多数据库支持 - Milvus / Chroma 向量数据库
• 🌐 REST API - FastAPI 搜索接口
• 🤖 MCP Server - Model Context Protocol 服务器，支持 AI 助手直接调用
• 🇨🇳 中文优化 - 完美支持中文笔记语义搜索、标签过滤、Wiki链接检索

支持的嵌入模型

所有模型均针对中文语义理解优化:

快速开始

1. 安装

# 核心包（索引 + 搜索 API）
pip install obsidian2vector

# MCP Server（可选，依赖核心包自动安装）
pip install obsidian2vector-mcp

2. 配置

首次运行时自动在用户目录下生成配置文件：

编辑该文件：

{
  "vault_path": "/path/to/your/obsidian/vault",
  "embedding_model": "BAAI/bge-small-zh-v1.5",
  "db_type": "chroma",
  "chroma_path": "~/.obsidian2vector/chroma_db",
  "chroma_collection": "obsidian_notes"
}

<details> <summary>完整配置项</summary>

</details>

环境变量仍可使用，优先级高于 settings.json：VAULT_PATH、DB_TYPE、MILVUS_HOST 等。

3. 索引笔记

obsidian2vector-index

根据 db_type 配置自动选择 Milvus 或 Chroma。

4. 搜索

REST API：

obsidian2vector-search

根据 db_type 配置自动选择 Milvus 或 Chroma。

API 地址: http://localhost:8000

curl -X POST http://localhost:8000/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "论文", "top_k": 5}'

参数: query（搜索文本）、top_k（结果数）、tags（标签过滤，可选）、links（链接过滤，可选）

获取所有标签 / 链接

curl http://localhost:8000/tags
curl http://localhost:8000/links

MCP Server

供 Claude Desktop 等 AI 助手直接调用。

启动

obsidian2vector-mcp

Claude Desktop 配置

在 ~/.config/Claude/claude_desktop_config.json 中添加:

{
  "mcpServers": {
    "obsidian-search": {
      "command": "obsidian2vector-mcp"
    }
  }
}

MCP 工具

Milvus 环境配置

1. 安装 Docker Desktop

macOS (使用 Homebrew):

brew install --cask docker

启动 Docker Desktop 并确保其运行正常。

2. 使用 Docker Compose 启动 Milvus

创建 docker-compose.yml:

version: '3'
services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.5
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - ./etcd:/etcd
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd

  minio:
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    volumes:
      - ./minio:/minio_data
    command: minio server /minio_data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/liveness"]
      interval: 30s
      timeout: 20s
      retries: 3

  milvus:
    image: milvusdb/milvus:v2.4.0
    command: ["milvus", "run", "standalone"]
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ./milvus:/var/lib/milvus
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - etcd
      - minio

启动服务:

docker compose up -d

3. 配置

编辑 ~/.obsidian2vector/settings.json，设置 db_type 为 milvus 并填写连接信息。

4. 常用 Docker 命令

docker compose logs -f milvus    # 查看日志
docker compose down               # 停止服务
docker compose down -v            # 删除数据(重置)

Chroma 快速开始

Chroma 无需额外服务。在 settings.json 中设置 db_type 为 chroma，然后直接索引即可：

obsidian2vector-index

许可证

MIT