用图谱检索和向量检索为AI智能体构建长期记忆

## 把记忆分成从导入数据到检索的几个阶段 为持久化知识定义一条明确的生命周期：把原始文件、URL或文本摄取到数据集中；将材料转化为实体、关系、分块和摘要；通过选定策略检索相关知识；再用附加上下文或规则丰富已存储的图。 让各阶段既可独立调用，又在组合时保持一致。摄取阶段必须先创建持久化的数据集记录和数据记录，再进行转换。转换阶段对内容分类和分块，提取结构化关系，在有需要时生成摘要，并写入相互兼容的图表示与向量表示。检索阶段必须在返回结果前应用授权。丰富阶段必须保留来源沿袭和版本元数据。 ## 分层设计，让核心代码不直接调用提供方 将带版本的API或SDK入口、生命周期函数、流水线编排、任务执行、领域模块、基础设施适配器和外部服务分离。依赖关系应沿这些层级向下指向，使领域行为不直接导入特定提供方的客户端。 明确表达图的原子概念：节点或数据点带有稳定的标识符、类型、描述、版本和元数据；边带有源、目标和关系类型；三元组表示主语—谓语—宾语事实。使用知识图谱容器，在提取、存储和检索之间传递相互一致的节点与边集合。 ## 用小任务组成流水线，并明确选择检索策略 将处理步骤表示为可组合的任务；只要数据依赖允许，这些任务即可串行或并行运行。流水线应把分类、分块提取、结构化图提取、摘要和存储明确呈现为独立单元，使故障与重试保持在局部范围内。 通过明确的策略类型路由搜索。支持带生成补全的图遍历、由摘要支撑的图上下文、三元组检索、向量与词法分块搜索、文档摘要、时间感知检索、自然语言到结构化查询的转换、直接图查询，以及有充分依据时的自动策略选择。每种策略都必须共用授权过滤和稳定的结果契约。 ## 把存储和模型提供方放在接口之后，便于更换 分别为图存储、向量存储和关系型存储定义接口。通过工厂选择具体引擎，使本地默认实现、远程服务和生产数据库都能在不改变领域任务的情况下替换。把特定提供方的连接逻辑、能力检查和不支持操作的错误留在适配器内部。 对语言模型、嵌入引擎、结构化输出框架、文件加载器和对象存储采用相同的边界。由配置选择实现，领域代码只使用接口。当后端缺少直接图查询或某种检索模式等能力时，应明确拒绝该操作，而不是静默降级为语义不同的行为。 ## 按用户隔离数据时，必须同时启用身份验证 将访问关系建模为用户到数据集再到数据，并在图或向量检索前强制执行读取、写入、删除和共享权限。在支持的情况下，按用户和数据集隔离存储，使过滤错误无法暴露其他租户的知识。 把后端访问控制和API身份验证视为一套统一的安全姿态。启用租户隔离时必须要求身份验证；明确关闭身份验证的设置不得覆盖已启用的访问控制。单用户共享存储是一种有意选择的独立模式。应返回空结果，而不是透露不可访问记录的存在；同时为获授权的运维人员保留足够的内部诊断信息。 ## 成对配置语言模型和嵌入提供方，并统一检查生产环境设置 将语言模型提供方和嵌入提供方成对配置。如果只设置其中一个，另一个的隐式默认值可能导致缺少凭据、分词不兼容或意外的外部调用。启动时应验证两个提供方、端点、模型、结构化输出模式和速率限制。 把机密信息保存在由环境变量支持的配置中，并通过安装扩展项或功能组提供可选集成。本地默认配置可以使用基于文件的关系型、向量和图存储，但生产部署必须统一审查存储路径、远程请求权限、本地文件访问、原始查询权限、身份验证、租户隔离和持久对象存储。 ## 通过固定的注册点添加新的存储或检索策略 在范围最小且稳定的扩展点添加能力：实现一个任务并将其注册到流水线；为新后端实现存储接口；在模型网关之后添加提供方配置；为新格式扩展文档加载器；注册检索策略；或者定义扩展通用数据点契约的图模型。 对于以本体为基础的提取，应让解析器、本体来源和匹配策略保持可配置。存储前，验证提取出的实体类型和关系是否符合所选语义框架。新扩展必须声明所需依赖、支持的能力、配置字段和失败行为。 ## 测试每个组件，以及从导入数据到检索的完整流程 按单元行为、集成边界、命令行或API入口以及任务特定行为来组织测试。每项功能都需要聚焦测试，而存储适配器、模型网关和其他集成则需要使用贴近实际的配置与失败响应进行边界测试。 至少维护一条从摄取、转换到检索的完整生命周期集成路径，其中包括异步执行和授权过滤。通过直接等待或事件循环运行器测试每个公开的异步函数。按照仓库策略运行覆盖率、代码检查、格式化和类型检查，并使测试与源代码的分层结构保持一致。 ## 先检查配置，并区分空的检索结果和故障 在更改流水线逻辑前，先诊断配置故障。验证成对的模型与嵌入设置、结构化输出模式、分词器兼容性、数据库URL与凭据、服务可用性和速率限制设置。让提供方回退行为保持可见，避免部分配置静默选择非预期的远程服务。 区分经授权后得到的空结果与传输或解析故障。经过权限过滤的搜索不应泄露记录是否存在；连接故障应指出适配器和失败的前置条件；速率限制故障应给出重试时机；结构化输出故障应指出已配置的提取模式。使用结构化日志和可选的调试检测，但绝不记录凭据或检索到的敏感内容。