# OntoMind

**Repository Path**: abao365_admin/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**: 26
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## 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% 以上），支撑多跳推理和长链关联任务 |
| **多租户数据隔离** | 支持多个租户独立管理本体实例和数据源，适用于 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 多源联合查询
- Semantica 语义层：KG 构建、语义搜索、图分析、知识融合、SHACL 校验

### 7. MCP 标准协议
- 实现 Model Context Protocol (2024-11-05)，9 个标准工具
- 支持 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 一键部署，全链路健康检查

---

## 系统架构

```
┌──────────────────────────────────────────────────────────────────┐
│                         Nginx (17386)                            │
│                   前端 SPA + 反向代理路由                           │
└──────┬────────────────┬──────────────────┬───────────────────────┘
       │                │                  │
       ▼                ▼                  ▼
┌─────────────┐  ┌─────────────┐  ┌──────────────────┐
│ ontomind-web│  │ontomind-    │  │ontomind-         │
│ (React SPA) │  │server       │  │multimodal (8090) │
│             │  │(8080)       │  │LangGraph+Semantica│
└─────────────┘  │SpringBoot3  │  │FastAPI            │
                 │JPA+Security │  └────────┬─────────┘
                 │Jena TDB2    │           │
                 │HermiT/Pellet│           │
                 │Fuseki(3030) │           │
                 └──┬────┬─────┘           │
                    │    │                 │
       ┌────────────┼────┼─────────────────┘
       │            │    │
       ▼            ▼    ▼
┌──────────┐  ┌──────────┐  ┌─────────────┐
│ OxiRS    │  │ontomind- │  │PostgreSQL+  │
│(50051)   │  │agent     │  │Redis (基础)  │
│gRPC推理  │  │(8000)    │  │             │
│Rust原生  │  │FastAPI   │  └─────────────┘
│FC+BC+增量│  │Build Agent│
└──────────┘  └──────────┘
```

### 服务说明

| 服务 | 端口 | 技术栈 | 职责 |
|------|------|--------|------|
| **Nginx** | 17386 | Nginx + 静态资源 | 前端 SPA 托管，反向代理到后端和 Agent |
| **ontomind-server** | 8080 | Spring Boot 3.2 + Java 17 | 核心业务逻辑：本体 CRUD、推理、实例化管道、MCP Server、数据源管理 |
| **ontomind-agent** | 8000 | FastAPI + Python 3.11 | LLM 驱动的本体构建 Agent（Init→Plan→Execute→Verify）、KBQA、Hermes CLI 集成 |
| **ontomind-multimodal** | 8090 | FastAPI + LangGraph + Semantica | 多模知识问答 Agent：意图识别→计划生成→执行（SPARQL/语义搜索/图分析/知识融合）→答案合成 |
| **OxiRS** | 50051 | Rust + tonic/gRPC | 原生规则推理引擎：6 RPC（ForwardChain / BackwardChain / IncrementalUpdate / RegisterRules / RemoveRules / HealthCheck），FC+BC+增量推理，RETE 网络 + 半朴素迭代 |
| **PostgreSQL 16** | 5432 | PostgreSQL + Flyway | 业务数据持久化，27 个迁移脚本管理 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）
- **多模语义**：Semantica 0.4.0（KG 构建、向量搜索、图分析、知识融合、SHACL 校验）
- **前端可视化**：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 深度集成，可直接调用平台的 9 个 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 提供的 9 个标准知识库工具（SPARQL 查询、本体 schema、概念搜索等） |
| **磁盘技能** | 用户上传至 `~/.hermes/skills/` 的自定义技能（SKILL.md 格式） |

### 流式对话特性

- **思考过程可视化**：`<thinking>` 块内容折叠显示，用户可查看 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 意图）→ SPARQL 执行/知识更新/直接回答 → 流式答案生成（SSE） |
| **知识更新** | `/agent` | LLM 事实提取 → NeSyS TBox 校验 → TDB2 增量写入 → 结构化确认反馈（SSE） |

---

## 功能模块与使用流程

### 1. 快速入门四步走

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ ① 导入   │───▶│ ② AI提取 │───▶│ ③ 审核   │───▶│ ④ 问答   │
│ 文档/数据 │    │ 本体模型 │    │ 验证优化 │    │ 与应用   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
```

**Step 1 — 导入文档或连接数据源**
- 上传 Markdown 行业标准文档、PDF、Word 等
- 配置 JDBC 数据源连接（MySQL/PostgreSQL/Hive/ClickHouse/Doris）
- 文件自动解析为虚拟表，供后续实例化使用

**Step 2 — AI 提取本体模型**
- 选择 LLM 模型，将文档通过 SSE 流式转换为标准 OWL2 本体
- 自动生成分类（Classes）、对象属性（Object Properties）、数据属性（Data Properties）、SWRL 规则、TTL 内容
- 支持 FIBO/IOF 等行业参考本体的自动对齐

**Step 3 — 审核与验证**
- 在可视化图形编辑器中查看、编辑类层次和关系（Protege 风格，拖拽连线和节点）
- 运行 HermiT/Pellet 推理器验证一致性
- 自动修复检测到的问题（Auto-Fix）

**Step 4 — 问答与应用**
- 实例化本体：配置数据源映射 → 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  ★新增      │
│                      │ }                             │
│                      └──────────────────────────────┘
```

##### 知识更新

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  │──▶│ SemanticaService.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 探测、数据分页预览
- 虚拟表抽象层：将外部数据表映射为平台内统一 Schema

**非结构化数据** (`/unstructured-data`)：
- 文件夹管理（支持层级、重命名、删除）
- 多格式上传与预览（PDF、Word/DOCX、Excel/XLSX、PPT/PPTX、CSV、TXT、Markdown、图片）
- AI 文件转 Markdown（4 种模式）：
  - **标准模式**：常规文件 → Markdown
  - **本体抽取模式**：领域文档 → 本体结构 Markdown
  - **图本体模式**：含模板/示例的增强本体提取
  - **SQL 生成模式**：本体 Markdown → SQL DDL

---

### 7. 系统管理

**模型管理** (`/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 / 27 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 |
| **语义层** | Semantica | 0.4.0 |
| **LLM** | OpenAI-compatible API（DeepSeek/Qwen/Zhipu） | - |
| **文件解析** | Apache POI + PDFBox + Mammoth + JSZip | - |
| **部署** | Docker Compose + Nginx + shell scripts | - |

---

## 快速部署

### 环境要求
- 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 <file>  # 从备份恢复
./restart.sh build --no-cache  # 重新构建镜像
```

### 端口映射
| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 + 反向代理 | 17386 | Nginx，统一入口 |
| Java 后端 API | 8080 | REST API + Swagger（`/swagger-ui.html`） |
| Python Agent | 8001 | LLM 推理 + 本体构建 Agent |
| 多模问答服务 | 8090 | LangGraph + Semantica |
| 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 集成

平台实现了 [Model Context Protocol](https://spec.modelcontextprotocol.io/)（MCP 2024-11-05），可供任何兼容的 AI Agent 客户端使用。

### 可用工具（9 个）
| 工具 | 说明 |
|------|------|
| `sparql_query` | 执行 SPARQL 查询 |
| `get_ontology_schema` | 获取本体 Schema（类+属性） |
| `search_concepts` | 模糊搜索本体概念 |
| `get_class_hierarchy` | 获取类层次结构 |
| `get_property_info` | 获取属性详情 |
| `list_ontologies` | 枚举所有本体模型 |
| `get_individuals` | 查询个体实例列表 |
| `get_individual_details` | 查询个体详情 |
| `get_statistics` | 获取本体统计信息 |

### 接入方式
- **JSON-RPC 端点**：`POST http://localhost:8080/mcp`
- **REST 端点**：`POST http://localhost:8080/mcp/tools/call`
- **SSE 流式**：`POST http://localhost:8080/mcp/tools/call-stream`

---

## 项目结构

```
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+Semantica）
│   └── src/ontomind_multimodal/
│       ├── graph/nodes/     # Agent 节点（intent→plan→execute→synthesize）
│       └── services/        # Semantica 语义层 + Jena 客户端 + LLM 解析
├── 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/多模问答）
│       └── System/          # 系统管理
├── docker/                  # Docker Compose + Nginx 配置 + 备份脚本
│   ├── docker-compose.yml   # 生产环境编排（7 服务）
│   ├── docker-compose.dev.yml
│   └── docker-compose.infra.yml
├── docs/
│   └── MCP-USAGE.md         # MCP 使用文档
└── restart.sh               # 服务管理脚本（启动/停止/备份/恢复/构建）
```

---

## 版本历史

- **v1.0.0-SNAPSHOT** — 当前主分支
- 近期更新（2026-06）：
  - **本体管理增强人工精调**：新增 Ontology Manager 四位一体工作台（总览/对象类型/关系类型/逻辑规则），SWRL 规则可视化配置（VisualComposer 拖拽式 Atom 构建 + AI 辅助生成 + 语法校验 + 规则测试 + LLM 解释），LinkTypes G6 交互式图谱视图，对象类型/关系类型在线编辑与 TTL 双向同步
  - **SWRL 规则引擎增强**：SwrlBuiltinCatalog 内置函数静态目录（7 大类 50+ 函数，标注 OxiRS/Jena 支持级别），SwrlSyntaxValidator 语法校验器，规则依赖图接口
  - **规则和 TTL 在线修改**：修复规则在线修改和 TTL 在线修改后的 TTL 生成问题，TtlSyntaxFixer 新增 5 类自动修复
  - **本体提取质量优化**：Prompt 重构（反过度分析/SWRL 标准模式库/TTL 结构输出铁律/拼音→英文命名），实例化流水线 SSE 日志流 + TTL 数据库备份 + 列名语义翻译
  - **前端中文标签**：类实例统计/个体详情/数据属性表/对象属性表全链路增加中文标签展示

---

## License

Proprietary. All rights reserved.