Hindsight 内存整合Consolidation性能基准测试吞吐量测量与瓶颈定位实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读Consolidation内存整合是 Hindsight Agent 记忆系统的核心后台流水线它把 retain 阶段沉淀下来的原始记忆experience/world 事实自动整理为可复用的 observation观察支持新建、更新、合并、删除四种动作。本指南基于仓库中的整合性能基准 README 及其配套脚本与源码完整讲解如何测量整合吞吐量op/sec、解析 recall / LLM / embedding / DB write 四段耗时分布、对照基线数据解读结果并给出已在仓库中落地与推荐继续执行的优化清单。读完你将能够独立跑通基准、读懂输出报表并用源码级知识定位整合流水线的真实瓶颈。为什么需要整合性能基准在 consolidator.py 的模块注释中可以看到整合引擎作为 retain 操作完成后的后台任务运行它读取新记忆后要么从新事实创建 observation要么在既有证据支持、反驳或细化 observation 时更新它。observation 以fact_typeobservation存于 memory_units 表携带proof_count支撑记忆数、source_memory_ids来源记忆 UUID 数组、history随时间变化的 JSONB 记录等元数据。由于整合每一步都依赖大模型与向量检索整条流水线天然是重 I/O 重 LLM 的任务。性能基准的价值在于把整合很慢这个模糊感受量化为四个组件的精确耗时占比从而让优化决策有数据依据——是换更快的模型还是压缩 recall 预算还是减少观察结果条数都可以先用基准验证。快速开始三步跑通基准基准脚本位于 scripts/benchmarks/run-consolidation.sh运行前它会自动加载仓库根目录的.env如果存在并强制导出HINDSIGHT_API_ENABLE_OBSERVATIONStrue——这是整合功能的前置开关见 consolidation_benchmark.py 中if not config.enable_observations的检查。默认配置运行创建 100 条测试记忆./scripts/benchmarks/run-consolidation.sh自定义记忆数量NUM_MEMORIES50 ./scripts/benchmarks/run-consolidation.sh指定不同的整合模型以 groq 平台的 llama-3.1-70b-versatile 为例export HINDSIGHT_API_CONSOLIDATION_LLM_MODELllama-3.1-70b-versatile NUM_MEMORIES100 ./scripts/benchmarks/run-consolidation.sh脚本最终执行的命令是uv run python -m benchmarks.consolidation.consolidation_benchmark运行环境要求项目使用uv管理依赖基准依赖hindsight_api包配置、MemoryEngine、consolidator因此需要先在可用的 Hindsight API 环境含 PostgreSQL 数据库中执行。基准测量什么四段式流水线计时基准的完整流程定义在 consolidation_benchmark.py 的main()中共 7 步读取配置NUM_MEMORIES默认 100、HINDSIGHT_API_LLM_PROVIDER、HINDSIGHT_API_LLM_MODEL并生成独立的 bankconsolidation-bench-8位随机hex测试数据与生产库隔离。初始化 MemoryEngine数据库 URL 默认pg0LLM 默认 providergroq、默认模型openai/gpt-oss-120b可通过环境变量覆盖。创建测试银行记录整合前的 memory 统计按 fact_type 分组。批量摄入 N 条多样化测试记忆报告摄入速率mem/sec。运行整合并计时调用run_consolidation_job()计算总耗时、处理记忆数、吞吐量。分析计时分解从整合日志中提取 recall / llm / embedding / db_write 四段耗时。输出结果表并保存 JSON最后清理测试 bank 与连接池。测试记忆的多样性设计测试记忆来自SAMPLE_MEMORIES常量刻意覆盖了整合引擎需要处理的各类模式见 consolidation_benchmark.py L32-L64类别示例预期整合行为相似记忆Alice loves coffee… / Alice prefers coffee over tea…应合并为一条 observation不同主体Bob 与 Alice 的事实不应与 Alice 合并技术事实 / 产品信息Python、iPhone 15创建世界知识类 observation矛盾信息会议从周二改到周三应合并并解决冲突保留新信息实体丰富内容Sarah Smith / Microsoft / Stanford考验实体解析与归并时间信息项目 1 月 15 日启动、3 月 30 日截止验证时间跨度聚合偏好 / 世界知识 / 多实体dark mode、巴黎是法国首都、John and Mary覆盖通用与复杂场景每条记忆在循环复用样本的基础上追加(context: test N)后缀以避免完全重复。这套数据设计直接决定基准结果的代表性——如果只喂重复文本整合引擎无需 recall 与 LLM 决策测出的就不是真实瓶颈。计时数据从哪来整合过程中的分组件计时并非基准脚本自行埋点而是依赖整合引擎内部的性能日志对象ConsolidationPerfLog定义于 consolidator.py L1093-L1159。该对象record_timing(key, duration)累计每个组件recall、llm、embedding、db_write等的总秒数与调用次数从而区分一次很慢与很多次较快record_llm_call(obs_count, prompt_chars)记录单次 LLM 调用放入上下文的 observation 数量与提示词字符数flush()在作业结束时把全部日志行以CONSOLIDATION for bank ...头部、逐行明细、CONSOLIDATION COMPLETE: 总秒s total尾部输出到 logger。基准脚本在运行前会把hindsight_api.engine.consolidation.consolidator这个 logger 的级别设为 INFO 并挂接控制台 handler这就是示例输出中计时分解的来源。指标解读与基线对照核心指标Throughput (op/sec)每秒处理的记忆条数memories_processed / total_time是整合吞吐的顶层指标Timing Breakdown (%)各组件耗时占比用于定位瓶颈Observations Created / Updated / Merged整合动作的质量指标Skipped (No Durable Knowledge)表示被判定无持久知识价值的记忆数Memories Before / Observations After整合前后 bank 内数据规模变化验证整合确实浓缩了知识。官方基线数据groq / openai / gpt-oss-120b仓库 README 记录了该配置下的基线观测结果吞吐约 0.7–1.0 op/sec即每条记忆耗时 1–1.4 秒LLM 调用占 80–87%是第一瓶颈Recall相关 observation 召回占 10–17%是第二瓶颈。注意这是项目自测的参考基线实际数值随所选 provider、模型、网络延迟与数据库性能波动。基准的价值在于建立本环境的对照基线——先跑一次默认配置再逐项应用优化用前后两次报表对比优化收益。示例输出解析一次典型运行43 条待整合记忆的输出如下Consolidation Benchmark Results ┌────────────────────────────────┬─────────────┐ │ Metric │ Value │ ├────────────────────────────────┼─────────────┤ │ Total Time │ 60.28s │ │ Memories Processed │ 43 │ │ Throughput │ 0.71 op/sec │ │ Avg Time/Memory │ 1.402s │ │ │ │ │ Observations Created │ 4 │ │ Observations Updated │ 38 │ │ Observations Merged │ 0 │ │ Skipped (No Durable Knowledge) │ 1 │ └────────────────────────────────┴─────────────┘ Timing breakdown: recall6.295s (10.4%) llm52.144s (86.5%) ← BOTTLENECK embedding1.717s (2.8%) db_write0.075s (0.1%)解读要点43 条记忆中 38 条驱动了既有 observation 的更新、4 条创建了新的 observation、1 条被跳过——这与测试数据大量相似/矛盾记忆应合并更新的设计吻合说明整合决策质量正常86.5% 的时间花在 LLM 上说明吞吐的天花板是模型推理速度而非数据库embedding2.8%与 db_write0.1%几乎可忽略这为后续优化方向提供了明确信号。已实施与推荐优化从基线到行动已实施✅仓库 README 列出的三项已落地优化批量数据库查询Batch database queries修复了 N1 查询问题——按批拉取待整合记忆、批量写入 observation而非逐条往返数据库。在源码层面run_consolidation_job通过consolidation_batch_size、consolidation_llm_batch_size两个配置分别控制每批取多少记忆与每条 LLM 调用合并多少记忆见 config.py L4633-L4647从而把 DB 往返与 LLM 调用次数都压缩到常数级降低 recall token 预算5000 → 2000召回阶段喂给 LLM 的相关 observation 文本从 5000 token 压缩到 2000直接削减了 LLM 输入长度——对应配置项consolidation_recall_budget与consolidation_source_facts_max_tokensconfig.py L4665-L4670限制 observation 结果条数top 15每次召回最多返回 15 条候选 observation避免海量历史观察撑爆上下文。这三项优化在示例输出中的直接体现是recall 占比被压到 10.4%db_write 仅 0.1%LLM 成为唯一的、且可被换模型解决的瓶颈。推荐继续执行为整合使用更快的 LLM既然 LLM 占 80–87% 耗时换用吞吐更高的模型如通过HINDSIGHT_API_CONSOLIDATION_LLM_MODEL/HINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER指定是收益最大的杠杆启用提示词缓存prompt caching整合批次的系统提示与观察列表在相邻批次间高度相似缓存可显著降低重复前缀的推理开销优化提示词冗长度精简 prompts.py 中的系统提示与输入组装build_consolidation_system_prompt/build_consolidation_input减小每轮 LLM 的输入输出 token 数。另外值得关注源码中与性能/质量相关的配置consolidation_llm_parallelism并行批次数、consolidation_max_tokens/consolidation_max_completion_tokens预算上限、consolidation_dedup_threshold语义去重阈值见 config.py L4642-L4664。调大并行度可以进一步压榨多路 LLM 并发能力但需注意与数据库连接池及 provider 限流的平衡。配置参数速查表基准运行时可用的环境变量来自 README 与 config.py环境变量作用默认值/说明NUM_MEMORIES创建多少条测试记忆100见 run-consolidation.shHINDSIGHT_API_CONSOLIDATION_LLM_MODEL整合专用模型未设置时回退到HINDSIGHT_API_LLM_MODEL默认openai/gpt-oss-120bHINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER整合专用 provider未设置时回退到HINDSIGHT_API_LLM_PROVIDER默认groqHINDSIGHT_API_DATABASE_URL数据库连接串默认pg0由 Hindsight API 解析HINDSIGHT_LOG_LEVEL日志级别INFO可看到整合详细日志HINDSIGHT_API_ENABLE_OBSERVATIONS整合总开关由基准脚本强制设为true除基准自身的NUM_MEMORIES外其余变量与 Hindsight API 运行期配置同源——也就是说你可以在基准里用一套模型/预算参数在生产环境用另一套两者互不影响。整合引擎运行时的逐项配置批次大小、并行度、token 预算、去重阈值、scope 上限等均由HINDSIGHT_API_*前缀的环境变量或按 bank 的层级配置解析详见 config.py L4633-L4672 的解析逻辑。结果保存与后续分析基准结束后结果以 JSON 形式写入benchmarks/results/目录文件名带时间戳如consolidation_benchmark_20260101_120000.json内容包含运行时间戳、配置快照num_memories、bank_id、llm_provider、llm_model、完整指标total_time、memories_processed、ops_per_sec、整合结果明细以及整合前后的 bank 统计。关于结果分析文档仓库基准目录预期提供ANALYSIS.md瓶颈分析与RESULTS.md性能结果与建议两类报告文件连同benchmarks/results/原始 JSON 数据共同构成运行 → 归档 → 分析的闭环。建议在每次调整模型或配置后保留 JSON 快照用于跨版本、跨配置的对比回归。结语把基准纳入整合优化的日常流程Hindsight 的整合基准把一条依赖 LLM 与向量检索的重流水线变成了可量化、可对比、可回归的工程对象。推荐的日常用法是先以默认配置建立本环境基线再依次应用已实施清单验证收益最后针对 LLM 占比居高不下的现状用更快的模型、提示词缓存和更精简的提示词三个方向做定向优化。每次改动后重跑./scripts/benchmarks/run-consolidation.sh用吞吐量op/sec与计时分解两张报表说话——这就是这个基准存在的全部意义。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考