Hindsight 性能基准测试完全指南：从 perf-test 系统套件到独立负载测试

Hindsight 性能基准测试完全指南从 perf-test 系统套件到独立负载测试【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南基于 Hindsight 仓库的 性能基准测试文档 撰写系统讲解 Hindsight Agent 记忆系统如何利用mock LLM pg0构建确定性、与 LLM 无关的性能基线。你将掌握perf-test系统性能测试的六大套件retain、recall、graph-maintenance、graph-maintenance-contention、stats 及扩展套件、五档规模配置、huge生产模拟加载以及retain_perf.py/recall_perf.py两个独立基准脚本的完整用法与底层原理并理解基准是如何抓到真实生产问题#1919、#2529的。一、什么是 perf-test确定性性能基线的设计哲学Hindsight 的 Agent 记忆流水线由 retain写入、recall检索、consolidation整合、graph maintenance图谱维护等核心环节组成而性能测量最头疼的问题是真实 LLM 调用的延迟与抖动会淹没数据库与引擎本身的性能信号。为此perf-test系统性能测试采用了两大设计原则Mock LLM用确定性回调替换真实 LLM 的事实抽取、嵌入生成调用使每次运行的行为可复现pg0嵌入式 Postgres无需外部数据库依赖即可本地运行整套测试。二者结合产出确定性的、与 LLM 无关的性能基线deterministic, LLM-independent performance baselines这是所有套件共用的基础设施。从源码看mock 回调通过_attach_mock_callback挂到引擎的_retain_llm_config与_llm_config上system_perf.py而合成数据则复用recall_perf.py中沉淀的FACT_TEMPLATES约 300 条事实模板与_fill_template填充逻辑。perf-test本身是一个薄编排器thin orchestrator每个套件完全独立——使用自己的引擎、自己的 bank、自己的清理逻辑——通过SUITES注册表system_perf.py统一调度最终收集为结构化 JSON 结果。二、快速上手命令行用法perf-test的入口定义在 hindsight-dev/pyproject.tomlperf-test benchmarks.perf.system_perf:main因此可以通过uv直接运行。文档给出四种基础用法uv run perf-test # 运行全部套件small 规模 uv run perf-test --suite retain # 只运行单个套件 uv run perf-test --scale medium # 使用更大规模 uv run perf-test --output results.json # 将结果保存为 JSON对应的 CLI 参数源码 system_perf.py如下参数取值默认说明--scaletiny/small/medium/large/hugesmall测试规模直接决定数据量与运行时长--suiteretain/recall/recall-with-observations/recall-temporal/consolidation/graph-maintenance/graph-maintenance-contention/stats全部可重复传入以运行多个套件--output文件路径无将完整结果序列化为 JSON 写入文件规模与耗时参考源码 docstring 注释tiny约 10 秒适合 CI 冒烟、small约 30 秒默认、medium约 2 分钟、large约 10 分钟。任何套件失败都会使进程以退出码 1 结束raise SystemExit(1)便于 CI 直接判定。除了直接uv run仓库还提供了包装脚本 scripts/benchmarks/run-perf-test.sh它会自动cd到hindsight-dev后执行exec uv run perf-test $所有参数原样透传适合在仓库根目录下使用。三、六大核心测试套件详解文档用一张表格概括了各套件的测量目标这里结合源码逐一展开其实现细节套件测量内容retain完整 retain 流水线mock LLM事实抽取回调、嵌入生成、DB 写入、实体链接recall预填充 bank 的 recall4 路并行检索语义、BM25、图谱、时间RRF 融合百分位延迟graph-maintenance一批删除后隔离运行run_graph_maintenance_jobrelink 遍历按探针语义 ANN vs 时间拆分墙钟耗时并统计实体/共现剪除数量#1919graph-maintenance-contention在并发 retain 负载下的维护共现扫描驱动prune_stale_cooccurrences对抗 retain 形态的排序共现 upsert统计死锁静默丢弃的维护趟数#2529stats/stats端点get_bank_stats未缓存聚合延迟节点/链接计数 实体 rollup join对比缓存延迟及缓存加速比。运行在结果缓存禁用TTL0状态下头条数字即真实每次轮询代价3.1 retain写入吞吐run_retain_suitesystem_perf.py用retain_batch_async同步批量写入retain_items条合成内容测量总时长与吞吐items/s。它刻意disable_observationsTrue排除整合任务干扰只聚焦嵌入 DB 写入这条最核心路径。写完后立即delete_bank清理确保每个套件互不污染。3.2 recall检索延迟与阶段拆解run_recall_suitesystem_perf.py先通过_populate_bank用真实 retain 流水线预填充银行随后以Budget.HIGH、max_tokens4096调用recall_async。两个细节值得注意RRF 重排隔离套件把engine._cross_encoder_reranker替换为_RRFReranker用纯 RRF 融合替代 cross-encoder把 DB 检索性能从 CPU 密集的重排成本中剥离出来阶段时间拆解开启enable_traceTrue从结果 trace 的phase_metrics中按phase_name聚合出每个检索阶段语义/BM25/图谱/时间等的 p50/p95 分布最终汇总表会按均值降序展示 Top 5 阶段——哪条检索臂是瓶颈一目了然。查询集合RECALL_QUERIES覆盖了不同检索策略数据库迁移、性能回退、安全事件复盘、Kubernetes 监控等 8 条查询并在并发批次中轮转使用。3.3 recall 扩展套件带观测与时间臂压测perf-test还内置两个文档表格之外的强化套件专门针对特定退化模式recall-with-observationssystem_perf.py在事实基础上额外插入合成观测每观测携带长尾分布的源事实数均值由recall_obs_sources_per_observation控制把观测图中的数组长度成本路径压出来recall-temporalsystem_perf.py所有记忆被钉在同一日期RECALL_TEMPORAL_EVENT_DATE 2025-01-15查询经_augment_query_with_temporal附加 1 天时间窗口强制触发时间检索臂进入密集时间区——这正是 PR #1958 退化、#1983 限界的场景。3.4 graph-maintenancerelink 探针拆解#1919该套件复现了 #1919 报告的问题语义 ANN relink 遍历在约 1k 单位的银行上每批耗时 10–20 秒。run_graph_maintenance_suitesystem_perf.py的流程是用真实 retain 流水线填充银行保证有真实嵌入与链接按GRAPH_MAINTENANCE_DELETE_PCT 0.1均匀删除 10% 的 experience/world 类型单位并先捕获后删除enqueue_relink_victimsenqueue_entity_prune_candidates以镜像delete_memory_unit的顺序隔离运行run_graph_maintenance_job通过包装探测函数compute_semantic_links_ann与fetch_temporal_neighbors累计各自墙钟与调用次数。因为维护作业在自己的连接与事务深处运行唯一的无扰探测缝就是包装它调用的函数system_perf.py。最终输出 relink 探针拆解表语义 ANN、时间探针、其它claim/count/insert/sweep分别占总作业时长的百分比——让 #1919 的瓶颈直接可见。3.5 graph-maintenance-contention死锁逃逸率门控#2529这是全套件中最有代表性的一个值得单独展开。背景graph-maintenance套件隔离运行维护作业——没有并发写入者——因此 Pass 2/3 的共现扫描永远不可能与 retain upsert 重叠也就永远不会死锁。这正是持续性能测试从未抓到 #2529 的原因DeadlockDetectedError是prune_stale_cooccurrences的无序 DELETE 扫描与 retain 的排序(entity_id_1, entity_id_2)共现 upsertentity_resolver._flush_pending之间的争用现象而没有任何套件同时驱动双方。生产环境中败方死锁会静默丢弃一次维护趟——只表现为缓慢的图谱膨胀永远不会变成延迟数字。该套件system_perf.py的补位逻辑播种用_seed_contention_fixture生成graph_contention_entities个实体 graph_contention_pairs条陈旧共现对每个实体有专属 keeper 单位使prune_orphan_entities放过它们但没有任何单位同时引用两个实体构成精确的陈旧共现场景对打upsert_workers个任务按排序锁序持续 upsert 这些对与 retain 的entity_resolver._flush_pending同 SQL、同锁序sweep_workers个任务反复调用run_graph_maintenance_job其 Pass 2/3 以无序 join-scan 顺序 DELETE 同样的行计数通过包装prune_stale_cooccurrences统计原始死锁数修复前后都会触发证明争用真实存在并在_sweep_worker中统计从run_graph_maintenance_job逃逸、丢失趟数的次数。门控指标是死锁逃逸率sweep_deadlock_escape_rate 被丢弃的维护趟数 / 观察到的死锁数无修复每次死锁都逃逸 → 逃逸率 ≈ 100% → 套件失败有修复扫描包上带抖动的retry_with_backoff且重试预算更大扫描重试 → 逃逸率 ≈ 0% → 套件通过。在该套件刻意苛刻的多扫描合成负载下极小尾部仍可能漏过现实中的单银行单扫描负载则不会丢弃任何趟。阈值常量GRAPH_CONTENTION_ESCAPE_RATE_THRESHOLD 0.5system_perf.py干净地分隔两种状态回归到无修复时逃逸率会直接跳回 ≈1.0。此外还有一道空洞运行护栏ran_contention counters.upserts 0 and counters.attempted 0若工作负载根本没跑起来种子/worker 故障则判定结果无效而不是假装通过——同时刻意不以死锁数 0作为通过条件因为一个更彻底的源码级修复在 prune 中排序FOR UPDATE锁序会从源头消除死锁0 死锁同样是健康通过。文档记录的--scale small实测结果main ≈ 100% 逃逸每次死锁丢一趟→ FAIL修复后 0% 逃逸死锁仍发生但无一逃逸→ PASS。3.6 stats/stats 端点缓存代价量化/stats被控制平面与 CLI 高频轮询远多于 retain/recall因此其每次缓存未命中的聚合成本非常关键。run_stats_suitesystem_perf.py用BankStatsCache(ttl_seconds0, max_entries0)禁用进程内结果缓存等价于HINDSIGHT_API_BANK_STATS_CACHE_TTL_SECONDS0的配置测得真实未缓存聚合延迟——即每次轮询实际付出的代价随后换成ttl_seconds300预热缓存测得缓存命中路径稳态轮询客户端所见。输出包含未缓存/缓存两套百分位延迟以及cache_speedup cold_p50 / warm_p50加速比。需要说明的是聚合成本随单位/实体密度增长节点计数按fact_type、链接计数按link_type分组外加一个unit_entities → memory_units的 rollup join 来重建实体链接总数实体边不落库每实体按LEAST(n-1, 10)推导。3.7 consolidation整合吞吐扩展perf-test还包含consolidation套件system_perf.py开启观测HINDSIGHT_API_ENABLE_OBSERVATIONStrue并clear_config_cache后先用批量 retain 灌库此时整合任务只在队列中排队再显式调用run_consolidation_job输出 memories/s 吞吐及 created/updated/merged/skipped 四类动作计数。其 mock 回调会解析 prompt 中的事实 ID 构造真实的 create 动作保证整合路径被真实驱动。四、规模配置从 tiny 冒烟到 huge 生产模拟SCALES字典system_perf.py统一控制所有套件的负载形状文档中的核心表格如下ScaleRetain 条数Recall 银行大小Recall 迭代Recall 并发tiny202051small200200204medium1,0001,000508large5,0005,00010016huge—仅stats———源码层面还揭示了表格之外的丰富细节large规模的设计意图graph_maintenance_bank_size为 15,000 单位恰好越过 seqscan→HNSW 交叉点约 1 万单位使语义 ANN 探针真正走每银行局部 HNSW 索引路径Index Scan on idx_mu_emb_*而medium1k停留在精确扫描区间——两档规模覆盖了两种查询规划器路径观察源均值陷阱recall_obs_sources_per_observation在large下被设为 2 而非旧的常数 113注释给出了完整教训——把每个观测钉在高均值上会让少量种子触及几乎整个实体图使观测图臂永远停留在真实银行不可能出现的状态从而掩盖 #3510真实银行均值 1.7、p95 4呈长尾分布争用规模large下 200 实体 × 4,000 共现对保证扫描 DELETE 与排序 upsert 同时锁大量行在更高 worker 扇出下稳定复现反向锁序死锁。huge 规模stats 套件的生产模拟huge是仅面向stats套件的生产模拟规模system_perf.py批量加载约50 万单位与约1780 万条物理memory_links行语义 9,460,147 时间 8,344,084 caused_by 30,015外加一组unit_entities其LEAST(n-1, 10)rollup 恰好重建约11.09 万条派生实体链接实体边不落库。其他套件在该规模下回退到large尺寸——否则不可能在合理时间内 retain 50 万条所以请用uv run perf-test --suite stats --scale huge由于真实 retain 流水线在此规模不可行_bulk_populate_stats_banksystem_perf.py直接用 PostgreSQLCOPY批量灌入行形状与真实流水线产物完全一致。其中蕴含多个工程细节COPY 前丢弃索引、COPY 后重建先DROP INDEX五个memory_links索引并DISABLE TRIGGER ALL跳过约 3500 万条边端点的 FK 校验完成后原样重建包括/stats链接 GROUP BY 依赖的idx_memory_links_bank_id_link_type与唯一索引——保证测量时的规划器看到与生产一致的索引集合绕过语句超时连接池默认携带服务端statement_timeout引擎的 runaway 查询安全网默认 600 秒多行级唯一索引重建会合法地超过它因此加载期间SET statement_timeout 0、结束后恢复注释记录这正是首个 18M 行运行死亡的直接原因VACUUM (ANALYZE)而非仅ANALYZE刷新规划器统计并设置可见性映射——没有后者link_type 计数无法走 index-only scan每个元组都要堆可见性检查一次全新 COPY 会测出生产autovacuum 持续维护 vm永远不会付出的全堆扫描在 1800 万行银行上这相当于约 1.6 秒 seq scan 与约 1.0 秒 index-only scan 的差距。文档同时提醒批量加载需要几分钟FK 触发器与非必要索引会在 COPY 期间被移除、之后恢复。五、CI 集成与结果归档.github/workflows/perf-test.yml 定义了性能测试的持续运行触发方式每日 06:00 UTC 定时cron: 0 6 * * * 手动workflow_dispatch规模可配置workflow input 提供tiny/small/medium/large选择默认large并可指定单个套件结果归档结果写入hindsight-dev/perf-results.json并作为 artifact 上传保留 90 天模型预热job 会先预下载嵌入模型BAAI/bge-small-en-v1.5经 HuggingFace 缓存避免网络抖动污染测量看板发布CI 还会把结果perf JSON commit 元数据发布到持续性能监控看板的 gh-pages 分支前端按运行逐次渲染趋势图表。同工作流还并行运行 LoComo会话记忆质量与 obs观测去重质量两个真实 LLM 基准 job与 perf-test 形成质量 性能双轨持续监控。六、独立基准脚本retain_perf.py 与 recall_perf.py除perf-test编排器外perf/目录还提供两个可独立运行的基准脚本。6.1 retain_perf.pyretain 操作基准retain_perf.py 支持两种模式源码 docstringIn-memory--in-memory直接调用retain_batch_async单文件或目录绕过 HTTP测引擎内部耗时与 token 用量Async完整异步工作流——submit_async_retain提交操作WorkerPoller消费子批次任务还原真实异步链路同时内置stress_test_deadlocks死锁压力测试用极小实体池5 个人名 2 个地名让所有并发 retain 命中同一批entities/unit_entities/memory_links行最大化行锁序冲突复现并发死锁。uv run python hindsight-dev/benchmarks/perf/retain_perf.py \ --document file_path --in-memory--document支持文件或目录目录自动批量。环境变量控制引擎配置HINDSIGHT_API_DATABASE_URL默认pg0、HINDSIGHT_API_LLM_PROVIDER、HINDSIGHT_API_LLM_MODEL等。6.2 recall_perf.py大规模 recall 负载测试recall_perf.py 面向大银行 recall 负载首先生成合成银行——实体按Zipf 分布生成头部约 145 个跨人/技术/地点的常驻枢纽实体尾部随语料规模增长事实从约 300 条模板中抽取然后以分步拆解的方式基准 recall 延迟。支持进程内默认mock LLM 直连MemoryEngine与 HTTP--api-url打远程 Hindsight API两种执行方式。文档给出的三段式用法# 生成银行 uv run python hindsight-dev/benchmarks/perf/recall_perf.py generate \ --bank-id my-bank --scale small # 基准测试 uv run python hindsight-dev/benchmarks/perf/recall_perf.py benchmark \ --bank-id my-bank --query database migration --iterations 20 # 清理 uv run python hindsight-dev/benchmarks/perf/recall_perf.py clean \ --bank-id my-bank该脚本的独立规模档位为tiny1、mini50、small2K、medium10K、large33K、very-large100K。其generate还支持--event-date把所有记忆钉到同一日期用于复现 PR #1958 的慢时间检索benchmark支持--temporal-date强制时间臂、--api-url远程压测。七、结果解读结构化 JSON 与汇总报告所有套件结果统一落入PerfTestResults含时间戳、规模、git SHA 与各套件结果。--output results.json会写出完整 JSON其核心指标包括retainthroughput_items_per_sec、total_duration_seconds、total_itemsrecalllatencyp50/p95/p99/mean/min/max/count、throughput_queries_per_sec、phase_timings每检索阶段百分位、sources_per_observation观测套件附带防止 fixture 改动被误读为延迟回归graph-maintenancethroughput_units_per_sec、ms_per_victim、semantic_ann_seconds/calls、temporal_seconds/calls、剪除计数graph-maintenance-contentionsweep_deadlocks_observed、sweep_passes_dropped、sweep_deadlock_escape_rate门控指标sweep_passes_dropped从 0 降到 0 即修复的可测效果、sweep_latencystatscold_latency/warm_latency/cold_throughput_per_sec/cache_speedup/ 总单位与物理/派生链接数。百分位统计由PercentileStats.from_samples统一计算排序后按索引取 p50/p95/p99。终端输出则包含每个套件的 rich 表格与一张跨套件的统一汇总表含每套件 Top 5 阶段拆解任何套件失败会以红色 FAIL 标出并使进程非零退出。八、实战要点与扩展阅读何时用哪个工具需要覆盖全流水线的可复现基线 →uv run perf-test默认 small只需快速验证单点 →--suite retain/--suite recall验证死锁修复 →--suite graph-maintenance-contention这是唯一能证明 #2529 修复有效的门控评估 /stats 在高密度银行下的真实轮询代价 →--suite stats --scale huge环境要求需安装uvperf-test使用 mock LLM pg0无需任何外部 LLM/数据库密钥这是它可被 CI 每日运行的前提扩展阅读benchmarks 总览 介绍了 LoComo、LongMemEval、consolidation、multimodal retain 等质量型基准及 可视化器perf/目录下三个脚本system_perf.py、recall_perf.py、retain_perf.py的 docstring 与注释记录了每个套件背后对应的真实 issue#1919、#2529、#1958、#1983、#3085、#3510是理解 Hindsight 性能演进脉络的第一手材料。综上这套基准体系的价值不只在于测出数字graph-maintenance-contention用对打式负载把潜伏数月、只在争用下出现的死锁现象变成可复现、可门控的 CI 检查huge模拟则让 50 万单位/1800 万链接级别的生产形态成本在合并前就暴露——这正是 Agent 记忆系统性能工程应有的严谨度。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考