nano-graphrag实战指南：使用Amazon Bedrock、Ollama和DeepSeek API构建智能知识图谱

【免费下载链接】nano-graphrag A simple, easy-to-hack GraphRAG implementation 项目地址: https://gitcode.com/gh_mirrors/na/nano-graphrag

nano-graphrag是一个简单易用的GraphRAG实现，专为需要构建智能知识图谱的开发者设计。GraphRAG（图检索增强生成）技术结合了知识图谱和大型语言模型，能够从复杂文档中提取结构化信息并进行智能查询。本文将指导您如何快速上手nano-graphrag，并展示如何与Amazon Bedrock、Ollama和DeepSeek API等主流AI服务集成。

🚀 为什么选择nano-graphrag？

nano-graphrag相比官方GraphRAG实现更加轻量、易读且易于定制。整个核心代码仅约1100行，但保留了所有关键功能。它支持多种向量数据库（FAISS、HNSW、Milvus、Qdrant）和图数据库（Neo4j、NetworkX），并完全异步设计，性能卓越。

核心优势：

• 轻量级：代码简洁，易于理解和修改
• 模块化：各组件可独立替换
• 异步支持：充分利用现代Python异步特性
• 多后端支持：灵活的存储和计算后端选择

📦 快速安装与配置

首先克隆项目并安装依赖：

git clone https://gitcode.com/gh_mirrors/na/nano-graphrag
cd nano-graphrag
pip install -e .

🔧 基础使用示例

最简单的nano-graphrag使用方式：

from nano_graphrag import GraphRAG, QueryParam

# 初始化GraphRAG实例
graph_func = GraphRAG(working_dir="./my_graphrag_cache")

# 插入文档数据
with open("your_document.txt") as f:
    graph_func.insert(f.read())

# 执行查询
prompt = "文档中的主要主题是什么？"
result = graph_func.query(prompt, param=QueryParam(mode="global"))
print(result)

🌐 集成Amazon Bedrock

nano-graphrag原生支持Amazon Bedrock，让您可以使用Claude等先进模型：

from nano_graphrag import GraphRAG, QueryParam

graph_func = GraphRAG(
    working_dir="../bedrock_example",
    using_amazon_bedrock=True,
    best_model_id="us.anthropic.claude-3-sonnet-20240229-v1:0",
    cheap_model_id="us.anthropic.claude-3-haiku-20240307-v1:0",
)

# 详细示例见：examples/using_amazon_bedrock.py

配置要点：

• 设置using_amazon_bedrock=True启用Bedrock集成
• 可配置不同模型用于不同任务（质量vs成本）
• 支持AWS凭证的自动发现

🤖 本地模型集成：Ollama

对于需要本地部署的场景，nano-graphrag完美支持Ollama：

import os
import logging
import ollama
from nano_graphrag import GraphRAG, QueryParam

logging.basicConfig(level=logging.WARNING)
logging.getLogger("nano-graphrag").setLevel(logging.INFO)

# 定义Ollama模型适配器
async def ollama_model_if_cache(prompt, system_prompt=None, history_messages=[], **kwargs):
    # 移除Ollama不支持的参数
    kwargs.pop("max_tokens", None)
    kwargs.pop("response_format", None)
    
    ollama_client = ollama.AsyncClient()
    messages = []
    if system_prompt:
        messages.append({"role": "system", "content": system_prompt})
    
    # 完整实现见：examples/using_ollama_as_llm.py

Ollama集成特色：

• 支持多种本地模型（Llama、Qwen、Mistral等）
• 异步客户端提升性能
• 智能缓存机制减少重复计算

🧠 DeepSeek API集成

DeepSeek提供高性价比的API服务，nano-graphrag可轻松集成：

import os
import logging
from openai import AsyncOpenAI
from nano_graphrag import GraphRAG, QueryParam

DEEPSEEK_API_KEY = "sk-XXXX"
MODEL = "deepseek-chat"

async def deepseepk_model_if_cache(prompt, system_prompt=None, history_messages=[], **kwargs):
    openai_async_client = AsyncOpenAI(
        api_key=DEEPSEEK_API_KEY, 
        base_url="https://api.deepseek.com"
    )
    # 详细实现见：examples/using_deepseek_as_llm.py

DeepSeek配置技巧：

• 使用OpenAI兼容的SDK接口
• 支持流式响应和批量处理
• 成本控制友好

🔄 混合配置：DeepSeek + GLM

nano-graphrag支持混合配置，如使用DeepSeek作为LLM，GLM作为Embedding模型：

from nano_graphrag import GraphRAG, QueryParam
from nano_graphrag.base import BaseKVStorage

GLM_API_KEY = "XXXX"
DEEPSEEK_API_KEY = "sk-XXXX"

# 配置示例见：examples/using_deepseek_api_as_llm+glm_api_as_embedding.py

这种混合配置让您可以根据不同任务选择最优的模型组合，平衡性能、成本和效果。

🗄️ 存储后端选择

nano-graphrag支持多种存储后端，您可以根据需求灵活选择：

向量数据库：

• vdb_hnswlib.py：HNSWlib，高性能本地向量搜索
• vdb_nanovectordb.py：NanoVectorDB，轻量级向量存储
• 支持FAISS、Milvus、Qdrant等

图数据库：

• gdb_neo4j.py：Neo4j集成，企业级图数据库
• gdb_networkx.py：NetworkX，Python原生图计算

键值存储：

• kv_json.py：JSON文件存储，简单易用

📊 查询模式详解

nano-graphrag支持两种主要的查询模式：

全局查询（Global Search）

result = graph_func.query(prompt, param=QueryParam(mode="global"))

• 在整个知识图谱中搜索
• 适合宏观分析和主题发现
• 返回整体性见解

局部查询（Local Search）

result = graph_func.query(prompt, param=QueryParam(mode="local"))

• 在相关子图中搜索
• 适合具体问题解答
• 更精确、更快速

🛠️ 高级配置与优化

1. 缓存策略优化

nano-graphrag内置智能缓存机制，可显著提升重复查询性能：

from nano_graphrag._utils import compute_args_hash
from nano_graphrag.base import BaseKVStorage

# 自定义缓存逻辑
class CustomCache(BaseKVStorage):
    def get(self, key: str):
        # 自定义获取逻辑
        pass
    
    def set(self, key: str, value: str):
        # 自定义存储逻辑
        pass

2. 实体提取配置

实体提取模块位于nano_graphrag/entity_extraction/，支持自定义提取策略：

from nano_graphrag.entity_extraction import EntityExtractor

# 自定义实体提取器
extractor = EntityExtractor(model="your_model")
entities = extractor.extract_from_text(text)

3. 性能监控

nano-graphrag提供详细的日志输出，便于性能分析和调试：

import logging
logging.getLogger("nano-graphrag").setLevel(logging.DEBUG)

🧪 测试与验证

项目包含完整的测试套件，确保功能稳定性：

• tests/test_rag.py：RAG核心功能测试
• tests/test_neo4j_storage.py：Neo4j存储测试
• tests/test_hnsw_vector_storage.py：HNSW向量存储测试
• tests/entity_extraction/：实体提取模块测试

运行测试：

pytest tests/

📈 性能基准

根据项目基准测试，nano-graphrag在保持核心功能的同时，相比官方实现：

• 代码量减少：约80%
• 启动速度提升：约40%
• 内存占用降低：约30%
• 查询延迟减少：约25%

详细基准数据见docs/benchmark-zh.md。

🔍 故障排除

常见问题

1. 模型响应解析失败

   • 检查模型输出格式是否符合JSON规范
   • 调整prompt模板确保模型输出结构化数据

2. 向量搜索性能差

   • 考虑使用HNSW或FAISS替代默认向量存储
   • 调整向量维度参数

3. 内存占用过高

   • 启用分块处理大文档
   • 使用外部数据库存储向量和图形数据

调试技巧

# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 检查缓存状态
print(graph_func._cache_stats())

🚀 下一步行动

nano-graphrag提供了简单而强大的GraphRAG实现，让您能够快速构建智能知识图谱应用。无论是使用云端API还是本地模型，都能找到合适的集成方案。

推荐学习路径：

1. 从基础示例开始：examples/using_amazon_bedrock.py
2. 尝试本地部署：examples/using_ollama_as_llm.py
3. 探索混合配置：examples/using_deepseek_api_as_llm+glm_api_as_embedding.py
4. 定制存储后端：nano_graphrag/_storage/目录
5. 贡献代码：参考docs/CONTRIBUTING.md

通过nano-graphrag，您可以轻松构建强大的知识检索系统，将非结构化文档转化为可查询的知识图谱，为您的AI应用提供坚实的知识基础。

【免费下载链接】nano-graphrag A simple, easy-to-hack GraphRAG implementation 项目地址: https://gitcode.com/gh_mirrors/na/nano-graphrag