STARWARCLOUD STARWAR.AI
返回市场
读慧向量数据库

读慧向量数据库

作者：leonardsellem24 星标更新：2025-07-28
安装使用来源：spider==github.com

项目介绍

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

构建 覆盖率状态 许可证：MIT

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

目录

快速开始

# ❶ 克隆并安装
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进行开发 → 生产一致性

文档:

开发与贡献

  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提供支持。