接口参考（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/13-api-reference
翻译时间：2026-05-27T08:45:28.515Z
翻译模型：deepseek-chat
原文字符数：15567
项目：Cognee (cognee)
---
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 层组织
graph TB
subgraph "客户端接口"
RestClient["REST API 客户端<br/>(HTTP/HTTPS)"]
PythonClient["Python SDK<br/>(cognee.add/cognify/search)"]
MCPClient["MCP 客户端<br/>(Claude, Cursor)"]
end
subgraph "API 层"
FastAPIServer["FastAPI 服务器<br/>(cognee/api/client.py)"]
PythonAPI["Python API 函数<br/>(cognee/__init__.py)"]
MCPServer["MCP 服务器<br/>(FastMCP)"]
end
subgraph "路由层"
AddRouter["添加路由<br/>(get_add_router.py)"]
CognifyRouter["认知化路由<br/>(get_cognify_router.py)"]
SearchRouter["搜索路由<br/>(get_search_router.py)"]
DatasetsRouter["数据集路由<br/>(get_datasets_router.py)"]
PermissionsRouter["权限路由<br/>(get_permissions_router.py)"]
SettingsRouter["设置路由<br/>(get_settings_router.py)"]
DeleteRouter["删除路由<br/>(get_delete_router.py)"]
VisualizeRouter["可视化路由<br/>(get_visualize_router.py)"]
end
subgraph "核心服务"
AuthService["认证<br/>(get_authenticated_user)"]
DTOLayer["DTO 模型<br/>(InDTO, OutDTO)"]
TelemetryService["遥测<br/>(send_telemetry)"]
end
subgraph "后端"
CorePipeline["核心处理<br/>(cognify, add, search)"]
Database["数据库层<br/>(关系型、向量、图)"]
end
RestClient --> FastAPIServer
PythonClient --> PythonAPI
MCPClient --> MCPServer
FastAPIServer --> AddRouter
FastAPIServer --> CognifyRouter
FastAPIServer --> SearchRouter
FastAPIServer --> DatasetsRouter
FastAPIServer --> PermissionsRouter
FastAPIServer --> SettingsRouter
FastAPIServer --> DeleteRouter
FastAPIServer --> VisualizeRouter
PythonAPI --> CorePipeline
MCPServer --> CorePipeline
AddRouter --> AuthService
CognifyRouter --> AuthService
SearchRouter --> AuthService
AddRouter --> DTOLayer
CognifyRouter --> DTOLayer
SearchRouter --> DTOLayer
AddRouter --> TelemetryService
CognifyRouter --> TelemetryService
AddRouter --> CorePipeline
CognifyRouter --> CorePipeline
SearchRouter --> CorePipeline
DatasetsRouter --> CorePipeline
CorePipeline --> Database
来源： 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 构建，采用模块化路由架构。每个功能区域都有独立的路由模块来处理相关端点。
路由组织
graph TB
subgraph "FastAPI 应用"
Server["FastAPI 服务器<br/>(cognee/api/client.py)"]
end
subgraph "认证层"
JWTAuth["JWT 认证<br/>(DefaultJWTStrategy)"]
UserAuth["get_authenticated_user<br/>(依赖注入)"]
ApiKeyAuth["X-Api-Key 请求头"]
end
subgraph "路由模块"
AddEndpoints["/v1/add<br/>POST /add"]
CognifyEndpoints["/v1/cognify<br/>POST /cognify"]
SearchEndpoints["/v1/search<br/>GET /search<br/>POST /search"]
DatasetEndpoints["/v1/datasets<br/>GET /datasets<br/>POST /datasets<br/>DELETE /datasets/{id}"]
PermEndpoints["/v1/permissions<br/>POST /datasets/{id}<br/>POST /roles<br/>POST /users/{id}/roles"]
UpdateEndpoints["/v1/update<br/>PATCH /update"]
DeleteEndpoints["/v1/delete<br/>DELETE /delete"]
MemifyEndpoints["/v1/memify<br/>POST /memify"]
end
subgraph "请求/响应模型"
InDTO["InDTO<br/>(cognee/api/DTO.py)"]
OutDTO["OutDTO<br/>(cognee/api/DTO.py)"]
Payloads["载荷 DTO<br/>(CognifyPayloadDTO<br/>SearchPayloadDTO)"]
end
subgraph "遥测与日志"
Telemetry["send_telemetry<br/>(cognee/shared/utils.py)"]
Logger["setup_logging<br/>(cognee/shared/logging_utils.py)"]
end
Server --> AddEndpoints
Server --> CognifyEndpoints
Server --> SearchEndpoints
Server --> DatasetEndpoints
Server --> PermEndpoints
Server --> UpdateEndpoints
Server --> DeleteEndpoints
Server --> MemifyEndpoints
AddEndpoints --> UserAuth
CognifyEndpoints --> UserAuth
SearchEndpoints --> UserAuth
UserAuth --> JWTAuth
UserAuth --> ApiKeyAuth
AddEndpoints --> Payloads
CognifyEndpoints --> Payloads
SearchEndpoints --> Payloads
Payloads --> InDTO
Payloads --> OutDTO
AddEndpoints --> Telemetry
CognifyEndpoints --> Telemetry
SearchEndpoints --> Telemetry
AddEndpoints --> Logger
CognifyEndpoints --> Logger
来源： 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 函数参考
graph LR
subgraph "数据入库"
add["add(data, dataset_name, user)"]
update["update(data_id, data, dataset_id)"]
end
subgraph "知识图谱生成"
cognify["cognify(datasets, user)"]
memify["memify(extraction_tasks, enrichment_tasks)"]
end
subgraph "查询与检索"
search["search(query_text, query_type)"]
recall["recall(text)"]
remember["remember(text)"]
end
subgraph "管理"
delete["delete(data_id, dataset_id)"]
prune["prune()"]
forget["forget(text)"]
end
subgraph "可观测性"
enable_tracing["enable_tracing()"]
get_last_trace["get_last_trace()"]
end
subgraph "可视化"
visualize_graph["visualize_graph(path)"]
start_ui["start_ui()"]
end
来源： 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 层次结构
graph TB
subgraph "基础模型"
InDTO["InDTO<br/>(cognee/api/DTO.py)"]
OutDTO["OutDTO<br/>(cognee/api/DTO.py)"]
end
subgraph "请求模型 (InDTO)"
CognifyPayloadDTO["CognifyPayloadDTO<br/>datasets: List[str]<br/>run_in_background: bool<br/>custom_prompt: str"]
SearchPayloadDTO["SearchPayloadDTO<br/>search_type: SearchType<br/>query: str<br/>top_k: int"]
SelectTenantDTO["SelectTenantDTO<br/>tenant_id: UUID"]
end
subgraph "响应模型 (OutDTO)"
DatasetDTO["DatasetDTO<br/>id: UUID<br/>name: str<br/>owner_id: UUID"]
DataDTO["DataDTO<br/>id: UUID<br/>name: str<br/>dataset_id: UUID"]
GraphDTO["GraphDTO<br/>nodes: List[GraphNodeDTO]<br/>edges: List[GraphEdgeDTO]"]
end
InDTO --> CognifyPayloadDTO
InDTO --> SearchPayloadDTO
InDTO --> SelectTenantDTO
OutDTO --> DatasetDTO
OutDTO --> DataDTO
OutDTO --> GraphDTO
来源： 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 密钥认证。
认证实现
sequenceDiagram
participant 客户端
participant 路由["API 路由"]
participant 认证["get_authenticated_user"]
participant 用户数据库["用户数据库"]
客户端->>路由: 请求 + X-Api-Key/Bearer
路由->>认证: 依赖注入(get_authenticated_user)
认证->>用户数据库: 校验凭证
用户数据库-->>认证: 用户上下文
认证-->>路由: 已认证用户
路由->>路由: 处理请求
路由-->>客户端: JSON 响应
来源： 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 端点。