agentic_huge_data_base / wiki
页面 Cognee · 1.1 安装与设置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 1.1

1.1 · 安装与设置（Installation & Setup）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节1.1 状态全文译文 模块模型调用与提供方适配、接口与服务契约、配置治理、安装与启动
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Installation & Setup 上一章1 下一章1.2
源码线索
  • .env.example
  • .env.template
  • .github/CODEOWNERS
  • .github/pull_request_template.md
  • .github/workflows/approve_dco.yaml
  • .github/workflows/backend_docker_build_test.yml
  • .github/workflows/clean_stale_pr.yaml
  • CONTRIBUTING.md
  • NOTICE.md
  • README.md
模块标签
  • 模型调用与提供方适配
  • 接口与服务契约
  • 配置治理
  • 安装与启动
  • 系统架构

章节正文

安装与设置

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/1.1-installation-and-setup

安装与设置

相关源文件

本章引用的主要源码文件：

  • .env.example
  • .env.template
  • .github/CODEOWNERS
  • .github/pull_request_template.md
  • .github/workflows/approve_dco.yaml
  • .github/workflows/backend_docker_build_test.yml
  • .github/workflows/clean_stale_pr.yaml
  • CONTRIBUTING.md
  • NOTICE.md
  • README.md
  • assets/cognee_benefits.png
  • cognee/api/v1/config/config.py
  • cognee/infrastructure/llm/config.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
  • cognee/modules/settings/__init__.py
  • cognee/modules/settings/get_settings.py
  • cognee/modules/settings/save_llm_config.py
  • cognee/modules/settings/save_vector_db_config.py
  • cognee/tests/unit/infrastructure/llm/test_get_llm_client.py
  • licenses/README.md

本指南介绍如何安装 Cognee 并进行首次使用配置。你将学习如何通过 pip/uv 安装核心库、设置所需的环境变量（主要是大语言模型（LLM）API 密钥），以及验证安装是否成功。

前提条件

Cognee 需要以下环境：

  • Python：3.10 至 3.14 版本 README.md:106
  • 操作系统：macOS、Linux 或 Windows
  • 大语言模型（LLM）API 密钥：至少需要一个 OpenAI API 密钥（或来自其他受支持提供商的等效密钥）.env.template:6

安装方法

方式一：通过 pip 安装（标准方式）

安装 Cognee 基础包：

pip install cognee

对于需要特定数据库后端或功能的生产环境部署，可以安装可选依赖项。Cognee 使用"扩展组"来管理不同提供商的依赖：

常用可选依赖项：

扩展组用途关键依赖
postgresPostgreSQL + PGVector 支持psycopg2、pgvector、asyncpg
neo4jNeo4j 图数据库neo4j
anthropicAnthropic Claude 模型anthropic
ollama本地模型支持ollama
baml通过 BAML 实现结构化输出baml-py cognee/infrastructure/llm/config.py:130-134

来源：README.md:108-115、cognee/infrastructure/llm/config.py:130-134

方式二：通过 uv 安装（推荐用于开发）

uv 是 Cognee 开发推荐的包管理器，因为它速度快且锁文件管理可靠 CONTRIBUTING.md:67。

# 通过 uv 安装 Cognee
uv pip install cognee

用于本地开发设置和贡献：

git clone https://github.com/topoteretes/cognee.git
cd cognee
uv sync # 在虚拟环境中安装所有依赖

来源：README.md:113、CONTRIBUTING.md:67-77、CONTRIBUTING.md:112

环境配置

Cognee 使用环境变量进行所有配置。在项目根目录下创建一个 .env 文件，使用提供的 .env.template 作为模板。

最小配置

对于使用默认基于文件的数据库（SQLite、LanceDB、Kuzu）的快速启动，只需要一个大语言模型（LLM）API 密钥：

# 最小 .env 文件
LLM_API_KEY="你的_openai_api_密钥"

来源：.env.template:1-7、README.md:117-120

配置架构

下图展示了环境变量如何映射到核心配置实体和内部引擎工厂。

自然语言到代码实体的映射：配置流程

Cognee · 配置架构 · 图 1
Cognee · 配置架构 · 图 1

来源：cognee/infrastructure/llm/config.py:15-88、cognee/api/v1/config/config.py:96-145、cognee/modules/settings/get_settings.py:32-36

核心配置部分
大语言模型（LLM）和嵌入向量设置

Cognee 通过 LLMConfig 类支持多个提供商。它包含对 Ollama 等提供商的內建校验 cognee/infrastructure/llm/config.py:155-170。

# 大语言模型（LLM）提供商配置
LLM_PROVIDER="openai" # openai、anthropic、gemini、mistral、ollama、bedrock、azure、llama_cpp
LLM_MODEL="openai/gpt-5-mini"
LLM_API_KEY="你的_api_密钥"

# 结构化输出框架
STRUCTURED_OUTPUT_FRAMEWORK="instructor" # "instructor"（默认）或 "baml"

来源：cognee/infrastructure/llm/config.py:42-45、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:70-93、.env.template:14-22

数据库提供商选择

Cognee 采用三数据库设计。默认使用基于文件的数据库，实现零配置启动 .env.template:1-5。

数据库类型环境变量默认值支持的值
关系型DB_PROVIDERsqlitesqlite、postgres
向量VECTOR_DB_PROVIDERlancedblancedb、pgvector、qdrant、weaviate、milvus、chromadb
图GRAPH_DATABASE_PROVIDERkuzukuzu、neo4j、kuzu-remote

来源：.env.template:120-157、cognee/modules/settings/get_settings.py:44-85

验证与设置

初始化知识引擎

Cognee 的 API 提供四个核心操作：remember（记忆）、recall（回忆）、forget（遗忘）和 improve（改进）README.md:127-129。

import cognee
import asyncio

async def main():
    # 永久存储（执行 add + cognify + improve）
    await cognee.remember("Cognee 将文档转化为 AI 记忆。")

    # 使用自动路由进行查询
    results = await cognee.recall("Cognee 是做什么的？")
    for result in results:
        print(result)

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

来源：README.md:130-156

运行时配置

你也可以通过 cognee.config 命名空间以编程方式配置 Cognee，这样无需修改环境变量即可更新设置 cognee/api/v1/config/config.py:96-116。

import cognee

cognee.config.set_llm_model("gpt-4o")
cognee.config.system_root_directory("./my_cognee_data")

来源：cognee/api/v1/config/config.py:108-113、cognee/api/v1/config/config.py:119-131

系统数据流

下图展示了从安装到首次调用 remember 的初始数据流，将高层 API 调用桥接到存储适配器。

代码实体空间：数据入库流程

Cognee · 系统数据流 · 图 2
Cognee · 系统数据流 · 图 2

来源：README.md:136-152、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:198-200、cognee/api/v1/config/config.py:133-145

故障排除

本地目录覆盖

默认情况下，Cognee 将数据存储在 .venv 或项目根目录中。你可以在 .env 文件中或通过配置 API 覆盖这些路径：

DATA_ROOT_DIRECTORY='/path/to/data/'
SYSTEM_ROOT_DIRECTORY='/path/to/system/'

来源：.env.template:93-98、cognee/api/v1/config/config.py:119-157

大语言模型（LLM）提供商校验

如果使用 Ollama，Cognee 会显式检查 LLM_MODEL、LLM_ENDPOINT 和 LLM_API_KEY，以确保本地服务可达 cognee/infrastructure/llm/config.py:155-197。

AWS Bedrock 认证

BedrockAdapter 支持三种认证模式：API 密钥（Bearer）、AWS 凭证（Access/Secret）或 AWS 配置文件（Boto3 链）cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py:32-38。

--- 来源：README.md:100-175、.env.template:1-161、cognee/infrastructure/llm/config.py:15-154、cognee/api/v1/config/config.py:96-180、CONTRIBUTING.md:63-137