1.2 · 快速开始指南（Quick Start Guide）

快速开始指南（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/1.2-quick-start-guide

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

翻译模型：deepseek-chat

原文字符数：10124

项目：Cognee (cognee)

---

快速入门指南

相关源文件

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

• cognee/api/v1/add/add.py
• cognee/api/v1/cognify/cognify.py
• cognee/modules/data/models/Data.py
• cognee/modules/graph/utils/get_graph_from_model.py
• cognee/modules/graph/utils/get_model_instance_from_graph.py
• cognee/modules/pipelines/operations/pipeline.py
• cognee/modules/pipelines/operations/run_tasks.py
• cognee/tasks/graph/extract_graph_and_summarize.py
• cognee/tasks/ingestion/ingest_data.py
• cognee/tasks/ingestion/save_data_item_to_storage.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
• poetry.lock
• pyproject.toml
• uv.lock

本指南通过实际示例演示 Cognee 的核心工作流。在安装 Cognee 并配置好环境后（参见 1.1. 安装与设置），您可以通过三个简单步骤开始构建 AI 记忆：使用 add() 入库数据，使用 cognify() 将其处理为知识图谱，以及使用 search() 检索洞察信息。

核心工作流总览

Cognee 的主要工作流包含一系列操作，将原始数据转换为可查询的知识。系统提供了高级 API，包括 remember()（整合了 add、cognify 和 improve）和 recall()（自动路由搜索）。

graph LR
    A["原始数据<br/>（文本、文件、URL）"]
    B["add()<br/>数据入库"]
    C["cognify()<br/>知识图谱<br/>生成"]
    D["search()<br/>查询结果"]

    A --> B
    B --> C
    C --> D

    B -.存储.-> E[（数据集<br/>SQLAlchemyAdapter）]
    C -.处理.-> F[（图数据库 + 向量<br/>数据库）]
    D -.查询.-> F

来源： cognee/api/v1/add/add.py:116-120、cognee/api/v1/cognify/cognify.py:60-65、cognee/api/v1/cognify/cognify.py:136-150

系统中的数据流

下图将用户操作映射到内部管线任务和具体的代码实体。

flowchart TB
    subgraph "用户操作：cognee.add()"
        INPUT["用户输入"]
        ADD_FUNC["add()<br/>[cognee/api/v1/add/add.py]"]
    end

    subgraph "内部：入库层"
        INGEST_TASK["ingest_data()<br/>[cognee/tasks/ingestion/ingest_data.py]"]
        SAVE_STORE["save_data_item_to_storage()<br/>[cognee/tasks/ingestion/save_data_item_to_storage.py]"]
        DB_DATA[（数据表<br/>cognee.modules.data.models.Data）]
    end

    subgraph "用户操作：cognee.cognify()"
        COGNIFY_FUNC["cognify()<br/>[cognee/api/v1/cognify/cognify.py]"]
    end

    subgraph "内部：管线编排"
        RUN_PIPELINE["run_pipeline()<br/>[cognee/modules/pipelines/operations/pipeline.py]"]
        RUN_TASKS["run_tasks()<br/>[cognee/modules/pipelines/operations/run_tasks.py]"]
        TASK_CLASS["任务类<br/>[cognee/modules/pipelines/tasks/task.py]"]
    end

    subgraph "存储层"
        VECTOR[（向量数据库<br/>VectorDBInterface）]
        GRAPH[（图数据库<br/>GraphDBInterface）]
        RELATIONAL[（关系数据库<br/>SQLAlchemyAdapter）]
    end

    INPUT --> ADD_FUNC
    ADD_FUNC --> INGEST_TASK
    INGEST_TASK --> SAVE_STORE
    SAVE_STORE --> DB_DATA

    COGNIFY_FUNC --> RUN_PIPELINE
    RUN_PIPELINE --> RUN_TASKS
    RUN_TASKS --> TASK_CLASS

    TASK_CLASS --> VECTOR
    TASK_CLASS --> GRAPH
    TASK_CLASS --> RELATIONAL

来源： cognee/api/v1/add/add.py:92-114、cognee/tasks/ingestion/ingest_data.py:26-34、cognee/tasks/ingestion/save_data_item_to_storage.py:27-97、cognee/api/v1/cognify/cognify.py:43-59、cognee/modules/pipelines/operations/pipeline.py:33-44、cognee/modules/pipelines/operations/run_tasks.py:56-65、cognee/modules/data/models/Data.py:1-41

Python API：基本示例

Cognee 提供了两种 API 模式：细粒度的 add → cognify → search 工作流，以及简化的 remember → recall 工作流。

细粒度工作流

import cognee
import asyncio

async def main():
    # 步骤 1：添加数据
    await cognee.add("Cognee 将文档转化为 AI 记忆。")

    # 步骤 2：处理为知识图谱
    await cognee.cognify()

    # 步骤 3：搜索知识
    results = await cognee.search("Cognee 有什么作用？")

    for result in results:
        print(result)

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

简化的智能体工作流

remember 函数会自动运行 add、cognify 和 improve 任务。

import cognee
import asyncio

async def main():
    # 永久存储到知识图谱中
    await cognee.remember("Cognee 将文档转化为 AI 记忆。")

    # 使用自动路由进行查询（自动选择最佳搜索策略）
    results = await cognee.recall("Cognee 有什么作用？")
    for result in results:
        print(result)

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

来源： cognee/api/v1/add/add.py:116-126、cognee/api/v1/cognify/cognify.py:136-150、notebooks/cognee_demo.ipynb:8-35

处理文件和 URL

Cognee 通过 save_data_item_to_storage 将各种输入类型解析为内部存储路径。

输入格式	示例	内部逻辑
绝对路径	/path/to/file.pdf	save_data_item_to_storage 转换为 URI cognee/tasks/ingestion/save_data_item_to_storage.py:72-79
相对路径	data/file.txt	通过 Path.cwd() 解析 cognee/tasks/ingestion/save_data_item_to_storage.py:48-51
S3 路径	s3://bucket/key.pdf	通过 parsed_url.scheme == "s3" 处理 cognee/tasks/ingestion/save_data_item_to_storage.py:59-60
HTTP(S) URL	https://example.com	通过 fetch_page_content 获取 cognee/tasks/ingestion/save_data_item_to_storage.py:61-63
二进制对象	open("f.txt", "rb")	通过 hasattr(data_item, "file") 处理 cognee/tasks/ingestion/save_data_item_to_storage.py:41-42

来源： cognee/tasks/ingestion/save_data_item_to_storage.py:27-97、cognee/api/v1/add/add.py:127-143

管线执行细节

run_tasks 函数负责编排各个 Task 对象的执行。它使用基于信号量的并发模型来处理数据项。

sequenceDiagram
    participant API as cognee.cognify()
    participant RP as run_pipeline()
    participant RT as run_tasks()
    participant SEM as 信号量
    participant RTI as run_tasks_data_item()
    participant T as 管线任务

    API->>RP: 数据集、用户
    RP->>RT: 任务、数据、数据集ID
    RT->>SEM: 获取（data_per_batch）
    RT->>RTI: 处理数据项
    RTI->>T: classify_documents
    RTI->>T: extract_chunks_from_documents
    RTI->>T: extract_graph_and_summarize
    RTI->>T: add_data_points
    T-->>RT: 结果
    RT->>SEM: 释放
    RT-->>API: PipelineRunCompleted

来源： cognee/modules/pipelines/operations/run_tasks.py:56-160、cognee/api/v1/cognify/cognify.py:82-88、cognee/api/v1/cognify/cognify.py:22-33

高级配置选项

增量加载

默认情况下，Cognee 使用内容哈希检测。如果再次添加同一个文件但内容未发生变化，系统会识别出已有的数据点。这一过程在 ingest_data 中通过比较 new_content_hash 与 Data 模型中存储的 content_hash 来实现。

来源： cognee/tasks/ingestion/ingest_data.py:148-163、cognee/api/v1/cognify/cognify.py:54、cognee/modules/data/models/Data.py:27

批量调优

用户可以通过批量参数控制性能：

• data_per_batch：并发处理的文件数量（默认值：20）。cognee/api/v1/cognify/cognify.py:57
• chunks_per_batch：在 cognify 任务中每个批次处理的文本片段数量。cognee/api/v1/cognify/cognify.py:49

来源： cognee/api/v1/cognify/cognify.py:49-57、cognee/modules/pipelines/operations/run_tasks.py:63

自定义图谱模型

cognify() 中的 graph_model 参数允许用户传入自定义的 Pydantic BaseModel。这会指示大语言模型（LLM）提取符合特定模式的实体和关系，而不是使用默认的 KnowledgeGraph。

来源： cognee/api/v1/cognify/cognify.py:46、cognee/api/v1/cognify/cognify.py:90-95、cognee/api/v1/cognify/cognify.py:102-103