百乐餐
个人知识数据库MCP服务器 -使用Google Takeout、GDPR导出等对您的AI助手进行个性化设置。
\[！警告\] 该项目正在积极开发中。尚未准备好用于生产。
概述
Potluck是一个隐私优先的个人知识管理系统，它：
- 摄入 来自Google Takeout、Reddit GDPR导出、WhatsApp、YNAB等的数据
- 重复数据删除 对媒体使用感知哈希，对文本使用内容哈希
- 链接 通过时间、空间和语义关系跨源实体
- 暴露 通过模型上下文协议（MCP）将数据传输到LLM
- 保持 所有数据本地-没有用于嵌入或处理的外部API调用
特性
- 源不可知实体：聊天消息模型适用于WhatsApp、Telegram、SMS等。
- 混合搜索：将PostgreSQL全文搜索（关键字）与pgvector相似性（语义）相结合
- 人脸识别：通过自动聚类将照片链接到人（谷歌照片风格）
- 图像字幕：AI为图像生成alt文本描述
- 多个嵌入：支持每个实体的不同嵌入类型（文本、多模式）
- 网页用户界面：通过FastAPI+HTMX接口查看、搜索和管理您的数据
技术栈
- Python 3.12+ 使用FastAPI、SQLModel、Celery
- PostgreSQL 带有pgvector和pg_tde加密的（Percona风味）
- e5-small-v2 用于文本嵌入（通过句子转换）
- SigLIP 用于多模态嵌入（文本到图像搜索）
- EasyOCR 用于图像文本提取
- MTCNN+ArcFace 用于人脸检测和嵌入
- BLIP-2 用于AI图像字幕
- Docker Compose 便于部署
安装
快速安装（推荐）
只需一个命令即可安装并运行Potluck：
curl -fsSL https://raw.githubusercontent.com/DoubleGremlin181/potluck/main/scripts/install.sh | bash这将：
- 创建
~/.potluck/包含所有配置文件 - 生成安全的数据库凭据
- 拉取并启动所有Docker容器
- 运行数据库迁移
- 打印Claude Desktop的MCP配置
支持GPU （需要NVIDIA GPU+NVIDIA容器工具包）：
curl -fsSL https://raw.githubusercontent.com/DoubleGremlin181/potluck/main/scripts/install.sh | bash -s -- --gpu安装后：
- 网页用户界面: http://localhost:8000
- 日志:
cd ~/.potluck && docker compose logs -f - 停止:
cd ~/.potluck && docker compose down
开发设置
对于想要修改代码的贡献者：
git clone https://github.com/DoubleGremlin181/potluck.git
cd potluck
./scripts/setup.sh # Start all services
# or
./scripts/setup.sh --db-only # Start only DB, run app locally with: uv run potluck web密钥管理
Potluck使用 pg_tde 用于透明数据加密。所有数据库表都是静态加密的。
开发（基于文件的密钥）
默认情况下，加密密钥存储在本地文件中。这是 仅适用于开发:
# Default setup uses file-based keys
./scripts/setup.sh您将看到一个警告：
⚠️ SECURITY WARNING: Using file-based encryption keys生产（HashiCorp保险库）
对于生产，配置 HashiCorp 保险库 作为密钥提供者：
- 设置保险库 使用KV v2 secrets引擎：
# Enable KV v2 secrets engine (if not already enabled)
vault secrets enable -path=secret kv-v2- 配置Potluck 使用Vault凭据：
# Option 1: Interactive setup
./scripts/setup.sh
# When prompted, enter your Vault URL and token
# Option 2: Manual configuration in .env
VAULT_URL=https://vault.example.com:8200
VAULT_TOKEN=your-vault-token
VAULT_MOUNT=secret- 重新开始 （切换密钥提供者时需要）：
docker compose down -v
./scripts/setup.sh其他关键管理系统
pg_tde还支持KMIP兼容的KMS提供商（AWS KMS、Azure密钥库等）。请参阅 pg_tde文档 有关配置详细信息。
测试
所有测试都在Docker中运行，以确保本地开发和CI之间的一致性。
# Run all tests
docker compose --profile test run --rm test
# Run specific test file
docker compose --profile test run --rm test uv run pytest tests/unit/models/ -v
# Run with e2e tests (database integration)
docker compose --profile test run --rm test uv run pytest tests/ -v --run-e2eGitHub Actions使用与 test 轮廓。
测试验证：
- Docker容器正确启动（使用pgvector+pg_tde的Percona PostgreSQL 17）
- PostgreSQL扩展已安装（vector、pg_tde、uuid ossp）
- 所有表都是在启用pg_tde加密的情况下创建的
- Alembic迁移成功运行
- 机器学习处理（OCR、人脸检测、字幕）工作正常
用法
MCP服务器（用于克劳德桌面）
添加到您的Claude桌面配置(claude_desktop_config.json):
{
"mcpServers": {
"potluck": {
"command": "docker",
"args": ["exec", "-i", "potluck-app", "potluck", "mcp"]
}
}
}安装脚本会自动打印此配置。
网页用户界面
访问http://localhost:8000安装后。
项目结构
potluck/
├── src/potluck/
│ ├── core/ # Config, logging, Celery, exceptions
│ ├── models/ # SQLModel entities
│ ├── pipeline/ # Ingestion + processing pipeline
│ │ ├── ingestion/ # Source-specific data importers
│ │ ├── processing/# OCR, hashing, faces, captioning
│ │ ├── tasks/ # Celery background tasks
│ │ └── utils/ # Archive extraction, parsers
│ ├── embeddings/ # Embedding providers
│ ├── search/ # Hybrid search implementation
│ ├── linkers/ # Entity relationship detection
│ ├── mcp/ # MCP server and tools
│ ├── web/ # FastAPI + HTMX web UI
│ └── db/ # Database session management
├── alembic/ # Database migrations
├── tests/ # Unit and integration tests
├── scripts/ # Setup and utility scripts
└── docker/ # Dockerfiles for app and database许可证
MIT许可证-请参阅 许可证 了解详情。