Cognee 入门指南：用 ECL 流水线为 AI 智能体构建持久化知识图谱记忆

Cognee 入门指南：用 ECL 流水线为 AI 智能体构建持久化知识图谱记忆

【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee

Cognee 是一款面向 AI 智能体的开源记忆平台，通过自托管的"知识图谱引擎"为 LLM 与 Agent 提供跨会话的持久化长期记忆。本文以社区俄文版说明文档（assets/community/README.ru.md）为核心骨架，结合仓库源码与配置逐层展开，带读者从零完成 Cognee 的安装、配置、数据注入、知识图谱生成与语义检索，并深入 ECL（Extract → Cognify → Load）流水线的内部实现，掌握在真实项目中落地 AI 记忆层所需的完整技术方案。

Cognee 是什么：为智能体提供动态记忆层

Cognee 的定位不是普通的向量数据库或 RAG 工具，而是一套完整的"AI 记忆平台"：它把历史对话、文档、图片、音频转录等异构数据接入系统，经过抽取、认知加工与装载三个阶段，构建出持续演化的知识图谱，并以此显著提升 LLM 与 AI 智能体回答的准确性和可靠性。

文档开篇即给出了这一核心价值主张：

Cognee - это платформа для управления памятью ИИ, предназначенная для повышения точности и надежности ответов больших языковых моделей (LLM) и ИИ-агентов.（Cognee 是用于管理 AI 记忆的平台，旨在提升大语言模型与 AI 智能体回答的准确性和可靠性。）

其技术内核是一个可扩展、模块化的ECL 流水线（Extract → Cognify → Load，即"抽取 → 认知 → 装载"）：

• Extract（抽取）：把原始数据解析、清洗并结构化，为后续加工做准备；
• Cognify（认知）：利用 LLM 从文本中抽取实体与关系，生成知识图谱；
• Load（装载）：将节点、边与向量持久化到图数据库与向量数据库。

这一概念在源码中有直接对应：cognee/api/v1/cognify/cognify.py中get_default_tasks()构建的默认任务链即按三个阶段的注释明确划分——classify_documents（EXTRACT）、extract_chunks_from_documents（EXTRACT）、extract_graph_and_summarize（COGNIFY）、add_data_points（LOAD），并可选追加溯源账本（record_provenance）与矛盾检测（detect_contradictions）等增强任务。

核心功能特性

社区文档列出的功能点，对应着 Cognee 的核心能力矩阵：

• 数据集成与抽取：可接入并检索过去的对话、文档、图片和音频转录，覆盖多样化信息来源；
• 降低幻觉与成本：通过图谱化的上下文显著减少不可靠回答的产生，同时降低 AI 应用的开发与运维成本；
• 仅用 Pydantic 完成数据装载：只需 Pydantic 模型即可将数据加载到图数据库与向量数据库，简化集成过程（cognee/low_level.py中DataPoint即继承自cognee.infrastructure.engine.ExtendableDataPoint，正是自定义图模型的基类）；
• 数据转换与组织：可从 30 多个数据源（PDF、表格等）摄取并结构化数据；
• 模块化 ECL 流水线：Extract / Cognify / Load 三阶段解耦，保证系统灵活性与可扩展性；
• 基于 RDF 的 Ontology 支持：利用 RDF 本体实现更智能的数据管理与语义理解（.env.template中的ONTOLOGY_RESOLVER=rdflib、MATCHING_STRATEGY=fuzzy、ONTOLOGY_FILE_PATH即为其配置入口）；
• 本地部署与可扩展性：可在自有服务器上部署，保障数据安全与隐私合规，并能扩展以处理大规模数据。

架构总览

整个系统的设计理念可以概括为：一端接入多模态、多来源的数据，另一端输出可供 Agent 检索的图谱化记忆。仓库中提供了概念架构图：

从仓库源码结构看，这一架构落地为多个职责清晰的子系统：

• ingestion 与 loaders：cognee/modules/ingestion 与 cognee/infrastructure/loaders 负责多格式数据解析（文本、PDF、图片 OCR、音视频转录等）；
• LLM 网关：cognee/infrastructure/llm/LLMGateway.py 统一管理实体抽取、摘要等 LLM 调用；
• 三类数据库抽象：cognee/infrastructure/databases 下分别有graph（图库）、vector（向量库）、relational（关系库）与unified（统一入口）实现；
• 检索层：cognee/modules/retrieval 与 cognee/modules/search 支撑多模式搜索。

安装

文档明确说明：可以使用pip、poetry、uv或任意 Python 包管理器安装 Cognee。以 pip 为例：

pip install cognee

仓库根目录的 pyproject.toml 与 poetry.lock 定义了完整的依赖集合，使用 poetry 时执行poetry add cognee即可。官方 README（README.md）补充了运行前提：Python 3.10 至 3.14。如需按功能裁剪安装（如 Turso、OCR、tracing 等扩展），可参考 .env.template 中标注的pip install cognee"[turso]"、pip install "cognee[rapidocr]"等可选依赖写法。

环境配置

Cognee 的配置通过环境变量完成，最核心的一条是 LLM API Key。文档给出的最小化设置是：

import os os.environ["LLM_API_KEY"] = "ВАШ_OPENAI_API_KEY" # 替换为你的 OpenAI API Key

更推荐的方式是创建.env文件，使用仓库根目录的 .env.template 模板，将变量填入后 Cognee 会在导入时自动加载（见 cognee/init.py 中的dotenv.load_dotenv(override=True)）。

.env.template采用四级分层结构，除LLM_API_KEY外，最常用的覆盖项包括：

模板底部还提供了完整的提供商切换范例，例如使用本地 Ollama：

LLM_API_KEY="ollama" LLM_MODEL="llama3.1:8b" LLM_PROVIDER="ollama" LLM_ENDPOINT="http://localhost:11434/v1" EMBEDDING_PROVIDER="ollama" EMBEDDING_MODEL="nomic-embed-text:latest" EMBEDDING_ENDPOINT="http://localhost:11434/api/embed" EMBEDDING_DIMENSIONS=768

默认的 SQLite + LanceDB + Kuzu 三件套均为文件型存储、无需任何外部服务，因此只需配置好 LLM API Key 即可本地运行完整流程。

快速上手：add → cognify → search 三步走

社区文档提供了一个"标准流水线"示例——这也是 Cognee 最经典的入门用法：先注入文本，再生成知识图谱，最后语义检索。完整脚本如下：

import cognee import asyncio async def main(): # 1. 向 cognee 添加文本 await cognee.add("Обработка естественного языка (NLP) - это междисциплинарная область компьютерных наук и информационного поиска.") # 2. 生成知识图谱 await cognee.cognify() # 3. 执行检索 results = await cognee.search("Расскажите мне о NLP") # 4. 展示结果 for result in results: print(result) if __name__ == '__main__': asyncio.run(main())

示例输出（俄语版文档中的原始结果）：

Обработка естественного языка (NLP) — это междисциплинарная область, которая объединяет компьютерные науки и информационный поиск. Она включает в себя технологии и методы обработки человеческого языка для создания интерфейсов и обработки данных.

三个 API 全部由 cognee/init.py 统一导出：from .api.v1.add import add、from .api.v1.cognify import cognify、from .api.v1.search import SearchType, search。它们背后的执行链路正是 ECL 流水线的工程化实现。

源码级解析：三个核心 API 的底层原理

cognee.add()：接入任意格式的数据

add的实现位于 cognee/api/v1/add/add.py，其函数签名揭示出它支持极其宽泛的输入类型：

• 纯文本字符串：不以/或file://开头的字符串被直接当作文本内容；
• 本地文件路径：绝对路径（/path/to/document.pdf）、文件 URL（file:///path/to/document.pdf）、S3 路径（s3://bucket/path/file.pdf）；
• 二进制文件对象：open("file.txt", "rb")；
• 列表：一次调用混合传入多个文件与文本；
• 网页 URL：可配合extraction_rules（CSS 选择器）或tavily_config、soup_crawler_config指定抓取方式。

支持的文件格式覆盖.txt/.md/.csv、.pdf、图片（.png/.jpg/.jpeg，经 OCR/视觉模型抽取）、音频（.mp3/.wav，转录为文本）、代码文件（.py/.js/.ts等，解析结构与内容）以及 Office 文档（.docx/.pptx）。

从实现上看，add内部依次完成：数据源解析（resolve_data_directories）→ 内容抽取与落库（ingest_data）→ 数据集权限绑定（resolve_authorized_user_dataset）→ 以add_pipeline名义执行流水线。默认数据集名为main_dataset，可通过dataset_name参数拆分多个知识域。

cognee.cognify()：把文本加工成知识图谱

cognify是 Cognee 的核心加工步骤，实现在 cognee/api/v1/cognify/cognify.py。其默认任务链（get_default_tasks）完整对应 ECL 三阶段：

1. EXTRACT：classify_documents识别文档类型 →extract_chunks_from_documents按语义切分文本块（默认使用段落式TextChunker，chunk 大小由 LLM 上下文自动计算：min(embedding_max_completion_tokens, llm_max_completion_tokens // 2)）；
2. COGNIFY：extract_graph_and_summarize调用 LLM 抽取实体与关系、并为每个文本块生成摘要；
3. LOAD：add_data_points把节点、边与向量批量写入图库与向量库。

可选增强项包括：record_provenance（溯源账本，逐条记录本次摄取产出的文档/块/实体/关系）、detect_contradictions（矛盾检测，将新事实与图谱已有事实对比并标记contradicts边）、resolve_temporal_contradictions（对单值关系按时间先后标记 superseded）。三者默认关闭，可通过 cognify 配置项开启。

此外cognify还支持：

• graph_model：自定义 Pydantic 图模型（继承DataPoint），用于领域定制；
• ontology_file_path：接入 OWL 本体约束抽取；
• temporal_cognify=True：切换为时间感知流水线，额外执行事件与时间戳抽取；
• run_in_background=True：大文件（>100MB）推荐后台异步执行，用pipeline_run_id跟踪进度；
• dry_run=True：不调用 LLM、不写库，仅估算 token 用量与成本。

cognee.search()：多模式语义检索

search实现于 cognee/api/v1/search/search.py，默认query_type为SearchType.HYBRID_COMPLETION。文档示例展示的是最常用的问答场景，而源码揭示了丰富的检索模式：

常用调优参数包括top_k（默认 15，上限 100）、datasets（限定检索范围以提升速度与相关性）、node_name（按实体名过滤）以及system_prompt_path（自定义回答提示词，默认answer_simple_question.txt）。检索前置条件是已通过add+cognify完成数据加工。

图形可视化：让记忆变得可见

知识图谱构建完成后，可以像文档展示的那样把结果可视化。仓库的社区目录中提供了俄文版文档配套的图谱可视化示例图：

可视化能力由 cognee/api/v1/visualize 与 cognee/modules/visualization（含浏览器端 JS/HTML 渲染实现）提供，可通过cognee.visualize_graph(...)与cognee.start_visualization_server(...)等 API 调用。图形化界面有助于理解实体间的关联结构，也是调试图谱质量、向非技术成员展示系统的直观手段。

本地部署与规模化

由于默认存储全部为文件型（SQLite/LanceDB/Kuzu），Cognee 天然支持单机零依赖部署，满足数据不出内网的安全与隐私要求。当数据规模增长或需要多用户共享时，可通过.env.template平滑升级：

• 关系库切换 Postgres：DB_PROVIDER="postgres"+DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD/DB_NAME；
• 图库切换 Neo4j：GRAPH_DATABASE_PROVIDER="neo4j"+GRAPH_DATABASE_URL=bolt://localhost:7687等连接参数；
• 向量库切换 pgvector：VECTOR_DB_PROVIDER="pgvector"；
• 多租户隔离：保持ENABLE_BACKEND_ACCESS_CONTROL=True，系统会为每个"用户 + 数据集"创建独立数据库/模式，实现数据层面的强隔离。

规模化并发场景还可调整DATABASE_MAX_LRU_CACHE_SIZE（引擎实例 LRU 缓存上限）与DATASET_QUEUE_MAX_CONCURRENT（并发数据集处理槽位）来防止资源耗尽。

更进一步：从示例到生产

仓库内提供了大量可直接运行的参考材料：

• 完整示例脚本：examples/guides/simple_cognee_example.py、examples/guides/recall_core.py、examples/guides/ontology_quickstart.py；
• 高级用法：examples/guides/sessions.py（会话持久化）、examples/guides/memory_provenance.py（溯源）、examples/guides/local_ollama_example.py（本地模型）；
• 端到端测试：仓库根目录与 cognee/tests 下分布着test_load.py、test_search_db.py、test_custom_graph_model等用例，可作为 API 行为的可执行文档；
• 使用场景清单：catalog/entries/use-cases 收录了 agent-memory、document-qa、temporal-reasoning 等典型场景的 YAML 配置。

结语

Cognee 的社区俄文文档给出了一个清晰的最小闭环：注入数据（add）→ 构建图谱（cognify）→ 语义检索（search），而仓库源码则揭示了这背后模块化 ECL 流水线的完整工程实现。无论是为 Agent 构建跨会话持久记忆、用 GraphRAG 提升回答准确率，还是以 RDF 本体约束领域语义，Cognee 都提供了开箱即用、可本地自托管、可平滑扩展的落地方案。建议读者以本文的示例为起点，结合 examples 目录中的实战脚本逐步深入。

【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee