[Bug]: `refresh_ref_docs()` / `arefresh_ref_docs()` drop kwargs after the first document in a batch

快速结论：该 Bug 在调用 refresh_ref_docs() 或 arefresh_ref_docs() 并传入 insert_kwargs 或 update_kwargs 时触发，导致除第一个文档外的后续文档都无法接收到这些 kwargs，最终静默回退为 {}。优先排查是否在循环中使用了 .pop() 操作了共享字典。

问题场景

该 Bug 存在于 LlamaIndex 工具的 BaseIndex 类中，具体在 refresh_ref_docs() 和其异步版本 arefresh_ref_docs() 方法中。当用户想批量刷新多个文档并为每个文档传入自定义 insert_kwargs 或 update_kwargs 时，只有批次中第一个文档能正确收到这些参数。

报错原文

refresh_ref_docs with insert_kwargs={'my_flag': True}:
transform received: {'my_flag': True}
transform received: {}
transform received: {}
[True, True, True]

原因分析

这是一个已确认的 Bug。根源在于 refresh_ref_docs() 和 arefresh_ref_docs() 方法在文档循环内部调用了 .pop() 操作。由于 update_kwargs 是同一个字典对象，第一次迭代中 .pop() 会移除对应键（如 "insert_kwargs"），导致后续所有文档读取时键已不存在，返回 {}，且不产生任何错误提示。

环境排查

LlamaIndex 版本：0.14.21（确认存在 Bug 的版本）
相关源码文件：llama-index-core/llama_index/core/indices/base.py（行 ~429-482）
Python 版本无特殊要求
不需要特定 CUDA 或 GPU 环境

解决步骤

修改 refresh_ref_docs()：在文档循环之前使用 .get() 方法提取 insert_kwargs 和 update_kwargs，避免在循环内部使用 .pop()。具体修改如下：

# 循环之前
_insert_kwargs = update_kwargs.get("insert_kwargs", {})
_update_kwargs = update_kwargs.get("update_kwargs", {})

# 循环内部
for i, document in enumerate(documents):
    existing_doc_hash = self._docstore.get_document_hash(document.get_doc_id())
    if existing_doc_hash is None:
        self.insert(document, **_insert_kwargs)
        refreshed_documents[i] = True
    elif existing_doc_hash != document.hash:
        self.update_ref_doc(document, **_update_kwargs)
        refreshed_documents[i] = True

同步修改异步方法：对 arefresh_ref_docs() 做完全相同的修改。
可优先尝试：如果无法立即修改源码，可考虑在调用 refresh_ref_docs() 时，在回调函数或外层逻辑中为每个文档单独调用 insert() 或 update_ref_doc()，绕过批量接口。
注意：目前尚无合入该修复的 PR，如果愿意可以自行提交修复。

验证方法

使用原 Issue 中的复现代码，在修改后重新运行，如果输出变为以下内容，则问题已解决：

refresh_ref_docs with insert_kwargs={'my_flag': True}:
transform received: {'my_flag': True}
transform received: {'my_flag': True}
transform received: {'my_flag': True}
[True, True, True]