内容
<div align="center">
<h1>Preciso</h1>
<p><strong>从您的文档中精确构建知识图谱。</strong></p>
<p><em>以布鲁诺·费尔南德斯命名。每一次传球都恰到好处。</em></p>
<p>
<img src="https://img.shields.io/badge/Codex-Agent-111111?style=for-the-badge&logo=openai&logoColor=white" alt="Codex 代理支持" />
<img src="https://img.shields.io/badge/Claude%20Code-Agent-C8102E?style=for-the-badge" alt="Claude Code 代理支持" />
<img src="https://img.shields.io/badge/OpenCode-Agent-FFFFFF?style=for-the-badge&logoColor=C8102E&color=C8102E" alt="OpenCode 代理支持" />
<img src="https://img.shields.io/badge/Copilot-Agent-7F1D1D?style=for-the-badge&logo=github&logoColor=white" alt="Copilot 代理支持" />
</p>
<p>
<img src="https://img.shields.io/badge/本地优先-FFFFFF?style=for-the-badge&logoColor=C8102E&color=C8102E" alt="本地优先工作流" />
<img src="https://img.shields.io/badge/Python-3.11%2B-111111?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.11+" />
<img src="https://img.shields.io/badge/许可证-Apache%202.0-blue?style=for-the-badge" alt="Apache 2.0 许可证" />
</p>
</div>
---
大多数 RAG 工具都检索文档。Preciso 构建一个 **知识图谱** —— 这样您的代理可以推理连接，而不仅仅是查找相似的文本。
```
原始 .md / .txt 文件 → 代理选择技能 → 提取 JSON → MCP 摄入 → 本地图谱
```
将源文件放入 `to_be_extracted/`。代理读取它们，使用特定于领域的技能提取实体和关系，并在本地的 `GRAPH_IS_HERE/` 中持久化一个可查询的知识图谱。不需要云。不需要配置管道。
---
## 目录
- [为什么选择 GraphRAG？](#为什么选择GraphRAG？)
- [基准测试结果](#基准测试结果)
- [快速入门（3 分钟）](#快速入门（3分钟）)
- [工作原理](#工作原理)
- [技能选择](#技能选择)
- [MCP 工具](#MCP工具)
- [查询图谱](#查询图谱)
- [下游导出（可选）](#下游导出（可选）)
- [手动回退路径](#手动回退路径)
- [许可证](#许可证)
---
## 为什么选择 GraphRAG？
**普通 RAG：**
```
“苹果的风险因素是什么？”
→ 返回风险因素部分文本
```
**Preciso：**
```
“苹果的风险因素是什么？哪些高管负责管理它们？”
→ 遍历风险因素 → 暴露于 → 公司 → 雇佣 → 人员
→ 返回带有证据的连接答案
```
图谱使得多跳推理成为可能。
---
## 基准测试结果
在 23 个沃尔玛 FY2022 + FY2023 10-K 文件的财务 QA 问题上进行了评估：
| 指标 | 分数 |
| --- | --- |
| 上下文相关性 | 0.983 |
| 忠实度 | **1.000** |
| 答案正确性 | 0.960 |
| 精确度 | 0.910 |
| **总体** | **0.954** |
- **幻觉：** 0 / 23
- **失败问题：** 0 / 23
**Preciso 的比较：**
| 系统 | 分数 |
| --- | --- |
| **Preciso** | **95.4%** |
| GPT-4 + 长上下文（79k tokens） | ~79% |
| GPT-4 + 标准 RAG | ~19% |
参见 [eval-guide.md](docs/eval-guide.md) 获取详细方法和多跳分解。
---
## 快速入门（3 分钟）
### 1. 克隆并安装
```bash
git clone <your-fork-or-this-repo-url>
cd graphrag-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
> Preciso 需要 Python 3.11+、本地虚拟环境 `.venv` 和从仓库根目录打开的代理。`.mcp.json` 使用存储库本地启动器，优先使用 `.venv/bin/python`。
### 2. 将文件放入 `to_be_extracted/`
最佳输入格式：
- `.md`
- `.txt`
- README 文件、wiki 导出、笔记和其他文本优先的源材料
> 默认情况下，不建议使用 PDF。Preciso 本身不解析 PDF —— 先将它们转换为 `.md` 或 `.txt`，或依赖具有原生 PDF 支持的外部代理。
### 3. 运行代理提示
在 Codex、Claude Code、GitHub Copilot 或 OpenCode 中打开此仓库并运行：
```text
Call get_server_status().
If overall is ready, proceed.
If overall is degraded, explain what is degraded, what still works, and ask whether to proceed or fix first.
Read the files in to_be_extracted/.
Choose the most appropriate extraction skill from the skills folder for each file.
Extract entities, relationships, and chunks into extractions/{source_name}_extracted.json.
Validate that every source_id maps to a real chunk_id and that all relationships reference defined entities.
If the extraction looks clean, call ingest_from_file for each generated extraction file.
If you find duplicate entities, orphaned relationships, or conflicts, use the reconciliation skill before ingestion.
Then confirm the graph artifacts written to GRAPH_IS_HERE/ and summarize what was ingested.
```
---
## 工作原理
Preciso 围绕代理、存储库本地技能和 MCP 服务器之间的六步契约构建：
1. 开发人员将源文件放入 `to_be_extracted/`
2. 代理读取这些文件
3. 代理从 `skills/` 中选择正确的提取技能
4. 代理将结构化提取输出写入 `extractions/`
5. 代理调用适当的 MCP 摄入工具
6. 存储库在 `GRAPH_IS_HERE/` 中持久化图谱神器
### 红白工作流
| 阶段 | 目录 | 描述 |
| --- | --- | --- |
| 🔴 红色 | `to_be_extracted/` | 原始源文档到达此处 |
| ⚪ 白色 | `extractions/` | 代理写入结构化提取 JSON |
| 最终传递 | `GRAPH_IS_HERE/` | MCP 摄入提取并持久化图谱 |
### 规范文件夹
```
to_be_extracted/ ← 待代理提取的源文件
skills/ ← 特定领域提取技能
extractions/ ← 代理生成的提取 JSON 文件
GRAPH_IS_HERE/ ← 持久化图谱和检索神器
```
---
## 技能选择
代理根据源材料类型选择技能：
| 技能 | 路径 | 用途 |
| --- | --- | --- |
| 金融提取 | `skills/Financial-Graph-Extraction/SKILL.md` | 10-Ks、10-Qs、收益电话会议、分析师报告 |
| 研究论文提取 | `skills/Research-paper-graph-extraction-skill/SKILL.md` | 研究论文、科学文献、学术语料库 |
| 通用提取 | `skills/General-graph-extraction-skill/SKILL.md` | 代码库、README、wiki、内部文档 |
| 调和 | `skills/Reconciliation-Subagent-Skill/SKILL.md` | 现有提取 JSON 的清理 - 不适用于原始源 |
---
## MCP 工具
MCP 是代理在提取后使用的工具接口。它负责摄入提取的 JSON、查询图谱和可选的下游导出。
### 核心工具
| 工具 | 描述 |
| --- | --- |
| `get_server_status` | 运行时健康检查 - 在任何提取或摄入之前调用 |
| `ingest_graph_tool` | 将提取的有效载荷摄入图谱 |
| `ingest_from_file` | 从命名的提取 JSON 文件中摄入 |
| `reingest_from_file` | 重新摄入现有的提取文件 |
| `ingest_with_reconciliation_tool` | 摄入时解决冲突 |
| `query_graph_tool` | 查询持久化的图谱 |
| `export_graph_to_neo4j` | 将图谱结构导出到 Neo4j |
| `export_vectors_to_qdrant` | 将向量神器导出到 Qdrant |
### `get_server_status` - 运行时真相表面
在任何提取或摄入之前调用它。它返回嵌入、图谱存储和 LLM 配置的当前状态。
**健康响应：**
```json
{
"overall": "ready",
"warnings": [],
"embedding": {
"mode": "local",
"provider": "ollama",
"model": "mxbai-embed-large",
"dimension": 768,
"status": "active"
},
"graph": {
"storage": "networkx",
"location": "/path/to/GRAPH_IS_HERE",
"entities": 142,
"relationships": 281,
"documents_ingested": 1,
"chunks": 96
},
"llm": {
"configured": true,
"provider": "custom",
"model": "custom_llm",
"status": "active"
}
}
```
**降级响应：**
```json
{
"overall": "degraded",
"warnings": [
"备用嵌入处于活动状态；图谱创建仍然有效，但向量相似性质量降低。",
"LLM 摘要未配置；提取和图谱创建仍然有效，但摘要生成被跳过。"
],
"embedding": { "mode": "fallback", "status": "degraded" },
"llm": { "configured": false, "status": "inactive" }
}
```
如果 `overall` 为 `degraded`，代理必须解释什么已降级，什么仍然有效，并询问是否继续。
---
## 摄入后可以查询的内容
```
“苹果的前 5 个已披露的风险因素是什么？”
“哪些高管与供应链风险有关？”
“哪些指标逐年下降？”
“服务部门与整体收入有何关联？”
```
图谱连接实体跨文档章节，以便您的代理获得推理答案，而不仅仅是检索到的块。
---
## 图谱神器
摄入后，图谱在 `GRAPH_IS_HERE/` 中持久化，可在会话之间重用：
```
GRAPH_IS_HERE/
├── graph_graph.graphml ← 最便携的神器
├── kv_store_text_chunks.json
├── kv_store_entity_chunks.json
├── kv_store_relation_chunks.json
├── vdb_entities.json
├── vdb_relationships.json
├── vdb_chunks.json
└── artifact_manifest.json
```
---
## 下游导出（可选）
<p>
<img src="https://img.shields.io/badge/Neo4j-导出目标-8A2BE2?style=for-the-badge" alt="Neo4j 导出目标" />
<img src="https://img.shields.io/badge/Qdrant-向量导出-DC2626?style=for-the-badge" alt="Qdrant 向量导出" />
</p>
`GRAPH_IS_HERE/` 始终是真实来源。Neo4j 和 Qdrant 是可选的下游副本 - 而不是替换。
```
本地图谱（主）→ （可选）→ Neo4j 副本
本地图谱（主）→ （可选）→ Qdrant 副本
```
将其视为将 Google Doc 导出为 PDF。Doc 是真实的东西。PDF 是用于共享的快照。
### 导出到 Neo4j
```json
{
"uri": "bolt://localhost:7687",
"username": "neo4j",
"password": "your-password",
"database": "neo4j",
"workspace": "default",
"clear_existing": false
}
```
所需环境变量：`GRAPHRAG_NEO4J_URI`、`GRAPHRAG_NEO4J_USERNAME`、`GRAPHRAG_NEO4J_PASSWORD`，可选 `GRAPHRAG_NEO4J_DATABASE`
### 导出到 Qdrant
```json
{
"url": "http://localhost:6333",
"api_key": null,
"collection_prefix": "preciso",
"workspace": "default",
"clear_existing": false
}
```
所需环境变量：`GRAPHRAG_QDRANT_URL`，可选 `GRAPHRAG_QDRANT_API_KEY`、`GRAPHRAG_QDRANT_COLLECTION_PREFIX`
> Neo4j 导出图谱结构。Qdrant 导出向量神器。两者都在本地创建后发生，而不是代替。
---
## 手动回退路径
对于希望在提取后手动驱动摄入的高级用户：
```bash
# 摄入现有的提取文件
python3 test/ingest_manual.py extractions/reconciled_apple_10k_2024_1779725404.json
# 查询持久化的图谱
python3 test/query_manual.py "Tim Cook 的角色是什么？" mix
# 运行协调演示流程
python3 test/reconcile_manual.py
```
---
## MCP 设置
此存储库包含用于本地开发的工作区 `.mcp.json`：
```json
{
"mcpServers": {
"graphrag-mcp": {
"type": "stdio",
"command": "/bin/sh",
"args": ["scripts/mcp_launcher.sh"],
"cwd": ".",
"tools": ["*"]
}
}
}
```
如果您想要直接回退，请将 `command` 替换为您的 `.venv/bin/python` 的绝对路径。
---
## 提取契约
提取 JSON 必须包括：
```json
{
"document_id": "...",
"entities": [...],
"relationships": [...],
"chunks": [...]
}
```
输出文件名模式：`extractions/{source_filename}_extracted.json`
---
## 当前限制
- 检索质量取决于嵌入配置质量
- Neo4j 和 Qdrant 导出需要外部服务及其 Python 客户端依赖项
- 本地图谱神器仍然是真实来源；下游导出是单向同步目标
- PDF 处理需要用户侧转换或具有原生 PDF 支持的外部代理（claude code 和 Codex 不需要转换）
---
## 许可证
该项目在 **Apache License, Version 2.0** 下获得许可。有关完整条款，请参见 [LICENSE](LICENSE)。
