12.1 · 基础用量示例（Basic Usage Examples）

基础用量示例（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/12.1-basic-usage-examples

翻译时间：2026-05-27T08:45:13.841Z

翻译模型：deepseek-chat

原文字符数：8996

项目：Cognee (cognee)

---

基本使用示例

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

• cognee/modules/graph/utils/get_graph_from_model.py
• cognee/modules/graph/utils/get_model_instance_from_graph.py
• cognee/tasks/graph/extract_graph_and_summarize.py
• cognee/tasks/storage/add_data_points.py
• cognee/tasks/summarization/summarize_text.py
• cognee/tests/unit/api/v1/__init__.py
• cognee/tests/unit/api/v1/config/__init__.py
• cognee/tests/unit/api/v1/config/test_config_set_method.py
• examples/demos/simple_cognee_example.py
• notebooks/cognee_demo.ipynb
• notebooks/cognee_multimedia_demo.ipynb
• notebooks/cognee_simple_demo.ipynb
• notebooks/data/alice_in_wonderland.txt
• notebooks/data/enriched_medical_ontology_with_classes.owl
• notebooks/data/scientific_papers/TOJ-22-0073_152Mendoza.pdf
• notebooks/data/scientific_papers/nutrients-13-01241.pdf
• notebooks/ontology_demo.ipynb

本文通过简单实用的示例演示了 Cognee 的基本操作。内容涵盖核心工作流：添加数据、将数据转化为知识图谱，以及以最小配置查询结果。

关于高级搜索模式和结果过滤，请参见高级检索策略。关于代码仓库分析，请参见高级搜索模式。关于生产环境部署配置，请参见配置系统。

---

核心工作流概览

Cognee 工作流由三个主要函数组成，它们构成了一个简单的管线：

基础三步管线

graph LR
    add["cognee.add()"] --> cognify["cognee.cognify()"]
    cognify --> search["cognee.search()"]

1. cognee.add()：入库原始数据（文本、文件、URL），并将其存储在关系数据库中。
2. cognee.cognify()：通过执行分类、片段切分和实体提取的管线来处理已添加的数据，从而构建知识图谱和向量索引。
3. cognee.search()：使用自然语言查询知识图谱和向量存储，返回上下文感知的结果。

数据流：从原始输入到代码实体

graph TD
    subgraph "自然语言空间"
        Input["原始文本 / 文件 / URL"]
    end

    subgraph "代码实体空间"
        API_Add["cognee.add()"]
        API_Cognify["cognee.cognify()"]
        API_Search["cognee.search()"]

        DataPoint["DataPoint（基础模型）"]
        DocumentChunk["DocumentChunk（任务输出）"]
        GraphNode["Node（图谱实体）"]
        Triplet["Triplet（嵌入关系）"]
    end

    Input --> API_Add
    API_Add --> API_Cognify
    API_Cognify --> DocumentChunk
    DocumentChunk --> DataPoint
    DataPoint --> GraphNode
    GraphNode --> Triplet
    Triplet --> API_Search

来源：notebooks/cognee_demo.ipynb:33-35, cognee/tasks/storage/add_data_points.py:30-35, cognee/tasks/graph/extract_graph_and_summarize.py:12-20

---

最小示例：文本输入

最简单的 Cognee 工作流处理一个文本字符串并进行查询。默认情况下，Cognee 使用 SearchType.GRAPH_COMPLETION 进行检索。

import cognee
import asyncio
from cognee.api.v1.search import SearchType

async def main():
    # 清理现有数据以获得干净的环境
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata = True)

    # 向 cognee 添加文本
    text = "自然语言处理（NLP）是计算机科学的一个跨学科子领域。"
    await cognee.add(text)

    # 生成知识图谱
    await cognee.cognify()

    # 查询知识图谱
    query_text = "请介绍一下 NLP"
    results = await cognee.search(
        query_type = SearchType.GRAPH_COMPLETION,
        query_text = query_text
    )

    for result in results:
        print(result)

if __name__ == "__main__":
    asyncio.run(main())

实现细节： cognee.add() 函数接受原始字符串或文件路径。在 cognify() 过程中，系统会调用 extract_graph_from_data 和 summarize_text 等任务，将输入转换为结构化实体 cognee/tasks/graph/extract_graph_and_summarize.py:12-37。

来源：examples/demos/simple_cognee_example.py:12-34, notebooks/cognee_simple_demo.ipynb:126-128

---

配置要求

API 密钥和提供者设置

在运行 Cognee 之前，必须配置大语言模型（LLM）和数据库提供者。Cognee 提供了 config.set() 方法来动态更新设置。

import os
import cognee

# 通过环境变量设置 LLM 凭证
os.environ["LLM_API_KEY"] = "YOUR_OPENAI_API_KEY"

# 通过配置方法设置提供者
cognee.config.set("llm_provider", "openai")
cognee.config.set("llm_model", "gpt-4o-mini")
cognee.config.set("vector_db_provider", "lancedb")

数据库选择： Cognee 采用三数据库架构。可以通过环境变量或 config API 选择提供者：

• GRAPH_DATABASE_PROVIDER：例如 "kuzu"、"neo4j"、"networkx" notebooks/cognee_multimedia_demo.ipynb:75。
• VECTOR_DB_PROVIDER：例如 "lancedb"、"qdrant"、"weaviate" notebooks/cognee_multimedia_demo.ipynb:82。
• DB_PROVIDER：例如 "sqlite"、"postgres" notebooks/cognee_multimedia_demo.ipynb:88。

来源：cognee/tests/unit/api/v1/config/test_config_set_method.py:21-32, notebooks/cognee_multimedia_demo.ipynb:69-98

---

文件和多媒体入库

Cognee 会自动检测并处理各种数据类型，包括文本文件、PDF 和多媒体文件。

添加多媒体（图片和音频）

Cognee 可以通过生成描述或转录文本来处理图片和音频，然后将这些内容添加到知识图谱中。

import cognee
import asyncio
import os

async def multimedia_example():
    # 多媒体文件路径
    mp3_file_path = "data/audio_sample.mp3"
    png_file_path = "data/image_sample.png"

    # 将文件添加到系统
    await cognee.add(mp3_file_path)
    await cognee.add(png_file_path)

    # cognify 从多媒体中提取元数据和内容
    await cognee.cognify()

    # 在生成的图谱中进行搜索
    results = await cognee.search(
        query_text = "图片中有什么？",
        query_type = "GRAPH_COMPLETION"
    )
    print(results)

asyncio.run(multimedia_example())

来源：notebooks/cognee_multimedia_demo.ipynb:34-49, notebooks/cognee_simple_demo.ipynb:59-61

---

知识图谱生成细节

当调用 cognee.cognify() 时，会触发 add_data_points 任务。该任务使用 get_graph_from_model 遍历基于 Pydantic 的数据模型，提取节点和边以存入图数据库 cognee/tasks/storage/add_data_points.py:62-76。

图谱提取逻辑

graph TD
    subgraph "cognee.tasks.storage"
        ADP["add_data_points()"]
        GGFM["get_graph_from_model()"]
        DNE["deduplicate_nodes_and_edges()"]
        UN["upsert_nodes()"]
        UE["upsert_edges()"]
    end

    ADP --> GGFM
    GGFM --> DNE
    DNE --> UN
    DNE --> UE

数据模型到图谱实例： 工具函数 get_model_instance_from_graph 可以从图谱节点和边重建 Pydantic 模型，使系统能够在持久化图谱存储和结构化 Python 对象之间建立桥梁 cognee/modules/graph/utils/get_model_instance_from_graph.py:68-132。

来源：cognee/tasks/storage/add_data_points.py:8-13, cognee/modules/graph/utils/get_graph_from_model.py:178-183, cognee/modules/graph/utils/get_model_instance_from_graph.py:68-72

---

数据管理与清理

为了在开发过程中保持环境整洁或重置系统，Cognee 提供了清理工具。

import cognee

async def cleanup():
    # 从关系数据库和向量数据库中移除已添加的数据
    await cognee.prune.prune_data()

    # 移除系统元数据和图谱结构
    await cognee.prune.prune_system(metadata = True)

asyncio.run(cleanup())

来源：examples/demos/simple_cognee_example.py:14-15, notebooks/ontology_demo.ipynb:123-124