trustgraph/docs/tech-specs/ontorag.zh-cn.md

---
layout: default
title: "OntoRAG: 基于本体的知识提取和查询技术规范"
parent: "Chinese (Beta)"
---

# OntoRAG: 基于本体的知识提取和查询技术规范

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## 概述

OntoRAG 是一个基于本体的知识提取和查询系统，它在从非结构化文本中提取知识三元组以及查询结果知识图谱的过程中，强制执行严格的语义一致性。类似于 GraphRAG，但具有正式的本体约束，OntoRAG 确保所有提取的三元组都符合预定义的本体结构，并提供具有语义意识的查询功能。

该系统使用向量相似性匹配，动态选择相关的本体子集，用于提取和查询操作，从而实现专注于上下文相关的处理，同时保持语义有效性。

**服务名称**: `kg-extract-ontology`

## 目标

**符合本体的提取**: 确保所有提取的三元组严格符合加载的本体。
**动态上下文选择**: 使用嵌入向量来选择每个文本块相关的本体子集。
**语义一致性**: 维护类层次结构、属性域/范围以及约束。
**高效处理**: 使用内存中的向量存储，以实现快速的本体元素匹配。
**可扩展架构**: 支持多个并发的本体，具有不同的领域。

## 背景

当前的知识提取服务 (`kg-extract-definitions`, `kg-extract-relationships`) 在没有正式约束的情况下运行，这可能会产生不一致或不兼容的三元组。OntoRAG 通过以下方式解决此问题：

1. 加载正式的本体，定义有效的类和属性。
2. 使用嵌入向量将文本内容与相关的本体元素进行匹配。
3. 限制提取，仅产生符合本体的三元组。
4. 提供对提取知识的语义验证。

这种方法结合了神经网络提取的灵活性和正式知识表示的严谨性。

## 技术设计

### 架构

OntoRAG 系统由以下组件组成：

```
┌─────────────────┐
│  Configuration  │
│    Service      │
└────────┬────────┘
         │ Ontologies
         ▼
┌─────────────────┐      ┌──────────────┐
│ kg-extract-     │────▶│  Embedding   │
│   ontology      │      │   Service    │
└────────┬────────┘      └──────────────┘
         │                      │
         ▼                      ▼
┌─────────────────┐      ┌──────────────┐
│   In-Memory     │◀────│   Ontology   │
│  Vector Store   │      │   Embedder   │
└────────┬────────┘      └──────────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────┐
│    Sentence     │────▶│   Chunker    │
│    Splitter     │      │   Service    │
└────────┬────────┘      └──────────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────┐
│    Ontology     │────▶│   Vector     │
│    Selector     │      │   Search     │
└────────┬────────┘      └──────────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────┐
│    Prompt       │────▶│   Prompt     │
│   Constructor   │      │   Service    │
└────────┬────────┘      └──────────────┘
         │
         ▼
┌─────────────────┐
│  Triple Output  │
└─────────────────┘
```

### 组件详情

#### 1. 本体加载器

**目的**: 使用事件驱动的更新，从配置服务检索和解析本体配置。

**实现**:
本体加载器使用 TrustGraph 的 ConfigPush 队列接收事件驱动的本体配置更新。当类型为“本体”的配置元素被添加或修改时，加载器通过 config-update 队列接收更新，并解析包含元数据、类、对象属性和数据类型属性的 JSON 结构。这些解析的本体存储在内存中，作为结构化的对象，以便在提取过程中高效访问。

**主要操作**:
订阅 config-update 队列，用于本体类型配置
将 JSON 本体结构解析为 OntologyClass 和 OntologyProperty 对象
验证本体结构和一致性
将解析的本体缓存到内存中，以便快速访问
使用 flow-specific 向量存储，处理每个流程的数据

**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/ontology_loader.py`

#### 2. 本体嵌入器

**目的**: 为所有本体元素创建向量嵌入，以实现语义相似性匹配。

**实现**:
本体嵌入器处理加载的本体中的每个元素（类、对象属性和数据类型属性），并使用 EmbeddingsClientSpec 服务生成向量嵌入。对于每个元素，它将元素的标识符、标签和描述（注释）组合成文本表示。然后，将此文本转换为高维向量嵌入，以捕获其语义含义。这些嵌入存储在每个流程的内存 FAISS 向量存储中，以及有关元素类型、源本体和完整定义的元数据。嵌入器会自动从第一个嵌入响应中检测嵌入维度。

**主要操作**:
从元素 ID、标签和注释创建文本表示
通过 EmbeddingsClientSpec 生成嵌入（使用 asyncio.gather 进行批量处理）
将嵌入以及全面的元数据存储在 FAISS 向量存储中
按本体、元素类型和元素 ID 进行索引，以便高效检索
自动检测嵌入维度，用于向量存储初始化
使用独立的向量存储，处理每个流程的嵌入模型

**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/ontology_embedder.py`

#### 3. 文本处理器（句子分割器）

**目的**: 将文本块分解为细粒度的片段，以便进行精确的本体匹配。

**实现**:
文本处理器使用 NLTK 进行句子分词和词性标注，将传入的文本块分解为句子。它通过尝试下载 `punkt_tab` 和 `averaged_perceptron_tagger_eng` 来处理 NLTK 版本兼容性，如果需要，可以回退到较旧的版本。每个文本块被拆分为独立的句子，这些句子可以独立地与本体元素进行匹配。

**主要操作**:
使用 NLTK 句子分词，将文本拆分为句子
处理 NLTK 版本兼容性（punkt_tab vs punkt）
创建包含文本和位置信息的 TextSegment 对象
支持完整的句子和单独的块

**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/text_processor.py`

#### 4. 本体选择器

**目的**: 识别当前文本块中最相关的本体元素子集。

**实现**:
本体选择器使用 FAISS 向量相似性搜索，在文本片段和本体元素之间执行语义匹配。对于文本块中的每个句子，它生成一个嵌入，并在向量存储中搜索最相似的本体元素，使用具有可配置阈值（默认值为 0.3）的余弦相似度。在收集所有相关元素后，它执行全面的依赖关系解析：如果选择了类，则包含其父类；如果选择了属性，则添加其域和范围类。此外，对于每个选定的类，它会自动包含**引用该类的所有属性**（无论是其域还是范围）。这确保了提取过程可以访问所有相关的关系属性。

**关键操作**:
为每个文本段（句子）生成嵌入向量
在 FAISS 向量存储中执行 k 近邻搜索（top_k=10，threshold=0.3）
应用相似度阈值以过滤弱匹配项
解决依赖关系（父类、领域、范围）
**自动包含与所选类相关的所有属性**（领域/范围匹配）
构建包含所有必需关系的连贯本体子集
消除多次出现的元素

**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/ontology_selector.py`

#### 5. 提示构建

**目的**: 创建结构化的提示，引导 LLM 仅提取符合本体的元组。

**实现**:
提取服务使用从 `ontology-prompt.md` 加载的 Jinja2 模板，该模板格式化本体子集和文本以供 LLM 提取。该模板使用 Jinja2 语法动态地循环遍历类、对象属性和数据类型属性，并显示它们的描述、领域、范围和层次关系。该提示包含关于仅使用提供的本体元素的严格规则，并请求 JSON 格式的输出以进行一致的解析。

**关键操作**:
使用 Jinja2 模板，对本体元素进行循环
格式化具有父关系（subclass_of）和注释的类
格式化具有领域/范围约束和注释的属性
包含明确的提取规则和输出格式要求
使用模板 ID "extract-with-ontologies" 调用提示服务

**模板位置**: `ontology-prompt.md`
**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/extract.py` (build_extraction_variables 方法)

#### 6. 主提取服务

**目的**: 协调所有组件以执行端到端的基于本体的三元组提取。

**实现**:
主提取服务 (KgExtractOntology) 是管理完整提取工作流程的编排层。它使用 TrustGraph 的 FlowProcessor 模式，并对每个流程进行组件初始化。当收到本体配置更新时，它会初始化或更新流程特定的组件（本体加载器、嵌入器、文本处理器、选择器）。当接收到用于处理的文本块时，它会协调管道：将文本拆分为段，通过向量搜索找到相关的本体元素，构建受约束的提示，调用提示服务，解析和验证响应，生成本体定义三元组，并发出内容三元组和实体上下文。

**提取管道**:
1. 通过 chunks-input 队列接收文本块
2. 如果需要，初始化流程组件（在第一个块或配置更新时）
3. 使用 NLTK 将文本拆分为句子
4. 搜索 FAISS 向量存储以查找相关的本体概念
5. 构建包含自动属性包含的本体子集
6. 构建 Jinja2 模板的提示变量
7. 使用 extract-with-ontologies 模板调用提示服务
8. 将 JSON 响应解析为结构化的三元组
9. 验证三元组并扩展 URI 为完整的本体 URI
10. 生成本体定义三元组（具有标签/注释/领域/范围的类和属性）
11. 从所有三元组构建实体上下文
12. 发送到三元组和实体上下文队列

**关键特性**:
每个流程的向量存储支持不同的嵌入模型
通过 config-update 队列驱动的本体更新
使用本体 URI 自动扩展 URI
将本体元素添加到知识图谱中，包含完整的元数据
实体上下文包含内容和本体元素

**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`

### 配置

该服务使用 TrustGraph 的标准配置方法，通过命令行参数：

```bash
kg-extract-ontology \
  --id kg-extract-ontology \
  --pulsar-host localhost:6650 \
  --input-queue chunks \
  --config-input-queue config-update \
  --output-queue triples \
  --entity-contexts-output-queue entity-contexts
```

**关键配置参数**:
`similarity_threshold`: 0.3 (默认值，可在代码中配置)
`top_k`: 10 (每个段检索的本体元素数量)
`vector_store`: Per-flow FAISS IndexFlatIP with auto-detected dimensions
`text_processor`: NLTK with punkt_tab sentence tokenization
`prompt_template`: "extract-with-ontologies" (Jinja2 模板)

**本体配置**:
本体通过 config-update 队列以 type="ontology" 的方式动态加载。

### 数据流

1. **初始化阶段** (每个流程):
   通过 config-update 队列接收本体配置
   将本体 JSON 解析为 OntologyClass 和 OntologyProperty 对象
   使用 EmbeddingsClientSpec 为所有本体元素生成嵌入向量
   将嵌入向量存储在每个流程的 FAISS 向量存储中
   从第一个响应中自动检测嵌入维度

2. **提取阶段** (每个块):
   从 chunks-input 队列接收块
   使用 NLTK 将块拆分为句子
   计算每个句子的嵌入向量
   在 FAISS 向量存储中搜索相关的本体元素
   构建包含自动属性的本体子集
   使用文本和本体构建 Jinja2 模板变量
   使用 extract-with-ontologies 模板调用提示服务
   解析 JSON 响应并验证三元组
   使用本体 URI 扩展 URI
   生成本体定义三元组
   从所有三元组构建实体上下文
   发送到 triples 和 entity-contexts 队列

### 内存向量存储

**目的**: 为本体元素匹配提供快速、基于内存的相似性搜索。

**实现: FAISS**

该系统使用 **FAISS (Facebook AI Similarity Search)**，并使用 IndexFlatIP 进行精确的余弦相似性搜索。 关键特性：

**IndexFlatIP**: 使用内积进行精确的余弦相似性搜索
**自动检测**: 从第一个嵌入响应确定维度
**每个流程的存储**: 每个流程都有独立的向量存储，用于不同的嵌入模型
**归一化**: 在索引之前，所有向量都进行归一化
**批量操作**: 适用于初始本体加载的高效批量添加

**实现位置**: `trustgraph-flow/trustgraph/extract/kg/ontology/vector_store.py`

### 本体子集选择算法

**目的**: 动态地为每个文本块选择本体中最小的相关部分。

**详细算法步骤**:

1. **文本分割**:
   使用 NLP 句子检测将输入块拆分为句子
   从每个句子中提取名词短语、动词短语和命名实体
   创建一个层次结构，保留上下文的段落

2. **嵌入生成**:
   为每个文本段（句子和短语）生成向量嵌入
   使用与本体元素相同的嵌入模型
   缓存重复段的嵌入，以提高性能

3. **相似性搜索**:
   对于每个文本段嵌入，搜索向量存储
   检索最相似的 k 个（例如，10）本体元素
   应用相似性阈值（例如，0.7）以过滤弱匹配
   汇总所有段的结果，跟踪匹配频率

4. **依赖关系解析**:
   对于每个选定的类，递归地包含所有父类，直到根类
   对于每个选定的属性，包含其域和范围类
   对于反向属性，确保包含两个方向
   如果本体中存在等效类，则添加它们

5. **子集构建**:
   在保留关系的同时，对收集的元素进行去重
   组织为类、对象属性和数据类型属性
   确保所有约束和关系都得到保留
   创建一个自包含的迷你本体，该本体是有效且完整的

**示例演示**:
给定的文本: "The brown dog chased the white cat up the tree."
段落: ["brown dog", "white cat", "tree", "chased"]
匹配的元素: [dog (class), cat (class), animal (parent), chases (property)]
依赖关系: [animal (dog 和 cat 的父类), lifeform (animal 的父类)]
最终子集: 包含 animal 层次结构和 chase 关系的完整迷你本体

### 三元组验证

**目的**: 确保所有提取的三元组严格符合本体约束。

**验证算法**:

1. **类验证 (Class Validation)**:
   验证主体是否是本体子集中定义的类的实例。
   对于对象属性，验证对象是否也是有效的类实例。
   检查类名是否与本体的类字典匹配。
   处理类层次结构 - 子类的实例对于父类的约束有效。

2. **属性验证 (Property Validation)**:
   确认谓词是否对应于本体子集中的属性。
   区分对象属性（实体到实体）和数据类型属性（实体到字面量）。
   验证属性名称是否完全匹配（如果存在，则考虑命名空间）。

3. **域/范围检查 (Domain/Range Checking)**:
   对于每个用作谓语的属性，检索其域和范围。
   验证主体的类型是否匹配或继承自属性的域。
   验证对象的类型是否匹配或继承自属性的范围。
   对于数据类型属性，验证对象是否是具有正确 XSD 类型的字面量。

4. **基数验证 (Cardinality Validation)**:
   跟踪每个主体属性的使用计数。
   检查最小基数 - 确保必需的属性存在。
   检查最大基数 - 确保属性未被使用太多次。
   对于函数属性，确保每个主体最多有一个值。

5. **数据类型验证 (Datatype Validation)**:
   根据其声明的 XSD 类型解析字面值。
   验证整数是否为有效数字，日期是否格式正确等。
   检查字符串模式，如果定义了正则表达式约束。
   确保 URI 对于 xsd:anyURI 类型是格式正确的。

**验证示例 (Validation Example)**:
三元组: ("Buddy", "has-owner", "John")
检查 "Buddy" 是否被标记为可以具有 "has-owner" 属性的类。
检查 "has-owner" 是否存在于本体中。
验证域约束：主体必须是 "Pet" 类型或子类型。
验证范围约束：对象必须是 "Person" 类型或子类型。
如果有效，则添加到输出；如果无效，则记录违规并跳过。

## 性能考虑 (Performance Considerations)

### 优化策略 (Optimisation Strategies)

1. **嵌入缓存 (Embedding Caching)**: 缓存常用文本片段的嵌入。
2. **批量处理 (Batch Processing)**: 并行处理多个片段。
3. **向量存储索引 (Vector Store Indexing)**: 使用近似最近邻算法进行大型本体。
4. **提示优化 (Prompt Optimisation)**: 通过仅包含必要的本体元素来最小化提示大小。
5. **结果缓存 (Result Caching)**: 缓存相同块的提取结果。

### 可扩展性 (Scalability)

**水平扩展 (Horizontal Scaling)**: 具有共享本体缓存的多个提取器实例。
**本体分区 (Ontology Partitioning)**: 通过域分割大型本体。
**流式处理 (Streaming Processing)**: 在不进行批处理的情况下处理到达的块。
**内存管理 (Memory Management)**: 定期清理未使用的嵌入。

## 错误处理 (Error Handling)

### 故障场景 (Failure Scenarios)

1. **缺少本体 (Missing Ontologies)**: 回退到不受约束的提取。
2. **嵌入服务故障 (Embedding Service Failure)**: 使用缓存的嵌入或跳过语义匹配。
3. **提示服务超时 (Prompt Service Timeout)**: 使用指数退避重试。
4. **无效三元组格式 (Invalid Triple Format)**: 记录并跳过格式错误的元组。
5. **本体不一致 (Ontology Inconsistencies)**: 报告冲突并使用最具体的有效元素。

### 监控 (Monitoring)

需要跟踪的关键指标：

本体加载时间和内存使用情况。
嵌入生成延迟。
向量搜索性能。
提示服务响应时间。
三元组提取准确性。
本体符合性率。

## 迁移路径 (Migration Path)

### 从现有提取器 (From Existing Extractors)

1. **并行运行 (Parallel Operation)**: 初始阶段与现有提取器并行运行。
2. **逐步推广 (Gradual Rollout)**: 从特定文档类型开始。
3. **质量比较 (Quality Comparison)**: 将输出质量与现有提取器进行比较。
4. **完全迁移 (Full Migration)**: 在验证质量后，替换现有提取器。

### 本体开发 (Ontology Development)

1. **从现有知识生成初始本体 (Bootstrap from Existing)**: 从现有知识生成初始本体。
2. **基于提取模式进行迭代改进 (Iterative Refinement)**: 基于提取模式进行迭代改进。
3. **领域专家审查 (Domain Expert Review)**: 由领域专家进行验证。
4. **基于提取反馈进行持续改进 (Continuous Improvement)**: 基于提取反馈进行持续改进。

## 基于本体的查询服务 (Ontology-Sensitive Query Service)

### 概述 (Overview)

基于本体的查询服务提供多种查询路径，以支持不同的后端图存储。它利用本体知识，为 Cassandra（通过 SPARQL）和基于 Cypher 的图存储（Neo4j、Memgraph、FalkorDB）提供精确、语义化的问答功能。

**服务组件 (Service Components)**:
`onto-query-sparql`: 将自然语言转换为 Cassandra 的 SPARQL。
`sparql-cassandra`: 用于 Cassandra 的 rdflib 的 SPARQL 查询层。
`onto-query-cypher`: 将自然语言转换为图数据库的 Cypher。
`cypher-executor`: 用于 Neo4j/Memgraph/FalkorDB 的 Cypher 查询执行。

### 架构

```
                    ┌─────────────────┐
                    │   User Query    │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐      ┌──────────────┐
                    │   Question      │────▶│   Sentence   │
                    │   Analyser      │      │   Splitter   │
                    └────────┬────────┘      └──────────────┘
                             │
                             ▼
                    ┌─────────────────┐      ┌──────────────┐
                    │   Ontology      │────▶│   Vector     │
                    │   Matcher       │      │    Store     │
                    └────────┬────────┘      └──────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Backend Router  │
                    └────────┬────────┘
                             │
                 ┌───────────┴───────────┐
                 │                       │
                 ▼                       ▼
    ┌─────────────────┐          ┌─────────────────┐
    │ onto-query-     │          │ onto-query-     │
    │    sparql       │          │    cypher       │
    └────────┬────────┘          └────────┬────────┘
             │                            │
             ▼                            ▼
    ┌─────────────────┐          ┌─────────────────┐
    │   SPARQL        │          │   Cypher        │
    │  Generator      │          │  Generator      │
    └────────┬────────┘          └────────┬────────┘
             │                            │
             ▼                            ▼
    ┌─────────────────┐          ┌─────────────────┐
    │ sparql-         │          │ cypher-         │
    │ cassandra       │          │ executor        │
    └────────┬────────┘          └────────┬────────┘
             │                            │
             ▼                            ▼
    ┌─────────────────┐          ┌─────────────────┐
    │   Cassandra     │          │ Neo4j/Memgraph/ │
    │                 │          │   FalkorDB      │
    └────────┬────────┘          └────────┬────────┘
             │                            │
             └────────────┬───────────────┘
                          │
                          ▼
                 ┌─────────────────┐      ┌──────────────┐
                 │   Answer        │────▶│   Prompt     │
                 │  Generator      │      │   Service    │
                 └────────┬────────┘      └──────────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Final Answer   │
                 └─────────────────┘
```

### 查询处理流程

#### 1. 问题分析器

**目的**: 将用户问题分解为语义组件，用于本体匹配。

**算法描述**:
问题分析器接收输入的自然语言问题，并使用与提取流程相同的句子分割方法将其分解为有意义的片段。它识别问题中提到的关键实体、关系和约束。每个片段都用于分析问题类型（事实、聚合、比较等）以及预期的答案格式。这种分解有助于确定本体的哪些部分最相关，以回答问题。

**主要操作**:
将问题拆分为句子和短语
识别问题类型和意图
提取提到的实体和关系
检测问题中的约束和过滤器
确定预期的答案格式

#### 2. 用于查询的本体匹配器

**目的**: 识别回答问题所需的相关的本体子集。

**算法描述**:
与提取流程中的本体选择器类似，但针对问题解答进行了优化。匹配器为问题片段生成嵌入向量，并在向量存储中搜索相关的本体元素。但是，它侧重于找到用于查询构造的概念，而不是提取。它扩展选择范围，包括可能在图探索过程中被遍历的关联属性，即使这些属性没有明确地在问题中提到。例如，如果询问“员工”，它可能包括“工作单位”、“管理”、“汇报”等属性，这些属性可能与查找员工信息相关。

**匹配策略**:
嵌入问题片段
查找直接提到的本体概念
包含连接到提到的类的属性
添加反向和相关属性以进行遍历
包含父/子类以进行层次查询
构建面向查询的本体分区

#### 3. 后端路由器

**目的**: 根据配置，将查询路由到适当的后端特定的查询路径。

**算法描述**:
后端路由器检查系统配置以确定哪个图后端处于活动状态（Cassandra 或 Cypher 驱动）。它将问题和本体分区路由到适当的查询生成服务。路由器还可以支持跨多个后端进行负载平衡，或者在主后端不可用时提供回退机制。

**路由逻辑**:
检查系统设置中配置的后端类型
路由到 `onto-query-sparql` 用于 Cassandra 后端
路由到 `onto-query-cypher` 用于 Neo4j/Memgraph/FalkorDB
支持具有查询分发的多个后端配置
处理故障转移和负载平衡场景

#### 4. SPARQL 查询生成 (`onto-query-sparql`)

**目的**: 将自然语言问题转换为 SPARQL 查询，以便在 Cassandra 上执行。

**算法描述**:
SPARQL 查询生成器接收问题和本体分区，并构造一个针对 Cassandra 后端优化的 SPARQL 查询。它使用带有 SPARQL 特定模板的提示服务，该模板包含 RDF/OWL 语义。该生成器理解 SPARQL 模式，例如属性路径、可选子句和过滤器，这些模式可以有效地转换为 Cassandra 操作。

**SPARQL 生成提示模板**:
```
Generate a SPARQL query for the following question using the provided ontology.

ONTOLOGY CLASSES:
{classes}

ONTOLOGY PROPERTIES:
{properties}

RULES:
- Use proper RDF/OWL semantics
- Include relevant prefixes
- Use property paths for hierarchical queries
- Add FILTER clauses for constraints
- Optimise for Cassandra backend

QUESTION: {question}

SPARQL QUERY:
```

#### 5. Cypher 查询生成 (`onto-query-cypher`)

**目的**: 将自然语言问题转换为用于图数据库的 Cypher 查询。

**算法描述**:
Cypher 查询生成器创建针对 Neo4j、Memgraph 和 FalkorDB 优化的原生 Cypher 查询。它将本体类映射到节点标签，并将属性映射到关系，使用 Cypher 的模式匹配语法。该生成器包含 Cypher 专有的优化，例如关系方向提示、索引使用和查询计划提示。

**Cypher 生成提示模板**:
```
Generate a Cypher query for the following question using the provided ontology.

NODE LABELS (from classes):
{classes}

RELATIONSHIP TYPES (from properties):
{properties}

RULES:
- Use MATCH patterns for graph traversal
- Include WHERE clauses for filters
- Use aggregation functions when needed
- Optimise for graph database performance
- Consider index hints for large datasets

QUESTION: {question}

CYPHER QUERY:
```

#### 6. SPARQL-Cassandra 查询引擎 (`sparql-cassandra`)

**目的**: 使用 Python rdflib 对 Cassandra 执行 SPARQL 查询。

**算法描述**:
SPARQL-Cassandra 引擎使用 Python 的 rdflib 库实现了一个 SPARQL 处理器，并具有自定义的 Cassandra 后端存储。它将 SPARQL 图模式转换为适当的 Cassandra CQL 查询，处理连接、过滤器和聚合。该引擎维护一个 RDF 到 Cassandra 的映射，该映射保留了语义结构，同时针对 Cassandra 的列族存储模型进行了优化。

**实现特性**:
用于 Cassandra 的 rdflib Store 接口实现
支持常见的 SPARQL 1.1 查询模式
将三元组模式高效地转换为 CQL
支持属性路径和分层查询
用于大型数据集的结果流式传输
连接池和查询缓存

**示例翻译**:
```sparql
SELECT ?animal WHERE {
  ?animal rdf:type :Animal .
  ?animal :hasOwner "John" .
}
```
将其翻译为针对 Cassandra 的优化查询，利用索引和分区键。

#### 7. Cypher 查询执行器 (`cypher-executor`)

**目的**: 对 Neo4j、Memgraph 和 FalkorDB 执行 Cypher 查询。

**算法描述**:
Cypher 执行器提供了一个统一的接口，用于在不同的图数据库上执行 Cypher 查询。它处理特定于数据库的连接协议、查询优化提示以及结果格式标准化。执行器包括针对每种数据库类型的重试逻辑、连接池和事务管理。

**多数据库支持**:
**Neo4j**: Bolt 协议、事务函数、索引提示
**Memgraph**: 自定义协议、流式结果、分析查询
**FalkorDB**: Redis 协议适配、内存优化

**执行特性**:
数据库无关的连接管理
查询验证和语法检查
超时和资源限制强制
结果分页和流式传输
按数据库类型进行性能监控
数据库实例之间的自动故障转移

#### 8. 答案生成器

**目的**: 从查询结果中合成自然语言答案。

**算法描述**:
答案生成器接收结构化的查询结果和原始问题，然后使用提示服务生成一个全面的答案。与简单的基于模板的响应不同，它使用 LLM 来在问题的上下文中解释图数据，处理复杂的关联、聚合和推断。生成器可以通过引用本体结构和从图中检索的特定三元组来解释其推理过程。

**答案生成过程**:
将查询结果格式化为结构化上下文
包含相关的本体定义以提高清晰度
构建包含问题和结果的提示
通过 LLM 生成自然语言答案
验证答案是否符合查询意图
如果需要，添加指向特定图实体的引用

### 与现有服务的集成

#### 与 GraphRAG 的关系

**互补**: onto-query 提供语义精度，而 GraphRAG 提供广泛的覆盖范围
**共享基础设施**: 两者都使用相同的知识图谱和提示服务
**查询路由**: 系统可以根据问题类型将查询路由到最合适的服务
**混合模式**: 可以结合两种方法来获得全面的答案

#### 与 OntoRAG 提取的关系

**共享本体**: 使用与 kg-extract-ontology 加载的相同的本体配置
**共享向量存储**: 重用提取服务中的内存嵌入
**一致的语义**: 查询在具有相同本体约束的图上运行

### 查询示例

#### 示例 1: 简单实体查询
**问题**: "哪些动物是哺乳动物？"
**本体匹配**: [animal, mammal, subClassOf]
**生成的查询**:
```cypher
MATCH (a:animal)-[:subClassOf*]->(m:mammal)
RETURN a.name
```

#### 示例 2：关系查询
**问题**: "哪些文档是由 John Smith 撰写的？"
**本体匹配**: [document, person, has-author]
**生成的查询**:
```cypher
MATCH (d:document)-[:has-author]->(p:person {name: "John Smith"})
RETURN d.title, d.date
```

#### 示例 3：聚合查询
**问题**: "猫有多少条腿？"
**本体匹配**: [猫, 腿的数量 (数据类型属性)]
**生成的查询**:
```cypher
MATCH (c:cat)
RETURN c.name, c.number_of_legs
```

### 配置

```yaml
onto-query:
  embedding_model: "text-embedding-3-small"
  vector_store:
    shared_with_extractor: true  # Reuse kg-extract-ontology's store
  query_builder:
    model: "gpt-4"
    temperature: 0.1
    max_query_length: 1000
  graph_executor:
    timeout: 30000  # ms
    max_results: 1000
  answer_generator:
    model: "gpt-4"
    temperature: 0.3
    max_tokens: 500
```

### 性能优化

#### 查询优化

**本体图剪枝**: 仅在提示中包含必要的本体图元素
**查询缓存**: 缓存常见问题及其查询
**结果缓存**: 存储相同查询的结果，并在指定时间窗口内
**批量处理**: 使用单次图遍历处理多个相关问题

#### 可扩展性考虑

**分布式执行**: 在图分区上并行化子查询
**增量结果**: 为大型数据集流式传输结果
**负载均衡**: 在多个服务实例之间分配查询负载
**资源池**: 管理到图数据库的连接池

### 错误处理

#### 故障场景

1. **无效查询生成**: 回退到 GraphRAG 或简单的关键词搜索
2. **本体图不匹配**: 扩展搜索范围到更广泛的本体图子集
3. **查询超时**: 简化查询或增加超时时间
4. **无结果**: 建议重新构建查询或提供相关问题
5. **LLM 服务故障**: 使用缓存的查询或基于模板的响应

### 监控指标

问题复杂性分布
本体图分区大小
查询生成成功率
图查询执行时间
答案质量分数
缓存命中率
按类型划分的错误频率

## 未来增强功能

1. **本体图学习**: 根据提取模式自动扩展本体图
2. **置信度评分**: 为提取的三元组分配置信度分数
3. **解释生成**: 提供三元组提取的推理
4. **主动学习**: 请求人工验证不确定的提取结果

## 安全性考虑

1. **防止提示注入**: 在构建提示之前，清理文本块
2. **资源限制**: 限制向量存储的内存使用量
3. **速率限制**: 限制每个客户端的提取请求
4. **审计日志**: 跟踪所有提取请求和结果

## 测试策略

### 单元测试

带各种格式的本体图加载器
嵌入式生成和存储
句子分割算法
向量相似度计算
三元组解析和验证

### 集成测试

端到端提取管道
配置服务集成
提示服务交互
并发提取处理

### 性能测试

处理大型本体图（1000+ 个类）
处理大量文本块
负载下的内存使用情况
延迟基准测试

## 发布计划

### 概述

OntoRAG 系统将分四个主要阶段交付，每个阶段都提供增量价值，并逐步构建到完整的系统。 该计划侧重于首先建立核心提取功能，然后添加查询功能，然后是优化和高级功能。

### 第一阶段：基础和核心提取

**目标**: 建立基于本体图驱动的基本提取管道，并使用简单的向量匹配。

#### 第一步：本体图管理基础
实现本体图配置加载器 (`OntologyLoader`)
解析和验证本体图 JSON 结构
创建内存中的本体图存储和访问模式
实现本体图刷新机制

**成功标准**:
成功加载和解析本体图配置
验证本体图结构和一致性
处理多个并发本体图

#### 第二步：向量存储实现
实现简单的基于 NumPy 的向量存储作为初始原型
添加 FAISS 向量存储实现
创建向量存储接口抽象
实现具有可配置阈值的相似度搜索

**成功标准**:
高效地存储和检索嵌入向量
以<100毫秒的延迟执行相似性搜索
支持NumPy和FAISS后端

#### 步骤 1.3：本体嵌入管道
与嵌入服务集成
实现 `OntologyEmbedder` 组件
为所有本体元素生成嵌入向量
将嵌入向量及其元数据存储在向量存储中

**成功标准**:
为类和属性生成嵌入向量
存储带有适当元数据的嵌入向量
在本体更新时重建嵌入向量

#### 步骤 1.4：文本处理组件
使用NLTK/spaCy实现句子分割器
提取短语和命名实体
创建文本段层级结构
为文本段生成嵌入向量

**成功标准**:
准确地将文本分割成句子
提取有意义的短语
维护上下文关系

#### 步骤 1.5：本体选择算法
实现文本与本体之间的相似性匹配
构建本体元素的依赖关系解析
创建最小的、连贯的本体子集
优化子集生成性能

**成功标准**:
使用>80%的精度选择相关的本体元素
包含所有必要的依赖项
在<500毫秒内生成子集

#### 步骤 1.6：基本提取服务
实现用于提取的提示构建
与提示服务集成
解析和验证三元组响应
创建 `kg-extract-ontology` 服务端点

**成功标准**:
提取符合本体的三元组
验证所有三元组与本体
优雅地处理提取错误

### 第二阶段：查询系统实现

**目标**: 添加具有对多个后端支持的本体感知查询功能。

#### 步骤 2.1：查询基础组件
实现问题分析器
创建用于查询的本体匹配器
调整向量搜索以适应查询上下文
构建后端路由器组件

**成功标准**:
将问题分析成语义组件
将问题与相关的本体元素匹配
将查询路由到适当的后端

#### 步骤 2.2：SPARQL路径实现
实现 `onto-query-sparql` 服务
使用LLM创建SPARQL查询生成器
开发用于SPARQL生成的提示模板
验证生成的SPARQL语法

**成功标准**:
生成有效的SPARQL查询
使用适当的SPARQL模式
处理复杂的查询类型

#### 步骤 2.3：SPARQL-Cassandra引擎
为Cassandra实现rdflib Store接口
创建CQL查询翻译器
优化三元组模式匹配
处理SPARQL结果格式

**成功标准**:
在Cassandra上执行SPARQL查询
支持常见的SPARQL模式
以标准格式返回结果

#### 步骤 2.4：Cypher路径实现
实现 `onto-query-cypher` 服务
使用LLM创建Cypher查询生成器
开发用于Cypher生成的提示模板
验证生成的Cypher语法

**成功标准**:
生成有效的Cypher查询
使用适当的图模式
支持Neo4j、Memgraph、FalkorDB

#### 步骤 2.5：Cypher执行器
Implement multi-database Cypher executor
Support Bolt protocol (Neo4j/Memgraph)
Support Redis protocol (FalkorDB)
Handle result normalization

**Success Criteria**:
Execute Cypher on all target databases
Handle database-specific differences
Maintain connection pools efficiently

#### Step 2.6: Answer Generation
Implement answer generator component
Create prompts for answer synthesis
Format query results for LLM consumption
Generate natural language answers

**Success Criteria**:
Generate accurate answers from query results
Maintain context from original question
Provide clear, concise responses

### Phase 3: Optimization and Robustness

**Goal**: Optimize performance, add caching, improve error handling, and enhance reliability.

#### Step 3.1: Performance Optimization
Implement embedding caching
Add query result caching
Optimize vector search with FAISS IVF indexes
Implement batch processing for embeddings

**Success Criteria**:
Reduce average query latency by 50%
Support 10x more concurrent requests
Maintain sub-second response times

#### Step 3.2: Advanced Error Handling
Implement comprehensive error recovery
Add fallback mechanisms between query paths
Create retry logic with exponential backoff
Improve error logging and diagnostics

**Success Criteria**:
Gracefully handle all failure scenarios
Automatic failover between backends
Detailed error reporting for debugging

#### Step 3.3: Monitoring and Observability
Add performance metrics collection
Implement query tracing
Create health check endpoints
Add resource usage monitoring

**Success Criteria**:
Track all key performance indicators
Identify bottlenecks quickly
Monitor system health in real-time

#### Step 3.4: Configuration Management
Implement dynamic configuration updates
Add configuration validation
Create configuration templates
Support environment-specific settings

**Success Criteria**:
Update configuration without restart
Validate all configuration changes
Support multiple deployment environments

### Phase 4: Advanced Features

**Goal**: Add sophisticated capabilities for production deployment and enhanced functionality.

#### Step 4.1: Multi-Ontology Support
Implement ontology selection logic
Support cross-ontology queries
Handle ontology versioning
Create ontology merge capabilities

**Success Criteria**:
Query across multiple ontologies
Handle ontology conflicts
Support ontology evolution

#### Step 4.2: Intelligent Query Routing
Implement performance-based routing
Add query complexity analysis
Create adaptive routing algorithms
Support A/B testing for paths

**Success Criteria**:
Route queries optimally
Learn from query performance
Improve routing over time

#### Step 4.3: Advanced Extraction Features
Add confidence scoring for triples
Implement explanation generation
Create feedback loops for improvement
Support incremental learning

**Success Criteria**:
Provide confidence scores
Explain extraction decisions
Continuously improve accuracy

#### Step 4.4: Production Hardening
Add rate limiting
Implement authentication/authorization
Create deployment automation
Add backup and recovery

**Success Criteria**:
Production-ready security
Automated deployment pipeline
Disaster recovery capability

### Delivery Milestones

1. **Milestone 1** (End of Phase 1): Basic ontology-driven extraction operational
2. **Milestone 2** (End of Phase 2): Full query system with both SPARQL and Cypher paths
3. **Milestone 3** (End of Phase 3): Optimized, robust system ready for staging
4. **Milestone 4** (End of Phase 4): Production-ready system with advanced features

### Risk Mitigation

#### Technical Risks
**Vector Store Scalability**: Start with NumPy, migrate to FAISS gradually
**Query Generation Accuracy**: Implement validation and fallback mechanisms
**Backend Compatibility**: Test extensively with each database type
**Performance Bottlenecks**: Profile early and often, optimize iteratively

#### Operational Risks
**Ontology Quality**: Implement validation and consistency checking
**Service Dependencies**: Add circuit breakers and fallbacks
**Resource Constraints**: Monitor and set appropriate limits
**Data Consistency**: Implement proper transaction handling

### Success Metrics

#### Phase 1 Success Metrics
Extraction accuracy: >90% ontology conformance
Processing speed: <1 second per chunk
Ontology load time: <10 seconds
Vector search latency: <100ms

#### Phase 2 Success Metrics
Query success rate: >95%
Query latency: <2 seconds end-to-end
Backend compatibility: 100% for target databases
Answer accuracy: >85% based on available data

#### Phase 3 Success Metrics
System uptime: >99.9%
Error recovery rate: >95%
Cache hit rate: >60%
Concurrent users: >100

#### Phase 4 Success Metrics
Multi-ontology queries: Fully supported
Routing optimization: 30% latency reduction
Confidence scoring accuracy: >90%
Production deployment: Zero-downtime updates

## References

[OWL 2 Web Ontology Language](https://www.w3.org/TR/owl2-overview/)
[GraphRAG Architecture](https://github.com/microsoft/graphrag)
[Sentence Transformers](https://www.sbert.net/)
[FAISS Vector Search](https://github.com/facebookresearch/faiss)
[spaCy NLP Library](https://spacy.io/)
[rdflib Documentation](https://rdflib.readthedocs.io/)
[Neo4j Bolt Protocol](https://neo4j.com/docs/bolt/current/)