mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
233
docs/tech-specs/zh-cn/query-time-explainability.zh-cn.md
Normal file
233
docs/tech-specs/zh-cn/query-time-explainability.zh-cn.md
Normal file
|
|
@ -0,0 +1,233 @@
|
|||
---
|
||||
layout: default
|
||||
title: "查询时可解释性"
|
||||
parent: "Chinese (Beta)"
|
||||
---
|
||||
|
||||
# 查询时可解释性
|
||||
|
||||
> **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.
|
||||
|
||||
## 状态
|
||||
|
||||
已实现
|
||||
|
||||
## 概述
|
||||
|
||||
本规范描述了 GraphRAG 如何记录和在查询执行期间传递可解释性数据。目标是实现完全的可追溯性：从最终答案，再到选择的边，最后到源文档。
|
||||
|
||||
查询时可解释性捕获了 GraphRAG 管道在推理过程中的行为。它与提取时的来源信息相关联，该信息记录了知识图谱事实的来源。
|
||||
|
||||
## 术语
|
||||
|
||||
| 术语 | 定义 |
|
||||
|---|---|
|
||||
| **可解释性** | 结果的推导方式 |
|
||||
| **会话** | 单个 GraphRAG 查询执行 |
|
||||
| **边选择** | 使用 LLM 进行相关边的选择，并提供推理 |
|
||||
| **来源链** | 从边 → 块 → 页面 → 文档 |
|
||||
|
||||
## 架构
|
||||
|
||||
### 可解释性流程
|
||||
|
||||
```
|
||||
GraphRAG 查询
|
||||
│
|
||||
├─► 会话活动
|
||||
│ └─► 查询文本，时间戳
|
||||
│
|
||||
├─► 检索实体
|
||||
│ └─► 从子图检索的所有边
|
||||
│
|
||||
├─► 选择实体
|
||||
│ └─► 使用 LLM 推理选择的边
|
||||
│ └─► 每条边都与提取来源关联
|
||||
│
|
||||
└─► 答案实体
|
||||
└─► 指向合成响应 (在库员中)
|
||||
```
|
||||
|
||||
### 两阶段 GraphRAG 管道
|
||||
|
||||
1. **边选择**：LLM 从子图中选择相关的边，并提供每个边的推理
|
||||
2. **合成**：LLM 从选择的边生成答案
|
||||
|
||||
这种分离实现了可解释性：我们知道哪些边贡献了结果。
|
||||
|
||||
### 存储
|
||||
|
||||
- 可解释性三元组存储在可配置的集合中 (默认：`explainability`)
|
||||
- 使用 PROV-O 语义网进行来源关系
|
||||
- 使用 RDF-star 重新表达进行边引用
|
||||
- 答案内容存储在库员服务中 (不在内联位置 - 过于庞大)
|
||||
|
||||
### 实时流
|
||||
|
||||
可解释性事件在查询执行时流式传输到客户端：
|
||||
|
||||
1. 创建会话 → 发出事件
|
||||
2. 检索边 → 发出事件
|
||||
3. 使用推理选择边 → 发出事件
|
||||
4. 答案合成 → 发出事件
|
||||
|
||||
客户端接收 `explain_id` 和 `explain_collection` 以获取完整详细信息。
|
||||
|
||||
## URI 结构
|
||||
|
||||
所有 URI 使用 `urn:trustgraph:` 命名空间和 UUID：
|
||||
|
||||
| 实体 | URI 模式 |
|
||||
|---|---|
|
||||
| 会话 | `urn:trustgraph:session:{uuid}` |
|
||||
| 检索 | `urn:trustgraph:prov:retrieval:{uuid}` |
|
||||
| 选择 | `urn:trustgraph:prov:selection:{uuid}` |
|
||||
| 答案 | `urn:trustgraph:prov:answer:{uuid}` |
|
||||
| 边选择 | `urn:trustgraph:prov:edge:{uuid}:{index}` |
|
||||
|
||||
## RDF 模型 (PROV-O)
|
||||
|
||||
### 会话活动
|
||||
|
||||
```turtle
|
||||
<session-uri> a prov:Activity ;
|
||||
rdfs:label "GraphRAG 查询会话" ;
|
||||
prov:startedAtTime "2024-01-15T10:30:00Z" ;
|
||||
tg:query "What was the War on Terror?" .
|
||||
```
|
||||
|
||||
### 检索实体
|
||||
|
||||
```turtle
|
||||
<retrieval-uri> a prov:Entity ;
|
||||
rdfs:label "检索的边" ;
|
||||
prov:wasGeneratedBy <session-uri> ;
|
||||
tg:edgeCount 50 .
|
||||
```
|
||||
|
||||
### 选择实体
|
||||
|
||||
```turtle
|
||||
<selection-uri> a prov:Entity ;
|
||||
rdfs:label "选择的边" ;
|
||||
prov:wasDerivedFrom <retrieval-uri> ;
|
||||
tg:selectedEdge <edge-sel-0> ;
|
||||
tg:selectedEdge <edge-sel-1> .
|
||||
|
||||
<edge-sel-0> tg:edge << <s> <p> <o> >> ;
|
||||
tg:reasoning "This edge establishes the key relationship..." .
|
||||
```
|
||||
|
||||
### 答案实体
|
||||
|
||||
```turtle
|
||||
<answer-uri> a prov:Entity ;
|
||||
rdfs:label "GraphRAG 答案" ;
|
||||
prov:wasDerivedFrom <selection-uri> ;
|
||||
tg:document <urn:trustgraph:answer:{uuid}> .
|
||||
```
|
||||
|
||||
`tg:document` 引用库员服务中存储的答案。
|
||||
|
||||
## 名称空间常量
|
||||
|
||||
定义在 `trustgraph-base/trustgraph/provenance/namespaces.py`：
|
||||
|
||||
| 常量 | URI |
|
||||
|---|---|
|
||||
| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
|
||||
| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
|
||||
| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
|
||||
| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
|
||||
| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
|
||||
| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
|
||||
| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
|
||||
|
||||
## GraphRagResponse 模式
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class GraphRagResponse:
|
||||
error: None | None = None
|
||||
response: str = ""
|
||||
end_of_stream: bool = False
|
||||
explain_id: str | None = None
|
||||
explain_collection: str | None = None
|
||||
message_type: str = "" # "chunk" 或 "explain"
|
||||
end_of_session: bool = False
|
||||
```
|
||||
|
||||
### 消息类型
|
||||
|
||||
| message_type | 目的 |
|
||||
|---|---|
|
||||
| `chunk` | 响应文本 (流式或最终) |
|
||||
| `explain` | 可解释性事件，包含 IRI 引用 |
|
||||
|
||||
### 会话生命周期
|
||||
|
||||
1. 多个 `explain` 消息 (会话、检索、选择、答案)
|
||||
2. 多个 `chunk` 消息 (流式响应)
|
||||
3. 最终的 `chunk`，`end_of_session=True`
|
||||
|
||||
## 边选择格式
|
||||
|
||||
LLM 返回 JSONL 格式的边：
|
||||
|
||||
```jsonl
|
||||
{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
|
||||
{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}
|
||||
```
|
||||
|
||||
`id` 是使用 `edge_id()` 计算的 `(labeled_s, labeled_p, labeled_o)` 的哈希值。
|
||||
|
||||
## URI 保留
|
||||
|
||||
### 问题
|
||||
|
||||
GraphRAG 向 LLM 显示了人类可读的标签，但为了可追溯性，需要原始 URI。
|
||||
|
||||
### 解决方案
|
||||
|
||||
`get_labelgraph()` 返回：
|
||||
- `labeled_edges`: 包含 `(label_s, label_p, label_o)` 的列表，供 LLM 使用
|
||||
- `uri_map`: 将 `edge_id(labels)` 映射到 `(uri_s, uri_p, uri_o)` 的字典
|
||||
|
||||
在存储可解释性数据时，使用 `uri_map` 中的 URI。
|
||||
|
||||
## 来源追踪
|
||||
|
||||
### 从边到源
|
||||
|
||||
可以追踪选择的边：
|
||||
|
||||
1. 查询包含的子图：`?subgraph tg:contains <<s p o>>`
|
||||
2. 遵循 `prov:wasDerivedFrom` 链，找到根文档
|
||||
3. 每个步骤中的链：块 → 页面 → 文档
|
||||
|
||||
### 支持 Cassandra 引用
|
||||
|
||||
Cassandra 查询服务支持引用：
|
||||
|
||||
```python
|
||||
# 在 get_term_value() 中：
|
||||
elif term.type == TRIPLE:
|
||||
return serialize_triple(term.triple)
|
||||
```
|
||||
|
||||
这允许查询：
|
||||
```
|
||||
?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>
|
||||
```
|
||||
|
||||
## CLI 使用
|
||||
|
||||
```bash
|
||||
tg-invoke-graph-rag --explainable -q "What was the War on Terror?"
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- PROV-O (W3C Provenance Ontology): https://www.w3.org/TR/prov-o/
|
||||
- RDF-star: https://w3c.github.io/rdf-star/
|
||||
- 提取时的来源信息: `docs/tech-specs/extraction-time-provenance.md`
|
||||
Loading…
Add table
Add a link
Reference in a new issue