Azure AI Search：上传文档后检索无结果，生产环境索引等待最佳实践

阿华AIGC实验室

2026-6-13

Azure AI Search异步索引后可靠检索的最佳实践

使用索引状态轮询机制
利用Azure AI Search Python SDK的get_index_statistics方法定期检查索引的文档计数，对比你上传的文档总数，当两者匹配时再执行检索。这种方式比固定延迟更灵活，能根据实际索引进度动态等待，避免不必要的耗时。
示例代码：

from azure.search.documents import SearchClient
from azure.core.credentials import AzureKeyCredential
import time

def wait_for_index_completion(search_client, expected_doc_count, max_retries=20, retry_interval=5):
    retries = 0
    while retries < max_retries:
        stats = search_client.get_index_statistics()
        current_count = stats['document_count']
        if current_count == expected_doc_count:
            return True
        time.sleep(retry_interval)
        retries += 1
    return False

# 初始化搜索客户端
search_client = SearchClient(endpoint="你的搜索服务端点", index_name="目标索引名", credential=AzureKeyCredential("你的密钥"))
# 假设上传了100份文档，等待索引完成
if wait_for_index_completion(search_client, 100):
    # 执行检索逻辑
    results = search_client.search(query="你的检索语句")
else:
    print("索引超时，未完成文档处理")

启用索引器事件通知（适用于索引器导入场景）
如果是通过索引器（比如从Blob Storage导入文档）创建索引，可以配置Azure Event Grid接收索引器的运行状态事件（如IndexerCompleted）。当收到索引完成的事件后，再触发检索流程，完全不需要轮询，适合大规模文档导入的生产场景。
核心操作：在Azure门户配置Event Grid订阅，将索引器事件发送到你的后端服务（如Azure Function或自定义Web API），服务收到事件后执行检索逻辑。
结合批量上传确认与索引轮询
当使用upload_documents批量上传文档时，先通过SDK返回的结果确认所有文档上传成功，再启动索引状态轮询。这样能避免因上传失败导致的索引计数不匹配问题，进一步提升可靠性。
示例片段：
```
upload_results = search_client.upload_documents(documents=你的文档列表)
all_uploaded = all(result.succeeded for result in upload_results)
if all_uploaded:
    wait_for_index_completion(search_client, len(你的文档列表))
    # 执行检索操作
```
调整索引实时性配置（按需使用）
Azure AI Search默认支持近实时索引，你可以根据业务需求调整索引的indexing_mode为realtime（仅适用于特定场景），或修改索引器的refresh_interval缩短索引可见周期。注意：实时索引会增加资源消耗，生产环境需权衡性能与成本，不建议盲目启用。