Hindsight Setup

后见之明设置（macOS优先）

macOS本地HindSight构建：API和模型在本地Python中运行。 啊 docker-compose 仅用于PostgreSQL+PgVector。

为什么不是Full Docker

• 在MacOS上，Docker Desktop中没有CUDA/MPS的正常通行证。
• 因此，容器内的Embeddings/ReRanker性能明显较差。
• 最佳路径：本地Python进程（hindsight-api)+Postgres-Docker。

建筑

┌──────────────────────────────────────────┐
│ macOS host                               │
│  - hindsight-api (Python venv)           │
│  - local embeddings/reranker (MPS/CPU)   │
│  - UI via npx (optional)                 │
└───────────────────────┬──────────────────┘
                        │ localhost:5432
┌───────────────────────▼──────────────────┐
│ docker-compose                            │
│  - postgres (pgvector)                    │
└───────────────────────────────────────────┘

docker-compose.yaml 此存储库仅包含 postgres.

快速启动

cp .env.example .env
# заполни минимум: HINDSIGHT_API_LLM_BASE_URL, HINDSIGHT_API_LLM_API_KEY

make install
make start
curl http://localhost:8888/health

发射后：

• API http://localhost:8888
• UI： http://localhost:9999

要求

• macOS（此版本的主要目标）
• Docker 桌面版
• uv
• Node.js（仅限UI，如果需要）

主要命令

• make start -提升Postgres、API和UI
• make stop 停止API和UI
• make stop-all 停止一切，包括Postgres
• make status 显示服务状态
• make logs 查看API/UI日志
• make health 健康检查API

配置

变量模板： .env.example.

重要的是：

• .env 被Git忽略
• 仅对存储库发表评论 .env.example
• localhost上的默认DB URL： postgresql://hindsight:@localhost:5432/hindsight_db

故障排除

API无法启动

• 检查日志： make logs
• 检查健康： make health
• 确保 .env 由 .env.example

数据库连接错误

• 确保postgres被举起： docker compose ps
• 重新启动Postgres： docker compose up -d postgres

UI不会上升

• 安装Node.js npx)
• 或者只使用API，UI不是必需的

贡献/安全

• 贡献指南： CONTRIBUTING.md
• 安全策略： .github/SECURITY.md