企业官网建设流程全解析

cognee 如何用最小 docker-compose 启动 API 服务并完成首次 add、cognify、search 请求

【免费下载链接】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 的 API 服务——把一段文本加进数据集（add）、构建成知识图谱（cognify）、再用检索请求（search）查出来——可以用仓库提供的最小 docker-compose 方案：一份单服务配置文件、预构建镜像cognee/cognee:main、默认本地数据库（SQLite、LanceDB、Ladybug），不需要克隆代码、不需要构建镜像，唯一需要你提供的是一个 LLM API key。

准备条件

• Docker 并安装 Compose 插件。可以是 Docker Desktop、Colima，或任意 OCI 兼容运行时。
• 一个 OpenAI API key，作为默认的 LLM 和 embedding 提供方。

使用 Colima 的话，按 docs/docker-colima-setup.md 安装启动后用以下命令确认 daemon 可用：

docker info # Should print server information without errors docker run --rm hello-world

如果提示 "Docker daemon is not responding"，按运行时装法处理：Docker Desktop 等引擎启动完成；Colima 执行colima start；Linux systemd 执行sudo systemctl start docker。

第 1 步：在空目录写入 docker-compose.yml

选一个空目录（最小方案不需要克隆仓库），把下面内容保存为docker-compose.yml：

services: cognee: image: cognee/cognee:main ports: - "8000:8000" environment: LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key} # Single-user try-out: no auth, shared local databases. # Remove this line (or set it to true) for multi-tenant mode, # which requires authentication on every API call. ENABLE_BACKEND_ACCESS_CONTROL: "false"

两处关键配置的用途：

• LLM_API_KEY通过 shell 环境变量注入，:?表示未设置时 Compose 会直接报错退出，所以启动前必须先导出它。
• ENABLE_BACKEND_ACCESS_CONTROL: "false"是单用户试用模式：共享本地数据库且所有 API 调用都不要求认证。删掉这行或设为true则是多租户模式，每次 API 调用都必须带认证。

第 2 步：启动服务

export LLM_API_KEY="sk-..." # 替换为你的 OpenAI API key docker compose up

sk-...替换成你自己的 key。

第 3 步：验证服务已就绪

先请求健康检查端点：

curl http://localhost:8000/health

再打开http://localhost:8000/docs查看交互式 API 参考。仓库根目录的完整 docker-compose.yml 中，cognee 服务也把curl -f http://localhost:8000/health配成了周期性 healthcheck（30 秒一次），说明/health就是服务就绪的判断端点。

第 4 步：发送首次 add、cognify、search 请求

以下三条命令对应「加入数据 → 构建知识图谱 → 检索」的完整链路，datasetName/datasets统一使用main_dataset。

先造一个待加料的文本文件，然后调用 add 接口把它作为数据上传：

# Ingest a text file echo "Cognee turns documents into AI memory." > note.txt curl -X POST http://localhost:8000/api/v1/add \ -F "data=@note.txt" \ -F "datasetName=main_dataset"

data=@note.txt表示把本地文件note.txt作为表单字段上传，datasetName指定归属数据集。

add 完成后调用 cognify 接口，对指定数据集构建知识图谱：

# Build the knowledge graph curl -X POST http://localhost:8000/api/v1/cognify \ -H "Content-Type: application/json" \ -d '{"datasets": ["main_dataset"]}'

最后用 search 接口查询，searchType使用GRAPH_COMPLETION：

# Search it curl -X POST http://localhost:8000/api/v1/search \ -H "Content-Type: application/json" \ -d '{"searchType": "GRAPH_COMPLETION", "query": "What does Cognee do?", "datasets": ["main_dataset"]}'

三条请求都基于同一数据集main_dataset，顺序是 add → cognify → search：先有数据，再建图，图建好后检索才会命中该数据集的内容。如果 search 返回与main_dataset无关的结果或为空，先确认前两步是否针对同一数据集成功执行。

可选：让数据在重启后保留

上面的最小文件把数据全部存在容器内，删除容器数据就没了。要持久化，把数据目录指到命名卷上：

services: cognee: image: cognee/cognee:main ports: - "8000:8000" environment: LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key} ENABLE_BACKEND_ACCESS_CONTROL: "false" DATA_ROOT_DIRECTORY: /cognee-data/data SYSTEM_ROOT_DIRECTORY: /cognee-data/system volumes: - cognee_data:/cognee-data volumes: cognee_data:

即通过DATA_ROOT_DIRECTORY和SYSTEM_ROOT_DIRECTORY两个环境变量把数据根目录和系统根目录固定到挂载卷cognee_data下。

边界与下一步

• 默认数据库（SQLite、LanceDB、Ladybug）都是文件型，开箱即用；换其他 LLM 提供方（Anthropic、Gemini、Ollama 等）时，在 compose 里追加对应的LLM_PROVIDER/LLM_MODEL/LLM_ENDPOINT变量，完整变量列表见 .env.template。
• 需要 UI、MCP 服务、Postgres、Neo4j 时，仓库根目录的 docker-compose.yml 以 opt-in profile 提供，不在本文最小方案范围内。
• 对外暴露 API 之前建议开启多租户模式（ENABLE_BACKEND_ACCESS_CONTROL=true，即默认值），它要求认证并按用户和数据集隔离数据；启用前对照 .env.template 审查相关安全变量。

【免费下载链接】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