Hindsight 文档文件上传：从 Markitdown 标准提取到 Iris 增强提取的记忆导入实战

Hindsight 文档文件上传从 Markitdown 标准提取到 Iris 增强提取的记忆导入实战【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是面向 Agent 的会学习的记忆系统。本文基于 Hindsight Cloud 的文件上传能力系统讲解如何把 PDF、Word、PPT、Excel、图片与纯文本直接导入任意 memory bank包括标准提取Markitdown与增强提取Iris两种方式的选择、支持的文件类型、完整工作流程并结合仓库源码解析器实现、HTTP 接口、配置定义深入说明底层机制帮助你为 Agent 建立可持续检索、可回忆recall、可反思reflect的结构化文档记忆。背景为什么 Agent 需要文档记忆Agent 的记忆通常来自对话过程或显式的 retain 操作但当资料以文件形态存在——报告、会议纪要、幻灯片、数据表、截图——它们必须被转化为与既有记忆一致的结构化数据才能被 recall 与 reflect 查询命中。Hindsight 的做法是上传文件 → 提取文本 → 作为结构化记忆存入 bank之后 Agent 可以像检索普通记忆一样检索文档内容。两种提取方式StandardMarkitdown与 EnhancedIris上传文件时你需要在两种处理路径中选择标准提取Standard extraction基于微软开源的 Markitdown 库把文档转为 Markdown 文本。免费适合文本密集的文件PDF、Word、纯文本。增强提取Enhanced extraction / Iris基于 AI 的云端处理理解文档的结构与语义适合复杂排版、扫描件与图片按 token 计费。无论哪种方式提取结果都会作为结构化记忆存入 bank。两者的差异在源码层面非常清晰hindsight-api-slim/hindsight_api/engine/parsers/目录下注册了多种解析器markitdown.py、iris.py、llama_parse 等并通过 FileParserRegistry 统一管理支持按名称指定、按扩展名自动探测以及有序回退链fallback chain。工作原理上传到记忆的完整流程在 Hindsight Cloud 中打开任意 memory bank点击上传按钮并选择文件选择 Standard 或 EnhancedIris提取方式在 Document Operations 面板中通过状态指示器跟踪进度。处理完成后提取内容成为 bank 记忆的一部分Agent 可以像对待任何其他记忆一样对文档内容执行 recall 与 reflect。底层 APIfiles/retain 上传接口从源码看该能力对应POST /v1/default/banks/{bank_id}/files/retain接口见 test_file_retain.py 的端到端测试。上传使用 multipart/form-datafiles字段携带文件字节request字段携带 JSON 配置如{document_tags: [test], async: true}。该接口始终异步处理——即使不传async也走异步队列因为文件转换可能耗时较长。请求模型 FileRetainRequest 支持请求级与文件级两级参数请求级parser默认解析器或有序回退链例如markitdown或[iris, markitdown]未设置时回退到服务端默认值。文件级files_metadata[].parser单文件覆盖优先级高于请求级配置files_metadata[].strategy可覆盖该文件在 bank 配置中定义的 retain 策略document_id、context、metadata、tags、timestamp用于标注该文件生成的记忆单元。请求级operation_id可选的客户端自供 UUID用于幂等去重——以相同 operation_id 重试不会创建重复任务复用属于其他操作的 id 会返回 HTTP 409。解析器注册与自动探测FileParserRegistry 是解析器的统一入口register(parser)注册解析器实例按parser.name()索引get_parser(name, filename, content_type)显式指定名称时直接返回对应解析器未注册则抛ValueError未指定时遍历注册表调用各解析器的supports()做扩展名/MIME 探测convert_with_fallback(parsers, file_data, filename)按顺序尝试解析器链当前解析器抛出UnsupportedFileTypeError、返回空内容或任意异常都会触发回退到下一个直到链耗尽——这正是标准/增强混合方案与高可用性的底层实现list_parsers()列出全部已注册解析器。FileParser 是解析器抽象基类定义convert()与name()两个抽象方法supports()默认返回 True注释明确说明委托给远程服务的解析器如 Iris应保持 supports() 为 True而在 convert() 内抛出UnsupportedFileTypeError因为远程 API 才知道它实际支持哪些类型。支持的文档类型PDF——报告、白皮书、研究论文Word 文档.docx——会议纪要、规格说明、提案PowerPoint 演示文稿.pptx——幻灯片、培训材料Excel 电子表格.xlsx——数据表、财务报告图片.png、.jpg——截图、图表建议使用增强提取纯文本.txt、.md——日志、笔记、文档Markitdown 解析器在 supports() 中声明的扩展名集更广包括.doc/.ppt/.xls等旧版 Office 格式、.html/.htm、.csv以及带转写能力的音频.mp3/.wav。深入 Markitdown 解析器标准提取的工程细节MarkitdownParser 的实现体现了几个值得注意的工程决策懒加载与启动开销构造函数只通过importlib.util.find_spec(markitdown)检查包是否安装不实际导入。注释说明这是有意为之MemoryEngine.initialize()会在启动时急切构造解析器而导入 markitdown连带 bs4 → lxml会让每次服务启动多花约 400ms即使从未转换过文件。真正的 import 被推迟到首次convert()调用。线程池执行markitdown 是同步库convert()通过loop.run_in_executor(None, self._convert_sync, ...)放入线程池避免阻塞事件循环markitdown.py。临时文件与清理markitdown 需要文件路径而非字节流因此先把字节写入tempfile.NamedTemporaryFile保留原扩展名解析完成后在finally中删除临时文件。UTF-8 显式提示针对.json/.jsonl/.ipynb/.txt/.text/.md/.markdown/.csv/.html/.htm等文本类扩展名如果字节能干净地解码为 UTF-8则通过StreamInfo(charsetutf-8)显式传入字符集提示。原因是 markitdown 只采样首个 chunk 做字符集检测一个带长 ASCII 前缀的 UTF-8 文件会被误判为 ASCII进而导致 JSON/ipynb 转换器在解码首个多字节字符时崩溃。可选 OCRmarkitdown 支持通过 OpenAI 兼容的 vision 端点做图片 OCR。_validate_ocr_config()在启动期而非首次转换时校验三项配置模型、API Key、Base URL任何缺失都会让服务拒绝启动避免启动正常、上传图片才失败的陷阱。启用 OCR 时用 OpenAI SDK 构造llm_client、llm_model、llm_prompt传给MarkItDown未启用时对.jpg/.jpeg/.png图片直接抛错提示启用 OCR。深入 Iris 解析器AI 增强提取的调用链IrisParser 调用 Vectorize Iris 云端提取服务完整流程分为四步申请预签名上传地址POST https://api.vectorize.io/v1/org/{org_id}/files携带{name: filename, contentType: content_type}响应中拿到fileId与uploadUrl上传文件字节向预签名 URL 直接PUT不带鉴权头Content-Type 保持原文件的 MIME 类型启动提取任务POST .../org/{org_id}/extraction携带{fileId: file_id}返回extractionId轮询直到就绪GET .../org/{org_id}/extraction/{extraction_id}默认每 2 秒轮询一次poll_interval2.0总超时 300 秒timeout300.0ready为 true 后检查data.success成功则返回data.text。鉴权需要HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN与HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID两个环境变量分别对应 Vectorize API token 与组织 ID以Authorization: Bearer token传入。错误语义_raise_for_status()把 4xx 响应统一转为UnsupportedFileTypeError文件被云端拒绝——支持哪些类型由 Iris API 决定其他 HTTP 错误转为RuntimeError。这正是上面提到的远程解析器在 convert() 内抛 UnsupportedFileTypeError模式的实际落地Iris 不支持的格式会通过 fallback 链自动回退到 markitdown。配置与参数一览以下环境变量在 config.py 中定义控制文件解析行为环境变量默认值说明HINDSIGHT_API_FILE_PARSERmarkitdown默认解析器/有序回退链逗号分隔如iris,markitdownHINDSIGHT_API_FILE_PARSER_ALLOWLIST空允许客户端请求的解析器白名单空 全部已注册解析器HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_ENABLEDfalse是否启用 Markitdown 图片 OCRHINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_API_KEY空OCR 端点的 API KeyHINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_BASE_URL空OpenAI 兼容的 OCR/vision 端点地址HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_MODEL空OCR/vision 模型名HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_PROMPT见源码OCR 转写提示词默认要求只转写可见文本、不描述不推断HINDSIGHT_API_FILE_PARSER_MARKITDOWN_OCR_DEFAULT_HEADERSnull附加到 OpenAI 客户端的默认请求头JSONHINDSIGHT_API_FILE_PARSER_IRIS_TOKEN空Vectorize API tokenIrisHINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID空Vectorize 组织 IDIrisHINDSIGHT_API_FILE_PARSER_LLAMA_PARSE_API_KEY空LlamaCloud API Keyllama_parse 解析器默认的 OCR 提示词DEFAULT_FILE_PARSER_MARKITDOWN_OCR_PROMPT明确要求仅转写图片中可见文本不做描述、总结、翻译或补全保留原始语言、措辞、数字、标点、大小写与阅读顺序清晰版面重建为 Markdown 标题/列表/键值/表格无法辨认处标记[unclear]——这也是增强提取输出质量的重要一环。此外还有两个批量限制HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE_MB单次请求所有文件合计的最大 MB 数与HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE单次请求最大文件数。token 与 api_key 类配置file_parser_markitdown_ocr_api_key、file_parser_iris_token等位于配置模型的敏感字段清单中避免被日志暴露。解析器链与标准增强混合策略HINDSIGHT_API_FILE_PARSER的默认值是markitdown但注释给出了推荐形态iris,markitdown——优先用 Iris 的 AI 提取失败或不支持的格式自动回退到免费的 markitdown。这种有序回退链的语义在 convert_with_fallback() 中实现逐个尝试UnsupportedFileTypeError、空内容或任何异常都触发下一个全部失败才抛出最终错误。对扫描件/复杂排版优先 Iris、普通文本省钱用 markitdown的实际场景可以直接在请求级或文件级parser字段指定。相关能力Bank 级 API Key 与 MCP 支持本次更新之前的两个相关能力值得一并了解Bank 级 API Key3 月 3 日可将 API Key 限制到特定 memory bank适合多租户场景——每个客户/Agent 只能访问自己的记忆未授权访问返回 403。MCP 支持2 月 13 日为 Claude、Cursor、VS Code 等 AI 客户端提供 Model Context Protocol 集成支持单 bank 模式专用 Agent 记忆与多 bank 模式跨 bank 操作开箱即用约 30 个工具。文件上传与两者协同上传后的文档记忆既可以通过 bank 级 Key 做租户隔离也可以通过 MCP 工具被 Claude/Cursor 等客户端直接 recall/reflect。验证方式从测试用例看端到端行为仓库中的 test_file_retain.py 给出了可复现的端到端验证路径先用最小 PDF 字节一个含 Test Document 文本流的最小合法 PDF或纯文本构造文件创建 bank 后调用POST /v1/default/banks/{bank_id}/files/retainmultipart 携带files与requestJSON再通过操作状态查询确认转换完成。test_markitdown_parser.py则针对 MarkitdownParser 做单元级验证。想要本地跑通可按hindsight-api-slim/pyproject.toml安装依赖其中声明了markitdown与httpx配置对应环境变量后启动服务即可。开始使用在 Hindsight Cloud 中上传你的第一个文档然后对它发起一条 recall 查询验证效果。文件上传现已可用打开任意 memory bank点击上传按钮选择文件选择 Standard 或 EnhancedIris提取即可在 Document Operations 面板跟踪处理进度。处理完成后文档内容将与既有记忆一起参与 recall 与 reflect成为 Agent 长期记忆的一部分。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考