内容
# 上下文图
[](LICENSE)
[](pyproject.toml)
[](lightrag/api)
[](lightrag_webui)
[](https://github.com/HKUDS/LightRAG)
**基于 LightRAG 的决策感知知识图谱系统。**
上下文图将标准的基于三元组的知识图谱（`头节点，关系，尾节点`）扩展为上下文四元组（`h, r, t, rc`）—— 其中 `rc` 是一个**关系上下文**，它捕获了每个图谱边后完整的决策过程：谁批准了，为什么，通过哪个渠道，在哪个政策下，以及多久有效。
结果是一个*决策系统*，而不仅仅是一个*记录系统*：一个有生命的、可查询的组织知识档案，不仅知道存在哪些关系，还知道关系背后的操作现实。
<p align="center">
<img src="docs/screenshots/dashboard.png" alt="Context Graph dashboard — graph health, quality metrics, and the decision ledger" width="900">
</p>
<p align="center"><em>仪表盘：图谱健康度、质量指标和决策账本 — 每个边都由其 <code>(h, r, t, rc)</code> 四元组支持。</em></p>
---
## 目录
- [为什么是上下文图](#为什么是上下文图)
- [核心概念](#核心概念)
- [安装](#安装)
- [快速开始](#快速开始)
- [配置](#配置)
- [文档摄入](#文档摄入)
- [网页摄入](#网页摄入)
- [实时决策捕获](#实时决策捕获)
- [治理与行动](#治理与行动)
- [AI 代理开发](#AI-代理开发)
- [查询](#查询)
- [REST API](#REST-API)
- [集成模式](#集成模式)
- [存储后端](#存储后端)
- [LLM 提供商](#LLM-提供商)
- [测试](#测试)
- [架构](#架构)
- [基于](#基于)
---
## 为什么是上下文图
标准的 RAG 检索相关的文本块，并让 LLM 从中回答。标准的知识图谱存储 `(主语，谓语，宾语)` 三元组。两者都无法捕捉到关系*存在的原因*。
考虑一个定价决策：
```
标准 KG: Sarah Chen --APPROVES--> MegaCorp
上下文图: Sarah Chen --APPROVES--> MegaCorp
rc = {
decision_trace: "Approved 20% discount citing 5-year relationship
and Salesforce competitive pressure",
approved_by: "Sarah Chen",
approved_via: "in_person",
valid_from: "2024-08-14",
valid_until: "2024-12-31",
policy_ref: "DiscountPolicy_Standard",
quantitative_data: "20% discount",
provenance: "Slack #deals-review, Aug 14 2024",
confidence_score: 0.97
}
```
<p align="center">
<img src="docs/assets/fig1-triple-vs-quadruple.svg" alt="Standard triple versus a Context Graph quadruple" width="820">
</p>
<p align="center"><em><b>图 1.</b> 相同的边，两种记忆。三元组知道批准发生了；四元组知道背后的决策过程 — 并可以在任何字段上查询。</em></p>
使用上下文图，您可以回答以下问题：
- *"谁批准了 2024 年第三季度超过 15% 的折扣，以及这些批准是否仍然有效？*"
- *"查找过去 6 个月内通过 Slack 批准的所有定价例外情况*"
- *"是否有豁免标准付款条款以换取续约承诺的先例？*"
- *"哪些由区域副总裁批准的优惠活动至今仍在进行中？*"
- *"显示引用 DiscountPolicy_v2 的所有决策*"
这些问题都无法仅凭文本块回答。
---
## 核心概念
### 上下文四元组 `(h, r, t, rc)`
上下文图中的每个关系都是一个四组件结构：
| 组件 | 含义 |
|-----------|---------|
| `h` | 头实体（源） |
| `r` | 关系类型 / 关键词 |
| `t` | 尾实体（目标） |
| `rc` | **关系上下文** — 决策记录 |
### 关系上下文
`关系上下文`（[context_graph/types.py](context_graph/types.py)）是一个包含 11 个字段的数据类：
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `supporting_sentences` | `List[str]` | 源文档的逐字引用 |
| `temporal_info` | `str \| None` | 自由格式的有效期（`"Q4 2026"`，`"since 2020"`） |
| `quantitative_data` | `str \| None` | 数值指标（折扣%，预算，计数） |
| `decision_trace` | `str \| None` | **为什么** — 理由，例外，覆盖，批准 |
| `approved_by` | `str \| None` | 批准者实体名称（`"VP_Smith"`，`"Finance_Team"`） |
| `approved_via` | `str \| None` | 批准渠道：`slack` `zoom` `email` `in_person` `jira` `system` |
| `valid_from` | `str \| None` | ISO-8601 生效日期（`"YYYY-MM-DD"`） |
| `valid_until` | `str \| None` | ISO-8601 过期日期（`"YYYY-MM-DD"`） |
| `policy_ref` | `str \| None` | 遵循或覆盖的政策名称/ID |
| `provenance` | `str \| None` | 源引用：线程 ID，文档部分，调用时间戳 |
| `confidence_score` | `float` | 提取可靠性 0.0–1.0（默认 `1.0`） |
<p align="center">
<img src="docs/assets/fig2-relationcontext-anatomy.svg" alt="RelationContext anatomy — the 11 fields grouped by what they answer" width="820">
</p>
<p align="center"><em><b>图 2.</b> 11 个关系上下文字段，按它们回答的问题分组 — 来源，谁决定，持续多久。</em></p>
### 两条关系上下文路径
**提取路径** — 通过 `ainsert()` 摄入散文文档。LLM 从每个句子中提取实体、关系和关系上下文 JSON 对象。适用于历史记录、通话记录、电子邮件线程、会议笔记。
**发射路径** — 在做出决策时直接调用 `emit_decision_trace()`。关系上下文直接写入图谱。适用于 webhook、审批机器人、工作流系统。
两条路径都馈入相同的图谱和相同的向量索引。
<p align="center">
<img src="docs/assets/fig3-two-capture-paths.svg" alt="Two capture paths — extraction from prose and direct emission" width="820">
</p>
<p align="center"><em><b>图 3.</b> 提取从散文摄入关系上下文；发射在决策时直接写入。两者都落在相同的图谱和索引中。</em></p>
### CGR3 推理
CGR3（检索 → 排名 → 推理）是上下文图的迭代多跳查询循环。它重复执行最多 `max_iterations` 次，每次传递可能会发现新的实体，这些实体将成为下一次检索的种子：
1. **检索** — 获取具有关系上下文的候选实体和边
2. **排名** — 要求 LLM 按相关性排序候选
3. **推理** — 要求 LLM 判断累积上下文是否足以回答；如果不足，识别后续实体并重复
<p align="center">
<img src="docs/assets/fig4-cgr3-loop.svg" alt="The CGR3 Retrieve-Rank-Reason loop" width="800">
</p>
<p align="center"><em><b>图 4.</b> 每次传递都可能发现新的实体，这些实体将成为下一次检索的种子，因此图谱遍历加深，直到上下文足够（或达到 <code>max_iterations</code>）。</em></p>
---
## 安装
### Docker（推荐）
仓库提供 `Dockerfile` 和 `docker-compose.yml` — 快速启动服务器 + WebUI：
```bash
git clone https://github.com/dsivov/Context_Graph.git
cd Context_Graph
cp env.example .env # set USE_CONTEXT_GRAPH=true + your LLM/embedding keys
docker compose up -d # server + WebUI on http://localhost:9621/webui/
```
参见 [`docs/DockerDeployment.md`](docs/DockerDeployment.md) 获取存储后端和生产环境说明。
### 从源代码（Python 3.12）
```bash
git clone https://github.com/dsivov/Context_Graph.git
cd Context_Graph
uv sync --extra api # API server support (recommended)
# or: uv sync --extra api --extra offline-storage --extra offline-llm --extra test
source .venv/bin/activate
lightrag-server --host 0.0.0.0 --port 9621
```
**要求：**
- Python 3.12
- 具有至少 32B 参数和 32K 上下文窗口的 LLM（例如 `gpt-4o`）
- 嵌入模型（例如，`text-embedding-3-large`，`BAAI/bge-m3`）
---
## 快速开始
### Python SDK
```python
import asyncio
from lightrag import ContextGraph, QueryParam, RelationContext
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed
async def main():
cg = ContextGraph(
working_dir="./cg_storage",
llm_model_func=gpt_4o_mini_complete,
embedding_func=openai_embed,
)
await cg.initialize_storages()
# ── 1. 摄入文档 ─────────────────────────────────────────────
await cg.ainsert(
"During the Q3 2024 business review, Sarah Chen (VP of Sales) approved "
"a 20% discount for MegaCorp's enterprise deal, citing their five-year "
"relationship and a competing offer from Salesforce. The discount was "
"valid until December 31, 2024. Discussed in Slack #deals-review."
)
# ── 2. 标准查询（边由关系上下文丰富） ────────────
result = await cg.aquery(
"What discount did Sarah Chen approve for MegaCorp?",
param=QueryParam(mode="hybrid"),
)
print(result)
# ── 3. CGR3 迭代多跳推理 ────────────────────────────
answer = await cg.cgr3_query(
"Why was the MegaCorp deal discounted and is the approval still valid?",
max_iterations=3,
)
print(answer)
# ── 4. 实时决策捕获 ────────────────────────────────────
await cg.emit_decision_trace(
src="Regional_VP",
tgt="StrategicAccount_XYZ",
relation_type="APPROVES_EXCEPTION",
rc=RelationContext(
decision_trace="Approved 30% discount — 5-year renewal at risk",
approved_by="Regional_VP",
approved_via="slack",
valid_from="2025-01-15",
valid_until="2025-06-30",
policy_ref="DiscountPolicy_v2",
quantitative_data="30% discount",
provenance="Slack #exec-deals, Jan 15 2025",
confidence_score=1.0,
),
)
# ── 5. 语义先例搜索 ─────────────────────────────────────
precedents = await cg.find_precedents(
"discount approved for strategic renewal at risk",
top_k=5,
min_confidence=0.7,
)
for p in precedents:
rc = p["relation_context"]
print(f"{p['src_id']} -> {p['tgt_id']}: {rc.decision_trace}")
# ── 6. 结构化决策过滤 ────────────────────────────────────
active = await cg.get_all_decisions(
approved_by="Regional_VP",
active_as_of="2025-03-01",
)
print(f"{len(active)} active decisions by Regional_VP")
await cg.finalize_storages()
asyncio.run(main())
```
### API 服务器
```bash
# 配置
cp env.example .env
# 编辑 .env — 设置 USE_CONTEXT_GRAPH=true 和您的 LLM/嵌入式凭证
# 启动服务器
lightrag-server
# 或使用热重载进行开发
uvicorn lightrag.api.lightrag_server:app --reload
```
---
## 配置
### 环境变量
创建 `.env` 文件（参见 `env.example` 获取完整模板）：
```env
# ── 上下文图 ─────────────────────────────────────────────────────────
USE_CONTEXT_GRAPH=true # 启用 CG 模式（需要 CG 功能）
CGR3_MAX_ITERATIONS=3 # 最大 CGR3 推理迭代次数（默认：3）
# ── LLM ───────────────────────────────────────────────────────────────────
LLM_BINDING=openai
LLM_MODEL=gpt-4o
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_API_KEY=sk-...
# ── 嵌入式 ─────────────────────────────────────────────────────────────
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_DIM=3072
EMBEDDING_API_KEY=sk-...
# ── 存储 ───────────────────────────────────────────────────────────────
# 基于文件（默认，无需设置）：
KV_STORAGE=JsonKVStorage
VECTOR_STORAGE=NanoVectorDBStorage
GRAPH_STORAGE=NetworkXStorage
DOC_STATUS_STORAGE=JsonDocStatusStorage
# PostgreSQL（生产环境）：
# KV_STORAGE=PGKVStorage
# VECTOR_STORAGE=PGVectorStorage
# GRAPH_STORAGE=Neo4JStorage
# POSTGRES_URL=postgresql://user:pass@host:5432/db
# ── 查询默认值 ────────────────────────────────────────────────────────
TOP_K=60
MAX_TOTAL_TOKENS=32768
DEFAULT_QUERY_MODE=hybrid
```
### Python 构造函数
```python
cg = ContextGraph(
working_dir="./cg_storage",
workspace="project_name", # 命名空间隔离
llm_model_func=gpt_4o_mini_complete,
embedding_func=openai_embed,
kv_storage="PGKVStorage", # 覆盖默认值
vector_storage="PGVectorStorage",
graph_storage="Neo4JStorage",
doc_status_storage="PGDocStatusStorage",
)
```
---
## 文档摄入
`ainsert()` 接受文本字符串、列表和可选的文件路径元数据用于引用：
```python
# 单个文档
await cg.ainsert("Meeting notes text...")
# 批量
await cg.ainsert([
"Q3 review transcript...",
"Policy document text...",
"Email thread content...",
])
# 带有文件路径元数据（用于出处/引用）
await cg.ainsert(
["Call transcript...", "Approval email..."],
file_paths=["calls/2024-08-14.txt", "emails/approval-123.eml"],
)
```
在摄入过程中，LLM 提取每个关系的 6 个字段记录，其中第 6 个字段是紧凑的关系上下文 JSON：
```
relation<|#|>Sarah Chen<|#|>MegaCorp<|#|>discount approval<|#|>
Sarah Chen approved a 20% discount for MegaCorp.<|#|>
{"supporting_sentences":["VP of Sales approved 20% discount"],"temporal_info":
"Valid until December 31, 2024","quantitative_data":"20% discount","decision_trace":
"Approved citing five-year relationship and Salesforce competition","approved_by":
"Sarah Chen","approved_via":"in_person","valid_from":null,"valid_until":"2024-12-31",
"policy_ref":null,"provenance":"Slack #deals-review Aug 14 2024","confidence_score":0.97}
```
LLM 在批准者和渠道被提及时填充 `approved_by` / `approved_via`，在出现明确日期时填充 `valid_from` / `valid_until`，在引用政策名称时填充 `policy_ref`。如果文本中没有证据，字段将被设置为 `null`。
---
## 网页摄入
将上下文图指向一个公共网站，它会直接将内容爬取到图中。`POST /scrape` 启动一个异步作业，该作业以 breadth-first 方式遍历相同域 — 尊重 `robots.txt`、速率限制、深度和页面数量限制 — 提取每个页面的可读主文本，并插入 **带有页面 URL 作为文件路径**，以便 URL 成为从中提取的每个四元组的出处。
<p align="center">
<img src="docs/assets/fig6-web-ingestion-pipeline.svg" alt="Web ingestion pipeline — crawl, read, ingest" width="860">
</p>
<p align="center"><em><b>图 5.</b> 指向 URL；它礼貌地爬取，读取任何格式，并将内容交给上下文图的摄入，同时保留 URL 作为出处。</em></p>
```bash
# 启动 JS-rendered、LLM-filtered 爬取（工作区范围）
curl -X POST http://localhost:9621/scrape \
-H "LIGHTRAG-WORKSPACE: district_acme" -H "Content-Type: application/json" \
-d '{"url":"https://acme.k12.org","render_js":true,"analyze":true,"max_depth":3}'
# -> {"job_id":"a1b2c3d4e5f6","state":"running"}
curl http://localhost:9621/scrape/a1b2c3d4e5f6 -H "LIGHTRAG-WORKSPACE: district_acme"
```
- **礼貌爬虫** — 同域 BFS、`robots.txt`、每主机速率限制、站点地图种子、主文本提取。
- **可插拔连接器** — 平台插件，破解通过 JS 小部件或私有 API 隐藏文件的站点。WordPress、Finalsite/Blackboard 和 BoardDocs 已启用；添加一个只需复制模板。
- **LLM 引导采集** — 使用 `analyze=true`，LLM 选择正确的连接器并过滤值得摄入的资源。如果未配置 LLM，则失败时会采用确定性行为。
> 📖 完整指南：[`docs/SCRAPER.html`](https://dsivov.github.io/Context_Graph/SCRAPER.html)
---
## 实时决策捕获
`emit_decision_trace()` 在决策**做出时**将决策写入图中，来自代理代码或 webhook 处理程序 - 无需文档摄入往返。
```python
rc = RelationContext(
decision_trace="豁免30天付款期限；客户承诺3年续约",
approved_by="爱丽丝",
approved_via="zoom",
valid_from="2024-11-01",
valid_until="2025-10-31",
policy_ref="PaymentPolicy_Standard",
quantitative_data="净-30豁免",
provenance="Zoom通话录音 2024-11-01",
confidence_score=1.0,
)
await cg.emit_decision_trace(
src="爱丽丝",
tgt="AcmeCorp",
relation_type="WAIVES_PAYMENT_TERMS",
rc=rc,
upsert=True, # 如果边已经存在则合并（默认）
)
```
**当 `upsert=True` 时的合并语义：**
- `supporting_sentences`：联合（去重，保留顺序）
- 所有标量字符串字段（`decision_trace`、`approved_by`等）：第一个非None值获胜
- `confidence_score`：所有版本中最大值
`decision_trace` 文本立即在 `decisions` 向量存储中索引，使该决策可通过 `find_precedents()` 无延迟发现。
---
## 治理与行动
工作区范围的层将一个记住决策的图变成一个治理决策的图 - 而且，通过操作层，可以从中操作。规则和本体通过 WebUI（**规则** 和 **本体** 标签）或 REST 进行管理；通过 REST 管理和调用操作。
### 业务规则引擎
**预发射治理门控**：在写入任何决策之前，工作区的规则会评估它并返回三种结果之一 - `PASS`（持久化）、`FLAG`（持久化，标记 `needs_review`）或 `REJECT`（中止，什么也不持久化）。规则使用小型 DSL 编写，该 DSL 通过语义 `sim()` 谓词将结构化字段与精确运算符和自由文本字段*按含义*匹配（本地 `minishlab/potion-retrieval-32M` 嵌入 - 无 API 成本）。评估是**开放失败**：配置错误的规则被跳过并发出警告，永远不会崩溃摄入。
```text
rule "large discount needs finance review" priority 10
when
sim(relation_type, "APPROVAL") > 0.4
and percent > 0.15
and approved_via == "slack"
then
flag("Discount >15% approved over Slack — route to Finance")
end
```
用纯英语描述一个策略，`POST /rules/generate` 编写 DSL，定义概念，并**证明**它与干燥运行自测试，然后再保存。参见 [`docs/RULES_ENGINE.html`](https://dsivov.github.io/Context_Graph/RULES_ENGINE.html).
### 本体
工作区的**类型化模式** - 对象类型和有向链接类型，每个都有类型化属性 - 每个提取都针对该模式进行验证。验证是**强制**的：检查记录的相同过程会规范化它（`" $ 25,000"` → `25000.0` ， `"20%"` → `0.2`），这就是规则引擎获得实际数字而不是自由文本的原因，而不是自由文本。默认情况下开放世界（未知类型警告）；封闭世界拒绝它们。`POST /ontology/generate` 从领域描述中草拟模式。参见 [`docs/ONTOLOGY.html`](https://dsivov.github.io/Context_Graph/ONTOLOGY.html).
### 操作层
**绑定到对象类型的可执行操作** - `ApproveOrder`、`CancelShipment`。调用一个操作会将推理图转换为操作图：它验证类型化参数（重用本体的强制类型），**通过规则门控授权和记录执行** (`emit_decision_trace`)，并且 - 仅在 `PASS`/`FLAG` 上 - 运行可选的副作用。写入图的审计边是执行的动作记录，因此动作的治理与任何其他决策完全相同。
```bash
# 注册目录，然后调用 - 规则门控在副作用之前授权
curl -X POST http://localhost:9621/actions -H "LIGHTRAG-WORKSPACE: sales" \
-H "Content-Type: application/json" -d '{"catalog":{"name":"sales","actions":[
{"name":"ApproveOrder","object_type":"Order","relation_type":"APPROVED",
"params":[{"name":"discount","kind":"percent","required":true}]}]}}'
curl -X POST http://localhost:9621/actions/invoke -H "LIGHTRAG-WORKSPACE: sales" \
-H "Content-Type: application/json" \
-d '{"action":"ApproveOrder","actor":"Sarah","object_ref":"Order#123","args":{"discount":"20%"}}'
# -> outcome FLAG · audit rule "large discount review" · edge Sarah -APPROVED-> Order#123
```
- **通过构造治理** - 门控先运行，因此 `REJECT`（映射到 HTTP 422）永远不会触发副作用。
- **类型化参数** - 货币/百分比参数被强制转换为 `quantitative_data`，因此规则可以对其进行推理。
- **SSRF 保护的处理程序** - `none`（仅记录）或 `webhook`；除非 `allow_internal`，否则 webhook 拒绝环回/私有主机。
> 📖 完整指南：[`docs/ACTIONS.html`](https://dsivov.github.io/Context_Graph/ACTIONS.html)
> 这些功能需要 `USE_CONTEXT_GRAPH=true` 并且否则返回 **HTTP 503**.
---
## AI 代理开发
将编码代理 - 或整个开发团队的代理 - 指向上下文图，它停止重建已经存在的内容，停止丢失过去选择背后的**原因**，并遵循图**强制**的方法论（规则，RBAC，生命周期）。方法论本身就是**数据** - `agentic-dev` 预设的本体/规则/操作/RBAC/生命周期 - 所以核心保持通用。这是一个决策感知平台上的管理系统，而不是在 IDE 上附加的代码索引。
**绿地入职只有一个 URL.** 服务器提供代理的剧本和引导包，**实时**从工作区的安装配置（真实对象类型，操作，防护栏）生成 - 仓库中没有指南文件需要手动复制：
```bash
# 1) 代理初始化所需的一切 - mcp 配置，补全命令，剧本/清单链接
curl -s http://localhost:9621/workspace/bootstrap -H "LIGHTRAG-WORKSPACE: myproj"
# 2) 补全现有仓库/分支 - 服务器提供脚本；代理在本地运行它
# （导入模块，作者，提交，文档，如果 --code 则源代码本身）
curl -s http://localhost:9621/workspace/backfill-script | python - --repo . --workspace myproj --code
# 3) 实时操作指南（Markdown）- 三个习惯，你的动作，信号
curl -s http://localhost:9621/workspace/playbook -H "LIGHTRAG-WORKSPACE: myproj"
```
入职一个**全新**的工作区？`POST /onboard` 带有纯英文描述的定制本体 + 规则，并返回相同的引导包，在一次调用中为代理提供其入口点。
> 📖 完整用例：[`docs/AGENTIC_DEVELOPMENT.html`](https://dsivov.github.io/Context_Graph/AGENTIC_DEVELOPMENT.html) · 设计讨论：[`docs/AGENTIC_PROJECT_GRAPH.html`](https://dsivov.github.io/Context_Graph/AGENTIC_PROJECT_GRAPH.html)
> 需要 `USE_CONTEXT_GRAPH=true`.
---
## 查询
上下文图保留所有标准的检索模式，并添加一个 `auto` 路由器，为您选择最佳模式 - 分类一次，缓存判决，并附带推理结果。
<p align="center">
<img src="docs/assets/fig5-auto-query-router.svg" alt="自动查询路由器 - 分类一次，路由到最佳模式" width="860">
</p>
<p align="center"><em><b>图 7.</b> <code>auto</code> 路由器一次性分类（并缓存），路由到最佳模式，并返回带有推理的答案。</em></p>
### 标准查询
所有标准的 LightRAG 查询模式均无变化。检索到的边包括其 RelationContext 在 LLM 的上下文窗口中，基于实际决策记录的答案。
```python
from lightrag import QueryParam
result = await cg.aquery(
"2025 年第一季度批准了哪些定价例外？",
param=QueryParam(
mode="hybrid", # local | global | hybrid | naive | mix
top_k=60,
enable_rerank=True,
),
)
```
### CGR3 迭代推理
```python
answer = await cg.cgr3_query(
query="为什么批准了 MegaCorp 例外，谁授权了它， "
"它是否仍然有效？",
mode="hybrid",
max_iterations=3, # 如果找到足够的上下文，则提前停止
top_k=60,
)
```
每次迭代：
1. 检索具有 RelationContext 的候选实体/边
2. 按 LLM 评估的相关性进行排名
3. 判断上下文是否足够 - 如果是，则返回答案；否则，种子下一个迭代
### 先例搜索
索引的 `decision_trace` 文本上的语义向量相似性：
```python
precedents = await cg.find_precedents(
query_text="批准的战略续约折扣例外",
top_k=10,
min_confidence=0.7,
)
for p in precedents:
rc = p["relation_context"]
print(f"{p['src_id']} -> {p['tgt_id']}")
print(f" 决策：{rc.decision_trace}")
print(f" 由 {rc.approved_by} 批准，通过 {rc.approved_via}")
print(f" 有效：{rc.valid_from} → {rc.valid_until}")
print(f" 策略：{rc.policy_ref}")
print(f" 今日活跃：{rc.is_active()}")
```
### 决策过滤
枚举所有具有结构化过滤器的决策边（所有参数均为 AND）：
```python
# 所有当前有效的特定审批者的决策
decisions = await cg.get_all_decisions(
approved_by="CFO_Johnson",
active_as_of="2025-04-01",
min_confidence=0.8,
)
# 所有 Slack 批准的引用特定策略的例外
decisions = await cg.get_all_decisions(
approved_via="slack",
policy_ref="DiscountPolicy_v2",
)
# 完整的审计日志 - 无过滤
all_decisions = await cg.get_all_decisions()
```
### 时间有效性
`RelationContext.is_active()` 执行日期范围检查：
```python
rc = RelationContext(valid_from="2024-01-01", valid_until="2024-12-31")
rc.is_active() # True/False 基于今天
rc.is_active(as_of="2024-06-15") # True
rc.is_active(as_of="2025-01-01") # False - 过期
rc.is_active(as_of="2023-12-31") # False - 尚未生效
```
如果两个日期均未设置，则返回 `True`（有效性未知）。
---
## REST API
使用 `USE_CONTEXT_GRAPH=true` 启动服务器。下面的所有端点如果服务器未在上下文图模式下运行，则返回 **HTTP 503**，因此客户端可以在运行时检测功能。
### 端点概述
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/query` | 标准 RAG 查询 - 边缘由 RelationContext 丰富 |
| `POST` | `/documents/text` · `/documents/texts` · `/documents/upload` | 摄入内容并提取 RelationContext |
| `POST` | `/cgr3/query` | CGR3 迭代检索→排名→推理 |
| `GET` | `/graph/edge/context` | 特定图的 RelationContext |
| `GET` | `/graph/entity/edges-with-context` | 实体所有上下文丰富的边 |
| `POST` | `/graph/decision/emit` | 直接向图写入决策 |
| `GET` | `/graph/decisions/search` | 语义先例搜索 |
| `GET` | `/graph/decisions` | 列出/过滤所有决策边 |
| `POST` | `/scrape` | 爬取网站到图（异步作业）- 参见 [Web 摄入](#web-ingestion) |
| `GET` | `/scrape/{job_id}` · `/scrape` | 轮询 / 列出 web-ingest 作业 |
| `GET`/`POST`/`DELETE` | `/rules` | 获取，保存或删除工作区规则策略 |
| `POST` | `/rules/evaluate` · `/rules/toggle` · `/rules/generate` | 试运行，启用/禁用或从纯英语编写规则 |
| `GET`/`POST`/`DELETE` | `/ontology` | 获取，保存或删除工作区本体 |
| `POST` | `/ontology/generate` · `/ontology/validate` | 从描述中编写模式；验证提取 |
| `GET`/`POST`/`DELETE` | `/actions` | 获取，保存或删除工作区操作目录 |
| `GET`/`POST` | `/actions/{name}` · `/actions/invoke` | 获取一个操作；调用操作（验证→门控→副作用） |
---
### `POST /cgr3/query`
迭代多跳推理。
```http
POST /cgr3/query
Content-Type: application/json
{
"query": "为什么 MegaCorp 交易获得折扣，谁批准了它？",
"mode": "hybrid",
"max_iterations": 3,
"top_k": 60,
"include_references": true
}
```
```json
{
"response": "MegaCorp 交易获得 20% 折扣，由销售副总裁 Sarah Chen 于 2024 年 8 月 14 日批准。理由是与 Salesforce 的竞争报价和五年的关系。该折扣有效期至 2024 年 12 月 31 日。",
"references": null
}
```
**请求字段：
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `query` | 字符串 | 必需 | 自然语言问题（最小 3 个字符） |
| `mode` | 字符串 | `"hybrid"` | 检索模式：`local` `global` `hybrid` `naive` `mix` |
| `max_iterations` | int | `3` | CGR3 迭代（1-10） |
| `top_k` | int | 服务器默认值 | 每个迭代的实体/关系 |
| `include_references` | bool | `true` | 在响应中包含源引用 |
---
### `POST /graph/decision/emit`
在运行时直接向图中写入决策。
```http
POST /graph/decision/emit
Content-Type: application/json
{
"src": "Regional_VP",
"tgt": "StrategicAccount_XYZ",
"relation_type": "APPROVES_EXCEPTION",
"relation_context": {
"decision_trace": "批准 30% 折扣 - 5 年续约有风险",
"approved_by": "Regional_VP",
"approved_via": "slack",
"valid_from": "2025-01-15",
"valid_until": "2025-06-30",
"policy_ref": "DiscountPolicy_v2",
"quantitative_data": "30% 折扣",
"provenance": "Slack #exec-deals, Jan 15 2025",
"confidence_score": 1.0
}
}
```
```json
{
"status": "ok",
"edge": "Regional_VP -> StrategicAccount_XYZ"
}
```
如果边已经存在，则 RelationContexts 会合并。`decision_trace` 立即在决策向量存储中索引。
---
### `GET /graph/edge/context`
检索存储在特定图边上的 RelationContext。
```http
GET /graph/edge/context?src=Sarah+Chen&tgt=MegaCorp
```
```json
{
"src_id": "Sarah Chen",
"tgt_id": "MegaCorp",
"has_context": true,
"relation_context": {
"supporting_sentences": ["Sarah Chen（销售副总裁）批准为 MegaCorp 提供 20% 的折扣"],
"temporal_info": "有效期至 2024 年 12 月 31 日",
"quantitative_data": "20% 折扣",
"decision_trace": "批准理由是五年的关系和 Salesforce 的竞争报价",
"approved_by": "Sarah Chen",
"approved_via": "in_person",
"valid_from": null,
"valid_until": "2024-12-31",
"policy_ref": null,
"provenance": "Slack #deals-review, August 14 2024",
"confidence_score": 0.97
}
}
```
---
### `GET /graph/entity/edges-with-context`
指定实体所有上下文丰富的边。
```http
GET /graph/entity/edges-with-context?entity_name=Sarah+Chen
```
```json
{
"entity_name": "Sarah Chen",
"total_count": 2,
"edges": [
{
"src_id": "Sarah Chen",
"tgt_id": "MegaCorp",
"keywords": "discount approval, deal negotiation",
"description": "Sarah Chen 批准为 MegaCorp 提供 20% 的折扣。",
"weight": 1.5,
"relation_context": { "..." }
}
]
}
```
---
### `GET /graph/decisions/search`
语义向量搜索索引决策轨迹。
```http
GET /graph/decisions/search?q=discount+approved+strategic+renewal&top_k=5&min_confidence=0.7
```
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `q` | 字符串 | 必需 | 自然语言查询 |
| `top_k` | int | `10` | 最大结果数（1-100） |
| `min_confidence` | float | `0.0` | 置信度阈值（0.0-1.0） |
```json
{
"query": "discount approved strategic renewal",
"total_count": 2,
"results": [
{
"src_id": "Regional_VP",
"tgt_id": "StrategicAccount_XYZ",
"relation_context": {
"decision_trace": "Approved 30% discount — 5-year renewal at risk",
"approved_by": "Regional_VP",
"approved_via": "slack",
"valid_from": "2025-01-15",
"valid_until": "2025-06-30",
"policy_ref": "DiscountPolicy_v2",
"confidence_score": 1.0
}
}
]
}
```
---
### `GET /graph/decisions`
列出所有决策边，带有可选的结构化过滤器。所有参数均为 AND。
```http
GET /graph/decisions?approved_by=CFO_Johnson&active_as_of=2025-04-01&min_confidence=0.8
```
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `approved_by` | 字符串 | - | 按批准者实体名称过滤 |
| `approved_via` | 字符串 | - | 按渠道过滤：`slack` `zoom` `email` `in_person` `jira` `system` |
| `policy_ref` | 字符串 | - | 按策略名称/ID 过滤 |
| `min_confidence` | float | `0.0` | 置信度阈值 |
| `active_as_of` | 字符串 | - | ISO-8601 日期 - 仅在该日期有效的决策 |
```json
{
"total_count": 3,
"decisions": [
{
"src_id": "CFO_Johnson",
"tgt_id": "GlobalTech",
"relation_context": {
"decision_trace": "Q1 2025 批准 GlobalTech 例外",
"approved_by": "CFO_Johnson",
"approved_via": "email",
"valid_from": "2025-01-05",
"valid_until": "2025-03-31",
"policy_ref": "DiscountPolicy_v2",
"quantitative_data": "25% 折扣",
"confidence_score": 0.94
}
}
]
}
```
---
## 集成模式
```
### 1. 销售线索 / HubSpot 审批 Webhook
在您的 CRM 中记录交易审批时触发 `emit_decision_trace`，无需批量重新摄入即可保持图的更新。
```python
async def on_opportunity_approval(event: dict):
"""由 Salesforce webhook 在折扣审批时调用。"""
await cg.emit_decision_trace(
src=event["approver_name"],
tgt=event["account_name"],
relation_type="APPROVES_DISCOUNT",
rc=RelationContext(
decision_trace=event["approval_comment"],
approved_by=event["approver_name"],
approved_via="system",
valid_from=event["effective_date"],
valid_until=event["expiry_date"],
policy_ref=event.get("policy_applied"),
quantitative_data=f"{event['discount_pct']}%折扣",
provenance=f"Salesforce 交易机会 {event['opportunity_id']}",
confidence_score=1.0,
),
)
```
### 2. Slack 审批机器人
通过事件 API 实时捕获在 Slack 频道中做出的审批。
```python
async def on_slack_approval(message: dict):
"""/approve 在 #deals-review 中使用斜杠命令处理程序。"""
parsed = parse_approval_message(message["text"])
await cg.emit_decision_trace(
src=parsed.approver,
tgt=parsed.account,
relation_type=parsed.decision_type,
rc=RelationContext(
decision_trace=parsed.rationale,
approved_by=parsed.approver,
approved_via="slack",
valid_until=parsed.expiry,
provenance=f"Slack #{message['channel_name']}, {message['ts']}",
confidence_score=1.0,
),
)
```
### 3. 夜间文档同步
按计划批量摄入通话记录、会议笔记和电子邮件线程。LLM 自动提取关系上下文。
```python
async def nightly_ingest(docs_dir: str):
from pathlib import Path
texts, paths = [], []
for p in Path(docs_dir).glob("*.txt"):
texts.append(p.read_text())
paths.append(str(p))
await cg.ainsert(texts, file_paths=paths)
```
### 4. AI 销售代表助手
助手尊重当前政策，在推荐折扣之前引用实际先例。
```python
import datetime
async def advise_on_discount(account: str, requested_pct: float) -> str:
# 查找类似的过去决策
precedents = await cg.find_precedents(
f"{requested_pct}% 折扣批准给企业账户",
top_k=5, min_confidence=0.7,
)
# 检查该账户现有的活动审批
active = await cg.get_all_decisions(
active_as_of=datetime.date.today().isoformat()
)
account_active = [d for d in active if d["tgt_id"] == account]
# 构建上下文字符串
context_lines = [
f"- {p['relation_context'].decision_trace} "
f"(批准人：{p['relation_context'].approved_by}, "
f"置信度 {p['relation_context'].confidence_score:.0%})"
for p in precedents
]
return await cg.cgr3_query(
f"我们应该为 {account} 批准 {requested_pct}% 的折扣吗？ "
f"现有的活动审批：{len(account_active)}。 "
f"相关先例：\n" + "\n".join(context_lines),
)
```
### 5. 合规审计轨迹
生成指定期间内所有定价异常的完整审计报告。
```python
async def pricing_audit_report(as_of: str) -> list[dict]:
"""给定日期激活的所有决策，引用定价政策。"""
decisions = await cg.get_all_decisions(
policy_ref="DiscountPolicy_v2",
active_as_of=as_of,
min_confidence=0.5,
)
return [
{
"approver": d["relation_context"].approved_by,
"account": d["tgt_id"],
"channel": d["relation_context"].approved_via,
"decision": d["relation_context"].decision_trace,
"period": f"{d['relation_context'].valid_from} → {d['relation_context'].valid_until}",
"policy": d["relation_context"].policy_ref,
"confidence": d["relation_context"].confidence_score,
}
for d in decisions
]
```
### 6. HTTP API 集成（任何语言）
```bash
# 从 shell 脚本或 CI 管道发出决策
curl -s -X POST http://localhost:9621/graph/decision/emit \
-H "Content-Type: application/json" \
-d '{
"src": "CTO",
"tgt": "VendorABC",
"relation_type": "APPROVES_CONTRACT",
"relation_context": {
"decision_trace": "批准具有退出条款的 3 年供应商合同",
"approved_by": "CTO",
"approved_via": "email",
"valid_from": "2025-03-01",
"valid_until": "2028-02-28",
"policy_ref": "ProcurementPolicy_v3",
"confidence_score": 1.0
}
}'
# 查找先例
curl -s "http://localhost:9621/graph/decisions/search?q=vendor+contract+approved&top_k=5"
# 按审批人列出所有决策
curl -s "http://localhost:9621/graph/decisions?approved_by=CTO&active_as_of=2025-06-01"
```
---
## 存储后端
Context Graph 支持所有 LightRAG 存储后端。通过 `.env` 或构造函数参数进行配置。
### 图存储
| 后端 | 类 | 用例 |
|---------|-------|----------|
| NetworkX（默认） | `NetworkXStorage` | 开发，单进程 |
| Neo4j | `Neo4JStorage` | 生产环境，复杂图查询 |
| Memgraph | `MemgraphStorage` | 高吞吐量图工作负载 |
### 向量存储
| 后端 | 类 | 用例 |
|---------|-------|----------|
| NanoVectorDB（默认） | `NanoVectorDBStorage` | 开发，无需设置 |
| PostgreSQL pgvector | `PGVectorStorage` | 生产环境，统一数据库 |
| Qdrant | `QdrantStorage` | 大规模向量搜索 |
| Milvus | `MilvusStorage` | 大规模部署 |
| Faiss | `FaissStorage` | 本地，CPU 优化 |
`decisions` 向量命名空间（Context Graph 新增）自动使用相同的配置向量后端。
### 键值存储
| 后端 | 类 | 用例 |
|---------|-------|----------|
| JSON 文件（默认） | `JsonKVStorage` | 开发 |
| PostgreSQL | `PGKVStorage` | 生产环境 |
| Redis | `RedisKVStorage` | 高吞吐量缓存 |
| MongoDB | `MongoKVStorage` | 面向文档的工作负载 |
---
## LLM 提供商
| 提供商 | 模块 |
|----------|--------|
| OpenAI / 兼容 | `lightrag.llm.openai` |
| Azure OpenAI | `lightrag.llm.azure_openai` |
| Ollama | `lightrag.llm.ollama` |
| Anthropic | `lightrag.llm.anthropic` |
| Google Gemini | `lightrag.llm.gemini` |
| AWS Bedrock | `lightrag.llm.bedrock` |
| Hugging Face | `lightrag.llm.hf` |
| NVIDIA NIM | `lightrag.llm.nvidia_openai` |
**良好提取质量的最低要求：**
- 32B+ 参数
- 32K 上下文窗口（推荐 64K）
- 在索引期间避免推理/思维链模型 — 它们会产生不可靠的结构化输出
---
## 测试
```bash
# 运行完整的离线套件（无需外部服务）— 711 通过
python -m pytest tests context_graph/tests -q
# 仅运行核心 Context Graph 测试
python -m pytest tests/test_context_graph.py tests/test_context_graph_api.py -v --tb=short
# 运行集成测试（需要配置外部服务）
python -m pytest tests --run-integration
# 保留工件进行调试
python -m pytest tests --keep-artifacts
```
**测试套件覆盖率**（711 通过 / 35 跳过）：
| 区域 | 位置 | 覆盖率 |
|------|-------|---------|
| 核心 CG | `tests/test_context_graph.py` (75) | 关系上下文字段、`is_active()`、`merge()`、提取管道、`emit_decision_trace`、`find_precedents`、`get_all_decisions` |
| CG API | `tests/test_context_graph_api.py` (36) | CG 端点、Pydantic 模型、 plain LightRAG 的 503、配置解析 |
| 治理和质量 | `context_graph/tests/` | 规则引擎/网关/存储、ontology、RBAC、生命周期、操作、去重、垃圾过滤、连接性、社区 |
---
## 架构
### 类层次结构
```
LightRAG — 基础 RAG 引擎（ainsert、aquery、存储生命周期）
└── ContextGraph — CG 扩展
├── __post_init__ — 在标准存储之上创建 decisions_vdb
├── initialize_storages — 调用 super() + decisions_vdb.initialize()
├── finalize_storages — 调用 super() + decisions_vdb.finalize()
├── _process_extract_entities — 重写为使用 CG 6 字段提示
├── get_edge_context — 为特定边获取关系上下文
├── get_edges_with_context — 实体所有上下文丰富的边
├── emit_decision_trace — 在决策时直接写入 RC
├── find_precedents — 决策 vdb 上的语义搜索
├── get_all_decisions — 对所有决策边进行结构化筛选
└── cgr3_query — 迭代 Retrieve→Rank→Reason 循环
```
### 存储命名空间
| 命名空间 | 类型 | 内容 |
|-----------|------|---------|
| `full_docs` | KV | 原始插入文档 |
| `text_chunks` | KV | 分割的文档段落 |
| `llm_response_cache` | KV | LLM 提取缓存 |
| `entities` | Vector | 实体嵌入 |
| `relationships` | Vector | 关系嵌入 |
| `chunks` | Vector | 文本块嵌入 |
| `decisions` | Vector | 决策轨迹嵌入（仅 CG） |
| `chunk_entity_relation` | Graph | 带有关系上下文的实体关系图 |
| `doc_status` | 文档状态 | 文档处理状态 |
### 提取格式
LLM 在 CG 提取期间生成 6 字段关系记录：
```
relation<|#|>source_entity<|#|>target_entity<|#|>keywords<|#|>description<|#|>RC_JSON
```
其中 `RC_JSON` 是一个紧凑的单行 JSON 对象。标准 LightRAG 提取（5 字段格式）也被接受，`relation_context` 默认值为 `null` — 确保与任何现有的图数据向后兼容。
### 向后兼容性
- 所有新的关系上下文字段默认为 `None` — 现有图数据无需修改即可加载
- 标准 5 字段提取记录的解析方式与以前相同
- 所有标准 LightRAG 端点（`/query`、`/documents/*`、`/graph/...`）均保持不变
- 当 `USE_CONTEXT_GRAPH=false` 时，Context Graph 端点返回 HTTP 503，因此客户端可以正常降级
### 置信度评分指南
| 分数 | 含义 |
|-------|---------|
| `1.0` | 始终为 `emit_decision_trace()` 设置 — 结构化源，无歧义 |
| `0.9+` | 源文本中的明确、无歧义的陈述 |
| `0.7–0.9` | 清晰但隐含或推断 |
| `< 0.7` | 模糊 — 考虑使用 `min_confidence` 过滤 |
---
## 设计中的隐私保护：基于模式的丰富
Context Graph 遵循 **模式而非身份** 的原则进行对话丰富。在摄入真实的客户对话（销售记录、支持聊天）时，系统在知识图谱进入图谱之前会匿名化所有 PII。
### 匿名管道
| 数据类型 | 处理方式 | 示例 |
|-----------|-----------|---------|
| 客户姓名 | 完全删除 | `"Hi Natalie"` → `"Hi customer"` |
| 确切金额 | 分桶到范围 | `₪4,386.06` → `"3,000-5,000"` |
| 确切日期 | 仅月份/年份 | `2025-11-14` → `"November 2025"` |
| 电话号码 | 正则表达式清理 | `054-123-4567` → `[phone]` |
| 电子邮件地址 | 正则表达式清理 | `user@example.com` → `[email]` |
| 以色列 ID 号码 | 正则表达式清理 | `123456789` → `[id]` |
| 信用卡号码 | 正则表达式清理 | `4580-1234-5678-9012` → `[card]` |
| 街道地址 | 正则表达式清理 | `12 רחוב הרצל` → `[address]` |
| 机会 ID | SHA-256 哈希 | `abc-123-def` → `anon-7f3a2b1c9e4d` |
### 图谱学习内容
匿名后的对话文档教会图谱 **行为模式**：
- **交叉销售模式** — 客户一起购买哪些产品
- **异议处理** — 出现哪些顾虑以及如何解决
- **销售技巧** — 哪些信息传递会推动转化
- **产品比较** — 产品在实际客户对话中的差异
- **用例映射** — 客户实际需要产品的用途
### 图谱不存储的内容
- 客户姓名或标识符
- 确切的交易金额或日期
- 电话号码、电子邮件、物理地址
- 医疗状况、残疾或个人情况
- 任何可能识别特定个人的数据
这种方法灵感来自 [Context Graphs](https://foundationcapital.com/ideas/context-graphs-ais-trillion-dollar-opportunity) 范式：价值在于 **模式** （哪些产品放在一起，出现哪些异议） — 而不是 **身份** （谁购买了什么）。
> 这是一个推荐的 **客户端** 模式：在数据进入 `ainsert()` / `emit_decision_trace()` 之前进行 PII 清理和分桶，这样识别数据就不会进入图谱。
---
## 研究基础
Context Graph 实现了 [Liang et al., 2024](https://arxiv.org/abs/2406.11160) 中的 **CGR3（带有检索-排名-推理的上下文图）** 范式，基于 HKUDS 的基于图的 RAG 引擎 [LightRAG](https://github.com/HKUDS/LightRAG)。
### 论文对齐
| 论文概念 | 我们的实现 | 备注 |
|---|---|---|
| 事实四元组 `(h,r,t,rc)` | `RelationContext` 数据类（11 个字段） | 忠实 — 扩展了决策特定字段 |
| 关系上下文（时间、数量、来源、置信度） | `temporal_info`、`quantitative_data`、`provenance`、`confidence_score` | 直接映射 |
| CGR3：检索 → 排名 → 推理 | 带有迭代循环的 `cgr3_query()` | 忠实 — 最大 3 次迭代，提前停止 |
| 来自维基数据的实体上下文 | 从摄入文档的 LLM 提取 | 适用于文档优先的工作流 |
| KGE 嵌入（ComplEx、RotatE） | 文本嵌入（text-embedding-3-large，3072d） | 适配 — 结构化语义相似性 |
| 波束搜索（宽度 M，深度 D=3） | CGR3 每次传递的迭代实体种子细化 | 适配 |
| 添加上下文后 +33% Hits@1 | 混合模式 78.1% vs 朴素 70.4% 相关性 | 一致性改进 |
### 超出论文的扩展
| 扩展 | 描述 |
|-----------|-------------|
| **多租户** | 带有每个租户 Neo4j 标签隔离的工作区池，延迟初始化 |
| **实时决策捕获** | `emit_decision_trace()` — 无需重新摄入文档即可写入决策 |
| **设计中的隐私保护** | PII 清理、金额分桶、名称删除、哈希源 ID |
| **大小感知路由** | 小型目录的 `catalog_bypass`（<100 个产品），`auto` 路由器 |
| **先例搜索** | `find_precedents()` — 决策轨迹的语义搜索 |
| **时间过滤** | `is_active(as_of)` 用于日期范围有效性检查 |
| **业务规则引擎** | 预发射治理门 — DSL + 语义 `sim()`、PASS/FLAG/REJECT、NL 政策作者 |
| **本体论** | 每个工作区的类型化模式、强制执行提取验证、NL 模式作者 |
| **网页摄入** | 有礼貌的爬虫 + 可插入连接器，拉取任何带有 URL 来源的站点到图谱中 |
| **操作层** | 可执行操作绑定到对象类型；调用 → 规则门 → 审计边，具有 SSRF 保护的处理器 |
## 项目结构
所有Context Graph代码都位于顶级 **`context_graph/`** 包中； **`lightrag/`** 是可重用的基础RAG引擎和它所接入的HTTP服务器。
```
context_graph/ — 所有Context Graph代码（该分支的独立包）
├── core.py — ContextGraph类 + CG提取管道（主要入口点）
├── types.py — RelationContext, ContextNode, ContextEdge 数据类
├── jsonio.py — 无依赖的LLM-JSON解析器，所有CG模块共享
├── api/
│ └── routes.py — CG API端点（CGR3，决策，重复数据删除/质量/社区）
├── rules/ — 业务规则引擎（DSL，门，sim()，自然语言作者）
├── ontology/ — 类型化模式，强制验证，自然语言作者
├── rbac/ — 对象级基于角色的访问控制
├── lifecycle/ — 声明式对象状态机
├── actions/ — 绑定到对象类型的可执行操作，由门控
├── webingest/ — 礼貌的爬虫 + 可插件的站点连接器
├── dedup/ — 实体重复数据删除（规范化，解析，异步扫描）
├── quality/ — 垃圾节点过滤 + 隔离区
├── connectivity/ — 隔离救援 + 低度修剪
├── community/ — Louvain社区检测 + 摘要（全局模式）
└── tests/ — 管理/质量测试套件
lightrag/ — 基础LightRAG引擎 + FastAPI服务器（可重用依赖项）
├── lightrag.py — 基础LightRAG RAG引擎（插入，查询，存储生命周期）
├── operate.py — 提取和合并管道（关系感知）
├── prompt.py — CG紧凑提取提示（关系上下文模式）
├── base.py · namespace.py — 抽象存储接口，命名空间常量
├── api/
│ ├── lightrag_server.py — FastAPI应用；注册CG + 管理路由器
│ ├── config.py — 环境配置（USE_CONTEXT_GRAPH等）
│ ├── workspace_pool.py — 多租户工作区池和ASGI中间件
│ └── routers/ — 查询 · 文档 · 图 · 规则 · 本体 · RBAC ·
│ 生命周期 · 操作 · 网络爬虫 · 工作区路由器
├── kg/ — 存储后端（Neo4j，NetworkX，NanoVectorDB，
│ JSON KV，PostgreSQL，Redis，MongoDB，Qdrant，Milvus，Faiss）
└── llm/ — LLM提供商绑定（OpenAI，Ollama，Anthropic，
Azure，Gemini，Bedrock，HF，NVIDIA）
tests/ — 核心CG + API测试套件（使用pytest运行）
docs/ — 图解HTML现场指南 + Markdown参考
lightrag_webui/ — Context Graph品牌WebUI（React/TS；内置于lightrag/api/webui/）
```
---
## Context Graph 不是什么
为了设定期望值：
- **不是一个独立的图数据库。** 它在LightRAG的可插件存储（NetworkX / Neo4j / PostgreSQL）上添加了决策上下文，管理和CGR3检索。您可以自带后端。
- **不是LightRAG的直接替换。** 它是一个添加了决策/治理层的分支。它与LightRAG的端点保持API兼容，但价值在于其附加功能。
- **不是开箱即用的身份验证多租户SaaS。** 工作区隔离每个租户的数据，但生产身份验证和对象级访问强制执行是可选的，仍在加强中 - 在将其暴露给不受信任的用户之前，请添加身份验证。
- **尚未针对不受信任的输入进行强化。** 一些安全项（网络爬虫中的SSRF边缘情况，详细错误响应）已知并正在跟踪；在公开之前请审查。
- **不是IDE插件或代码索引。** 代理开发预设管理编码代理的工作方式，但Context Graph是一个知识/决策平台，而不是编辑器扩展。
---
## 基于
Context Graph实现了 [CGR3范式](https://arxiv.org/abs/2406.11160)（Liang等人，2024）- 将知识图三元组扩展为上下文四元组 `(h, r, t, rc)`，采用检索→排序→推理的迭代查询处理。基于 [LightRAG](https://github.com/HKUDS/LightRAG) 由HKUDS构建，具有多租户，实时决策捕获，业务规则引擎，类型本体层，网络爬虫和受控操作层的生产扩展。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器