Readwise Vector Db

Readwise矢量数据库-自助托管您的阅读亮点搜索

  

将Readwise库变成一个超快的语义搜索引擎 –包括夜间同步、矢量搜索API、Prometheus指标，以及用于LLM客户端的流式MCP服务器。

______________________________________________________________________

目录

• Readwise矢量数据库-自助托管您的阅读亮点搜索

- 目录 - 快速开始 - 使用Supabase Cloud - 通过3个命令部署到Vercel - 为什么在无服务器中为MCP提供SSE？ - 详细设置 - 先决条件 - 环境变量 - 数据库和迁移 - 同步命令（CLI） - 使用示例 - 矢量搜索（HTTP API） - 流媒体搜索（HTTP SSE） - 流媒体搜索（MCP TCP） - 架构概述 - - Vercel+Supabase（云） - 发展与贡献 - 维护人员注意事项 - 许可证和信用证

______________________________________________________________________

快速开始

# ❶ Clone & install
git clone https://github.com/leonardsellem/readwise-vector-db.git
cd readwise-vector-db
poetry install --sync

# ❷ Boot DB & run the API (localhost:8000)
docker compose up -d db
poetry run uvicorn readwise_vector_db.api:app --reload

# ❸ Verify
curl http://127.0.0.1:8000/health     # → {"status":"ok"}
open http://127.0.0.1:8000/docs       # interactive swagger UI

提示： 代码空间用户？点击“运行→ 步骤后在浏览器中打开❷.

______________________________________________________________________

使用Supabase Cloud

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

# ❶ Create Supabase project at https://supabase.com/dashboard
# ❷ Enable pgvector extension in SQL Editor:
#   CREATE EXTENSION IF NOT EXISTS vector;

# ❸ Set up environment
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-...

# ❹ Run migrations and start the API
poetry run alembic upgrade head
poetry run uvicorn readwise_vector_db.api:app --reload

# ❺ Initial sync
poetry run rwv sync --backfill

⚠️ 快速失败行为： 申请将提高 ValueError 启动后立即 SUPABASE_DB_URL 缺失时 DB_BACKEND=supabase.

所需的环境变量：

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

优点：

• ✅ 无需Docker设置
• ✅ 管理备份和扩展
• ✅ 内置pgvector支持
• ✅ 全球边缘网络
• ✅ SSE流媒体优化 –连接池和低于100ms的查询延迟

______________________________________________________________________

通过3个命令部署到Vercel

使用Supabase后端将FastAPI应用程序部署为无服务器功能：

# ❶ Set up Vercel project
npm install -g vercel
vercel login
vercel link  # or vercel --confirm for new project

# ❶ Configure environment variables in Vercel dashboard or CLI:
vercel env add SUPABASE_DB_URL
vercel env add READWISE_TOKEN
vercel env add OPENAI_API_KEY

# ❸ Deploy
vercel --prod

自动配置：

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

资源限制：

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

SSE流媒体支持：

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

GitHub集成：

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

💡 专业提示： 使用 vercel --prebuilt 以实现更快的后续部署。

为什么在无服务器中为MCP提供SSE？

传统的TCP MCP服务器无法在无服务器环境中工作 因为它们需要持久连接。这 基于HTTP的MCP服务器，具有服务器发送事件（SSE） 通过提供以下内容来解决这个问题：

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

📚 全面部署指南： 看 docs/deployment-sse.md 有关详细的平台特定说明、故障排除和性能调优。

______________________________________________________________________

详细设置

先决条件

• Python 3.12 | 诗歌≥1.8 | Docker+作曲

环境变量

创建 .env （参见 .env.example)–最小值：

READWISE_TOKEN=xxxx     # get from 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）

# first-time full sync
poetry run rwv sync --backfill

# daily incremental (fetch since yesterday)
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": "Large Language Models",
           "k": 10,
           "filters": {
             "source": "kindle",
             "tags": ["ai", "research"],
             "highlighted_at": ["2024-01-01", "2024-12-31"]
           }
         }'

流媒体搜索（HTTP SSE）

# Real-time streaming via Server-Sent Events (serverless-friendly)
curl -N -H "Accept: text/event-stream" \
  "http://127.0.0.1:8000/mcp/stream?q=neural+networks&k=10"

流媒体搜索（MCP TCP）

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

# then from another shell
printf '{"jsonrpc":"2.0","id":1,"method":"search","params":{"q":"neural networks"}}\n' | \
  nc 127.0.0.1 8375

💡 新 看看 SSE使用指南 JavaScript、Python和浏览器示例！

______________________________________________________________________

架构概述

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

Architecture Diagram

Docker+本地PostgreSQL（默认）

flowchart TB
  subgraph "🐳 Docker Deployment"
    subgraph Ingestion
      A[Readwise API] --> B[Backfill Job]
      C[Nightly Cron] --> D[Incremental Job]
    end
    B --> E[OpenAI Embeddings]
    D --> E
    E --> F[Local PostgreSQL + pgvector]
    F --> G[FastAPI Container]
    G --> H[MCP Server :8375]
    G --> I[Prometheus /metrics]
  end

Vercel+Supabase（云）

flowchart TB
  subgraph Serverless_Deployment
    subgraph Vercel_Edge
      J[FastAPI Serverless]
      K[/health endpoint/]
      L[/search endpoint/]
      M[/docs Swagger UI/]
      J --> K
      J --> L
      J --> M
    end
    subgraph Supabase_Cloud
      N[Managed PostgreSQL]
      O[pgvector Extension]
      P[Automated Backups]
      N --> O
      P --> N
    end
    J -.-> N
    Q[GitHub Actions]
    R[Auto Deploy on Tags]
    Q --> R
    R --> J
  end

主要区别：

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

文档：

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

______________________________________________________________________

发展与贡献

1. 环境

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

1. 运行测试和覆盖率

   poetry run coverage run -m pytest && coverage report

1. 性能检查 (make perf)–如果失败 /search P95＞500毫秒。
2. 分支模型：feature/xyz→ PR → 壁球合并。使用常规承诺(feat:, fix: …).
3. 编码风格：参见 .editorconfig 以及加强过梁。

看 贡献.md 获取完整指南。

______________________________________________________________________

维护人员注意事项

• CI/CD – .github/workflows/ci.yml 运行lint、类型检查、测试（Py 3.11+3.12）并将图像发布到GHCR。
• 备份 – pg_dump 每周cron将压缩转储作为工件上传(Goal G4).
• 释放 –凹凸版本 pyproject.toml，跑 make release.

______________________________________________________________________

许可证和信用证

*根据MIT许可证许可的代码。* 由...制作❤️ 由社区提供动力 快速API, SQL模型, pg载体, 开放人工智能 和 任务管理员AI.