👁 17 次阅读

如何解决 Azure AI Search 向量存储的 $filter 递归深度超限错误？

来源链接：https://github.com/run-llama/llama_index/issues/19370

现象描述

LlamaIndex 的 Azure AI Search 向量存储集成中，当用户需要按大量相对路径过滤检索结果时，会触发 Azure 搜索服务端 $filter 表达式的递归深度超限错误。该问题在 issue #19370 中由用户报告，标签为 bug、triage、stale，当前状态为 open。剔除机器人留言与无效留言后，实质讨论共 23 条，末条实质评论日期为 2026-03-24；此后 2026-08-11 仅有一条机器人归档提示。用户的实际场景规模较大：在总计 50k 条相对路径中，存在超过 1200 条唯一相对路径需要参与过滤。索引阶段用户将 metadatafields 设为 relative_path，并复用一个已存在的、可以按 relative_path 过滤的索引。按文档给出的代码做文件夹过滤在路径较少时“doing great”，但随着相对路径或 or 条件数量增加，开始出现错误 1：

{
  "detail": "() Invalid expression: Recursion depth exceeded allowed limit.\r\nParameter name: $filter\nCode: \nMessage: Invalid expression: Recursion depth exceeded allowed limit.\r\nParameter name: $filter"
}

用户日志显示，全部路径长度为 59071，缓存中动态生成的可选文件夹集合为 {'Sample1', 'green', 'Support', 'Data', 'Base', 'paper', 'sample2', 'test_folder'}，各文件夹包含的路径数分别为 33、530、603、15、6、5、2、4。用户随后选择全部文件夹时，命中的路径数达到 59071，请求随即返回上述错误，日志中记录为：

INFO: {"interactionid": "0dc9ec68-6b50-4e4b-9bb2-d1f69bbc5cd9_1752040373", "user_name": "string", "user_query": "explain me about health score formula", "execution_time_seconds": 0.0, "response": "An error occurred: () Invalid expression: Recursion depth exceeded allowed limit.\r\nParameter name: $filter\nCode: \nMessage: Invalid expression: Recursion depth exceeded allowed limit.\r\nParameter name: $filter"}

为绕开错误 1，用户尝试自行构造 odata filter 字符串，以 or 条件枚举全部相对路径，并通过 #vector_store_kwargs={"odata_filters": odata_filters} 传入 index.as_retriever，结果又抛出错误 2。错误 2 的具体文本在提供的讨论记录中未完整给出，但其性质在后续讨论中被确认为向 Azure 文档客户端传入了不被接受的参数（invalid param）。讨论中还出现另一个衍生问题：用户即使使用了 odata filter 试图把搜索空间限制在选中文件夹，测试性查询未选中的文件夹时仍返回了未选中文件夹的 chunk，用户追问 odata filter 是否真正限制了搜索空间。

背景原因

维护者 logan-markewich 在 2025-07-10 的回复中把过滤器的应用位置指向了

llama-index-integrations/vector_stores/llama-index-vector-stores-azureaisearch/llama_index/vector_stores/azureaisearch/base.py

第 1669 行附近的代码，并说明该 class 由社区维护，他自己“far from an azure expert”。从这段表述可以确认两点：过滤逻辑位于集成包的 base.py 中，且维护者认为代码本身“似乎很无辜，只是被传进去了”。换言之，错误 1 的递归深度超限并非 LlamaIndex 侧拼接逻辑的明显缺陷，而是构造出的 $filter 表达式规模触达了 Azure 搜索服务端的解析限制。错误 2 的成因在讨论后期得到澄清。Jash271 在 2025-09-02 表示自己也查看了 Azure 客户端侧的实现，那里同样没有使用 kwargs 中的额外 key，因此“额外 key 存在不应成为问题”，并希望看到导致 invalid param 错误的具体代码。federicocaccialanzaabb 在 2025-09-03 提供了复现代码，其中使用了若干辅助类，包含 embedding 模型与 Azure AI Search 的配置，并说明 azure ai search helper 的结构留在注释中以便查看其 class 与 client。Jash271 在 2025-09-04 之后确认：用 LlamaIndex 的 MetadataFilters 可以正常工作；而无论通过 filters 还是 vector_store_kwargs 传 odata，都会出现同样的 type error。federicocaccialanzaabb 补充，加入 pop 机制后过滤器在其侧生效，因为该处理发生在查询结果创建、发送给 Azure documents client 之前，此时过滤器已正确写入 filter 字段。 Jash271 在 2025-09-05 明确表示“you’re right, I see the issue，we’ll need to raise a PR to pop the kwargs”，并询问 federicocaccialanzaabb 是否愿意提交 PR。后者随后提交了 PR #19800。到 2026-03-24，federicocaccialanzaabb 在 issue 中留言“this can be closed guys it was fixed months ago”。需要注意状态口径：issue 本身在 GitHub 上仍为 open，标签仍包含 bug、triage、stale，官方并未在 issue 中给出合并记录或版本确认。PR #19800 是否已合并进主干、随哪个版本发布，事实依据中没有维护者的确认，正文不作推断。据 issue 讨论，社区侧认为问题已通过该 PR 修复，但这属于社区结论而非官方已确认修复。

排查或量化方法

定位问题时可从两个维度入手。其一是过滤条件的规模：用户日志已经给出可量化的对照——59071 条全部路径与 1200 条以上唯一相对路径。当 or 条件随路径数线性增长时，$filter 表达式的嵌套结构会随之加深，直到触达服务端允许的递归深度上限。错误信息中的 Recursion depth exceeded allowed limit 与 Parameter name: $filter 直接指向上限被突破，而非语法错误。其二是参数传递路径。区分两类写法有助于把问题归因到正确的层：

使用 LlamaIndex 的 MetadataFilters 构造过滤条件后传给 retriever；
通过 vector_store_kwargs 直接传入 odata_filters 字符串。

据 issue 讨论，前者在用户侧工作正常，后者会触发 invalid param 类错误，根因是 kwargs 中的额外 key 未在传给 Azure documents client 前被移除（pop）。federicocaccialanzaabb 的验证方式是加入 pop 机制后观察过滤器是否在查询结果创建、发送给 client 之前已正确进入 filter 字段——这一观察点可以作为自检的参照：如果过滤条件在最终请求的 filter 字段中是正确的，但请求仍失败，问题更可能在上游的表达式规模；如果 kwargs 中存在未被消费的 key，问题则在参数清洗环节。维护者给出的源码位置（base.py 第 1669 行附近）可作为进一步确认过滤器拼接行为的入口。由于该集成由社区维护，阅读该处代码时应以实际传入 Azure 客户端的参数为准，而不是只看 retriever 层的 kwargs。

完整解决方案（含必要代码）

据 issue 讨论，可行的处理路径分为两层。第一层是参数清洗，对应错误 2。讨论中确认的修复方向是在把 kwargs 交给 Azure documents client 之前 pop 掉多余的 key。federicocaccialanzaabb 提交的 PR 为：

https://github.com/run-llama/llama_index/pull/19800

PR 的具体 diff 在事实依据中没有展开，正文不补写实现细节。若使用尚未包含该改动的版本，可在应用侧自行处理：在初始化 retriever 时避免向 vector_store_kwargs 放入 Azure 客户端不识别的键，改用 MetadataFilters 表达过滤条件。据 issue 讨论，MetadataFilters 写法在用户环境中工作正常：

MetadataFilters(
            filters=[ExactMatchFilter(key="doc_extension", value="pdf")]
        )

retriever = vector_index.as_retriever(
            filters=self.filters, similarity_top_k=top_k_results
        )

上述片段来自 Jash271 在 2025-09-03 回复中给出的建议结构，完整参数以其原帖为准。第二层是过滤条件规模，对应错误 1。这条路径在事实依据中没有官方修复，issue 讨论也未给出替代的过滤构造方式。可确认的社区经验是：当 or 条件数量随相对路径增长到千级、命中路径达到数万条时，服务端会以递归深度超限拒绝请求；把同样的路径集改走 vector_store_kwargs 的 odata_filters 并不会绕开服务端解析限制，反而叠加了参数传递问题。因此在实际工程中需要控制单次过滤表达式的分支数量，但这属于应用层设计取舍，不是该 issue 中已验证的方案。社区结论的适用边界：federicocaccialanzaabb 在 2026-03-24 表示问题“was fixed months ago”，指向 PR #19800。该结论未经维护者在 issue 中确认合并与版本，正文按“据 issue 讨论”标注。若在较新版本上仍遇到同类报错，应回到上面两层分别核对参数是否被清洗、过滤表达式规模是否超限。

参数或对比表格

项目	情况 A：MetadataFilters	情况 B：vector_store_kwargs 传 odata_filters
讨论中的实测结果	可正常工作	触发 invalid param 类错误
根因	过滤条件由框架统一构造	kwargs 中额外 key 未被 pop，传入 Azure documents client
相关修复	无需额外处理	PR #19800，据 issue 讨论
与错误 1 的关系	表达式规模过大时同样可能触达服务端递归上限	不能绕开服务端解析限制
量化指标	数值（来自用户日志）
全部相对路径长度	59071
需参与过滤的唯一相对路径	超过 1200
全选文件夹时命中路径数	59071
动态文件夹数量	8

常见错误排查

Recursion depth exceeded allowed limit 且 Parameter name: $filter：这是 Azure 搜索服务端对过滤表达式嵌套深度的拒绝，不是 Python 侧异常。优先检查 or 条件分支数量与生成的表达式结构。
通过 vector_store_kwargs 传参后出现 invalid param：检查 kwargs 中是否存在 Azure documents client 不识别的 key。据 issue 讨论，这些 key 需要在下发请求前被移除。
过滤器看似生效但返回未选中文件夹的 chunk：讨论中用户报告过这一现象，并用未选中文件夹的查询做过测试。排查时应确认最终发送给 Azure 的请求中 filter 字段的实际内容，而不是只看 retriever 层的入参。
同一过滤条件在 MetadataFilters 下正常、在 kwargs 下失败：说明问题出在参数传递层而非过滤语义层，参考上表情况 B 处理。
在较新版本上仍复现：由于 issue 仍为 open 且无维护者合并确认，需自行核对所用版本是否包含 PR #19800 的改动，不能直接假定已修复。

实践建议

把过滤条件优先交给框架的统一入口表达，即使用 MetadataFilters 而非直接向 vector_store_kwargs 塞入原始 odata 字符串。据 issue 讨论，这是用户在复现中确认可用的路径，也能避免额外 key 污染下游客户端调用。对过滤表达式做规模控制。issue 中的失败案例是 1200 条以上唯一相对路径、全选后命中 59071 条路径，错误由服务端递归深度上限触发。在路径集合可能达到千级时，应在应用层评估是否需要拆分查询或改用层级更浅的过滤字段，而不是持续堆叠 or 条件。升级或排查时以可核实的信息为准。PR #19800 的状态可通过 GitHub API 查询，issue 状态字段与标签反映的是 issue 自身而非代码合并情况；官方发布说明确认包含与代码进入主干是两种不同说法，不应混用。对“已修复”的表述保持谨慎。issue 中末条实质评论来自社区用户，维护者未在 issue 内确认修复版本；在依赖该结论前，应验证所用版本的实际行为。

FAQ

问：这个错误的根因是 LlamaIndex 拼接过滤表达式出错吗？ 答：据维护者 logan-markewich 的回复，过滤器在 azureaisearch/base.py 第 1669 行附近被应用，代码“似乎很无辜，只是被传进去了”，该 class 由社区维护。错误 1 的文本指向 Azure 搜索服务端对 $filter 递归深度的限制，触发条件是过滤条件规模随路径数增长。 问：改用 vector_store_kwargs 传 odata_filters 能绕开递归深度限制吗？ 答：不能。讨论中用户尝试该写法后遇到的是另一类错误（invalid param），根因是 kwargs 中额外 key 未被 pop 就传给了 Azure documents client。Jash271 确认了这一点并推动了 PR #19800。服务端解析限制并未因此消失。 问：PR #19800 是否已经合并、随哪个版本发布？ 答：事实依据中没有维护者的合并记录或版本确认。社区用户在 2026-03-24 留言称问题“was fixed months ago”，这属于社区结论。PR 状态可通过 GitHub API 查询，不应直接表述为已随版本发布。 问：为什么用了 odata filter，仍然返回未选中文件夹的内容？ 答：讨论中用户报告过这一现象并做了针对性测试。排查方向是确认最终请求中 filter 字段的实际内容；federicocaccialanzaabb 的验证显示过滤器应在查询结果创建、发送给 client 之前已正确写入 filter 字段，若未写入则该环节可能存在问题。 问：issue 当前是什么状态？ 答：状态为 open，无关闭时间与关闭原因，标签为 bug、triage、stale。2026-03-24 有一条社区留言称问题已在数月前修复，2026-08-11 为机器人发出的 stale 归档提示。状态结论以剔除噪音后的末条实质评论为准：社区侧认为问题已修复，官方侧尚未在 issue 中确认。