Hindsight All-in-One 集成测试指南：从单测到全链路工作流验证

Hindsight All-in-One 集成测试指南从单测到全链路工作流验证【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文基于 Hindsight 仓库中 hindsight-all/tests/README.md 编写围绕hindsight-all全功能包的集成测试展开。hindsight-all是 HindsightAgent Memory That Learns的一体化分发包将 API 服务、客户端与嵌入式 PostgreSQL 打包在一起让开发者能以最小成本在本地跑通记忆库创建 → 记忆存储retain→ 记忆召回recall→ 上下文回答生成reflect的完整链路。读完本文你将掌握该测试套件的运行前提、逐条命令、并行执行限制背后的原理以及如何通过源码级证据定位测试中的常见故障。一、测试套件概览tests 目录里有什么hindsight-all/tests/目录存放针对hindsight-all一体化包的集成测试共 6 个测试文件加 1 个说明文件文件测试类型关注点test_server_integration.py集成完整工作流建库、retain、recall、reflect与服务器生命周期管理test_embedded.py集成HindsightEmbedded懒启动、上下文管理器、方法代理、多 bank、profile 隔离、崩溃恢复等test_embedded_config.py回归配置转发规则#3253回归覆盖校验未显式传入的配置不得下发占位符test_embedded_namespaces.py回归API 命名空间banks、mental_models、directives等每次调用前确保 daemon 已启动test_cleanup_timeout.py单元_cleanup锁超时行为#952修复验证锁被占用时清理不会无限挂起test_server_integration.py 内的其他用例集成手动启停服务器、嵌套上下文管理器、list_banks字段映射本文以 README 重点讲解的 test_server_integration.py 为主线其余文件作为佐证一并展开。二、核心测试test_server_integration.py 的三个场景1.test_server_context_manager_basic_workflow主集成测试这是 README 定义的主集成测试完整覆盖七步流程通过上下文管理器启动 Hindsight 服务器创建一个带背景信息的记忆库memory bank存储多条记忆含单条与批量两种操作基于不同查询编程偏好、ML 主题召回记忆多次在不同上下文下执行 reflect生成上下文相关回答上下文退出时自动停止服务器。源码中的对应实现test_server_integration.py展示了每一步的具体调用# Step 1: 创建带 mission 的记忆库 bank_response client.create_bank( bank_idbank_id, nameTest Assistant, missionAn AI assistant that helps with programming and data analysis tasks. ) assert bank_response.bank_id bank_id # Step 2: 存储 3 条单条记忆 1 次批量记忆 retain_response1 client.retain( bank_idbank_id, contentUser prefers Python over JavaScript for data analysis projects., contextUser conversation about programming languages ) assert retain_response1.success is True batch_response client.retain_batch( bank_idbank_id, items[ {content: User is interested in neural networks and deep learning.}, {content: User asked about best practices for training models.}, ] ) assert batch_response.items_count 2 # Step 3/4: 基于不同查询召回记忆 recall_results client.recall( bank_idbank_id, queryWhat programming languages and tools does the user prefer?, max_tokens4096 ) assert isinstance(recall_results.results, list) assert len(recall_results.results) 0 # Step 5/6: 两次 reflect第二次携带额外 context 与更低预算 reflect_response client.reflect( bank_idbank_id, queryWhat tools and libraries should I recommend for this users data analysis work?, budgetmid ) assert len(reflect_response.text) 0 reflect_with_context client.reflect( bank_idbank_id, queryShould I use TensorFlow or PyTorch?, budgetlow, contextThe user is starting a new deep learning project )值得注意的验证细节reflect 的断言不仅检查回答非空还校验回答文本确实命中了期望的关键词python、scikit-learn、matplotlib、seaborn、data这意味着该测试同时充当了端到端的记忆质量门禁——只有 recall 真正把相关记忆捞回来reflect 才能生成包含这些工具名的推荐。2.test_server_manual_start_stop显式生命周期管理该用例验证不依赖上下文管理器时服务器可以被显式start()/stop()控制。对应 server.py 中Server.start()后台线程启动、等待端口就绪、超时抛RuntimeError与Server.stop()置should_exit True、join 线程的实现测试仅通过 client 做基本操作验证服务器处于可用状态。3.test_server_with_client_context_manager嵌套上下文管理器验证服务器与客户端各自使用上下文管理器时能够正常协同工作对应 server.py 的__enter__/__exit__以及HindsightClient的上下文支持。4. 补充用例test_list_banks用于回归验证list_banks端点返回的是bank_id字段而非历史命名agent_id并校验命名空间 APIclient.banks.list()返回结构见 test_server_integration.py。三、运行前提安装、环境变量与 .env1. 安装带测试依赖的 hindsight 包cd hindsight uv pip install -e .[test][test]额外依赖在 pyproject.toml 中定义包括pytest7.0.0与pytest-asyncio0.21.0hindsight-all本体依赖hindsight-api-slim[all]、hindsight-client、hindsight-embed三个包。2. 配置 LLM 凭据在项目根目录的.env文件中设置HINDSIGHT_API_LLM_PROVIDERgroq HINDSIGHT_API_LLM_API_KEYyour-api-key HINDSIGHT_API_LLM_MODELopenai/gpt-oss-20b然后按 README 的流程加载并映射为测试使用的环境变量cd hindsight source ../.env export HINDSIGHT_LLM_PROVIDER$HINDSIGHT_API_LLM_PROVIDER export HINDSIGHT_LLM_API_KEY$HINDSIGHT_API_LLM_API_KEY export HINDSIGHT_LLM_MODEL$HINDSIGHT_API_LLM_MODEL环境变量约定的两种命名从源码看项目里同时存在两套命名约定HINDSIGHT_API_LLM_*API 服务侧使用的命名HINDSIGHT_LLM_*测试侧 fixture 使用的命名。test_embedded.py 中的llm_configfixture 对两套命名做了兼容回退优先读取HINDSIGHT_API_LLM_PROVIDER回退到HINDSIGHT_LLM_PROVIDER最后回退到硬编码默认值groq/openai/gpt-oss-120b。provider 的特殊情况llm_configfixture 中有一个关键分支test_server_integration.pyproviders_without_api_key (vertexai, ollama) if not api_key and provider not in providers_without_api_key: raise Exception(LLM API key not configured. Set HINDSIGHT_LLM_API_KEY environment variable.)即vertexai使用 GCP 服务账号凭据HINDSIGHT_API_LLM_VERTEXAI_*与ollama本地服务无需 key是例外其余 provider 缺少 API key 会直接抛出异常而非静默跳过。四、运行测试全部、单个与输出控制1. 运行全部测试pytest tests/ -v2. 运行单个测试pytest tests/test_server_integration.py::test_server_context_manager_basic_workflow -v3. 带标准输出运行-spytest tests/ -v -s-s会展示测试中的print语句。测试实现里穿插了大量进度输出print(f\n1. Creating memory bank: {bank_id})等观察这些输出可以实时跟踪建库 → 存记忆 → 召回 → 反思各阶段进展。4. 带超时运行LLM 调用耗时不可控README 建议pytest tests/ --timeout300需要说明的是--timeout依赖pytest-timeout插件若未安装需先补充安装。五、并行执行限制为什么必须串行README 特别强调这些测试必须串行运行禁止使用pytest -npytest-xdist 并行 worker。原因在于测试使用嵌入式 PostgreSQLpg0而pg0是单例无法在多个 pytest-xdist worker 进程间共享。从 server.py 可以看到Server默认db_urlpg0并在后台线程中通过MemoryEngine(db_urlpg0, ...)创建引擎多个进程各起一份pg0实例会互相冲突。六、随机 bank_id 设计隔离、可重复与未来并行README 解释了每个测试用 UUID 生成唯一bank_id的四个收益干净的测试隔离测试之间互不污染数据可重复运行无需清理即可多次执行可调试容易识别数据由哪个测试创建面向未来若从pg0切换到真实 PostgreSQL 实例这些测试将可以并行运行。源码中的实现模式如bank_id ftest_assistant_{uuid.uuid4().hex[:8]}多个测试文件test_server_integration.py、test_embedded.py 等均遵循该约定。值得注意的是 README 与测试实现之间存在一个细微出入README 称pg0 单例不可跨 xdist 共享必须串行而 test_server_integration.py 的 docstring 写着随机 bank_id 允许安全并行执行——这两个表述并存说明随机 bank_id 解决的是数据冲突问题而 pg0 进程级单例限制仍在最终是否可并行取决于你使用的数据库形态。在当前pg0前提下README 的串行执行结论是安全的。七、测试配置与预期行为测试栈的三个支柱嵌入式 PostgreSQLpg0无需外部数据库LLM provider通过环境变量注入自动端口分配服务器自动寻找空闲端口避免端口冲突。Server构造器中self.port port or _find_free_port()server.py_find_free_port()通过socket.bind((, 0))让操作系统分配一个临时端口这正是 README 所述自动端口分配的实现来源。成功运行的预期输出序列服务器在随机可用端口启动创建带背景信息的记忆库多条记忆被存储retain 操作基于不同查询召回记忆多次返回带上下文的 reflect 回答服务器自动停止上下文管理器场景。Sample Output 流程速查README 将主测试流程归纳为 7 步建库 → 存 5 条记忆3 单条 2 批量→ 召回编程偏好 → 召回 ML 相关 → 工具推荐反思 → 带框架选择上下文的二次反思 → 上下文管理器自动停服。八、跳过机制何时自动跳过测试测试会在HINDSIGHT_LLM_API_KEY未设置时自动跳过。需要区分两个文件的行为差异test_embedded.py 使用pytest.skip(...)优雅跳过并输出提示信息同时兼容HINDSIGHT_API_LLM_API_KEY/HINDSIGHT_LLM_API_KEY两种命名test_server_integration.py 的llm_configfixture 则直接raise Exception(...)vertexai、ollama除外属于缺失即失败的严格策略。九、故障排查1. 测试挂起或超时加大超时pytest tests/ --timeout600检查 LLM API key 是否有效确认到 LLM provider 的网络连通性。从源码层面看server.py 的start()带有 30 秒启动超时轮询端口连通stop()带 10 秒 join 超时LLM 调用本身的耗时差异是挂起的主因因此 README 的建议延长 pytest 超时 校验网络与源码的超时模型一致。2. 数据库错误测试使用嵌入式 PostgreSQLpg0应自动清理若出现 database system is shutting down 错误等待几秒重试两次测试运行之间嵌入式数据库需要时间正常关闭。补充一个同类问题的源码级佐证HindsightEmbedded的_cleanup在锁获取超时5 秒时会标记_closed并放弃共享状态清理依赖 daemon 自行空闲停止见 embedded.py 与 test_cleanup_timeout.py 的#952回归测试说明项目对清理时序这类竞态问题有专门的防御与测试覆盖。3. 端口冲突测试自动寻找空闲端口冲突应很少见若出现端口绑定错误检查是否有其他进程占用高位端口。十、从测试到源码集成测试背后的实现地图这篇 README 描述的测试套件实际验证的是hindsight-all三个核心组件的协同服务器侧server.py 的Server类在后台线程运行 uvicorn FastAPIcreate_app内置MemoryEngineHindsightServer即其别名start_server为便捷工厂函数init.py客户端侧client_wrapper.py 的HindsightClient继承自动生成的Hindsight客户端并叠加banks、mental_models、directives、memories四个命名空间嵌入式侧embedded.py 的HindsightEmbedded复用hindsight-embed的 daemon 管理接口首次调用时懒启动、崩溃后自动重启、profile 级数据隔离数据位于~/.pg0/instances/hindsight-embed-{profile}/并通过__getattr__代理全部客户端方法。这套集成测试的意义在于它用最少的搭建成本pg0 环境变量 随机端口把记忆写入 → 语义召回 → LLM 生成的真实链路跑通任何一环embedding、召回排序、LLM 调用、HTTP 路由回归都会在断言中暴露。对二次开发者而言运行pytest tests/ -v是验证本地环境与代码改动的第一道闸门。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考