5.6 · Cache Layer

Cache Layer（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/5.6-cache-layer

翻译时间：2026-05-27T08:45:13.818Z

翻译模型：deepseek-chat

原文字符数：10749

项目：Cognee (cognee)

---

缓存层

Cognee 中的缓存层为分布式锁、会话持久化、代理追踪存储和用量日志记录提供了基础设施。它支持多种后端：Redis 用于需要分布式协调的生产环境，文件系统（diskcache） 用于本地开发，以及 Tapes 用于将交互镜像到语义搜索表面 cognee/infrastructure/databases/cache/config.py:25-25, cognee/infrastructure/databases/cache/tapes/TapesCacheAdapter.py:1-9。

缓存架构

缓存系统基于 CacheDBInterface 协议构建，该协议定义了会话管理、代理追踪和锁定的标准操作 cognee/infrastructure/databases/cache/cache_db_interface.py:8-12。

缓存系统组件

代码到系统的映射：会话和追踪流

此图展示了会话数据和代理追踪如何从代码实体流入底层的缓存存储。

graph TD
    subgraph "自然语言空间"
        "用户问题" --> "问答条目"
        "代理动作" --> "追踪步骤"
        "大语言模型反馈" --> "追踪步骤"
    end

    subgraph "代码实体空间"
        "问答条目" --> "SessionQAEntry [cognee/infrastructure/databases/cache/models.py]"
        "追踪步骤" --> "SessionAgentTraceEntry [cognee/infrastructure/databases/cache/models.py]"

        "SessionQAEntry [cognee/infrastructure/databases/cache/models.py]" -- "create_qa_entry()" --> "CacheDBInterface [cognee/infrastructure/databases/cache/cache_db_interface.py]"
        "SessionAgentTraceEntry [cognee/infrastructure/databases/cache/models.py]" -- "append_agent_trace_step()" --> "CacheDBInterface [cognee/infrastructure/databases/cache/cache_db_interface.py]"

        "CacheDBInterface [cognee/infrastructure/databases/cache/cache_db_interface.py]" -- "继承" --> "RedisAdapter [cognee/infrastructure/databases/cache/redis/RedisAdapter.py]"
        "CacheDBInterface [cognee/infrastructure/databases/cache/cache_db_interface.py]" -- "继承" --> "FSCacheAdapter [cognee/infrastructure/databases/cache/fscache/FsCacheAdapter.py]"

        "RedisAdapter [cognee/infrastructure/databases/cache/redis/RedisAdapter.py]" -- "保存到" --> "Redis_数据库"
        "FSCacheAdapter [cognee/infrastructure/databases/cache/fscache/FsCacheAdapter.py]" -- "保存到" --> "DiskCache_文件"
    end

来源： cognee/infrastructure/databases/cache/cache_db_interface.py:70-89, cognee/infrastructure/databases/cache/cache_db_interface.py:163-180, cognee/infrastructure/databases/cache/models.py:1-20, cognee/infrastructure/databases/cache/redis/RedisAdapter.py:21-36, cognee/infrastructure/databases/cache/fscache/FsCacheAdapter.py:22-36

实现细节

缓存引擎工厂

get_cache_engine 函数作为入口点，利用 create_cache_engine 根据 cache_backend 配置返回相应的适配器 cognee/infrastructure/databases/cache/get_cache_engine.py:85-109。该工厂使用 lru_cache 确保每组参数只返回一个单例实例 cognee/infrastructure/databases/cache/get_cache_engine.py:10-26。

会话和代理追踪管理

Cognee 区分了两种类型的会话数据：

1. 问答会话： 用户问题、上下文和大语言模型回答的历史记录。通过 create_qa_entry 管理 cognee/infrastructure/databases/cache/cache_db_interface.py:70-82。条目包含 used_graph_element_ids 等元数据，用于追踪哪些图节点/边影响了回答 cognee/infrastructure/databases/cache/redis/RedisAdapter.py:105-118。
2. 代理追踪： 代理逻辑的详细执行步骤（例如，工具调用、错误）。通过 append_agent_trace_step 管理 cognee/infrastructure/databases/cache/cache_db_interface.py:163-180。

分布式锁

分布式锁协调多进程环境中对共享资源的访问，专门保护 Kuzu（旧版）或 Ladybug 等图数据库。

• Redis 实现： 使用 sync_redis.lock 并设置 thread_local=False，允许锁在不同于获取它的线程中释放 cognee/infrastructure/databases/cache/redis/RedisAdapter.py:207-220。它使用可配置的 agentic_lock_expire 和 agentic_lock_timeout cognee/infrastructure/databases/cache/config.py:34-35。
• 文件系统实现： 不支持锁定，会抛出 SharedLadybugLockRequiresRedisError 异常 cognee/infrastructure/databases/cache/fscache/FsCacheAdapter.py:179-183。

用量日志记录

当启用 usage_logging 时，系统会将 API 端点调用和 MCP 工具调用记录到缓存中 cognee/infrastructure/databases/cache/config.py:38-39。这些日志以可配置的 TTL（默认 7 天）存储 cognee/infrastructure/databases/cache/config.py:39-39。RedisAdapter 通过 rpush 将日志追加到由 log_key 标识的列表键中来实现此功能 cognee/infrastructure/databases/cache/redis/RedisAdapter.py:226-250。

数据流：分布式锁

此图展示了使用 Redis 适配器保护共享资源的锁定机制。

sequenceDiagram
    participant App as "Cognee 应用程序"
    participant Factory as "get_cache_engine()"
    participant Redis as "RedisAdapter [cognee/infrastructure/databases/cache/redis/RedisAdapter.py]"
    participant Server as "Redis 服务器"

    App->>Factory: 请求引擎
    Factory->>App: 返回 RedisAdapter 实例
    App->>Redis: hold_lock() [cognee/infrastructure/databases/cache/cache_db_interface.py]
    Redis->>Redis: acquire_lock()
    Redis->>Server: SET lock_key NX PX expire
    Server-->>Redis: OK（已获取）
    App->>App: 执行关键操作（例如，图写入）
    App->>Redis: release_lock()
    Redis->>Server: DEL lock_key

来源： cognee/infrastructure/databases/cache/cache_db_interface.py:40-49, cognee/infrastructure/databases/cache/redis/RedisAdapter.py:207-220, cognee/infrastructure/databases/cache/get_cache_engine.py:85-109

配置参数

设置通过 CacheConfig（Pydantic 设置）管理，支持环境变量覆盖 cognee/infrastructure/databases/cache/config.py:7-46。

来源：

• cognee/infrastructure/databases/cache/config.py
• cognee/infrastructure/databases/cache/cache_db_interface.py
• cognee/infrastructure/databases/cache/get_cache_engine.py
• cognee/infrastructure/databases/cache/redis/RedisAdapter.py
• cognee/infrastructure/databases/cache/fscache/FsCacheAdapter.py
• cognee/infrastructure/databases/cache/tapes/TapesCacheAdapter.py