接口参考
API 参考
相关源文件
本章引用的主要源码文件：
cognee/__init__.pycognee/api/DTO.pycognee/api/client.pycognee/api/v1/add/routers/get_add_router.pycognee/api/v1/cognify/routers/get_cognify_router.pycognee/api/v1/datasets/routers/get_datasets_router.pycognee/api/v1/delete/routers/get_delete_router.pycognee/api/v1/memify/routers/get_memify_router.pycognee/api/v1/permissions/routers/get_permissions_router.pycognee/api/v1/responses/routers/get_responses_router.pycognee/api/v1/search/routers/get_search_router.pycognee/api/v1/settings/routers/get_settings_router.pycognee/api/v1/sync/routers/get_sync_router.pycognee/api/v1/update/routers/get_update_router.pycognee/api/v1/users/routers/get_visualize_router.pycognee/api/v1/visualize/__init__.pycognee/api/v1/visualize/visualize.pycognee/shared/utils.pycognee/tests/test_telemetry.pycognee/tests/unit/processing/utils/utils_test.py
本文档全面介绍了 Cognee API 架构及其接口。它描述了 REST API 端点、Python SDK 函数、请求/响应模型以及认证机制，这些组件共同实现了与 Cognee 知识图谱平台的交互。
有关详细的端点规范，请参见 REST API 端点。有关 Python 函数签名，请参见 Python API 完整参考。有关数据库集成细节，请参见 数据库适配器接口。有关 MCP 协议集成，请参见 MCP 协议参考。
API 架构总览
Cognee 提供三种主要的 API 接口：基于 FastAPI 的 REST API、用于直接库集成的 Python SDK，以及用于 AI 助手集成的 MCP 服务器。所有接口共享相同的认证机制、数据模型和后端服务。
API 层组织
来源： cognee/__init__.py:18-65, cognee/api/client.py:18-50, cognee/api/v1/add/routers/get_add_router.py:25-47, cognee/api/v1/cognify/routers/get_cognify_router.py:71-85, cognee/api/v1/search/routers/get_search_router.py:42-106
REST 接口结构
REST API 基于 FastAPI 构建，采用模块化路由架构。每个功能区域都有独立的路由模块来处理相关端点。
路由组织
来源： cognee/api/client.py:18-50, cognee/api/v1/add/routers/get_add_router.py:25-134, cognee/api/v1/cognify/routers/get_cognify_router.py:71-135, cognee/api/v1/search/routers/get_search_router.py:42-106, cognee/api/v1/datasets/routers/get_datasets_router.py:83-210, cognee/api/v1/permissions/routers/get_permissions_router.py:33-176
核心 REST 端点
| 路由 | 路径 | 方法 | 用途 |
|---|---|---|---|
| 添加路由 | /v1/add | POST | 将文件、URL、GitHub 仓库入库到数据集中 |
| 认知化路由 | /v1/cognify | POST | 将数据集转换为知识图谱 |
| 搜索路由 | /v1/search | GET, POST | 查询知识图谱和搜索历史 |
| 数据集路由 | /v1/datasets | GET, POST, DELETE | 管理数据集并检索元数据 |
| 权限路由 | /v1/permissions | POST | 通过角色、租户和数据集权限控制访问 |
| 记忆化路由 | /v1/memify | POST | 运行图谱丰富和提取任务 |
| 更新路由 | /v1/update | PATCH | 更新数据集中的现有文档 |
| 删除路由 | /v1/delete | DELETE | 按 ID 删除数据（已废弃，推荐使用数据集级别的删除） |
来源： cognee/api/v1/add/routers/get_add_router.py:39-82, cognee/api/v1/cognify/routers/get_cognify_router.py:74-135, cognee/api/v1/search/routers/get_search_router.py:106-135, cognee/api/v1/datasets/routers/get_datasets_router.py:86-191, cognee/api/v1/delete/routers/get_delete_router.py:19-43
Python SDK 函数
Python SDK 提供了从 cognee/__init__.py 导出的高级函数，用于直接库集成。
Python API 函数参考
来源： cognee/__init__.py:21-65
关键 Python 函数
| 函数 | 用途 | 返回值 |
|---|---|---|
add(data, dataset_name, user, dataset_id, node_set) | 将数据入库到数据集中 | 管线运行信息 |
cognify(datasets, user, ...) | 将数据集处理为知识图谱 | 运行结果 |
search(query_text, query_type, user, ...) | 查询知识图谱 | 搜索结果 |
memify(extraction_tasks, enrichment_tasks, data, ...) | 执行图谱丰富管线 | 管线结果 |
remember(text) | 高级内存存储 | RememberResult |
recall(text) | 高级内存检索 | 上下文数据 |
visualize_graph(destination_file_path) | 生成图谱可视化 | HTML 字符串 |
来源： cognee/__init__.py:21-65, cognee/api/v1/visualize/visualize.py:17-30
请求/响应模型
Cognee 使用 Pydantic 模型进行请求校验和响应序列化。
DTO 层次结构
来源： cognee/api/v1/cognify/routers/get_cognify_router.py:41-68, cognee/api/v1/search/routers/get_search_router.py:25-40, cognee/api/v1/datasets/routers/get_datasets_router.py:37-73, cognee/api/v1/permissions/routers/get_permissions_router.py:29-31
认证与授权
API 使用 FastAPI Users 进行管理，并支持 Bearer 令牌和 API 密钥认证。
认证实现
来源： cognee/api/client.py:140-176, cognee/api/v1/cognify/routers/get_cognify_router.py:85, cognee/api/v1/permissions/routers/get_permissions_router.py:41
权限范围
通过 authorized_give_permission_on_datasets 方法和基于租户的角色来实施访问控制。
| 权限 | 描述 |
|---|---|
read | 检索数据集和搜索图谱 |
write | 添加和认知化数据 |
delete | 删除数据集或数据点 |
share | 向其他主体授予权限 |
来源： cognee/api/v1/permissions/routers/get_permissions_router.py:36-87, cognee/api/v1/datasets/routers/get_datasets_router.py:193-210
遥测与可观测性
Cognee 实现了使用遥测和结构化日志。
遥测实现
遥测数据会发送到中央代理以进行使用分析。每个事件都会发送三个身份层：anonymous_id、persistent_id 和 user_id。
| 函数 | 用途 |
|---|---|
send_telemetry() | 发送产品遥测事件，包含经过消毒的属性 |
get_anonymous_id() | 检索基于项目根目录的 ID，用于向后兼容 |
get_persistent_id() | 检索稳定的机器级 ID，在重新安装后仍然保留 |
_sanitize_nested_properties() | 使用 UUID5 对敏感属性（如 URL）进行哈希处理 |
来源： cognee/shared/utils.py:49-105, cognee/shared/utils.py:176-216
追踪
Cognee 提供了追踪函数来监控执行流程和性能。
| 函数 | 用途 |
|---|---|
enable_tracing() | 启用 OpenTelemetry 追踪 |
disable_tracing() | 禁用追踪 |
get_last_trace() | 检索最近的执行追踪 |
get_all_traces() | 检索所有存储的追踪 |
来源： cognee/__init__.py:52-58
总结
Cognee API 提供了以下功能：
- RESTful 端点，基于 FastAPI 实现多租户知识图谱管理。
- Python SDK，用于无缝集成到 AI 智能体工作流中。
- 结构化数据模型（DTO），确保请求/响应处理的一致性。
- 基于角色的访问控制，保障多用户环境的安全性。
- 强大的可观测性，通过集成的追踪和遥测实现。
有关实现细节，请参见 Python API 完整参考 和 REST API 端点。