Readwise Vector DB – 自托管阅读亮点搜索

将您的Readwise库转化为一个快速的语义搜索引擎 – 包括夜间同步、向量搜索API、Prometheus指标以及面向LLM客户端的流式MCP服务器。

---

目录

• Readwise Vector DB – 自托管阅读亮点搜索
  • 目录
  • 快速开始
  • 使用Supabase云
  • 通过3个命令部署到Vercel
    • 为什么在无服务器中使用SSE作为MCP？
  • 详细设置
    • 前提条件
    • 环境变量
    • 数据库与迁移
    • 同步命令（CLI）
  • 使用示例
    • 向量搜索（HTTP API）
    • 流式搜索（HTTP SSE）
    • 流式搜索（MCP TCP）
  • 架构概述
    • Docker + 本地PostgreSQL（默认）
    • Vercel + Supabase（云）
  • 开发与贡献
  • 维护者笔记
  • 许可证与致谢

---

快速开始

# ❶ 克隆并安装
git clone https://github.com/leonardsellem/readwise-vector-db.git
cd readwise-vector-db
poetry install --sync

# ❷ 启动数据库并运行API（localhost:8000）
docker compose up -d db
poetry run uvicorn readwise_vector_db.api:app --reload

# ❸ 验证
curl http://127.0.0.1:8000/health     # → {"status":"ok"}
open http://127.0.0.1:8000/docs       # 交互式的Swagger UI

提示: 使用Codespaces用户？在步骤❷后点击“运行 → 在浏览器中打开”。

---

使用Supabase云

跳过本地Docker设置，并使用支持pgvector的托管PostgreSQL：

# ❶ 在https://supabase.com/dashboard创建Supabase项目
# ❷ 在SQL编辑器中启用pgvector扩展：
#   CREATE EXTENSION IF NOT EXISTS vector;

# ❸ 设置环境
export DB_BACKEND=supabase
export SUPABASE_DB_URL="postgresql://postgres:[password]@db.[project].supabase.co:6543/postgres?options=project%3D[project]"
export READWISE_TOKEN=xxxx
export OPENAI_API_KEY=sk-...

# ❹ 运行迁移并启动API
poetry run alembic upgrade head
poetry run uvicorn readwise_vector_db.api:app --reload

# ❺ 初始同步
poetry run rwv sync --backfill

⚠️ 快速失败行为: 如果在启动时DB_BACKEND=supabase且缺少SUPABASE_DB_URL，应用程序会立即抛出ValueError。

所需环境变量:

• DB_BACKEND=supabase – 从本地Docker切换到Supabase
• SUPABASE_DB_URL – 来自Supabase仪表板的完整PostgreSQL连接字符串
• 标准变量: READWISE_TOKEN, OPENAI_API_KEY

优点:

• ✅ 不需要Docker设置
• ✅ 托管备份和扩展
• ✅ 内置pgvector支持
• ✅ 全球边缘网络
• ✅ 优化的SSE流式传输 – 连接池和低于100毫秒的查询延迟

---

通过3个命令部署到Vercel

将FastAPI应用作为具有Supabase后端的无服务器函数进行部署：

# ❶ 设置Vercel项目
npm install -g vercel
vercel login
vercel link  # 或对于新项目使用vercel --confirm

# ❶ 在Vercel仪表板或CLI中配置环境变量：
vercel env add SUPABASE_DB_URL
vercel env add READWISE_TOKEN
vercel env add OPENAI_API_KEY

# ❸ 部署
vercel --prod

自动配置:

• DEPLOY_TARGET=vercel – 由Vercel环境自动设置
• DB_BACKEND=supabase – 在vercel.json中预配置
• 构建过程使用优化的vercel_build.sh脚本

资源限制:

• ⏱️ 构建超时: 90秒
• 💾 构建期间内存限制: 1024MB
• 🚀 函数超时: 每次请求30秒

SSE流式传输支持:

• ✅ 基于HTTP的MCP服务器 – /mcp/stream端点无缝工作
• ✅ 实时搜索结果 – 用于流式响应的服务器发送事件
• ✅ 冷启动优化 – 少于1秒的初始化，自动扩展连接
• ✅ HTTP/2多路复用 – 每个客户端无限并发连接

GitHub集成:

• 标记的发布（v*.*.*）自动部署到生产环境
• 拉取请求创建预览部署
• CI验证Docker和Vercel构建

💡 提示: 使用vercel --prebuilt进行更快的后续部署。

为什么在无服务器中使用SSE作为MCP？

传统的TCP MCP服务器在无服务器环境中不起作用，因为它们需要持久连接。**基于HTTP的MCP服务器与服务器发送事件（SSE）**解决了这一问题，提供：

特性	TCP MCP服务器	HTTP SSE MCP服务器
无服务器支持	❌ 需要持久连接	✅ 在Vercel、Lambda等上工作
防火墙/代理	⚠️ 可能需要自定义端口	✅ 标准HTTP/HTTPS（80/443）
浏览器支持	❌ 没有原生支持	✅ 内置EventSource API
自动扩展	⚠️ 受限于连接池	✅ 通过HTTP基础设施无限扩展
冷启动	❌ 在重启期间连接丢失	✅ 无状态，自动重新连接
HTTP/2优势	❌ 不适用	✅ 多路复用，头部压缩

使用SSE端点进行云平台上的生产部署。TCP服务器仍然可用于本地开发和专用服务器部署。

📚 全面部署指南: 查看docs/deployment-sse.md以获取详细的平台特定指令、故障排除和性能调整。

---

详细设置

前提条件

• Python 3.12 | Poetry ≥ 1.8 | Docker + Compose

环境变量

创建.env（参考.env.example）– 最小配置：

READWISE_TOKEN=xxxx     # 从readwise.io/api_token获取
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql+asyncpg://rw_user:rw_pass@localhost:5432/readwise

所有变量都在docs/env.md中有详细记录。

数据库与迁移

docker compose up -d db       # Postgres 16 + pgvector
poetry run alembic upgrade head

同步命令（CLI）

# 第一次全量同步
poetry run rwv sync --backfill

# 每日增量（获取昨天以来的数据）
poetry run rwv sync --since $(date -Idate -d 'yesterday')

---

使用示例

向量搜索（HTTP API）

curl -X POST http://127.0.0.1:8000/search \
     -H 'Content-Type: application/json' \
     -d '{
           "q": "大型语言模型",
           "k": 10,
           "filters": {
             "source": "kindle",
             "tags": ["ai", "研究"],
             "highlighted_at": ["2024-01-01", "2024-12-31"]
           }
         }'

流式搜索（HTTP SSE）

# 通过服务器发送事件实现实时流式传输（适合无服务器）
curl -N -H "Accept: text/event-stream" \
  "http://127.0.0.1:8000/mcp/stream?q=神经网络&k=10"

流式搜索（MCP TCP）

poetry run python -m readwise_vector_db.mcp --host 0.0.0.0 --port 8375 &

# 然后从另一个shell
printf '{"jsonrpc":"2.0","id":1,"method":"search","params":{"q":"神经网络"}}\n' | \
  nc 127.0.0.1 8375

💡 新内容: 查看SSE使用指南以获取JavaScript、Python和浏览器示例！

---

架构概述

该系统支持多种部署模式以适应不同的基础设施需求：

Docker + 本地PostgreSQL（默认）

flowchart TB
  subgraph "🐳 Docker部署"
    subgraph Ingestion
      A[Readwise API] --> B[回填作业]
      C[夜间定时任务] --> D[增量作业]
    end
    B --> E[OpenAI嵌入]
    D --> E
    E --> F[本地PostgreSQL + pgvector]
    F --> G[FastAPI容器]
    G --> H[MCP服务器:8375]
    G --> I[Prometheus /metrics]
  end

Vercel + Supabase（云）

flowchart TB
  subgraph Serverless_Deployment
    subgraph Vercel_Edge
      J[FastAPI无服务器]
      K[/health端点/]
      L[/search端点/]
      M[/docs Swagger UI/]
      J --> K
      J --> L
      J --> M
    end
    subgraph Supabase_Cloud
      N[托管PostgreSQL]
      O[pgvector扩展]
      P[自动化备份]
      N --> O
      P --> N
    end
    J -.-> N
    Q[GitHub Actions]
    R[标签自动部署]
    Q --> R
    R --> J
  end

主要区别:

• Docker: 完全控制，本地数据，需要基础设施管理
• Vercel + Supabase: 零操作，全球边缘部署，托管扩展
• 混合: 使用Supabase与本地Docker进行开发 → 生产一致性

文档:

• 📊 架构图
• 🚀 SSE部署模式
• ⚙️ 平台特定配置

---

开发与贡献

1. 环境

   poetry install --with dev
   poetry run pre-commit install   # black, isort, ruff, mypy, markdownlint
   

2. 运行测试与覆盖率

   poetry run coverage run -m pytest && coverage report
   

3. 性能检查 (make perf) – 如果/search P95 >500 ms则失败。
4. 分支模型: feature/xyz → PR → squash-merge。使用常规提交(feat:, fix: …)。
5. 编码风格: 参见.editorconfig和强制执行的linter。

查看CONTRIBUTING.md以获取完整指南。

---

维护者笔记

• CI/CD – .github/workflows/ci.yml运行lint、类型检查、测试（Py 3.11 + 3.12），并将镜像发布到GHCR。
• 备份 – 每周pg_dump定时任务上传压缩的备份作为工件（目标G4）。
• 发布 – 在pyproject.toml中更新版本，运行make release。

---

许可证与致谢

代码根据MIT许可证授权。 由社区制作，由FastAPI、SQLModel、pgvector、OpenAI和Taskmaster-AI提供支持。