omnigraph — 知识库服务

omnigraph 是面向领域知识库的独立后端服务:把文档(PDF/Word/Markdown/图片) 转化为可检索的知识索引,并提供高质量的自研检索 API。它是从 RADAI 智能体平台 拆分出的知识库子系统,与智能体平台(radai) 通过 HTTP 协作,也可独立为任何需要"文档→知识→检索"能力的应用提供服务。

核心能力

1. 自研入库(self ingestion)

• 多格式解析:MinerU 管线解析 PDF/扫描件/图片,python-docx 解析 Word, Markdown/纯文本直读;公式/表格/图片块结构化保留
• 结构+语义混合分块:结构边界与语义边界结合,保持证据可溯源
• LLM/VLM 实体关系抽取:带质量门控与金样例校验,抽取实体/关系/媒体描述
• 七阶段事务提交:Staging 暂存 → MySQL(任务/分块/溯源)+ Milvus(向量)
  • NebulaGraph(实体关系图)+ Redis(BM25 词法索引)一致写入,崩溃可恢复
• 并发与围栏:跨进程入库租约(resource lease + fencing token), 旧 worker 不可能覆盖新 worker 的写入;失败自愈(repair worker)
• KB 生命周期:创建即建 Milvus collection 与 Nebula Space;删除时 全存储联动回收(含 MinIO 暂存对象);终态记录保留期 GC

2. 自研检索(self retrieval)— SelfDirectRetrieverV2

• 四路并行召回:实体向量(Milvus) + 关键词 BM25(Redis/HanLP)
  • chunk 向量(Milvus) + 图扩展(Nebula,无向 BFS 传导)
• 媒体检索:图片/表格/公式意图条件触发媒体向量召回,支持原图引用
• Stage-2 内容过滤:PPR / Rerank / MMR / RAW 按 KB Profile 编排 (垂直库 MMR_ONLY、轻量库 lightweight、百科 RAW)
• 深度检索:查询分解 + 全文边界裁判 + PPR 证据发现,显著提升多证据题 (详见评测报告)
• 检索 Profile:按 KB 类型(垂直领域/百科/轻量)自动选择召回路径与过滤策略

3. 知识库管理

• 知识库/文档/目录树/关键词索引的完整管理 API(admin 鉴权)
• 分片/批量文件上传,入库任务状态跟踪,失败重试
• 入库抽取 Schema(提示词模板)在线管理
• 知识图谱可视化数据接口

4. 对智能体平台的服务化接口

• 管理面:radai 反向代理透传(/api/v1/knowledge_bases|kb_documents|uploads|keywords|directories|ingestion|...)
• 检索面:X-Internal-Secret 保护的内部接口——单库检索、多库检索、 图片检索、暂存清理(契约见 docs/architecture.md)

检索效果(消融与 LightRAG 对比)

完整对比数据见 docs/evaluation-report.md。核心结论:

对比	结果
vs LightRAG 原生检索(期刊库 17 题)	自研四路 F1 0.6292 vs LightRAG 最优 naive 0.5536;CP +33%
vs LightRAG 原生(HotpotQA 多跳)	F1 +78%、Recall +72%,延迟更低
vs PathRAG(56 题困难多证据)	轻量直检综合分 0.7806 vs PathRAG 0.7625,延迟仅 1/7.8
必要种子	纯 HanLP/BM25(自研入库索引反哺)优于实体向量种子
深度检索组合	边界裁判+PPR 证据发现超可加(+0.023),Any Hit 100%

架构一览

                    ┌──────────────────────────────────────────┐
 文件上传/管理 API  │  API (FastAPI, 8086)                      │
 (radai 代理透传)──▶│  knowledge_bases/kb_documents/uploads/    │
                    │  keywords/directories/rag/...            │
                    └───────┬──────────────────────┬───────────┘
                            │                      │ X-Internal-Secret
                    ┌───────▼───────┐      ┌───────▼───────────┐
                    │ 自研入库       │      │ 自研检索 V2        │
                    │ MinerU→分块→  │      │ 四路召回→Profile   │
                    │ 抽取→七阶段提交│      │ 过滤→深度检索      │
                    └──┬────┬────┬──┘      └──┬────┬────┬─────┘
                       │    │    │            │    │    │
                 MySQL │    Milvus ── Nebula ──┘  Redis(BM25)
              (元数据/溯源) (向量)   (实体关系图)   (词法索引)
                       └──── MinIO(原始文件/暂存)

快速开始

cp .env.example .env    # 填写 MySQL/Redis/MinIO/Milvus/Nebula/LLM/MinerU 连接
make install
make init-db && make migrate
make run-api              # 知识服务 API(默认 8086,仅内网)
make run-ingest-worker    # 自研入库 worker(另一进程)

健康检查:GET /live(存活)、GET /health(数据库 + 自研检索就绪)。

目录结构

omnigraph/
  api/          HTTP 入口与知识库路由(http_server/startup/routers)
  rag/          自研检索核心(retriever_v2 四路召回 / content_filter / keywords)
  rag/ingestion/自研入库流水线(parsers/block_builder/extraction/commit_writer/storage)
  application/  检索与入库用例、内部多库检索、图片检索
  db/           SQLAlchemy 模型/CRUD/迁移(知识库域 + 共享账号表)
  storage/      MinIO 客户端/分片上传/暂存管理
  worker/       自研入库 worker(轮询 + 修复扫描 + GC)
scripts/
  migrations/   数据库迁移(KB + 共享)
  ops/          运维脚本(Milvus/Nebula 索引维护、重建、诊断)
docs/           architecture.md(服务契约)/ evaluation-report.md(评测)
deploy/         docker-compose / Dockerfile / systemd 单元
tools/          check_imports 拆分完整性门禁

关键配置

见 .env.example。最重要的三项:

变量	说明
INTERNAL_API_SECRET	内部检索接口共享密钥,须与 radai 一致
SELF_INGESTION_ENABLED / SELF_RETRIEVER_ENABLED	自研链路总开关
KNOWLEDGE_API_STATELESS_REPLICA	只读检索副本模式(不启动后台调度器)

本服务只支持自研入库/检索;原 LightRAG(legacy)链路已整体移除, 存量 legacy_lightrag 知识库一律阻塞提示迁移。

开发

make check-imports   # 内部导入闭包校验(拆分完整性门禁,须通过)
make lint            # flake8
make format          # black + isort

相关仓库

• radai — 智能体平台(会话/技能/题库/前端), 通过 KNOWLEDGE_SERVICE_BASE_URL + INTERNAL_API_SECRET 访问本服务