icey1287/SuperMew

SuperMew – 可审计的 RAG 优先智能体平台

简介 – SuperMew 是一个自托管的 AI 智能体框架，它将每次用户交互视为持久且可重放的工作流，而非一次性的 HTTP 调用。它将对话线程、运行（Runs）、事件和检查点串联起来，使得聊天可以暂停以供人在回路（HITL）审查，稍后恢复，并完全审计。

核心理念

• 持久化领域对象 – Thread、Message、Run、Event、Checkpoint、DocumentVersion 存储在 PostgreSQL（元数据）和 Milvus（向量块）中。这允许您重放或调试任何过去的交互。
• 两阶段文档发布 – 新的文档版本在隔离的候选作用域中构建，经过验证后，通过 PostgreSQL CAS 操作原子性地切换。正在进行的查询永远不会看到半成品的索引。
• 混合 RAG 管道 – 密集向量搜索（Milvus）+ 原生 BM25 通过倒数排名融合（Reciprocal Rank Fusion）融合，可选地重新排序，判断证据质量，并可以回退到单个 HyDE 或步骤回退重写。所有中间步骤都记录在 UI 可视化的 rag_trace 中。
• 技能/工具注册表 – 固定版本的技能（知识库查找、天气、只读 SQL、网络研究、沙箱代码执行、受限 HTTPS JSON）在注册表中声明。每个工具的架构仅在运行的权限检查后向智能体披露，并且护栏强制执行允许/拒绝/批准策略。
• 模型控制平面 – 管理员定义模型配置文件（无秘密信息）并将其分配给四个角色：Answer、Fast、Grader、Evaluator。当创建 Run 或评估作业时，确切的模型快照被冻结，保证可重现性。
• RAG 评估框架 – 版本化数据集、基线比较、CI 门控式质量检查和持久评估工作程序允许您自动测量正确性、有据性、相关性、完整性、不支持的主张和冲突披露。
• 安全与认证 – 短生命周期的内存访问令牌、存储在 HttpOnly Cookie 中的轮换不透明刷新令牌、RBAC、每端点速率限制 HMAC、CSP/标头，以及带有 AST 和 RLS 检查的只读 SQL 沙箱。

为什么重要 – 通过持久化每一步，SuperMew 使得以下成为可能：

1. 审计 确切地哪些文档、工具和模型输出产生了响应。
2. 恢复 在人工审查者添加澄清后暂停的对话。
3. 版本控制 知识库和模型配置，而不破坏现有的运行。
4. 基准测试 在类似生产的环境中端到端测试 RAG 管道。

---

架构概览

组件	技术	角色
API 服务器	FastAPI (Python 3.12)	HTTP、SSE、认证、线程/运行编排、静态前端服务
索引工作程序	Python 模块 backend.workers.indexing	构建不可变的文档版本，写入 Milvus 向量，管理候选作用域
RAG 评估工作程序	Python 模块 backend.workers.evaluation	执行离线评估作业，计算指标，存储结果
向量存储	Milvus (密集 + 原生 BM25)	快速最近邻检索
元数据存储	PostgreSQL + SQLAlchemy + Alembic	线程、运行、事件、模型快照、文档目录
缓存 / 低延迟通知	Redis	事件推送、速率限制计数器
对象存储	MinIO (由工作程序使用)	上传的原始文档
前端	Vite + Vue 3 + TypeScript + Pinia	聊天、技能中心、管理面板、评估工作台 UI

---

开始使用（本地开发）

1. 先决条件 – Python 3.12+、uv 包管理器、Node 20+、Docker Compose。
2. 配置 – 将 .env.example 复制为 .env 并填写：
   • 模型标识符 (MODEL、FAST_MODEL、…)
   • JWT_SECRET_KEY (≥32 个随机字符)
   • 可选的管理员邀请码。
3. 启动依赖项 – docker compose up -d (Postgres, Redis, etcd, MinIO, Milvus, Attu)。
4. 安装 Python 依赖项 – uv sync --frozen。
5. 构建前端 – cd frontend && npm ci && npm run build && cd ..。
6. 运行迁移和健全性检查 –

   uv run --frozen alembic upgrade head
   uv run --frozen python -m backend.tools.registry_cli validate
   

7. 启动三个进程 – ./scripts/start.sh (API, 索引工作程序, 评估工作程序)。使用 --no-reload 禁用热重载。
8. 打开 http://127.0.0.1:8000/ 访问 UI，http://127.0.0.1:8000/docs 访问 OpenAPI，http://127.0.0.1:8080/ 访问 Milvus Attu。

---

生产环境检查清单（摘要）

• 在监督程序（systemd, k8s 等）下部署相同的三个服务（API, 索引工作程序, 评估工作程序），确保它们共享相同的代码版本和 UPLOAD_DIR。
• 设置 APP_ENV=production 并提供 JWT、速率限制 HMAC、数据库密码和模型提供商密钥的真实秘密信息。
• 启用安全 Cookie (AUTH_REFRESH_COOKIE_SECURE=true)。
• 在 API 之前启动工作程序，运行健康检查，然后在公开公共端点之前执行最小端到端测试（创建线程、上传文档、运行 RAG 查询、启动小型评估作业）。
• 定期运行清理任务 python -m backend.auth.cleanup 以修剪过期的刷新令牌账本。

---

典型用例

用例	SuperMew 如何帮助
企业知识库问答	上传 PDF/文档，对其进行版本控制，并让智能体通过混合搜索检索，同时保留审计跟踪。
人在回路支持	在 Checkpoint 处暂停运行，让审查者编辑或批准工具调用，然后在不丢失上下文的情况下恢复。
受监管环境	带有严格允许列表、沙箱代码执行和策略驱动的工具护栏的只读 SQL 助手满足合规需求。
模型/RAG 基准测试	定义数据集，运行评估工作程序，与基线进行比较，并根据质量指标门控发布。
自定义技能集成	通过注册表添加新的 HTTP-JSON 工具或特定领域的技能；平台自动处理版本控制、权限检查和 UI 暴露。

---

长话短说

SuperMew 是一个全栈开源平台，用于构建依赖检索增强生成（RAG）的生产级 AI 智能体。它强调持久性、可审计性、人在回路控制和安全的版本化工具。如果您需要一个自托管的 RAG 系统，其中每一步都可以检查、重放或门控，SuperMew 提供了完整的堆栈——从基于 PostgreSQL 的事件溯源到基于 Vue 的 UI 和强大的评估框架。