ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Hindsight 0.8.3 版本解读:干跑事实抽取、文档 OCR 与更精准的检索

Hindsight 0.8.3 版本解读:干跑事实抽取、文档 OCR 与更精准的检索 Hindsight 0.8.3 版本解读干跑事实抽取、文档 OCR 与更精准的检索【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读Hindsight 0.8.3 是 Agent MemoryAgent 记忆领域的一次功能性版本迭代。本版本围绕让记忆系统更可控、输入更广泛、检索更精准、运维更透明四条主线展开新增 dry-run 事实抽取端点让你在真正写入记忆库之前先预览将要产生的 facts引入基于 MarkItDown 的可选 OCR 能力把 PDF、图片等富文档格式纳入记忆输入同时改进了中文时间表达解析、标签精确匹配与时效性打分并修复了一个影响大文档摄入的数据完整性缺陷——任何正在摄入大文档的用户都应当升级。阅读本文后你将掌握 0.8.3 的每个新能力、它们的配置方式、背后的源码实现以及升级的必要性判断依据。一、Dry-Run 事实抽取先预览再写入1.1 这个功能解决什么问题在 0.8.3 之前想要验证一段内容会抽取成什么样的事实facts只能真实调用 retain 接口把内容写进银行bank再通过查询来检查结果写错了还得清理容易留下一次性垃圾记忆。0.8.3 新增的 dry-run 抽取端点让你在不持久化任何数据的前提下预先看到一段内容会产生的全部 facts。根据源码注释memory_engine.py这个端点的定位是Run fact extraction ONLY — no entity resolution, links, embeddings, or persistence.即它只运行事实抽取这一环节不执行实体消解、不建链接、不生成 embedding、不做任何持久化。返回值是候选 factslist_memory_units条目形状的子集加上 LLM token 用量因此你可以用它在不改动银行的前提下对某个 mission 的抽取输出进行差异比对。1.2 端点的请求参数与行为HTTP 端点为POST /banks/{bank_id}/memories/dry-run-extract对应实现见 http.py 与 memory_engine.py参数类型说明contentstring待抽取的内容主体必填contextstring上下文信息默认空字符串event_datedatetime事件发生时间可选strategystring抽取策略名缺省时使用银行配置的retain_default_strategyoverridesdict按调用覆盖任意影响 prompt 的配置项例如测试一个候选 retain missionagent_namestring已弃用参数用于向后兼容官方建议在context中描述说话者几个值得注意的实现细节策略解析与真实 retain 完全一致。dry-run 通过_resolve_retain_config解析配置命名策略或银行默认策略会以与真实 retain 相同的方式落地而不是跳过策略直接抽取memory_engine.py。空输入前置拒绝。空白或纯空白内容在请求校验阶段就被拒绝返回 422不会进入抽取流程。操作预检precheck同样生效。dry-run 复用了真实 retain 的预检逻辑所以预览结果与真实调用的行为保持一致。测试用例test_dry_run_honors_operation_precheck专门验证了这一点。overrides白名单校验。只允许覆盖_EXTRACTION_OVERRIDE_FIELDS中列出的字段传入未知覆盖项会抛出ValueError并列出允许的字段memory_engine.py。chunks 抽取模式不调用 LLM。若银行配置的retain_extraction_mode为chunks每个 chunk 原样存为一条记忆真实 retain 中根本不经过 LLMdry-run 也会走同一分支直接返回 chunk 文本而不是错误地调用模型展示不存在的抽取结果memory_engine.py。每个 fact 标注来源 chunk 索引。_chunk_index_per_fact根据每个 chunk 的 fact 计数推导映射关系抽取出错的 chunk 不会导致索引错位memory_engine.py。1.3 返回值形状返回的DryRunExtractionResult包含facts抽取出的候选事实列表每项包含text、fact_type、occurred_start、occurred_end、entities、chunk_indexchunks本次抽取所基于的文本分块含text与fact_countusageLLM token 用量。从 response_models.py 的定义看facts 形状与list_memory_units条目的子集一致方便你直接对比抽取输出 vs 已存储记忆。1.4 安全开关与测试覆盖dry-run 端点默认开启但提供了关闭开关环境变量HINDSIGHT_API_ENABLE_DRY_RUN_EXTRACT默认值为true见 config.py设为false可移除该端点例如出于控制 LLM 成本的考虑。关闭后端点返回 404对应测试test_dry_run_disabled_returns_404。该功能的测试覆盖非常完整test_extract_dry_run_http.pytest_dry_run_extracts_without_persisting验证抽取不持久化test_dry_run_does_not_create_missing_bank验证不会因为 dry-run 调用而隐式创建不存在的银行test_dry_run_rejects_empty_content空白内容被 422 拒绝test_dry_run_honors_free_form_entities_override、test_dry_run_applies_the_banks_default_strategy、test_dry_run_honors_a_named_strategy验证 overrides 与策略解析行为test_dry_run_in_chunks_mode_returns_the_chunks_not_llm_facts验证 chunks 模式不走 LLM。二、文档 OCR基于 MarkItDown 的文件解析2.1 能力概述0.8.3 为摄入ingestion环节增加了可选的 MarkItDown 文件解析器能够在摄入过程中把文档中的文本提取出来。启用后之前必须以纯文本形式到达的内容现在可以从更丰富的文档格式PDF、Office 文档、图片等中抽取文本从而扩大可以被 retain 进记忆的输入范围。2.2 解析器链配置解析器通过file_parser配置项形成有序回退链ordered fallback chain。默认回退链是markitdown见 config.py也可以配置为列表形式例如[iris, markitdown]表示先尝试 iris 解析器失败时回退到 markitdownhttp.py。2.3 MarkItDown OCR 的配置参数MarkItDown 解析器支持可选的图片 OCR 能力相关环境变量如下定义见 config.py环境变量默认值说明HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_ENABLEDfalse是否启用图片 OCR默认关闭HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_API_KEY无OpenAI 兼容 OCR 服务的 API KeyHINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_BASE_URL无OpenAI 兼容 OCR 服务的 Base URLHINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_MODEL无OCR 使用的模型名HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_PROMPT见默认 prompt自定义 OCR 转写提示词HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_DEFAULT_HEADERSnull额外请求头JSON默认的 OCR prompt 定位为精确的 OCR 转写引擎DEFAULT_FILE_PARSER_MARKITDOWN_OCR_PROMPT见 config.py。当 OCR 未启用时遇到图片文件会抛出明确错误Image OCR is not enabled for the markitdown parser.markitdown.py。2.4 源码实现要点从 markitdown.py 可以看到几个关键设计延迟导入以控制启动成本。markitdown包会连带引入 bs4 → lxml在__init__中只做find_spec检查而不真正导入因为导入它会让每次服务器启动多花约 400ms见 markitdown.py。真正的实例在首次使用时才构建。同步库放入 executor 执行。markitdown 是同步库convert方法通过 executor 异步执行避免阻塞事件循环markitdown.py。显式 UTF-8 流提示。对文本文件显式传入 charset 提示避免 markitdown 基于采样的探测可能导致崩溃逻辑二进制或非 UTF-8 文本则返回None让 markitdown 走默认路径markitdown.py。配置在初始化时校验。API Key / Base URL / Model 是字符串级校验放在__init__而非首次使用时避免延迟暴露配置错误markitdown.py。三、更精准的检索时间查询、精确标签与时效性打分0.8.3 对记忆的查找与排序做了三项改进3.1 更好的中文时间表达解析中文时间表达被解析得更准确使带时间范围time-scoped的搜索能返回正确的时间窗口。这意味着类似上个月三天前这类中文时间表达在检索查询中可以被正确换算相关测试与时间窗口处理逻辑可参考test_recall_time_range.py、test_recall_temporal_window.py等测试文件对时间窗口解析的覆盖。3.2 精确标签匹配tags_matchexacttags_matchexact现在被正式地暴露到 UI、文档和客户端库中允许你要求精确的标签集合匹配而非宽松匹配。在 API 层tags_match参数支持anyOR默认、allAND与exact三种取值http.py。特别的在 observation 场景下tagsscope tags_matchexact组合可以把观察范围精确过滤到指定 scopehttp.py。测试覆盖见test_recall_time_range.py等召回相关测试套件。3.3 更智能的时效性打分时效性recency打分现在在主时间戳缺失时会回退到有效时间——例如事件被提及的时间或事件结束时间——从而对时间相关结果产生更合理的排序。这使得内容本身没有明确时间戳、但与被查询时间段存在隐含关联的记忆也能获得合理的时效权重。四、运维可见性异步队列仪表与多租户并行迁移4.1 异步操作与积压仪表Gauges自托管self-managed部署获得了对后台工作的更多洞察新增指标以gauge 形式暴露异步操作队列深度与合并积压consolidation backlog异步 worker 完成路径被加入 operation 指标埋点这使得运维人员可以直观判断记忆处理是否跟得上memory processing keeping up而不是在黑盒中等待。相关实现分布在worker、engine/consolidation与metrics.py中配合 monitoring/grafana 下的监控面板 JSON 使用。4.2 多租户并行 schema 迁移Schema 迁移现在跨租户并行执行在多租户部署中显著缩短迁移时间。测试覆盖见test_migrations_parallel_schemas.py该测试验证并行 schema 迁移的行为与隔离性。4.3 Gemini service tier 配置新增配置项用于选择 Gemini 服务层级service tier用于调节请求处理策略。对应环境变量为HINDSIGHT_API_LLM_GEMINI_SERVICE_TIERconfig.py取值None默认或flex50% 折扣的 best-effort 层级见 config.py。该配置仅在 LLM provider 为gemini时生效config.py并会经过parse_gemini_service_tier校验。类似的 service tier 配置还有 Groq 的on_demand/flex/auto、OpenAI 的flex、Bedrock 的flex/priority/reservedconfig.py。4.4 更精简的响应体API 响应现在省略 wire-safe 的 null 字段减小响应体体积降低传输开销。五、Retain 数据完整性修复为什么你必须升级5.1 修复内容这是 0.8.3 最值得升级的理由对 retain 分块逻辑的修复确保超大文档oversized documents在摄入期间被拆分成多个子批次sub-batches时不再丢失内容。从实现看超大文档会被拆分成多个顺序执行的子批次逐批处理orchestrator.py其中涉及_split_contents_into_sub_batches、_iter_raw_sub_batches等拆分逻辑第一个子批次提交其 chunksorchestrator.py。此前该路径存在内容丢失风险如 issue #3989 记录的那样超大 append 只报告了新尾部而丢失了先前内容0.8.3 修复后跨子批次的完整文档体得以保留。5.2 测试验证test_oversized_append_truncates_document.py 中的用例直接验证了修复效果test_a_split_append_stores_the_same_body_as_an_unsplit_one拆分 append 与未拆分 append 存储的正文一致test_split_append_keeps_the_whole_document拆分 append 保留整个文档。结论如果你正在用 Hindsight retain 大文档请立即升级到 0.8.3确保没有内容被丢弃。六、其他值得关注的修复除上述主功能外0.8.3 还包含以下修复LiteLLM 超时挂起的 LiteLLM 调用不再可能无限阻塞——completions 现在被硬性超时上限约束对应测试test_litellm_timeout.py。银行列表 overlays列出银行时bank-config 的 disposition 与 mission overlays 现在被一致地应用对应测试test_list_banks_config_overlay.py。合并健壮性consolidation 处理 LLM 返回的单值source_fact_ids时不再失败对应测试test_consolidation_*系列。配额重试延迟provider 配额重置quota-reset的重试被延迟以避免重试风暴对应测试test_provider_quota_reset_defer.py、test_codex_quota_reset_defer.py。输出净化非结构化输出中的畸形 reasoning 标签与未闭合代码块会被剥离对应测试test_strip_reasoning_tags.py。七、升级建议小结场景0.8.3 带来的价值想先验证抽取结果再写入使用POST /banks/{bank_id}/memories/dry-run-extract端点支持 overrides 与策略解析零持久化摄入 PDF/图片等富文档启用file_parser_markitdown默认链 可选 OCR 配置中文时间范围检索不准确升级后获得更准确的中文时间表达解析需要精确标签集合匹配使用tags_matchexact自托管多租户、关心后台处理速度使用新增的异步队列/合并积压 gauges享受并行 schema 迁移摄入超大文档务必升级——修复了子批次拆分导致的内容丢失问题本文所引用的全部实现细节、配置项与环境变量均可在仓库对应源码文件中验证。升级前建议先阅读 hindsight-docs 下的部署与配置文档确认自托管环境中的配置项兼容性。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表