# OntoMind **Repository Path**: zhy0203/onto-mind ## Basic Information - **Project Name**: OntoMind - **Description**: OntoMind 是一个基于大模型（LLM）的智能本体构建平台，遵循 W3C OWL 2 标准，提供从数据接入、本体建模、知识存储、行为规则到应用交互的全链路能力。平台通过 CodeAgent（Auto-Harness 模式）自动执行本体构建的四阶段流程：初始化 → 规划 → 执行 → 验证。 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 22 - **Created**: 2026-07-06 - **Last Updated**: 2026-07-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # OntoMind 智能本体平台 OntoMind 是一站式智能本体管理平台，覆盖本体建模、知识抽取、语义推理、多模知识问答和本体实例化的完整生命周期。平台深度融合 **LLM（大语言模型）+ 语义网技术（OWL2/RDF/SPARQL/SWRL）**，将结构化数据、非结构化文档和行业标准本体（FIBO/IOF）转化为可推理、可查询、可应用的语义知识库。 --- ## 使用场景 | 场景 | 说明 | |------|------| | **企业知识图谱构建** | 从数据库、Excel、PDF、Word、PPT 等多源异构数据自动抽取本体模型和实例数据，形成企业级知识图谱 | | **智能问答与语义检索** | 基于本体模型的自然语言问答（KBQA），支持 SPARQL 精确查询 + 向量语义搜索 + 图分析融合 | | **行业标准本体落地** | 导入 FIBO（金融）、IOF（制造）等行业标准本体，结合企业数据完成实例化和定制扩展 | | **数据治理与标准统一** | 通过 OWL2 本体定义业务术语标准，利用推理器（HermiT/Pellet）自动发现数据冲突和逻辑不一致 | | **规则驱动的决策支持** | 定义 SWRL 业务规则，基于本体推理实现自动分类、合规校验、风险预警等智能决策 | | **大模型幻觉抑制** | 以结构化本体三元组替代扁平文本块作为知识锚点，LLM 输出受限于 Schema 约束和关系路径，从根本上减少事实性错误 | | **复杂任务上下文压缩** | 本体图遍历按需提取精准子图，替代全量文档检索，大幅降低 Token 消耗（可达 80% 以上），支撑多跳推理和长链关联任务 | | **多模数据探索与预处理** 🆕 | 基于 Jupyter AI Notebook 的交互式数据分析，Schema-aware AI 辅助编码（Python/SQL/SPARQL），Ray 定时计算任务，填补数据接入与本体构建之间的探索空白 | | **多租户数据隔离** | 支持多个租户独立管理本体实例和数据源，适用于 SaaS 多客户场景 | --- ### 本体知识图谱 vs 传统向量 RAG：为什么能减少幻觉？ 传统向量 RAG 依赖文本块的**语义相似度**进行检索，存在三个结构性缺陷：文本块切分导致关系断裂、语义相近不等于逻辑相关（如"保温杯"与"保温大棚"误匹配）、无法支持跨文档多跳推理。2025 年多项基准研究表明，本体知识图谱通过**结构化关系建模**从根本上弥补了这些缺陷。 | 维度 | 传统向量 RAG | 本体知识图谱 RAG | |------|:-----------:|:---------------:| | **检索原理** | 文本块向量相似度 | 实体关系图遍历 + SPARQL 精确查询 | | **多跳推理** | 弱 — 孤立文本块无法关联 | 天然支持 — 沿关系边遍历至 N 跳 | | **幻觉率** | 依赖 chunk 切分质量（基准 13.52%~18.86%） | 结构化 Schema 约束 + 类型系统（Walk&Retrieve: 12.74%） | | **答案准确率** | Naive RAG 在技术数据上仅 43.82%，甚至低于纯 LLM（49.20%） | LightRAG（图增强）达 92.75% | | **Token 效率** | 全量文档检索，3,000~31,000 tokens | 子图按需展开，~1,500~5,500 tokens，约 **8x 节省** | | **可解释性** | 低 — 向量打分黑箱 | 高 — 推理路径可视化追溯 | | **知识更新** | 需重新嵌入 | 增量图更新（LLM 提取事实 → TBox 校验 → TDB2 追加 → 增量推理），无需重索引 | | **关系保留** | 断裂 — 引用/推导/对立等关系丢失 | 结构化保留 — Subject-Predicate-Object 三元组 | #### 本体抑制幻觉的三大核心机制 1. **Schema 类型约束** — OWL2 本体通过 `rdfs:domain`、`rdfs:range`、`owl:Restriction` 等约束，限定了属性和类之间的合法关系组合。LLM 在生成 SPARQL 或作答时，必须遵守这些语义边界，避免了传统 RAG 中常见的"张冠李戴"式事实错误。 2. **关系路径推理** — 知识图谱天然保留了实体间有向的语义关联。从问题实体出发，沿关系边一步步遍历至答案节点，形成完整的推理链。这种透明性使得幻觉来源可定位、可调试，例如在 KBQA 中 SPARQL 查询路径可被直接审计——而向量 RAG 只能给出一个相似度分数。 3. **递进式查询策略** — OntoMind 的 KBQA Agent 实现了"精确匹配 → 模糊匹配 → Schema 浏览兜底"的递进策略：先用精确 IRI 和 `rdfs:domain` 约束查询，无结果时回退到宽松条件，最终以类统计信息兜底，确保每个结果都锚定在真实知识库数据上，严格禁止 LLM 虚构答案。 #### 典型应用：高精度领域的幻觉控制 | 领域 | 幻觉控制效果 | 来源 | |------|-------------|------| | **金融** | GraphRAG 减少 **6%** 幻觉，Token 消耗降低 **80%**，矛盾检测复杂度降低 **734x** | GenAIK Workshop 2025 | | **公共卫生** | 多证据 KG 框架 MEGA-RAG 幻觉减少 **>40%**，F1 达 0.790 | PMC 2025 | | **文化计算** | 本体增强 RAG（OB-RAG）在忠实度和答案相关性上全面超越传统 RAG | ScienceDirect 2025 | | **通用问答** | Walk&Retrieve 零样本 KG 游走准确率 **57.08%**（传统 RAG 仅 14.73%） | SIGIR 2025 | > **结论**：本体知识图谱通过结构化 Schema 约束、关系路径推理和递进式查询策略，在减少大模型幻觉方面相比传统向量 RAG 具有根本性优势。当前产业界最佳实践趋向于 **"图索引 + 向量索引 + 全文索引"多引擎融合架构**（如 Fusion GraphRAG），OntoMind 平台的多模知识问答服务正是这一架构的落地实现。 --- ## 核心优势 ### 1. LLM + 语义网深度融合 - **Hermes CLI 智能体**：基于 Hermes CLI 的全功能 AI 对话引擎，集成 MCP 协议、技能系统和工具调用链追踪 - **Build Agent 构建智能体**：4 阶段流水线（Init→Plan→Execute→Verify）自动从数据源构建本体，支持断点续传 - LLM 负责自然语言理解、实体抽取、Schema 推断、SPARQL 生成等智能任务 - 语义网技术（OWL2/RDF/Jena）保证知识的精确性、可推理性和标准化 - 两者互补：LLM 提供灵活性，语义网提供确定性 ### 2. 全生命周期覆盖 - **建模** → **抽取** → **推理** → **实例化** → **应用** → **精调** 一站式闭环 - 支持 Markdown 描述文档 → AI 自动提取 → 完整 OWL2 本体模型 - **新增**：本体管理增强精调工作台，支持对象类型/关系类型/SWRL 规则的可视化人工精调 ### 3. 多源异构数据集成 - 结构化数据：JDBC（MySQL/PostgreSQL/Hive/ClickHouse/Doris）、REST API、MQ - 非结构化数据：PDF、Word、Excel、PPT、HTML、CSV（AI 自动转 Markdown → 本体抽取） - RDF 标准格式：TTL（Turtle）、OWL/RDF 直接导入 ### 4. OxiRS gRPC 推理引擎 + 双 OWL 推理器 + 嵌入式三员组存储 - **OxiRS gRPC (Rust)**：高性能原生规则推理引擎，6 个 RPC API（ForwardChain / BackwardChain / IncrementalUpdate / RegisterRules / RemoveRules / HealthCheck），FC+BC 双模式，RETE 网络 + 半朴素迭代，gRPC 协议协同。Java 侧 SwrlRuleClassifier 三阶段分类流水线（结构分析 → 依赖图 → FC/BC 决策），Jena GenericRuleReasoner 作为 fallback - **HermiT**：OWL2 DL 标准推理器，与 Protégé 一致 - **Pellet**：支持 SWRL 规则推理 + 解释生成 - **Jena TDB2**：嵌入式持久化三员组存储 + SPARQL 查询 - **Fuseki**：内嵌 SPARQL HTTP 端点，对外暴露标准查询接口 ### 5. 灵活的实例化管道 - 5 步向导式流水线：数据源选配 → AI 映射 → 实例生成 → 预览编辑 → 加载入库 - 支持全量覆盖和增量追加两种加载模式 - 支持 Cron 定时调度，实现数据的周期性自动同步 ### 6. 多模知识问答 + 知识更新闭环 - **本体智能体（Agent KBQA）**：5 意图识别（sparql_query / concept_explain / structure_analysis / knowledge_update / general_chat）+ 渐进式 SPARQL 查询 + 图谱 BFS 扩展 + 推理链剥离流式输出 - **知识更新闭环**：LLM 事实提取 → NeSyS TBox 校验 → TDB2 增量写入 → OxiRS 增量推理，实现问答到知识图谱的完整写入闭环 - LangGraph 驱动的多步推理 Agent（ontomind-multimodal） - 支持本体 KB + 向量 KB + 图 KB 多源联合查询 - 支持本体 KB 多源查询 ### 7. MCP 标准协议 - 实现 Model Context Protocol (2024-11-05)，11 个标准工具 - 支持 JSON-RPC + SSE 双模式 - 可被任何 MCP 兼容的 AI Agent 客户端集成 ### 8. 灵活的第三方模型接入 - 内置 5 种提供商类型（DeepSeek/Qwen/OpenAI/Zhipu/Custom） - **自定义类型支持任意 OpenAI 兼容 API**：Ollama、vLLM、Together AI、Groq、本地私有化部署等 - 统一 `ChatOpenAI` 客户端，即插即用，无需额外适配 - 可视化模型管理：连接测试、在线对话调试、能力标签、启停控制 - 支持环境变量一键初始化默认模型 ### 9. 企业级基础设施 - 多租户架构 + JWT 认证 + RBAC 权限（5 种角色） - 完善的备份恢复（数据库/Redis/文件/TDB2 全量+增量） - Docker Compose 一键部署，全链路健康检查 ### 10. 多模数据处理引擎（🆕） - **Polaris 统一元数据管理**：Apache Polaris 驱动的数据目录，自动发现和同步全平台资产（JDBC 表、非结构化文件、本体模型、知识库），提供 RBAC 权限隔离和资产标签分类 - **Jupyter AI 交互式 Notebook**：iframe 嵌入 JupyterLab + Jupyter AI v3，内置 OntoMind Persona（6 个 MCP 函数调用），AI 编码辅助（NL → Python/SQL/SPARQL 代码生成），支持 Schema-aware 代码生成与错误修复 - **Ray 异构计算引擎**：Ray Data 驱动的计算任务管理，支持 Notebook 参数化执行、Cron 定时调度、任务历史与日志追踪 - **ontomind-mcp 公共 MCP Server**：自建独立 MCP Server（Port 8101），6 个标准 MCP 工具（catalog_list_namespaces / catalog_list_tables / catalog_get_table_schema / catalog_get_ontology_context / catalog_get_file_context / catalog_search），聚合全平台上下文，供 Jupyter AI / Hermes CLI / 外部 Agent 消费 - **数据导入引擎**：Excel/CSV/TXT 文件一键导入到 PostgreSQL 物理表，AI 自动推断列类型（STRING/BIGINT/NUMERIC/DATE/TIMESTAMP 等）、空值检测、分批写入（1000 行/批），支持新建表或追加到已有表 ### 11. 本体 Action 管理 - 业务 Action 全生命周期管理：业务需求 → LLM 生成 SOP → 专家审核 → LLM 生成 Skill → 下载部署到 Agent - 基于本体语义上下文的 LLM 自动生成标准操作流程（SOP）和可执行 Skill - 技能自动上传到 Hermes CLI 本体智能体，实现从业务需求到 AI 执行的闭环 --- ## 系统架构 ``` ┌──────────────────────────────────────────────────────────────────────────┐ │ Nginx (17386) │ │ 前端 SPA + 反向代理路由 │ └──────┬──────────┬──────────┬──────────┬───────────┬───────────┬──────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ontomind- │ │ontomind-│ │ontomind- │ │ontomind- │ │ontomind- │ │ontomind- │ │web (SPA) │ │server │ │multimodal│ │mcp 🆕 │ │notebook🆕│ │ray 🆕 │ │ │ │(8080) │ │(8090) │ │(8101) │ │(8888) │ │(8102) │ │React+AntD│ │Spring │ │LangGraph │ │FastAPI │ │JupyterLab│ │FastAPI │ │ │ │Boot3 │ │+Jena │ │公共MCP │ │+JupyterAI│ │Ray Job │ │ │ │Jena TDB2│ │ │ │Polaris │ │ │ │调度 │ │ │ │HermiT/ │ │ │ │AutoSync │ │ │ │ │ │ │ │Pellet │ │ │ │ │ │ │ │ │ │ │ │Fuseki │ │ │ │ │ │ │ │ │ └──────────┘ └───┬──┬──┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ ┌────────────┼──┼─────────┼────────────┼────────────┼────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ OxiRS │ │ontomind- │ │PostgreSQL│ │Polaris🆕 │ │ MinIO 🆕│ │(50051) │ │agent │ │+Redis │ │(8181) │ │(9000) │ │gRPC推理│ │(8001) │ │(基础) │ │统一元数据 │ │S3兼容 │ │Rust原生│ │FastAPI │ │ │ │管理 │ │存储 │ │FC+BC │ │BuildAgent│ │ │ │ │ │ │ └────────┘ └──────────┘ └─────────┘ └──────────┘ └─────────┘ ``` ### 服务说明 | 服务 | 端口 | 技术栈 | 职责 | |------|------|--------|------| | **Nginx** | 17386 | Nginx + 静态资源 | 前端 SPA 托管，反向代理到后端和 Agent | | **ontomind-server** | 8080 | Spring Boot 3.2 + Java 17 | 核心业务逻辑：本体 CRUD、推理、实例化管道、MCP Server、数据源管理、数据导入 | | **ontomind-agent** | 8001 | FastAPI + Python 3.11 | LLM 驱动的本体构建 Agent（Init→Plan→Execute→Verify）、KBQA、Hermes CLI 集成 | | **ontomind-multimodal** | 8090 | FastAPI + LangGraph + Jena | 多模知识问答 Agent：意图识别→计划生成→执行（SPARQL）→答案合成 | | **ontomind-mcp** 🆕 | 8101 | FastAPI + Python 3.11 + FastMCP | 平台公共 MCP Server（6 个工具），Catalog REST API（Polaris 聚合），PolarisAutoSync 元数据自动扫描同步，Notebook 模型配置代理 | | **ontomind-notebook** 🆕 | 8888 | JupyterLab + Jupyter AI v3 + JupyterHub | 交互式 AI Notebook，OntoMind Persona（6 个 MCP function call），NL→Python/SQL/SPARQL 代码生成，PyIceberg 连接 Polaris | | **ontomind-ray** 🆕 | 8102 | FastAPI + Python 3.11 + Ray Data | Ray Job CRUD + Cron 定时调度 + 集群状态监控 + 任务日志追踪 | | **OxiRS** | 50051 | Rust + tonic/gRPC | 原生规则推理引擎：6 RPC（ForwardChain / BackwardChain / IncrementalUpdate / RegisterRules / RemoveRules / HealthCheck），FC+BC+增量推理，RETE 网络 + 半朴素迭代 | | **Apache Polaris** 🆕 | 8181 | Apache Polaris 1.5+ (内置 H2) | 统一数据目录：三层命名空间 (Catalog→Schema→Asset)，Iceberg REST API，自动零配置启动 | | **MinIO** 🆕 | 9000/9001 | MinIO | 本地 S3 兼容存储，用于 Notebook 文件和多模数据文件持久化 | | **PostgreSQL 16** | 5432 | PostgreSQL + Flyway | 业务数据持久化，40 个迁移脚本管理 schema 版本 | | **Redis 7** | 6379 | Redis（allkeys-lru） | 缓存、会话、Agent 状态持久化 | | **Jena TDB2** | 嵌入式 | Apache Jena + Pellet | 三员组持久化存储，SPARQL 查询引擎 | | **Fuseki** | 3030 (嵌入式) | Apache Jena Fuseki | 内嵌 SPARQL HTTP 端点，对外暴露标准查询接口 | ### 核心技术依赖 - **语义网**：OWL API 5.1、Apache Jena 4.10、HermiT 1.3.8、Openllet 2.6.5 - **规则推理**：OxiRS v0.3.0 (Rust, gRPC) — 6 RPC API：ForwardChain（全量/增量 FC）+ BackwardChain（BC）+ IncrementalUpdate（增量）+ RegisterRules/RemoveRules（规则生命周期）+ HealthCheck。Java 侧 SwrlRuleAnalyzer（结构分析）+ RuleDependencyGraph（依赖图）+ SwrlRuleClassifier（FC/BC 分类决策），SWRL→Jena 规则转换含变量识别、内置函数参数顺序兼容 - **Agent 框架**：LangGraph 0.2+、LangChain、OpenAI SDK（兼容 DeepSeek/Qwen/Zhipu） - **多模语义**：Jena TDB2（SPARQL 查询、Schema 探测） - **前端可视化**：AntV G6 5.0（知识图谱）、Ant Design 5.20（UI）、Ant Design Charts（图表） - **基础设施**：Docker Compose、Flyway 27 迁移、JWT 认证、RBAC 5 角色 --- ## Hermes CLI 本体智能体 Hermes CLI 是 OntoMind 平台的**核心 AI 对话引擎**，平台将其作为子进程集成，为用户提供自然语言驱动的本体知识问答、工具调用和技能执行能力。Hermes CLI 与 OntoMind MCP Server 深度集成，可直接调用平台的 11 个 MCP 标准工具进行知识检索与推理。 ### 架构概览 ``` 用户请求 (providerId::modelId + message + skills + ontology_ids) │ ▼ ┌──────────────────────────────────────────────────┐ │ ontomind-agent (/agent/hermes) │ │ ├─ 模型解析：providerId::modelId → API 配置 │ │ ├─ 动态配置生成：写入 ~/.hermes/config.yaml │ │ ├─ MCP 注册：hermes mcp add ontomind-kb │ │ └─ 子进程启动：hermes chat -q "..." --yolo │ └──────────────┬───────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────┐ │ Hermes CLI (子进程) │ │ ├─ LLM 对话 (ChatOpenAI 统一客户端) │ │ ├─ MCP 工具调用 (ontomind-kb) │ │ ├─ 技能执行 (CLI + MCP + Disk 三源合并) │ │ └─ 文件生成 (代码/报告/配置文件) │ └──────────────┬───────────────────────────────────┘ │ stdout 流式解析 ▼ ┌──────────────────────────────────────────────────┐ │ SSE 事件流 → 前端 │ │ ├─ thinking: LLM 思考过程 (折叠显示) │ │ ├─ trace: 工具调用链追踪 (步骤树 + 耗时统计) │ │ ├─ content: 最终回答内容 │ │ └─ done: 完成事件 (含生成文件列表) │ └──────────────────────────────────────────────────┘ ``` ### REST API 端点（`/agent/hermes`） | 方法 | 路径 | 说明 | |------|------|------| | `POST` | `/chat` | 非流式对话 | | `POST` | `/chat/stream` | **SSE 流式对话**（含工具调用追踪、思考过程展示） | | `GET` | `/status` | 检查 Hermes CLI 安装状态与模型可用性 | | `GET` | `/skills` | 获取可用技能列表（三源合并） | | `POST` | `/skills/upload` | 上传技能文件（SKILL.md 或 .zip） | | `DELETE` | `/skills/{name}` | 删除指定技能 | | `GET` | `/sessions/{id}` | 获取会话历史消息 | | `DELETE` | `/sessions/{id}` | 删除会话 | | `POST` | `/cancel/{task_id}` | 取消正在执行的流式任务 | | `GET` | `/tasks` | 查看运行中的任务列表 | | `GET` | `/files` | 查看生成的文件列表 | | `GET` | `/files/download` | 下载生成的文件 | ### 技能系统 技能从三个来源合并，在对话中可通过 `使用【skill_name】技能：` 语法或 API 参数调用： | 来源 | 说明 | |------|------| | **CLI 技能** | 通过 `hermes skills list` 获取的内置技能 | | **MCP 工具** | OntoMind MCP Server 提供的 11 个标准知识库工具（SPARQL 查询、本体 schema、概念搜索、KBQA 问答、实体画像等） | | **磁盘技能** | 用户上传至 `~/.hermes/skills/` 的自定义技能（SKILL.md 格式） | ### 流式对话特性 - **思考过程可视化**：`` 块内容折叠显示，用户可查看 LLM 推理过程 - **工具调用追踪**：每次 MCP 工具调用的输入/输出以 TracePanel 步骤树展示，含耗时统计 - **实时内容输出**：最终回答以 SSE 流式推送，逐字渲染 - **文件生成**：Hermes 生成的代码、报告等文件可在线预览和下载 ### 模型选择 对话请求通过 `providerId::modelId` 格式指定模型（如 `"provider1::deepseek-chat"`），Agent 服务自动从平台模型管理 API 获取对应提供商的 API 密钥、Base URL 和模型名称，构造统一的 `ChatOpenAI` 客户端调用 LLM。 --- ## 本体构建智能体（Build Agent） Build Agent 是 OntoMind 的**LLM 驱动本体自动构建引擎**，通过 4 阶段流水线从数据源自动发现、规划、创建和验证本体模型。每个阶段由独立的 Agent 执行，通过 Redis 传递中间结果，支持断点续传。 ### 4 阶段流水线 ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ① Init │───▶│ ② Plan │───▶│ ③ Execute│───▶│ ④ Verify │ │ 数据发现 │ │ 蓝图生成 │ │ 本体创建 │ │ 一致性 │ │ │ │ │ │ │ │ 验证 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ``` ### 各阶段详情 #### ① InitAgent — 数据源发现与分析 | 步骤 | 进度 | 说明 | |------|------|------| | 数据源发现 | 10% | 获取平台已配置的 JDBC 数据源列表 | | 表结构分析 | 30% | 获取每个数据源的表结构和字段信息 | | 外键分析 | 50% | 提取表间外键关系 + LLM 辅助推断隐式关联 | | 实体候选生成 | 70% | LLM 根据表结构推断实体类型和候选类 | | 行业本体加载 | 90% | 加载 FIBO（金融）/ IOF（制造）等行业参考本体 | #### ② PlanAgent — 蓝图生成与任务分解 | 步骤 | 进度 | 说明 | |------|------|------| | 读取分析报告 | 10% | 从 Redis 读取 InitAgent 产出的分析结果 | | 生成本体蓝图 | 50% | LLM 生成完整的本体结构：`{classes, objectProperties, datatypeProperties, instanceMappings}` | | 任务分解 | 80% | 将蓝图拆分为可执行的任务列表（创建类/属性/实例映射） | #### ③ ExecuteAgent — 本体元素创建 - 从 Redis 读取 PlanAgent 生成的蓝图和任务列表 - 逐任务调用后端 API 创建本体元素（ObjectType、LinkType、DatatypeProperty 等） - **断点续传**：每 5 个任务记录一次检查点，中断后可从上次位置恢复 - 产出 `{executedTasks, failedTasks, totalTasks, successCount, failCount}` #### ④ VerifyAgent — 一致性验证 | 步骤 | 进度 | 说明 | |------|------|------| | OWL 一致性检查 | 20% | SPARQL 查询空类、孤立的类等逻辑问题 | | 属性约束验证 | 40% | 校验 DatatypeProperty 范围是否为有效 XSD 类型 | | 循环继承检测 | 60% | DFS 遍历子类层次图检测循环继承 | | 修复建议生成 | 90% | LLM 对发现的问题生成修复建议 | | 验证报告 | 100% | `{consistency, propertyConstraints, inheritanceCycles, errorSummary, fixSuggestions, passed}` | ### Orchestrator 编排器 `BuildOrchestrator` 负责流水线的生命周期管理： - **启动**：创建异步任务，初始化 4 阶段总进度，后台执行 `run_pipeline()` - **阶段调度**：顺序执行 Init → Plan → Execute → Verify，每个阶段独立失败处理 - **失败策略**：Init/Plan 失败中止流水线；Execute 部分失败仍进入 Verify 诊断 - **进度查询**：实时返回 `BuildProgress`（当前阶段、完成百分比、状态） - **取消支持**：通过 `asyncio.Task.cancel()` 取消正在运行的构建任务 - **报告获取**：所有阶段完成后返回完整的验证报告 ### REST API 端点（`/agent`） | 方法 | 路径 | 说明 | |------|------|------| | `POST` | `/build-tasks` | 创建并启动构建任务 | | `GET` | `/build-tasks/{task_id}` | 查询任务状态（pending→initializing→planning→executing→verifying→completed/failed） | | `GET` | `/build-tasks/{task_id}/progress` | 获取阶段级进度详情 | | `POST` | `/build-tasks/{task_id}/cancel` | 取消构建任务 | | `GET` | `/build-tasks/{task_id}/report` | 获取最终验证报告 | ### 其他 Agent 能力 | 模块 | 路径前缀 | 说明 | |------|----------|------| | **智能推理** | `/agent` | LLM 驱动的 Schema 推断、实体抽取、关系抽取、规则抽取 | | **本体知识问答 (KBQA)** | `/agent` | NL→SPARQL 完整流水线：Schema 加载 → 意图识别+任务规划（5 意图）→ Schema 拓扑图展开（4 重策略）→ SPARQL 执行/知识更新/直接回答 → SSE 安全过滤 → 流式答案生成 | | **知识更新** | `/agent` | LLM 事实提取 → NeSyS TBox 校验 → TDB2 增量写入 → 结构化确认反馈（SSE） | ### 后端新增 API（Schema 拓扑图） | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/ontologies/{id}/object-property-graph` | **Schema 拓扑图**：返回类节点 + 对象属性边 + 标识属性共享组（identityOverlaps），供 KBQA 自动展开查询范围 | | `GET` | `/ontologies/{id}/probe-schema` | **ABox 数据探测**：返回 TDB2 实际数据（类/谓词/domain 映射/数据属性采样值/有✅无⚠️实例标记），含 `rdfs:range` 并行查询区分 isLiteral/!isLiteral 属性 | --- ## 功能模块与使用流程 ### 1. 快速入门四步走 ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ① 导入 │───▶│ ② 探索 │───▶│ ③ AI提取 │───▶│ ④ 审核 │───▶│ ⑤ 问答 │ │ 文档/数据 │ │ 预处理🆕 │ │ 本体模型 │ │ 验证优化 │ │ 与应用 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ``` **Step 1 — 导入文档或连接数据源** - 上传 Markdown 行业标准文档、PDF、Word、Excel、CSV 等 - 配置 JDBC 数据源连接（MySQL/PostgreSQL/Hive/ClickHouse/Doris） - 文件自动解析为虚拟表，供后续实例化使用 - 🆕 支持 Excel/CSV/TXT 文件一键导入到 PostgreSQL 物理表（AI 类型推断 + 分批写入） **Step 2 — 数据探索与预处理** 🆕 - 在 Jupyter AI Notebook 中交互式探索数据分布、清洗脏数据、特征工程 - 基于 Polaris Catalog 浏览全平台数据资产（数据源/文件/本体/知识库） - AI 辅助编码：自然语言 → Python/SQL/SPARQL 代码生成，Schema-aware 上下文感知 - Ray 计算任务：定时 Notebook 执行、批量数据处理 **Step 3 — AI 提取本体模型** - 选择 LLM 模型，将文档通过 SSE 流式转换为标准 OWL2 本体 - 自动生成分类（Classes）、对象属性（Object Properties）、数据属性（Data Properties）、SWRL 规则、TTL 内容 - 支持 FIBO/IOF 等行业参考本体的自动对齐 **Step 4 — 审核与验证** - 在可视化图形编辑器中查看、编辑类层次和关系（Protege 风格，拖拽连线和节点） - 运行 HermiT/Pellet 推理器验证一致性 - 自动修复检测到的问题（Auto-Fix） **Step 5 — 问答与应用** - 实例化本体：配置数据源映射 → AI 自动映射 → 生成实例 → 预览 TTL → 加载到 Jena TDB2 - SPARQL 查询控制台 - 自然语言知识问答（KBQA Agent） - 多模知识融合问答 --- ### 2. 本体模型管理 (`/ontology`) 完整工作流： 1. **创建本体**：命名、选择行业参考（FIBO/IOF/自定义/无）、版本号 2. **Markdown AI 提取**：上传行业规范 Markdown → 选择 LLM 模型 → SSE 流式提取 → 自动生成 OWL2 本体（类/属性/规则/TTL） 3. **TTL 导入**：直接导入标准 TTL/RDF 文件 4. **可视化编辑**： - G6 图形渲染类层次 + 关系网络 - 拖拽节点调整布局（位置自动持久化） - 右键连线绘制新关系 - 添加/编辑/删除类和属性 5. **推理验证**： - HermiT 推理：一致性检查 + 分类推导 - Pellet 推理：一致性 + SWRL 规则 + 解释生成 - Auto-Fix 自动修复检测到的逻辑问题 6. **导入导出**：TTL/OWL 导出、Markdown 文档导出、版本快照 7. **SPARQL 控制台**：直接在页面上编写和执行 SPARQL 查询 > **新增**：现在可通过 [本体管理 (Ontology Manager)](#8-本体管理-ontology-manager) 获得增强的人工精调体验，包括 SWRL 规则可视化配置、对象类型/关系类型在线编辑与 TTL 双向同步等高级功能。 --- ### 2+. 本体管理增强人工精调 (`/ontology-manager`) 参考 Palantir Ontology Manager 设计理念，为领域专家提供**本体对象类型、关系类型和 SWRL 逻辑规则**的可视化运维与精调工作台，实现本体模型的精细化人工管控。 #### 四位一体功能模块 ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 总览 │ │ 对象类型 │ │ 关系类型 │ │ 逻辑规则 │ │ Discover │ │ Object Types│ │ Link Types │ │ Logic Rules │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` ##### 总览 (Discover) - 统计仪表盘：对象类型数、关系类型数、逻辑规则数量 - 快捷导航卡片，一键跳转到目标管理模块 - 本体版本信息概览 ##### 对象类型 (Object Types) - **类列表浏览**：全量类表格，支持名称/标签搜索 - **关联属性查看**：选中类后展示其关联的对象属性（domain/range）和数据属性 - **关联规则展示**：展示引用该类的 SWRL 规则列表 - **在线编辑**：标签（`rdfs:label`）和描述（`rdfs:comment`）在线编辑，修改后自动同步到 TTL - **类删除**：安全删除类及其关联属性，自动更新 TTL ##### 关系类型 (Link Types) - **双视图切换**：表格视图 ↔ G6 交互式图谱视图 - **表格视图**：对象属性列表，支持按名称/domain/range 搜索，在线编辑标签描述 - **图谱视图**：使用 AntV G6 渲染本体类（节点）和对象属性关系（边）的交互式知识图谱 - 拖拽节点自由调整布局 - 右键连线快捷创建新关系 - 添加/编辑/删除类和关系属性 - 缩放、导出、刷新 - **编辑同步**：所有修改自动同步到 TTL，确保数据一致性 ##### 逻辑规则 (Logic Rules) SWRL 规则的全生命周期可视化配置管理： | 能力 | 说明 | |------|------| | **AI 辅助生成** | 自然语言描述 → LLM 自动生成 SWRL 表达（支持选择任意已激活模型） | | **可视化构建器** | VisualComposer 拖拽式 Atom 组合：类归属、对象属性、数据属性、内置函数（Builtin）、等价/不同个体 | | **SWRL 语法校验** | 实时语法检查，基于完整词汇表（类/属性/Builtin）验证 IRI 合法性 | | **规则测试** | 临时测试 SWRL 表达式（Ad-hoc），无需保存即可验证推理效果 | | **规则解释** | LLM 将 SWRL 规则翻译为自然语言，帮助领域专家理解规则含义 | | **内置函数目录** | SwrlBuiltinCatalog — 7 大类（比较/算术/字符串/日期时间/类型检查/列表/布尔），标注 OxiRS/Jena 引擎支持级别（FULL/OXIRS_ONLY/JENA_ONLY） | | **依赖图** | 规则间依赖关系可视化，辅助理解规则链 | | **TTL 双向同步** | DB ↔ TTL：从 TTL 提取规则入库（`sync-swrl-rules`），修改后同步回写 TTL（`sync-rules-to-ttl`） | | **在线修改** | 规则名称、描述、SWRL 表达式、激活状态在线编辑，修改后自动同步 TTL | ##### SWRL 规则从自然语言到推理执行的全流程 ``` 用户输入自然语言描述（如"当一个客户同时拥有贷款账户和存款账户时，标记为综合业务客户"） │ ▼ ┌────────────────────────────────────────┐ │ Step 1: LLM 生成 SWRL │ │ /agent/generate-swrl │ │ ├ 输入: 自然语言描述 + 本体词汇表 │ │ │ (类/对象属性/数据属性) │ │ └ 输出: SWRL 规则表达式 │ └──────────────┬─────────────────────────┘ │ ▼ ┌────────────────────────────────────────┐ │ Step 2: 可视化编辑 + 语法校验 │ │ ├ VisualComposer: Body(IF)/Head(THEN) │ │ │ 拖拽式 Atom 编辑 │ │ ├ SwrlSyntaxValidator: 语法 + IRI 校验 │ │ └ SwrlBuiltinCatalog: 内置函数参考 │ └──────────────┬─────────────────────────┘ │ ▼ ┌────────────────────────────────────────┐ │ Step 3: 规则测试（可选） │ │ ├ 临时推理验证 SWRL 效果 │ │ └ 查看推断三元组 + 执行耗时 │ └──────────────┬─────────────────────────┘ │ ▼ ┌────────────────────────────────────────┐ │ Step 4: 保存 + 同步 TTL │ │ ├ DB 存储规则元数据 │ │ ├ sync-rules-to-ttl: 回写 TTL 文件 │ │ └ OxiRS/Jena 推理引擎加载规则 │ └────────────────────────────────────────┘ ``` ##### 后端支撑 | 组件 | 技术 | 说明 | |------|------|------| | **RuleController** | Spring Boot REST | 规则 CRUD + 语法校验 + 依赖图 + 测试执行 + TTL 同步 | | **SwrlBuiltinCatalog** | Java 静态目录 | 7 大类 50+ SWRL Builtin 函数签名与支持级别 | | **SwrlSyntaxValidator** | Java 正则 + 词汇表校验 | SWRL 表达式语法解析 + IRI 合法性验证 | | **OntologyController** | Spring Boot REST | 对象类型/关系类型 CRUD + 标签描述编辑 + TTL 重新生成 | | **TtlSyntaxFixer** | Java 语法修复引擎 | 5 类 LLM 生成 TTL 的自动修复（RDF 集合逗号/主语逗号/角括号修正/空行压缩） | | **Agent generate-swrl** | FastAPI LLM 端点 | NL → SWRL 生成 + SWRL 自然语言解释 | --- ### 3. 本体实例化管道 (`/instantiation/pipeline`) 5 步向导流程： ``` Step 1 Step 2 Step 3 Step 4 Step 5 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 选择数据 │───────▶│ AI 映射 │───────▶│ 生成实例 │──────▶│ TTL 预览 │──────▶│ 加载入库 │ │ 源+本体 │ │ (SSE) │ │ (RML) │ │ 编辑 │ │ TDB2 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ``` **三种实例化模式**： - **DB + TTL 模式**：从数据源结合本体 TTL 定义，使用 RMLMapper 生成 RDF 实例 - **纯 DB 模式**：仅从数据源表结构自动推断映射并生成实例 - **纯 TTL 模式**：直接上传已有 TTL 实例数据加载到 Jena TDB2 **Step 1 — 数据源选择**：选择目标本体、数据源（JDBC/文件）、配置 Jena 模型名称 **Step 2 — AI 映射生成**： - LLM 自动分析数据源表结构和本体模型 - SSE 流式生成表→类、字段→属性的映射关系 - 用户确认、编辑映射结果 **Step 3 — 实例生成**： - RMLMapper 引擎按映射规则生成 RDF 实例 - SSE 实时日志流展示生成进度 - 支持全量覆盖/增量追加 **Step 4 — TTL 预览**：在线预览生成的 Turtle 文件，支持直接编辑修正 **Step 5 — 加载入库**：将 TTL 加载到 Jena TDB2，挂载为命名图（Named Graph），可通过 Fuseki SPARQL 端点查询 **定时调度**：支持 Cron 表达式配置，实现数据的周期性自动同步 --- ### 4. 智能知识问答 (KBQA) OntoMind 的知识问答体系分为两层：**本体知识服务**（Java 后端，负责结构化存储、推理与查询执行）和**本体智能体**（Python Agent，负责意图理解、查询规划、结果合成与知识更新）。两层通过 REST API 协作，形成完整的 KBQA 闭环。 --- #### 4.1 本体知识服务 — 底层引擎能力速览 本体知识服务是平台的**符号计算层**（Java 后端，Spring Boot + Jena），为上层 Agent 提供知识图谱的存储、推理与查询能力。 | 组件 | 技术 | 职责 | |------|------|------| | **三员组存储** | Jena TDB2（嵌入式） | RDF 三元组按命名图持久化，Union Default Graph 支持跨图联合查询 | | **SPARQL 引擎** | Jena ARQ + 嵌入式 Fuseki (3030) | SELECT 查询执行，对外暴露标准 HTTP SPARQL 端点 | | **Pellet 推理** | Openllet (OWL 2 DL) | 前向物化所有隐含推论（类层次/属性特征/个体分类）到 TDB2，查询时零推理开销 | | **HermiT 推理** | HermiT 1.3.8 (OWL 2 DL) | 一致性检查、不可满足类检测、隐含关系发现 | | **OxiRS 规则推理** | OxiRS v0.3.0 (Rust, gRPC) | 6 RPC 全覆盖：FC 全量物化 + 增量推理（forwardChain, incrementalMode）、BC 查询时推导（backwardChain）、增量事实更新（IncrementalUpdate ADD/REMOVE）、规则生命周期（RegisterRules / RemoveRules）、健康检查（HealthCheck）。三阶段规则分类流水线：SwrlRuleAnalyzer（谓词/类型/扩展比）→ RuleDependencyGraph（69 边依赖图）→ SwrlRuleClassifier（FC/BC 决策）。Java 侧 Jena GenericRuleReasoner 作为 OxiRS 失败时的 fallback。推理管道含：raw 属性默认值注入、SWRL builtin 参数顺序兼容（SWRL 结果在前 / Jena 结果在后）、变量 URI 识别（/variable# 模式兜底）、同 S+P 多值去重（保留最大值） | | **NeSyS 验证** | NeuroSymbolicVerifier | 校验 LLM 生成的 SPARQL（属性类型/domain-range/连通性/disjoint/functional）和待写入三元组事实 | | **知识更新** | loadTtlSnippet + incrementalAdd | TTL 片段增量追加到 TDB2 → OxiRS 增量推理，避免全量重物化 | ##### SWRL 规则推理流水线 ``` materializeJenaSwrlRules() │ ├─ 1. 规则转换: TTL SWRL → Jena Rule + OxiRS gRPC Rule │ ├─ SWRL→Jena: convertSwrlToJenaRules() (reorderForJena=true) │ │ 内置函数参数重排: SWRL(add(?r,a,b)) → Jena(sum(a,b,?r)) │ │ 变量识别: rdf:type swrl:Variable 或 /variable# 模式兜底 │ └─ OxiRS gRPC: buildJenaRuleFromProfile() (reorderForJena=false) │ 保持 SWRL 原生参数顺序(结果在前) │ ├─ 2. FC/BC 分类: SwrlRuleClassifier 三阶段流水线 │ ├─ SwrlRuleAnalyzer: 提取 body/head 谓词, 识别规则类型, 估算扩展比 │ ├─ RuleDependencyGraph: 构建谓词级依赖图 (69 条边) │ └─ SwrlRuleClassifier: 按类型+扩展比+依赖数分类 (34 FC + 0 BC) │ ├─ 3. 前置注入: 为非中间属性(raw props)注入默认值 0 │ └─ 确保 CorporateCustomer 标志位等原始字段完整 │ ├─ 4. OxiRS ForwardChain (maxIterations=100, incrementalMode=false) │ └─ 34 条 FC 规则迭代到不动点, 产出 311 条推断 │ ├─ 5. 通用去重: 同 subject+predicate 多值保留最大值 │ └─ 311 → 83 条最终推断 │ └─ 6. BC 规则管理: registerRules (前置 removeRules 清理旧版) ``` --- #### 4.2 本体智能体 — 意图理解、查询规划与知识更新 本体智能体是平台的**智能编排层**，由 Python Agent（FastAPI + LLM）承载。它将用户的自然语言需求转化为对知识服务的调用序列，并对返回结果做综合理解。 ##### KBQA 完整流程（5 意图 × 5 阶段） ``` 用户自然语言问题 │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Stage 0: Schema 加载 (TTL 缓存 600s) │ │ │ │ 并行请求 Java 后端: │ │ ├─ GET /ontologies/{id}/object-types + link-types │ │ │ → TBox schema (classes, objectProperties, │ │ │ datatypeProperties) │ │ └─ GET /ontologies/{id}/probe-schema │ │ → ABox 实际数据 (实际类、谓词、domain 映射、 │ │ 数据属性采样值、有/无实例标记) │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Stage 1: 意图解析 + 任务规划 (合并单次 LLM 调用) │ │ │ │ KBQA_INTENT_PLAN_PROMPT → 一步输出: │ │ │ │ ┌─────────────────────┬──────────────────────────────┐ │ │ │ 意图 │ 后续路径 │ │ │ ├─────────────────────┼──────────────────────────────┤ │ │ │ sparql_query │ 渐进式 SPARQL 查询 + 图谱扩展 │ │ │ │ concept_explain │ Schema 驱动的概念解释 │ │ │ │ structure_analysis │ Schema 驱动的结构分析 │ │ │ │ knowledge_update │ 事实提取 → 校验 → 写入 ★新增 │ │ │ │ general_chat │ 一般对话 / 领域关键词二次修正 │ │ │ └─────────────────────┴──────────────────────────────┘ │ │ │ │ 二次校验: general_chat + 领域关键词匹配 → 自动修正为 │ │ sparql_query │ │ │ │ sparql_query 意图时同步生成渐进式查询计划: │ │ Step 1: 精确匹配 (类型 + 名称 + 属性 FILTER) │ │ Step 2: 放宽条件 (去掉类型限制或最严格 FILTER) │ │ Step 3: 兜底浏览 (只保留 rdf:type 列出所有实例) │ └─────────────────────────────────────────────────────────┘ │ ├── intent = knowledge_update? ─────────────────────┐ │ │ ├── intent = sparql_query? ──────────────┐ │ │ │ │ └── intent = concept_explain / │ │ structure_analysis / general_chat │ │ │ │ │ ▼ ▼ ▼ ┌──────────────────────┐ ┌───────────────────────────┐ ┌──────────────────────┐ │ Stage 2: 直接回答 │ │ Stage 2: SPARQL 查询执行 │ │ Stage 2: 知识更新 ★ │ │ │ │ │ │ │ │ 基于裁剪后的 Schema │ │ 2a. LLM 生成的 SPARQL │ │ KBQA_KNOWLEDGE_ │ │ 文本，LLM 直接生成 │ │ ├ 本地修正 (IRI 补齐、 │ │ UPDATE_PROMPT │ │ 概念解释或结构分析 │ │ │ 禁选属性剔除、 │ │ ↓ │ │ │ │ │ SELECT DISTINCT) │ │ LLM 从对话上下文 + │ │ │ │ ├ NeSyS 快速验证 │ │ Schema 中提取结构化 │ │ │ │ │ (best effort) │ │ 事实 │ │ │ │ └ 渐进式执行 │ │ ↓ │ │ │ │ │ (有结果即停止) │ │ TBox 语义校验 │ │ │ │ │ │ (属性类型/domain/ │ │ │ │ 2b. 图谱扩展 │ │ functional 冲突) │ │ │ │ ├ 全文搜索定位种子实体 │ │ ↓ │ │ │ │ └ BFS 遍历 (最多 5 跳) │ │ TTL片段 → TDB2 写入 │ │ │ │ │ │ ↓ │ │ │ │ 2c. 兜底查询 (0 结果时) │ │ OxiRS 增量推理 │ │ │ │ ├ 全文字面量搜索 │ │ ↓ │ │ │ │ ├ 通配属性匹配 │ │ 结构化确认消息 │ │ │ │ └ 类级枚举 │ └──────────────────────┘ │ │ │ │ │ │ │ 底层的 Java 知识服务: │ │ │ │ → TDB2 查询 (含 FC 物化) │ │ │ │ → OxiRS BC 后向链 (透明) │ │ │ │ → 结果合并去重 │ │ │ │ │ │ │ │ 2d. 低置信度兜底 (非 │ │ │ │ sparql_query 但 │ │ │ │ confidence < 0.7) │ │ │ │ → 类级别统计浏览 │ │ └──────────────────────────────┘ │ │ │ ▼ │ ┌──────────────────────────────┐ │ │ Stage 3: 回答生成 │ │ │ │ │ │ knowledge_update → 结构化确认 │ │ │ "✅ 已更新 N 条三元组" │ │ │ │ │ │ sparql_query → │ │ │ KBQA_ANSWER_GENERATION_PROMPT│ │ │ 系统指令: 3 段式结构 │ │ │ (直接回答→洞察→建议) │ │ │ 流式输出 + 推理链剥离 │ │ │ │ │ │ 其他意图 → │ │ │ _agent_direct_answer() │ │ │ Schema 驱动的直接回答 │ │ └──────────────────────────────┘ │ │ │ ▼ │ ┌──────────────────────────────┐ │ │ Stage 4: 完成 │ │ │ │ │ │ SSE done: { │ │ │ intent, │ │ │ sparqlQuery, │ │ │ confidence, │ │ │ durationMs, │ │ │ knowledgeUpdate ★新增 │ │ │ } │ │ └──────────────────────────────┘ ``` ##### Schema 驱动的拓扑图展开（4 重展开策略） > 核心突破：将"查哪些类"从 LLM 概率性决策转为**确定性图遍历算法**。 OntoMind 独创的 Schema 拓扑分析引擎通过以下 4 重策略自动展开查询范围，确保不遗漏任何关联类： | 策略 | 触发条件 | 效果 | |------|---------|------| | **直接匹配** | 用户问题实体名匹配到类的标识属性值 | 精确定位目标实体的所有视图 | | **标识属性重叠** | 两个类共享同一标识属性（如 `station_name`）但不存在继承/等价关系 | **互补查询** — 两个类都查，而非渐进放宽后 skip | | **1-hop 对象属性链** | TDB2 中实际存在对象属性三元组连接 | 沿关系链查关联实体 | | **BFS 遍历（最多 5 跳）** | 高级扩展 | 4 层防护（边过滤 → 出边计数 → visited 去重 → 硬顶 5 跳），0 结果安全兜底 | **实现原理**： ``` Java 后端 Python Agent ───────── ──────────── GET /{id}/object-property-graph SchemaGraphExplorer ├─ 并行探测: classes + predicates + ├─ 构建邻接表 (class → target) │ objectProperties + dataProperties + domain ├─ 索引 identityOverlaps ├─ probeObjectPropertyConnections() └─ expand_classes_for_entity() │ → edges: [domainClass, rangeClass, → ExpandedQueryTarget[] │ propIri, tripleCount] └─ probeIdentityOverlaps() → LLM 每个 target 独立生成 → identityOverlaps: [{propIri, classes}] SPARQL，全部标记 complementary ``` 该机制从根本上解决了 SPARQL 查询中的类遗漏问题——此前 LLM 可能将不同粒度/维度的类（如 StationMonthly vs StationDaily）错误判定为"渐进放宽"关系，导致第二步查询因已有结果而被引擎跳过。 ##### SSE 流式安全过滤 保护 Agent 输出质量的多层安全防线： | 过滤器 | 适用场景 | 说明 | |--------|---------|------| | **节点级过滤器** | 多模 LangGraph Agent | 只将 synthesize 节点的 token/事件流式推送前端，屏蔽内部 intent/plan/execute 节点过程 | | **GLM 结构化推理过滤** | Zhipu GLM 模型 | 剥离编号式章节标记（`## 一、`等）和内部推理格式 | | **DeepSeek 推理过滤** | DeepSeek 模型 | 去除自我指涉句（如"根据查询结果"、"从数据来看"） | | **V4 Flash 口语化过滤** | DeepSeek V4 Flash | 过滤口语化推理填充（如"嗯"、"首先我需要"） | | **V4 Pro Prompt 泄露过滤** | DeepSeek V4 Pro | 过滤模型输出的系统 prompt 片段泄露 | | **Banner 装饰行过滤** | Hermes CLI | 过滤启动 Banner、框线等非内容字符 | | **ThinkFilter** | 本体提取 Agent | `` 标签内推理过程实时过滤，只输出最终结果 | ##### 知识更新 KBQA 首次实现了从对话到知识图谱的**完整写入闭环**： | 阶段 | 组件 | 说明 | |------|------|------| | **触发识别** | `KBQA_INTENT_PLAN_PROMPT` | LLM 从用户指令中识别 knowledge_update 意图（纠正/补充/新增语义） | | **事实提取** | `KBQA_KNOWLEDGE_UPDATE_PROMPT` | LLM 结合对话上下文 + 本体 Schema，输出结构化三元组事实（subjectIri/predicateIri/objectValue/objectType） | | **TBox 校验** | `NeuroSymbolicVerifier.validateTripleFacts()` | Java 后端校验属性类型、domain 匹配、functional property 冲突 | | **写入 TDB2** | `ReasoningService.loadTtlSnippet()` | 增量追加 TTL 片段到 TDB2 命名图，触发 OxiRS 增量推理 | | **确认反馈** | SSE stream | 结构化确认消息 + 更新前后对比，SSE done 事件含 knowledgeUpdate 字段 | --- #### 4.3 多模知识问答 (`/ontology-app/multi-modal-knowledge`) 独立的多模知识服务（`ontomind-multimodal`），基于 LangGraph 实现多源联合查询： ``` 用户问题 │ ▼ ┌─────────────┐ ┌─────────────────────────────────┐ │ intent_node │────▶│ 分类: sparql_query / │ │ 意图识别 │ │ semantic_search / graph_analytics│ └─────────────┘ │ / knowledge_fusion / general_chat│ └─────────────────────────────────┘ │ ▼ ┌───────────────┐ ┌─────────────────────────────────┐ │ execute_node │──▶│ QueryService.unified_query() │ │ 查询执行 │ │ ├─ 向量语义搜索 (vector_store) │ └───────────────┘ │ ├─ SPARQL 查询 (LLM 生成) │ │ ├─ 图分析 (PageRank/Betweenness) │ │ ├─ SWRL 推理 + SHACL 校验 │ │ └─ 知识融合 (跨 KB 联合) │ └─────────────────────────────────┘ │ ▼ ┌─────────────────┐ ┌─────────────────────────────────┐ │ synthesize_node │─▶│ LLM 融合多源结果为自然语言答案 │ │ 答案合成 │ │ SSE 流式输出 │ └─────────────────┘ └─────────────────────────────────┘ ``` --- #### 4.4 Agent 问答 (`/ontology-agent`) 基于 Hermes CLI 的全功能 AI 对话助手（详见 [Hermes CLI 本体智能体](#hermes-cli-本体智能体)），提供： - **流式对话**：SSE 流式推送，支持思考过程可视化（折叠展示）和逐字渲染 - **工具调用追踪**：每次 MCP 工具调用的输入/输出以 TracePanel 步骤树展示，含耗时统计 - **会话管理**：创建/切换/删除对话会话，历史消息持久化 - **模型选择**：`providerId::modelId` 格式动态切换 LLM - **技能系统**：CLI 内置技能 + MCP 工具 + 用户自定义技能，三源合一 - **文件生成与下载**：代码/报告/配置等生成文件可在线预览或下载 --- ### 5. 知识库管理 (`/knowledge-base`) 支持两类知识库： | 类型 | 支持后端 | 功能 | |------|----------|------| | **RAG 向量库** | Pinecone、Weaviate、Qdrant、Milvus、PgVector | 向量索引浏览、语义搜索 | | **图数据库** | Neo4j、FalkorDB、Apache AGE、HugeGraph | 图结构浏览、Cypher/Gremlin/SPARQL 查询 | - 连接测试、动态参数配置 - 跨知识库联合查询（Multi-KB 联邦 SPARQL） --- ### 6. 数据源与文件管理 **结构化数据** (`/datasource`)： - JDBC 数据源（MySQL/PostgreSQL/Hive/ClickHouse/Doris） - 连接测试、表发现、Schema 探测、数据分页预览（🆕 增至 1000 条） - 虚拟表抽象层：将外部数据表映射为平台内统一 Schema - **🆕 文件数据导入**：Excel/CSV/TXT → PostgreSQL 物理表，支持 AI 类型推断 + 分批写入 + 新建表/追加双模式（详见 [6+. 文件数据导入](#6-文件数据导入excelcsv--db)） **非结构化数据** (`/unstructured-data`)： - 文件夹管理（支持层级、重命名、删除） - 多格式上传与预览（PDF、Word/DOCX、Excel/XLSX、PPT/PPTX、CSV、TXT、Markdown、图片） - AI 文件转 Markdown（4 种模式）： - **标准模式**：常规文件 → Markdown - **本体抽取模式**：领域文档 → 本体结构 Markdown - **图本体模式**：含模板/示例的增强本体提取 - **SQL 生成模式**：本体 Markdown → SQL DDL --- ### 6+. 文件数据导入（Excel/CSV → DB） 平台支持将上传的 Excel、CSV、TXT 文件一键导入到 JDBC 数据源的物理数据库表中，实现文件数据到结构化存储的无缝流转。 **导入流程（3 步向导）：** ``` Step 1 Step 2 Step 3 ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 选择文件 │─────────▶│ 预览配置 │───────────▶│ 执行导入 │ │ +数据源 │ │ 类型映射 │ │ 进度追踪 │ └──────────┘ └──────────┘ └──────────┘ ``` | 步骤 | 说明 | |------|------| | **Step 1 — 选择文件与数据源** | 从已上传的 Excel/CSV/TXT 文件中选择目标文件，选择目标 JDBC 数据源（支持 schema 选择），选择新建表或追加到已有表 | | **Step 2 — 预览与配置** | AI 自动推断列类型（BIGINT / NUMERIC / DOUBLE PRECISION / DATE / TIMESTAMP / BOOLEAN / TEXT），支持手动覆盖类型、排除列、设置表名和批次大小（默认 1000 行/批） | | **Step 3 — 执行导入** | 异步执行分批写入，实时进度追踪，支持取消操作，失败自动记录错误信息 | **核心能力：** | 能力 | 说明 | |------|------| | **智能类型推断** | 扫描前 200 列数据，自动推断列类型（整数→BIGINT、小数→NUMERIC、日期→DATE/TIMESTAMP、布尔→BOOLEAN，兜底 TEXT） | | **空值检测** | 遍历数据样本检测 NULL 值，标记为 NULLABLE 列 | | **多 Sheet 支持** | Excel 文件支持选择特定 Sheet 导入 | | **双模式导入** | 新建表模式（自动建表 + 写入）和追加模式（写入到已有表，自动匹配列） | | **分批写入** | 默认 1000 行/批，避免大文件 OOM | | **取消支持** | 异步任务可随时取消，已写入数据不回滚（安全追加语义） | | **REST API** | `GET /api/v1/data-import/preview/{fileId}` — 预览推断 schema；`POST /api/v1/data-import/start` — 启动导入；`GET /api/v1/data-import/job/{id}` — 查询进度 | --- ### 7. 多模数据处理（🆕 MDP） 多模数据处理模块在「业务数据集成」与「本体自动构建」之间插入**数据探索与预处理**环节，基于 Apache Polaris + Jupyter AI + Ray 三大引擎，构建从数据发现到 AI 编码到大规模计算的全流程数据处理能力。 #### 7.1 元数据管理（Polaris Catalog） 基于 Apache Polaris 的统一数据目录，自动发现和同步全平台资产： ``` Polaris Catalog (ontomind) ├── datasource_{id}/ -- 结构化数据源表（JDBC Schema 自动同步） ├── files/ -- 非结构化文件/文件夹（Volume） ├── ontologies/ -- 本体模型（Model） ├── knowledge_bases/ -- 知识库连接（Connection） └── notebooks/ -- Notebook 资产 ``` | 能力 | 说明 | |------|------| | **自动资产发现** | `PolarisAutoSyncService` 启动时全量扫描平台数据源，通过 ontomind-server REST API 获取表结构、文件列表、本体/知识库列表，自动注册到 Polaris Catalog | | **增量变更同步** | 每 30 分钟定时增量扫描，对比 Polaris 已有资产与平台当前资产，增量注册新表、清理已删除资产 | | **实时通知触发** | ontomind-server 在创建/编辑/删除数据源/文件/本体/知识库时，异步通知 ontomind-mcp（`POST /catalog/refresh`），实现秒级 Catalog 更新 | | **RBAC 权限隔离** | 基于 OntoMind JWT Role → Polaris 命名空间权限映射（ADMIN 全权限 / DATA_ENGINEER 数据源权限 / BUSINESS_ANALYST 数据源+文件 / DOMAIN_EXPERT 本体权限 / VIEWER 只读） | | **资产标签与分类** | 支持表级标签（PII/finance 等）、业务分类（confidential/internal/public）、领域归属、负责人等元数据标注 | | **列级元数据** | 同步 JDBC `REMARKS` 注释，支持 PII 等敏感标签标注，AI 编码时自动感知并加脱敏逻辑 | | **Catalog REST API** | `GET /api/v1/mdp/catalog/namespaces` — 资产命名空间列表；`GET /api/v1/mdp/catalog/{ns}/tables/{name}` — 表 Schema + 采样数据；`GET /api/v1/mdp/catalog/search?q=` — 跨资产全文搜索 | | **降级策略** | Polaris 不可用时自动回退到 ontomind-server 数据（从 JDBC 直接获取表结构），确保 Catalog 功能不中断 | #### 7.2 Jupyter AI 交互式 Notebook JupyterLab 通过 iframe 嵌入前端，集成 Jupyter AI v3 + OntoMind Persona： ``` ┌──────────────────────────────────────────────────────┐ │ OntoMind 前端 │ │ ┌──────────┬────────────────────┬────────────┐ │ │ │ Catalog │ JupyterLab │ AI Chat │ │ │ │ 浏览器 │ (iframe 嵌入) │ Panel │ │ │ │ │ [Python Cell] │ NL→代码 │ │ │ │ │ [SQL Cell] │ 错误修复 │ │ │ │ │ [SPARQL Cell] │ 代码解释 │ │ │ │ │ [Markdown Cell] │ │ │ │ └──────────┴────────────────────┴────────────┘ │ └──────────────────────────────────────────────────────┘ ``` **核心能力：** | 能力 | 说明 | |------|------| | **AI 编码辅助** | NL → Python/SQL/SPARQL 代码生成，基于 MCP 实时获取全平台数据上下文（Schema/采样数据/本体/文件），生成的代码直接插入为 Notebook Cell | | **Schema-aware 代码** | LLM 自动查询 Catalog（`catalog_get_table_schema`）获取精确列名和类型，生成的 SQL/Python 代码准确率远超无上下文方案 | | **上下文感知** | AI 理解当前 Notebook 已有 Cell 内容和数据流，正确引用前序变量（如 `df = _cell_5`），避免重复加载数据 | | **错误修复 + 解释** | Cell 执行报错后，点击「AI 分析」自动分析错误堆栈并生成修复代码；`/explain` 命令解释选定代码 | | **OntoMind Persona** | Jupyter AI v3 自定义 Persona，通过 function calling 调用 ontomind-mcp 的 6 个 MCP 工具（catalog_list_namespaces / catalog_list_tables / catalog_get_table_schema / catalog_get_ontology_context / catalog_get_file_context / catalog_search），集成 PII 感知、代码工程理解、数据可视化建议 | | **3 种魔法 Cell** | `%%sql` — 直接执行 SQL 查询；`%%sparql` — 知识图谱查询；标准 Python Cell | | **模型选择** | 前端工具栏模型选择器 → ontomind-mcp 模型配置代理 → 复用平台已配置的 LLM（DeepSeek/Qwen/OpenAI/Zhipu/Custom），无需在 Notebook 中单独配置 API Key | | **JupyterHub 认证** | 自定义 `ontomind_jwt_auth.py` JWT 认证器，与平台认证体系统一，用户隔离（`/notebooks/{username}/`） | #### 7.3 多模计算任务（Ray Job） 基于 Ray Data 的异构计算任务管理，支持 Notebook 参数化执行和定时调度： | 能力 | 说明 | |------|------| | **Job CRUD** | 创建/编辑/删除 Ray 计算任务，绑定到指定 Notebook，支持自定义参数 JSON | | **定时调度** | 支持 Cron 表达式配置周期性执行（如每日统计任务、每周报表生成），一键启停 | | **手动触发** | 支持 Ad-hoc 即时执行，无需等待调度时间 | | **实时进度** | 任务状态轮询（10s 间隔）：pending → running → completed/failed，进度百分比可视化 | | **日志追踪** | 任务执行日志（stdout/stderr）在线查看，错误信息持久化 | | **Ray 集群状态** | 单机 Ray 模式，Ray Dashboard 内嵌访问，集群节点/资源监控 | | **REST API** | `GET/POST/PUT/DELETE /api/v1/mdp/jobs` — Job CRUD；`POST /api/v1/mdp/jobs/{id}/trigger` — 手动触发；`PUT /api/v1/mdp/jobs/{id}/schedule` — 配置调度 | #### 7.4 ontomind-mcp — 平台公共 MCP Server 独立于 ontomind-server 内置 MCP（11 个工具）的**公共 MCP 基础设施**，自建、解耦，供任何 MCP Client 消费： | 维度 | ontomind-server MCP (内置) | ontomind-mcp 🆕 (公共) | |------|--------------------------|----------------------| | **协议** | JSON-RPC + SSE（2024-11-05） | FastMCP（JSON-RPC） | | **工具数** | 11 个 | 6 个 | | **关注范围** | 本体知识检索与推理 | 全平台数据资产目录 | | **消费者** | Hermes CLI、外部 Agent | Jupyter AI、Hermes CLI、外部 Agent/IDE | | **依赖** | 与 Java 后端耦合 | 独立服务，Polaris/Server 降级运行 | **6 个 MCP 工具：** | 工具 | 说明 | |------|------| | `catalog_list_namespaces` | 列出所有资产命名空间（数据源/文件/本体/知识库分类） | | `catalog_list_tables` | 列出指定命名空间下的所有表/资产 | | `catalog_get_table_schema` | 获取表的完整 Schema（列名+类型+注释+标签）+ 采样数据 | | `catalog_get_ontology_context` | 获取本体语义上下文（类/属性/规则摘要），用于 AI 生成 SPARQL 时的 Schema 约束 | | `catalog_get_file_context` | 获取文件/文件夹列表，用于 AI 理解可用的非结构化数据 | | `catalog_search` | 跨所有资产类型全文搜索 | --- ### 8. 本体 Action 管理 基于业务 Action 需求的 AI 驱动标准操作流程（SOP）生成与 Skill 部署： | 阶段 | 说明 | |------|------| | **① 业务需求** | 用户用自然语言描述业务目标（如"当客户交易额超过 50 万时自动风险评估"） | | **② LLM 生成 SOP** | LLM 结合本体语义上下文（类/属性/SWRL 规则）自动生成标准操作流程（SOP），定义执行步骤和输入输出 | | **③ 专家审核** | 领域专家在线审核 SOP，支持编辑和状态流转（DRAFT → REVIEW → APPROVED → PUBLISHED） | | **④ LLM 生成 Skill** | 基于审核通过的 SOP，LLM 自动生成可执行的 Hermes Skill（SKILL.md 格式），含工具调用、推理逻辑和输出模板 | | **⑤ 下载部署到 Agent** | Skill 可直接下载或自动上传到 Hermes CLI 本体智能体，在对话中通过 `使用【skill_name】技能：` 语法调用 | **后端支撑：** - SOP CRUD + 状态机（DRAFT/REVIEW/APPROVED/PUBLISHED） - LLM SOP 生成（`/agent/generate-sop`）— 自然语言 → 结构化 SOP 步骤 - LLM Skill 生成（`/agent/generate-skill-from-sop`）— SOP → SKILL.md - 与 Hermes CLI 技能系统集成（自动上传到 `~/.hermes/skills/`） --- ### 9. 系统管理 **模型管理** (`/model-management`) — 支持用户配置任意第三方 LLM： 平台内置 5 种提供商类型，其中 **"自定义 (CUSTOM)"** 类型允许接入任何兼容 OpenAI API 的大模型服务。 | 提供商类型 | 说明 | 默认 API 地址 | |-----------|------|---------------| | **DeepSeek** | DeepSeek 官方模型 | `https://api.deepseek.com` | | **Qwen (通义千问)** | 阿里云通义千问系列 | 用户自定义 | | **OpenAI** | OpenAI 官方模型 | `https://api.openai.com` | | **Zhipu (智谱 GLM)** | 智谱 AI GLM 系列 | `https://open.bigmodel.cn/api/paas/v4` | | **Custom (自定义)** | **任意 OpenAI 兼容 API** | 用户自定义 | **自定义第三方模型的配置方式**： 1. 进入模型管理页面，点击"添加提供商" 2. 填写配置： - **名称**：任意可读名称（如 `Ollama 本地模型`、`vLLM 服务`、`Together AI`） - **类型**：选择"自定义 (Custom)" - **API 地址**：OpenAI 兼容的 Base URL（如 `http://localhost:11434/v1`、`https://api.together.xyz/v1`） - **API 密钥**：对应服务的认证密钥 3. 添加模型： - **模型 ID**：API 期望的模型名称（如 `llama3:8b`、`mistral-large`、`mixtral-8x7b`） - **最大 Token**：按模型上下文窗口设置 - **温度 (0~2)**：控制输出随机性 - **能力标签**：标注模型擅长的任务（本体提取/实体识别/关系抽取/规则抽取/NL2SPARQL/对话问答/推理/代码生成） > **兼容范围**：任何提供 OpenAI 兼容 API 的大模型服务均可接入，包括但不限于 Ollama、vLLM、LM Studio、Together AI、Groq、Fireworks AI、本地私有化部署等。 **模型解析流程**： ``` 前端 → providerId::modelId → Agent 服务查询后端 API → 获取 provider.apiUrl + apiKey + model.maxTokens → 构造 ChatOpenAI 实例 → 调用 LLM ``` 所有 LLM 调用均使用 `langchain_openai.ChatOpenAI` 统一客户端，不区分提供商类型，因此任何 OpenAI 兼容接口都能即插即用。 **模型管理页面的其他功能**： - 提供商启用/禁用开关（禁用后所有关联模型不可用） - API 连接测试（发送 `/models` 请求验证连通性） - 在线对话测试（可实时调节温度和 Token 上限，直接测试模型效果） - 通过环境变量 `DEFAULT_LLM_API_KEY` 可启动时自动初始化默认提供商 **用户管理** (`/system/users`)： - 5 种角色：ADMIN、DATA_ENGINEER、BUSINESS_ANALYST、DOMAIN_EXPERT、VIEWER - CRUD + 密码重置 + 状态管理 **备份恢复** (`/system/backup`)： - 手动/定时备份：数据库（PostgreSQL）+ Redis + 文件存储 + Jena TDB2 - 从备份记录恢复 / 从上传文件恢复 / 从本地文件恢复 - 压缩、保留策略、备份统计仪表盘 --- ## 技术栈总览 | 层级 | 技术 | 版本 | |------|------|------| | **前端** | React + TypeScript + Vite | 18.3 / 5.5 / 5.4 | | **UI** | Ant Design + AntV G6 + Ant Design Charts | 5.20 / 5.0 / 2.2 | | **后端** | Spring Boot + Java | 3.2.5 / 17 | | **安全** | Spring Security + JWT (jjwt) | HMAC-SHA512 | | **数据库** | PostgreSQL + Flyway | 16 / 40 migrations | | **缓存** | Redis | 7.4 | | **本体推理** | OWL API + HermiT + Pellet (Openllet) | 5.1.20 / 1.3.8 / 2.6.5 | | **规则推理** | OxiRS gRPC (Rust, tonic) | v0.3.0 | | **三员组存储** | Apache Jena TDB2 + Fuseki | 4.10.0 | | **Agent 服务** | FastAPI + LangGraph + LangChain | Python 3.11 | | **LLM** | OpenAI-compatible API（DeepSeek/Qwen/Zhipu） | - | | **文件解析** | Apache POI + PDFBox + Mammoth + JSZip | - | | **元数据管理** 🆕 | Apache Polaris (内置 H2) + PolarisAutoSync | 1.5.0+ | | **交互式 Notebook** 🆕 | JupyterLab + Jupyter AI v3 + JupyterHub + PyIceberg | 4.x / 3.0 / 5.x / 0.7 | | **计算引擎** 🆕 | Ray Data (单机模式) | 2.10+ | | **MCP Server** 🆕 | FastMCP (Python) — 公共 6 工具 MCP Server | 0.4+ | | **对象存储** 🆕 | MinIO (S3 兼容) | latest | | **部署** | Docker Compose + Nginx + shell scripts | 12 容器 | --- ## 快速部署 ### 环境要求 - Linux x86_64（推荐 Ubuntu 24.04） - Docker 26+ + Docker Compose v2 - 磁盘预留 ≥ 20GB ### 一键启动 ```bash # 1. 配置环境变量 cp docker/.env.example docker/.env # 编辑 docker/.env，填写 JWT_SECRET、DB_PASSWORD 等 # 2. 启动全部服务 ./restart.sh all # 3. 访问 # http://localhost:17386/ontomind # 默认账号: admin / admin123 ``` ### 常用命令 ```bash ./restart.sh all # 启动全部服务（生产模式） ./restart.sh infra # 仅启动基础设施（PostgreSQL + Redis） ./restart.sh docker-dev # 启动开发环境 ./restart.sh stop # 停止全部服务 ./restart.sh status # 查看服务状态 ./restart.sh logs [svc] # 查看日志 ./restart.sh backup # 手动备份 ./restart.sh restore # 从备份恢复 ./restart.sh build --no-cache # 重新构建镜像 ``` ### 端口映射 | 服务 | 端口 | 说明 | |------|------|------| | 前端 + 反向代理 | 17386 | Nginx，统一入口 | | Java 后端 API | 8080 | REST API + Swagger（`/swagger-ui.html`） | | Python Agent | 8001 | LLM 推理 + 本体构建 Agent | | 多模问答服务 | 8090 | LangGraph + Jena | | 公共 MCP Server 🆕 | 8101 | ontomind-mcp：Catalog API + MCP 工具 | | Ray 任务管理 🆕 | 8102 | ontomind-ray：Job CRUD + 调度 | | JupyterLab 🆕 | 8888 | Jupyter AI Notebook（iframe 嵌入） | | Polaris Catalog 🆕 | 8181 | Apache Polaris 统一元数据管理 | | MinIO S3 🆕 | 9000/9001 | 对象存储（Console/API） | | PostgreSQL | 5432 | 业务数据库 | | Redis | 6379 | 缓存服务 | | Fuseki SPARQL | 3030 | 嵌入式，通过 Java 后端访问 | ### OxiRS 推理引擎编译 OxiRS 是 Rust 编写的 gRPC 推理引擎，源码位于 `ontomind-agent/lib/oxirs-src/`。修改源码后需重新编译。 **方式一：WSL2 编译（推荐）** ```bash # 在 WSL2 中执行（需要 Rust 1.83+） sudo apt-get install -y pkg-config libssl-dev protobuf-compiler curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source ~/.cargo/env # 编译 cd /mnt/d/本体平台/ontomind-platform/ontomind-agent/lib/oxirs-src cargo build --release -p oxirs # 复制到 lib/ 目录供 Docker 构建使用 cp target/release/oxirs /mnt/d/本体平台/ontomind-platform/ontomind-agent/lib/oxirs/oxirs # 回到 PowerShell 构建镜像并重启 cd D:\本体平台\ontomind-platform bash docker/oxirs/build.sh --skip-build docker compose -f docker/docker-compose.yml build oxirs --no-cache docker compose -f docker/docker-compose.yml up -d oxirs ``` **方式二：Docker 内编译（带缓存加速）** ```bash cd D:\本体平台\ontomind-platform\docker\oxirs # 首次编译（~25 分钟），后续增量编译（~1-3 分钟） rm -f ../../ontomind-agent/lib/oxirs/oxirs ./build.sh --no-cache # 重建镜像并重启 cd .. docker compose -f docker/docker-compose.yml build oxirs --no-cache docker compose -f docker/docker-compose.yml up -d oxirs ``` > Docker 编译使用 `--mount=type=cache` 持久化 Cargo 缓存到宿主机，重复编译只需重编变更的 crate。 **验证** ```bash docker logs ontomind-oxirs | head -12 # 预期输出： # 🚀 OxiRS gRPC Reasoning Server # Version: 0.3.0 # Debug mode: OFF (set OXIRS_DEBUG=1 to enable) # IncrementalUpdate: incrementalUpdate RPC (ADD supported, REMOVE not yet) ``` **开启调试模式** 在 `docker/docker-compose.yml` 的 `oxirs.environment` 中添加： ```yaml OXIRS_DEBUG: "1" ``` --- ## MCP 集成 平台实现双 MCP Server 架构： ### 1. ontomind-server 内置 MCP（本体知识服务） 基于 [Model Context Protocol](https://spec.modelcontextprotocol.io/)（MCP 2024-11-05）的 **11 个本体知识工具**，可供任何兼容的 AI Agent 客户端使用。 | 工具 | 说明 | |------|------| | `sparql_query` | 执行 SPARQL 查询 | | `get_ontology_schema` | 获取本体 Schema（类+属性） | | `search_concepts` | 模糊搜索本体概念（仅搜索 `owl:Class`，不搜索实例实体名） | | `get_class_hierarchy` | 获取类层次结构 | | `get_property_info` | 获取属性详情 | | `list_ontologies` | 枚举所有本体模型（自动过滤实例图/Pellet 中间模型，只返回已完成实例化的本体） | | `get_individuals` | 查询个体实例列表 | | `get_individual_details` | 查询个体详情 | | `get_statistics` | 获取本体统计信息 | | `ontology_ask` | 🆕 本体知识问答：输入自然语言问题，通过 Agent KBQA 引擎进行智能推理和回答，内部自动完成意图识别→SPARQL生成→知识检索→答案生成 | | `entity_full_profile` | 🆕 实体完整画像：输入实体名称，一次调用聚合基本信息 + 所有关联维度详情（线索/产品/项目/评分等），替代 6-7 次串行 SPARQL，查询时间从 60-70s 降至 2-5s | **接入方式**： - **JSON-RPC 端点**：`POST http://localhost:8080/mcp` - **REST 端点**：`POST http://localhost:8080/mcp/tools/call` - **SSE 流式**：`POST http://localhost:8080/mcp/tools/call-stream` **MCP 安全配置**（可选启用）： 可通过环境变量启用 API Key 认证： ```bash # 启用 MCP 安全（生产环境推荐） MCP_SECURITY_ENABLED=true # 静态 API Key（兜底用，不配置则仅使用数据库动态 Key） MCP_API_KEY=your-secret-key # 工具白名单（逗号分隔，不配置则暴露全部 11 个工具） MCP_ENABLED_TOOLS=sparql_query,get_ontology_schema,ontology_ask ``` | 特性 | 说明 | |------|------| | **API Key 双通道认证** | ① 数据库动态 Key（SHA-256 哈希，平台内生成/销毁/启停）→ ② 环境变量静态 Key 兜底 | | **工具白名单** | 配置 `MCP_ENABLED_TOOLS` 按需暴露工具子集，适用于不同场景的权限隔离 | | **请求级限定** | 支持 URL 参数 `?ontology_id=xxx` 限定可见本体范围（多租户场景） | > **接入提示**：所有本体共享同一个 MCP 端点 `/ontomind/mcp`（Nginx 代理），调用工具时通过 `ontology_id` 参数指定目标本体。Nginx 已配置 Streamable HTTP 支持（长连接、SSE 流式、无缓冲），读写超时设为 21600s。 ### 2. ontomind-mcp 公共 MCP Server 🆕（全平台数据资产目录） 独立于 Java 后端的**公共 MCP 基础设施**（Port 8101），基于 FastMCP，自建、解耦，聚合全平台数据资产上下文，供 Jupyter AI / Hermes CLI / 外部 Agent 消费。 | 工具 | 说明 | |------|------| | `catalog_list_namespaces` | 列出所有资产命名空间（数据源/文件/本体/知识库分类） | | `catalog_list_tables` | 列出指定命名空间下的所有表/资产 | | `catalog_get_table_schema` | 获取表的完整 Schema（列名+类型+注释+标签）+ 采样数据 | | `catalog_get_ontology_context` | 获取本体语义上下文（类/属性/规则摘要），用于 AI 生成 SPARQL 时的 Schema 约束 | | `catalog_get_file_context` | 获取文件/文件夹列表，用于 AI 理解可用的非结构化数据 | | `catalog_search` | 跨所有资产类型全文搜索 | **接入方式**： - **MCP JSON-RPC**：`http://localhost:8101/mcp`（Jupyter AI / Hermes CLI / 外部 Agent） - **Catalog REST API**：`http://localhost:8101/api/v1/mdp/*`（前端 /mdp/ 页面） **降级能力**：Polaris 不可用时自动回退到 ontomind-server REST API，确保资产查询不中断。 --- ## 项目结构 ``` ontomind-platform/ ├── ontomind-server/ # Java 后端（Spring Boot 3.2） │ └── src/main/java/com/ontomind/ │ ├── ontology/ # 本体管理（CRUD/推理/导入导出） │ ├── instantiation/ # 实例化管道（5步流程+调度） │ ├── knowledgebase/ # 知识库管理（RAG+Graph） │ ├── mcp/ # MCP Server（JSON-RPC+SSE） │ ├── connector/ # 数据源连接器（JDBC/REST/File） │ ├── multikb/ # 跨知识库联邦查询 │ ├── rule/ # 业务规则/SWRL 管理 │ ├── skill/ # 技能定义与执行 │ ├── query/ # SPARQL & NL 查询 │ ├── backup/ # 备份恢复 │ └── auth/ # 认证与用户管理 ├── ontomind-agent/ # Python Agent 服务（FastAPI） │ └── src/ontomind_agent/ │ ├── agents/ # Build Agent（Init→Plan→Execute→Verify） │ ├── orchestrator/ # 构建流水线编排 │ ├── routes/ # API 路由（build/inference/query/pipeline/hermes） │ ├── llm/ # LLM 网关 + 兼容层 + 全部 Prompt 模板 │ └── multimodal/ # 多模知识 Agent（LangGraph） ├── ontomind-multimodal/ # 多模知识服务（FastAPI+LangGraph+Jena） │ └── src/ontomind_multimodal/ │ ├── graph/nodes/ # Agent 节点（intent→plan→execute→synthesize） │ └── services/ # 查询服务 + Jena 客户端 + LLM 解析 ├── ontomind-mcp/ 🆕 # 平台公共 MCP Server（FastAPI + FastMCP） │ └── src/ │ ├── mcp/server.py # 6 个 MCP 工具定义（catalog_list_namespaces 等） │ ├── api/catalog.py # Catalog REST API（namespace/table/schema/search/refresh） │ ├── api/notebook.py # Notebook CRUD + 模型配置代理 │ ├── api/ai.py # AI 配置接口（模型列表/providers） │ ├── services/polaris_client.py # Polaris REST API 客户端 │ ├── services/polaris_sync.py # PolarisAutoSync 元数据自动发现引擎 │ └── services/server_client.py # ontomind-server REST API 客户端 ├── ontomind-notebook/ 🆕 # Jupyter AI Notebook 容器构建 │ ├── jupyter_ai_config.py # Jupyter AI v3 配置（MCP/Persona） │ ├── personas/ontomind_unified_persona.py # OntoMind Persona（6 个 function call） │ ├── jupyterhub/jupyterhub_config.py # JupyterHub 配置 │ ├── jupyterhub/ontomind_jwt_auth.py # JWT 认证器 │ ├── launch_jupyter.py # 启动脚本 │ └── executor.py # Notebook 参数化执行器 ├── ontomind-ray/ 🆕 # Ray 计算任务管理服务（FastAPI） │ └── src/ │ ├── api/jobs.py # Ray Job CRUD + 调度 + 触发 + 日志 │ └── services/scheduler.py # Cron 定时调度引擎 ├── ontomind-web/ # 前端 SPA（React 18 + Ant Design 5） │ └── src/pages/ │ ├── Dashboard/ # 仪表盘 │ ├── Ontology/ # 本体模型管理（AI 提取/可视化编辑/推理/导入导出） │ ├── OntologyManager/ # 本体管理增强精调（对象类型/关系类型/SWRL规则） │ │ └── components/ │ │ ├── DiscoverView.tsx # 总览仪表盘 │ │ ├── ObjectListView.tsx # 对象类型运维列表 │ │ ├── LinkTypesView.tsx # 关系类型表格视图 │ │ ├── LinkTypesGraphView.tsx # 关系类型 G6 交互图谱 │ │ ├── LogicRulesView.tsx # SWRL 规则可视化配置 │ │ ├── ActionsView.tsx # 动作类型管理（规划中） │ │ └── editors/VisualComposer.tsx # SWRL Atom 可视化构建器 │ │ └── atoms/AtomRow.tsx # Atom 编辑行组件 │ ├── Instantiation/ # 实例化流水线 │ ├── KnowledgeBase/ # 知识库管理 │ ├── OntologyAgent/ # Hermes CLI 对话助手 │ ├── OntologyApp/ # 知识服务（KBQA/多模问答） │ ├── MultimodalDataProcessing/ 🆕 # 多模数据处理 │ │ ├── MdpCatalog.tsx # 元数据管理（Polaris 目录浏览器） │ │ ├── MdpNotebook.tsx # Notebook AI 管理列表 │ │ ├── MdpJobs.tsx # 多模计算任务管理 │ │ └── NotebookWizard.tsx # Notebook 创建向导 │ ├── ActionManagement/ 🆕 # 本体Action管理（SOP→Skill） │ │ ├── SopEditor.tsx # SOP 编辑器 │ │ └── flowEditors/ # 流式编辑器（SOP/Skill） │ └── System/ # 系统管理 ├── docker/ # Docker Compose + Nginx 配置 + 备份脚本 │ ├── docker-compose.yml # 生产环境编排（12 容器） │ ├── docker-compose.dev.yml │ ├── docker-compose.infra.yml │ ├── init-mdp-db.sql # 🆕 MDP 数据库初始化 │ └── backup-mdp.sh # 🆕 MDP 备份脚本 ├── docs/ │ ├── MCP-USAGE.md # MCP 使用文档 │ ├── schema-driven-sparql-generation-design.md # Schema 驱动的 SPARQL 自动生成方案 │ ├── kbqa-prompt-optimization-design.md # KBQA 提示词优化设计方案 │ ├── unified-notebook-design.md # 统一 Notebook 设计方案 │ ├── multimodal-data-processing-design.md # 🆕 多模数据处理模块设计方案 │ ├── databricks-unity-catalog-open-source-components.md # Unity Catalog 参考 │ └── hermes-skill/ # Hermes 技能开发文档 └── restart.sh # 服务管理脚本（启动/停止/备份/恢复/构建） ``` --- ## 版本历史 - **v1.0.0-SNAPSHOT** — 当前主分支 - 近期更新（2026-06 下旬）： - **🆕 多模数据处理引擎（Polaris + Jupyter AI + Ray）**：全新独立模块「多模数据处理」，填补「数据接入」与「本体构建」之间的数据探索与预处理空白 - **Apache Polaris 统一元数据管理**：自动部署零配置，PolarisAutoSync 引擎启动时全量扫描平台资产（数据源表/文件/本体/知识库）并注册到 Polaris Catalog；增量变更秒级同步（ontomind-server 实时通知 + 30 分钟兜底定时扫描）；对标 Databricks Unity Catalog 的 RBAC 权限隔离（5 角色→Polaris ACL）、资产标签分类（PII/domain/owner）、列级元数据增强（JDBC REMARKS + PII 标签），AI 编码时自动感知数据敏感级别 - **ontomind-mcp 公共 MCP Server**：自建独立服务（Port 8101），6 个标准 MCP 工具（catalog_list_namespaces / catalog_list_tables / catalog_get_table_schema / catalog_get_ontology_context / catalog_get_file_context / catalog_search），聚合全平台数据资产上下文，Polaris 不可用时自动降级到 ontomind-server REST API - **Jupyter AI 交互式 Notebook**：JupyterLab 嵌入前端 + Jupyter AI v3 + OntoMind Unified Persona（6 个 MCP function call），AI 编码辅助（NL→Python/SQL/SPARQL 代码生成 + Schema-aware 上下文 + Cell 变量依赖感知），3 种魔法 Cell（%%sql/%%sparql/Python），模型选择复用平台 LLM 配置，JupyterHub JWT 认证 - **Ray 异构计算引擎**：Ray Data 驱动的计算任务管理（Job CRUD + Cron 定时调度 + 手动触发 + 进度追踪 + 日志管理），单机 Ray 模式 - **🆕 文件数据导入（Excel/CSV → DB）**：AI 自动类型推断（扫描前 200 列智能推断 BIGINT/NUMERIC/DATE/TIMESTAMP/BOOLEAN/TEXT）+ 空值检测 + 分批写入（1000 行/批）+ 新建表/追加双模式 + 取消支持 + 多 Sheet 支持 - **🆕 本体 Action 管理**：业务需求 → LLM 生成 SOP → 专家审核 → LLM 生成 Skill → 下载部署 Agent 全生命周期管理，SOP 状态机（DRAFT→REVIEW→APPROVED→PUBLISHED），技能自动上传 Hermes CLI - **实例化增强**：选择部分表映射能力增强准确率；互逆对象属性自动声明（inverseOf）；Skill 生成保存提示词增强 - **结构化数据预览增强**：数据预览数量从默认调整到 1000 条；PG 备注信息（REMARKS）显示 - **知识更新增强**：实体解析优化、属性 IRI 标准化、旧值自动覆盖与显式删除 - 近期更新（2026-06 上旬）： - **KBQA Schema 驱动拓扑图展开**：新增强大的 SchemaGraphExplorer 基于对象属性拓扑图自动展开查询范围——标识属性重叠检测（identityOverlaps，如 StationMonthly/StationDaily 共享 station_name）→ 互补查询而非渐进放宽 → 1-hop 对象属性链展开 → BFS 遍历（5 层防护）。从根源上消除 LLM 主观判断类间关系导致的类遗漏问题，将"查哪些类"从概率性 LLM 决策转为确定性图遍历 - **SSE 流式安全过滤**：多模服务按节点过滤 SSE 流（只暴露 synthesize 节点输出，屏蔽内部节点过程）；Agent 端 4 类推理链泄露剥离（GLM 编号式章节 / DeepSeek 自我指涉 / V4 Flash 口语化推理 / V4 Pro prompt 泄露），Banner 和装饰行自动过滤 - **SPARQL 生成质量优化**：每类选取 2-3 个最有价值属性、CONTAINS 模糊匹配、OPTIONAL 多属性绑定；后处理管线（系统前缀剥离 → 禁止属性剔除 → label 修正 → DISTINCT 注入）；3 次重试 + 智能提取；schema 元数据诊断日志 - **知识查询深度增强**：KBQA 回答从表面数据罗列升级为关系驱动的因果分析 + 经验判断 + 关联溯源，利用本体关系链追溯根本原因而非仅给出数值 - **规则推理增强赋值能力**：完善规则推理对计算/聚合/条件赋值等场景的支持，增强本体知识查询 chat 返回深度 - **本体提取质量强化**：Prompt 重构（反过度分析/SWRL 标准模式库/TTL 结构输出铁律/拼音→英文命名/文档参考来源标记）；TtlSyntaxFixer 兼容 `var:` 前缀 SWRL 变量、自动检测前缀类型 - **属性管理 + MCP 工具完善**：对象类型/关系类型属性面板增强；MCP 工具输入输出标准化；TDB2 数据标注（✅⚠️）用于 LLM 区分有/无实例属性 - **非结构化文件在线编辑**：文档管理模块支持文件在线编辑保存；流水线实例化 Step4 合成 TTL 在线编辑能力增强 - **实例化流水线增强**：Step1 主键检测从表级细化为列级；外键字段兼容；保存 TTL 后同步 Agent 端预览；数据预览实时刷新 - **前端体验优化**：全链路中文标签增强；链路拓扑图可视化优化；知识问答服务交互改进 - **Docker 性能优化**：镜像体积优化（消除 build-cache COPY 层残留、排除 oxirs-src/target 构建上下文）；增量编译缓存持久化；knowledge 服务精简依赖移除 langgraph/langchain/celery（~350MB）；多模服务 PyTorch 从 CUDA 版切换到 CPU-only（~2.5GB→~200MB） --- ## License Proprietary. All rights reserved.