企业级知识库 Agent
面向生产架构的多租户企业知识问答系统，将身份、权限、可靠摄取、混合检索与可验证引用收敛为完整闭环。
企业级多租户RAGAI AgentPythonFastAPIPostgreSQLpgvectorOpenSearchRedis StreamsMinIOKeycloakDocling企业项目
1 / 2
- 3
- 独立扩缩容进程
- 2 路
- 混合检索召回
- 2 层
- 租户隔离防线
- 1024 维
- 向量索引契约
ENGINEERING HIGHLIGHTS
难点与亮点
权限进入检索内核
JWT、租户成员、知识库 ACL 与 PostgreSQL RLS 共同限定召回范围，候选 Chunk 进入 Prompt 前再次鉴权。
可恢复的异步摄取
Transactional Outbox、Redis Consumer Group 与数据库任务租约协作，覆盖重复投递、Worker 崩溃、重试和死信。
结构感知知识加工
保留页码、标题层级和表格语义，按 Token 预算切片；Embedding 数量、顺序、维度与有限值均有契约校验。
答案必须可追溯
pgvector 与 BM25 经 RRF 融合、可选重排，再执行时效过滤、上下文预算与引用白名单校验。
项目定位
这不是把文件塞进向量库后直接调用大模型的问答 Demo，而是一套围绕 多租户安全、数据一致性、任务可靠性与答案可验证性 设计的企业知识基础设施。系统支持 PDF、DOCX、Markdown、TXT 与 HTML 摄取，并通过 API 和飞书机器人复用同一套权限与检索链路。
系统架构
系统拆成可独立部署和扩缩容的 API、Outbox Dispatcher、Ingestion Worker 三类进程，并把数据分为权威数据与可重建派生索引：
| 层级 | 核心职责 | 关键设计 |
|---|---|---|
| 接入与安全 | FastAPI、OIDC/JWT、租户成员、知识库 ACL、用户级限流 | 应用查询显式携带 tenant_id，PostgreSQL RLS 在事务层兜底 |
| 可靠摄取 | 不可变原文、任务编排、解析、切片、Embedding、版本发布 | Outbox 保证任务不因跨系统双写而丢失；Redis Pending 与数据库租约支持崩溃接管 |
| 检索与生成 | pgvector 语义召回、OpenSearch BM25、RRF、可选 Rerank、LLM | 检索前收窄权限，Prompt 前二次鉴权，生成后校验引用白名单 |
| 数据与运维 | PostgreSQL、MinIO、OpenSearch、Redis、Prometheus | PostgreSQL 与 MinIO 保存权威数据；OpenSearch 可从 PostgreSQL 全量重建 |
文档摄取链路
- 上传阶段同时校验扩展名、MIME、文件签名、大小与 SHA-256；对象键由服务端生成，原文以不可变对象写入 MinIO。
- 文档版本、摄取任务和 Outbox 事件在同一 PostgreSQL 事务提交；Dispatcher 再以至少一次语义投递到 Redis Streams。
- Worker 通过 Consumer Group 与数据库租约领取任务，持续心跳；崩溃后可由其他实例接管，瞬时故障指数退避，毒消息进入 DLQ。
- Docling / OCR 保留 PDF 阅读顺序、页码、标题和表格结构；超长语义块才按 Token 预算切分，并保留受控 overlap。
- 新版本完成 pgvector 与 OpenSearch 写入后才原子发布；失败期间旧版本继续提供查询，不暴露半成品索引。
带引用问答链路
- 先根据当前租户身份与知识库 ACL 得到可检索范围，再并行执行 pgvector 语义召回和 OpenSearch BM25 关键词召回。
- 使用 RRF 按排名稳定融合两路结果；Reranker 仅作为质量增强，异常时可降级而不阻断主链路。
- 候选 Chunk 回到 PostgreSQL 做权限与发布状态复核，再按上下文 Token 预算组装 Prompt，并把文档内容视为不可信输入以隔离 Prompt Injection。
- LLM 只允许引用本次上下文中的 citation_id；返回前校验引用存在性与白名单，因此系统选择完整 JSON 响应，不提前流出未经验证的 Token。
关键工程取舍
- 权威数据单向派生：PostgreSQL 保存业务数据、Chunk 与向量，MinIO 保存原文；OpenSearch 损坏后重建，不允许反向覆盖权威数据。
- 至少一次而非伪“精确一次”：承认消息可能重复，通过幂等键、请求指纹、确定性 Chunk ID 与终态检查让重放安全。
- 跨存储显式补偿：MinIO 与 PostgreSQL 无法共享事务，数据库失败或请求取消时执行对象清理，缩小孤儿文件窗口。
- 版本原子切换：新版本完全就绪后再归档旧版本，保证摄取过程中的查询连续性。
质量与可运维性
项目提供 Alembic 迁移、Ruff、mypy strict、pytest、集成测试、JSONL 回归评测、Prometheus 指标、结构化日志、Request ID、存活/就绪探针，以及从 PostgreSQL 重建 OpenSearch 的运维命令。