agentic_huge_data_base / wiki
页面 Cognee · 2.3 REST API 服务端·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 2.3

2.3 · REST API 服务端（REST API Server）

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

项目Cognee 章节2.3 状态全文译文 模块接口与服务契约、检索、召回与索引、图谱与关系、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节REST API Server 上一章2.2 下一章2.4
源码线索
  • cognee/__init__.py
  • cognee/api/DTO.py
  • cognee/api/client.py
  • cognee/api/v1/add/routers/get_add_router.py
  • cognee/api/v1/cognify/routers/get_cognify_router.py
  • cognee/api/v1/datasets/routers/get_datasets_router.py
  • cognee/api/v1/delete/routers/get_delete_router.py
  • cognee/api/v1/memify/routers/get_memify_router.py
  • cognee/api/v1/ontologies/__init__.py
  • cognee/api/v1/ontologies/ontologies.py
模块标签
  • 接口与服务契约
  • 检索、召回与索引
  • 图谱与关系
  • 测试、发布与运维
  • 界面与交互

章节正文

REST API 服务端

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/2.3-rest-api-server

REST 接口服务器

相关源文件

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

  • cognee/__init__.py
  • cognee/api/DTO.py
  • cognee/api/client.py
  • cognee/api/v1/add/routers/get_add_router.py
  • cognee/api/v1/cognify/routers/get_cognify_router.py
  • cognee/api/v1/datasets/routers/get_datasets_router.py
  • cognee/api/v1/delete/routers/get_delete_router.py
  • cognee/api/v1/memify/routers/get_memify_router.py
  • cognee/api/v1/ontologies/__init__.py
  • cognee/api/v1/ontologies/ontologies.py
  • cognee/api/v1/ontologies/routers/__init__.py
  • cognee/api/v1/ontologies/routers/get_ontology_router.py
  • cognee/api/v1/permissions/routers/get_permissions_router.py
  • cognee/api/v1/responses/routers/get_responses_router.py
  • cognee/api/v1/search/routers/get_search_router.py
  • cognee/api/v1/settings/routers/get_settings_router.py
  • cognee/api/v1/sync/routers/get_sync_router.py
  • cognee/api/v1/update/routers/get_update_router.py
  • cognee/api/v1/users/routers/get_visualize_router.py
  • cognee/api/v1/visualize/__init__.py
  • cognee/api/v1/visualize/visualize.py
  • cognee/shared/utils.py
  • cognee/tests/test_cognee_server_start.py
  • cognee/tests/test_telemetry.py
  • cognee/tests/unit/api/test_ontology_endpoint.py
  • cognee/tests/unit/processing/utils/utils_test.py

目的与范围

REST API 服务器通过一个 FastAPI 应用程序提供对 Cognee 核心操作的 HTTP 访问。它通过标准的 HTTP 端点，支持以编程方式与 Cognee 的知识图谱功能进行交互。如需直接进行 Python 集成，请参阅 Python API 参考。如需命令行用法，请参阅 CLI 接口。如需集成 AI 助手，请参阅 面向 AI 代理的 MCP 服务器。

服务器架构

技术栈与进程模型

REST API 服务器基于 FastAPI 构建，并使用 uvicorn 作为 ASGI 服务器 cognee/api/client.py:5-9。应用程序入口点位于 cognee.api.client。

标题：REST API 服务器组件架构

Cognee · 技术栈与进程模型 · 图 1
Cognee · 技术栈与进程模型 · 图 1

架构细节：

  • 生命周期管理：lifespan 函数处理启动任务，包括通过 run_startup_migrations() 运行数据库迁移，并确保存在一个默认用户 cognee/api/client.py:75-98。
  • 优雅关闭：退出时，服务器会清除数据库引擎缓存（_create_graph_engine 和 _create_vector_engine），以确保预写日志（WAL）检查点能正确写入磁盘 cognee/api/client.py:101-112。
  • CORS 支持：可通过 CORS_ALLOWED_ORIGINS 环境变量进行配置，默认值为 UI_APP_URL 或 http://localhost:3000 cognee/api/client.py:119-135。
  • 安全性：同时支持 BearerAuth（JWT）和 ApiKeyAuth（X-Api-Key）cognee/api/client.py:152-157。
  • 异常处理：针对 RequestValidationError 和 CogneeApiError 的自定义处理器，确保返回一致的错误响应 cognee/api/client.py:179-195。
  • 可观测性：如果 ENV 设置为 prod，则会集成 Sentry 进行错误报告 cognee/api/client.py:57-69。

来源：cognee/api/client.py:75-115, cognee/api/client.py:119-135, cognee/api/client.py:140-176, cognee/api/client.py:179-195

核心 API 端点

数据入库 - /v1/add

add 端点接受文件和 URL，将数据入库到 Cognee 数据集中。

参数类型描述
dataList[UploadFile]要上传的文件 cognee/api/v1/add/routers/get_add_router.py:40
datasetNameOptional[str]目标数据集的名称 cognee/api/v1/add/routers/get_add_router.py:41
datasetIdOptional[UUID]现有数据集的 UUID cognee/api/v1/add/routers/get_add_router.py:43
node_setOptional[List[str]]用于图分组的标识符 cognee/api/v1/add/routers/get_add_router.py:44
run_in_backgroundOptional[bool]是否作为异步任务执行（默认值：False）cognee/api/v1/add/routers/get_add_router.py:45

来源：cognee/api/v1/add/routers/get_add_router.py:25-134

知识图谱生成 - /v1/cognify

/v1/cognify 端点触发处理管线，从已入库的数据中提取实体和关系 cognee/api/v1/cognify/routers/get_cognify_router.py:74-135。

标题：Cognify 数据流：从请求到执行

Cognee · v1 · 图 2
Cognee · v1 · 图 2

请求 DTO (CognifyPayloadDTO)：

  • datasets：要处理的数据集名称 cognee/api/v1/cognify/routers/get_cognify_router.py:42。
  • run_in_background：布尔值，决定管线是否作为异步任务运行 cognee/api/v1/cognify/routers/get_cognify_router.py:44。
  • custom_prompt：覆盖用于提取的默认大语言模型（LLM）提示词 cognee/api/v1/cognify/routers/get_cognify_router.py:46。
  • ontology_key：引用特定的本体，用于图构建 cognee/api/v1/cognify/routers/get_cognify_router.py:54。
  • chunk_size：每个片段的最大 Token 数 cognee/api/v1/cognify/routers/get_cognify_router.py:49。

来源：cognee/api/v1/cognify/routers/get_cognify_router.py:41-69, cognee/api/v1/cognify/routers/get_cognify_router.py:153-160

搜索与检索 - /v1/检索

搜索路由器提供基于语义和图的检索功能。

标题：搜索 API 组件与操作映射

Cognee · v1 · 图 3
Cognee · v1 · 图 3

搜索载荷 (SearchPayloadDTO)：

  • search_type：默认为 GRAPH_COMPLETION cognee/api/v1/search/routers/get_search_router.py:26。
  • query：搜索字符串 cognee/api/v1/search/routers/get_search_router.py:29。
  • top_k：返回的结果数量（默认值：10）cognee/api/v1/search/routers/get_search_router.py:34。
  • only_context：如果为 true，则仅返回为大语言模型（LLM）检索到的上下文 cognee/api/v1/search/routers/get_search_router.py:35。

来源：cognee/api/v1/search/routers/get_search_router.py:25-40, cognee/api/v1/search/routers/get_search_router.py:96-170

本体管理 - /v1/ontologies

本体系统允许用户上传 .owl 文件，以指导知识图谱的提取过程 cognee/api/v1/ontologies/ontologies.py:51-86。

方法端点描述
POST/v1/ontologies上传新的本体文件 cognee/api/v1/ontologies/ontologies.py:51-86
GET/v1/ontologies列出用户上传的所有本体 cognee/api/v1/ontologies/ontologies.py:179-181
DELETE/v1/ontologies/{key}移除一个本体及其元数据 cognee/api/v1/ontologies/ontologies.py:159-177

来源：cognee/api/v1/ontologies/ontologies.py:22-181

用户与权限管理

Cognee 包含一个可通过 API 访问的多租户权限系统。

  • 数据集管理：用于列出、创建和删除数据集的端点 cognee/api/v1/datasets/routers/get_datasets_router.py:86-210。
  • 权限路由器：
    • POST /v1/permissions/datasets/{principal_id}：向用户或角色授予数据集访问权限 cognee/api/v1/permissions/routers/get_permissions_router.py:36-87。
    • DELETE /v1/permissions/datasets/{principal_id}：撤销数据集权限 cognee/api/v1/permissions/routers/get_permissions_router.py:89-130。
    • POST /v1/permissions/roles：创建新的安全角色 cognee/api/v1/permissions/routers/get_permissions_router.py:132-173。

来源：cognee/api/v1/permissions/routers/get_permissions_router.py:33-173, cognee/api/v1/datasets/routers/get_datasets_router.py:83-210

启动与迁移

当服务器启动时，lifespan 上下文管理器会处理数据库的就绪状态 cognee/api/client.py:75-99。

  1. 关系型数据库迁移：调用 run_startup_migrations() 来升级关系型模式 cognee/api/client.py:85。
  2. 数据库初始化：如果迁移失败（例如，首次运行），则使用 get_relational_engine().create_database() 创建数据库 cognee/api/client.py:87-88。
  3. 默认用户：调用 get_default_user() 以确保在本地/开发环境中存在一个系统用户 cognee/api/client.py:94。

来源：cognee/api/client.py:75-99, cognee/run_migrations.py:43-57