Azure AI 搜索 Python SDK

你在解决什么问题

在 Azure 上落地全文检索、向量相似度与混合排序时，Python 侧往往要同时处理索引 schema、批量灌库、查询 DSL 以及 Entra 鉴权。azure-search-documents 的 API 面较宽，若凭据方式与客户端生命周期不统一，很容易在本地能跑、上线后泄漏密钥或连接未释放。

技能如何组织内容

本技能以 Azure AI Search Python SDK 为主线，强调两条贯穿示例的规则：优先 DefaultAzureCredential（本地 CLI/IDE 与云端托管标识同一套代码路径），以及每个客户端用上下文管理器（同步 with / 异步 async with，异步凭据同样要 async with）。

核心能力按工作流拆分：

• 索引：创建带 Collection(Edm.Single) 向量字段的索引，向量维度需与嵌入模型一致；大规模向量检索可配合 HNSW 配置（详见参考 references/vector-search.md）。
• 文档：批量上传文档；生产环境建议 100–1000 条/批，并可用 SearchIndexingBufferedSender 处理批处理与重试。
• 查询：关键词、vector_queries、混合搜索（向量 + 关键词）、语义排序（Semantic Ranking）；用 Filters 在打分前收窄集合，用 Facets 做聚合导航。
• 体验：Suggest / 自动完成需在创建索引时定义 suggester，之后无法补加。
• 管道：SearchIndexerClient 管理索引器、数据源与技能集（enrichment）。
• 智能体检索：KnowledgeBaseRetrievalClient 面向知识库问答——知识源指向索引，知识库封装 LLM 与查询规划；输出可为 EXTRACTIVE_DATA 或 ANSWER_SYNTHESIS（见 references/agentic-retrieval.md）。

客户端选型：SearchClient（搜索与文档 CRUD）、SearchIndexClient（索引与同义词）、SearchIndexerClient（索引器与技能集）。同步与异步（azure.*.aio）应整条调用链二选一，不要混用。

适用边界与注意点

• 尚未迁移到 Entra 的密钥化部署才继续用 AzureKeyCredential；新代码应走 DefaultAzureCredential，生产可设 AZURE_TOKEN_CREDENTIALS=prod 收紧凭据链。
• 自然语言查询要相关性上限时，应对混合搜索启用语义配置（见 references/semantic-ranking.md）。
• 索引创建可用 create_or_update_index 做幂等；脚本 scripts/setup_vector_index.py 可作为向量索引的 CLI 起点。