OmniGraph · 学科知识中心（KnowledgeNexus）

大规模多学科知识库平台：单学科 3–9 万篇文献、库群千万级文本块的入库、检索、治理、运维管理与大屏。

• K/R 双资产轴：知识资产 K0–K3（文档块 → 抽取 → 关系 → 图谱）+ 检索资产 R0–R3（词法/向量/合成查询/路由），代际原子切换，可重建投影与持久权威分离；
• 四服务：admin-api / ingest-worker / retrieval-api / observer-api（FastAPI），健康/就绪/配置摘要开箱即用；
• 三层学科 Schema：通用学术层 + 学科层（extends 继承）+ 自定义层，内置 20+ 学科、支持 LLM 起草新学科；
• 模型服务不自建：Embedding / LLM / MinerU 经环境变量注入外部端点，端点缺失时 /readyz 恒 not-ready（fail-fast）。

界面一览

图谱探索（星云观 · 结构下钻）

管理台内置图谱探索：星云力导向布局、类型着色与图例过滤、实体名检索、结构视图下钻、点选星体/节点/边查看详情、双击定位，支持力导/其他布局切换与全屏。

运维大屏

检索通道遥测（词法/向量/图通道的准入、缓存命中、拒绝、降级计数）、检索延迟 P50/P95/P99 分位、流量时序（10s 采样）、富化队列与能力位观测，页面即仪表盘。

学科 Schema（三层架构）

通用学术层 _base（13 实体/10 关系）+ 学科层（extends 继承：别名并集/约束覆盖）+ custom_* 自定义层；K1 词典/K3 词表/治理守卫随库绑定、热更新生效。内置学科覆盖农学、基础力学、生物学、化学、计算机科学、地球科学、经济学、教育学、工程、环境科学、历史学、水文地质、法学、文学、材料科学、数学、医学、核电子学、药学、物理学、心理学等，并可由 LLM 起草新学科（起草 + validator 校验，幂等可重跑补齐）。

仓库结构

omnigraph/
├── docs/                  # 技术方案 + 落地方案 + 参考文档（docs/images/ 为控制台截图）
├── schemas/               # 学科 Schema YAML（_base.yaml 通用层 + 18 学科层 + custom_* 自定义层）
├── services/              # 四服务（FastAPI）
│   ├── admin-api/         # 知识管理服务（管理端 API、整库发布闸门、管理台单页壳）
│   ├── ingest-worker/     # 入库加工服务（基础线 + 富化线，Bulk Index Profile）
│   ├── retrieval-api/     # 检索服务（Router → Planner → 通道 → 融合 → 精排 → 图证据）
│   └── observer-api/      # 治理与观测服务（分区治理、遥测、大屏聚合）
├── libs/                  # 复用库
│   ├── schema/            # 学科 Schema 体系（loader/validator/prompt 渲染）
│   ├── pipeline/          # 解析/分块/抽取/归并/提交状态机/合成查询/上下文摘要
│   ├── retrieval/         # 融合/父窗口/重排/PPR 算法核 + retrieval_profile
│   ├── knc-core/          # 四服务共享配置（外部模型/基础设施端点，stdlib-only；含 Basic Auth + API Key 网关）
│   └── engine/            # OpenSearch/Nebula/MySQL 适配层（Nebula MATCH 读边属性一律 properties(e)）
├── corpus/                # 语料采集（多源学术检索工具 + 订阅调度 + 学科 Schema 批产工具）
└── deploy/                # 部署定义（compose/SQL/索引模板/图空间 Schema/备份/资源守卫，见 deploy/README.md）

评测底座与测试代码（eval/ 题集、holdout、消融产物、HotpotQA/GraphRAG-Bench 基准数据，及 tests/）为本地资产，不随本仓库分发；本地开发按 AGENTS.md 纪律维护。

架构与端口

层	组件	端口
应用服务	admin-api / ingest-worker / retrieval-api / observer-api	18100 / 18110 / 18120 / 18130
自建基础设施	MySQL 8.4 · OpenSearch 3.8.0 · NebulaGraph v3.6（原生安装） · Redis 8.8 · MinIO	13306 · 19200 · 19669 · 16379 · 19000/19001
外部模型服务	Embedding · LLM · MinerU（不自建，.env.services 注入）	—

• 基础设施统一经 deploy/docker-compose.infra.yml 一键起，全部绑定 127.0.0.1（1 前缀端口域，与宿主机生产零冲突）；
• OpenSearch 索引（chunk/doc/query）经 alias 暴露，代际切换 = alias 原子切；MySQL 首启自动执行 deploy/sql/001_init.sql（17 表）；Nebula 图空间 knc_graph 点/边最小路由属性见 deploy/nebula/schema.nebula；
• 管理台为零构建链单页壳（services/admin-api/app/static/，vendor UMD：cytoscape/echarts），无前端构建步骤。

快速开始

# 0) 宿主机前置（OpenSearch 必需）
sudo sysctl -w vm.max_map_count=262144

# 1) 基础设施栈（MySQL 首启自动建表；nebula-init / minio-init 幂等）
cd deploy
cp .env.infra.example .env              # 修改所有 CHANGEME
docker compose -f docker-compose.infra.yml up -d

# 2) OpenSearch 索引（模板 + 首代索引 + alias）
OS_PWD='<OPENSEARCH_ADMIN_PASSWORD>' ./opensearch/bootstrap.sh

# 3) 应用服务（先填外部模型端点：EMBEDDING / LLM / MINERU）
cp .env.services.example .env.services
docker compose --env-file .env --env-file .env.services \
  -f docker-compose.services.yml up -d --build

# 4) 验证
curl -s 127.0.0.1:18100/healthz          # {"status":"ok","service":"admin-api"}
curl -s 127.0.0.1:18100/readyz           # ready=true（外部模型 + 基础设施齐备）

管理台入口：http://127.0.0.1:18100/（admin-api 静态壳）。

文档

文档	定位
docs/学科知识中心技术方案.md	目标态总体架构：K/R 双资产轴、四服务、数据权威、能力位门控、ACL、评测口径
docs/学科知识中心-落地方案.md	落地执行：复用映射、Phase 0–5 交付计划、风险预案
deploy/README.md	版本矩阵、端口规划、首启步骤、升级纪律
docs/reference/	算法设计背景材料（入库实现方案 / 知识库算法和架构 / 检索算法全流程）

安全边界

• 真实 .env / .env.services 永不入库，仓库只含 *.example 模板；
• 应用服务对外暴露须同时满足：KNC_AUTH_PASSWORD 已设（Basic Auth 网关，回环/预检/healthz 免认证）、KNC_CORS_ORIGIN_REGEX 显式配置、收紧口令只存 deploy/.env；亦支持 X-API-Key per-consumer 密钥（KNC_API_KEYS）；
• 对外暴露任何服务前，先确认开源许可清单（MinerU 为 AGPL-3.0）。

许可

项目许可证待定（发布前确认依赖许可清单）。外部模型服务依赖中的 MinerU 为 AGPL-3.0，对外提供服务时注意使用边界。