使用 Azure AI Search Python SDK 构建向量、混合与语义检索基于 agentic-awesome-skills 的技能实战指南【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本文以开源仓库 agentic-awesome-skills 中收录的azure-search-documents-py技能文档references/detailed-guide.md为骨架系统讲解使用azure-search-documentsPython SDK 完成全文检索、向量检索、混合检索、语义排序、索引管理与 AI 技能集Skillset的完整流程。读完本文你将掌握从环境准备、身份认证到索引创建、文档写入、多种查询模式与错误处理的端到端工程化能力并能直接复用在 RAG 与 Agentic Retrieval 场景中。技能定位一份带风险标记的社区级检索工程参考在 agentic-awesome-skills 的 catalog.json 中azure-search-documents-py被登记为category: cloud、risk: critical、source: community触发词覆盖azure、search、documents、vector、hybrid、semantic、ranking、indexing等。其根技能文件 SKILL.md 声明描述Azure AI Search SDK for Python用于向量搜索、混合搜索、语义排序、索引与技能集风险等级critical意味着执行前必须完整阅读参考指南并把其中的安全性、前置条件与校验要求视为强制项限制仅当任务与上述范围明确匹配时使用输出不能替代环境特定的验证、测试与专家评审当输入、权限、安全边界或成功标准缺失时应停下并请求澄清。该技能在仓库中以双镜像形式存在另一份位于 plugins/agentic-awesome-skills/skills/azure-search-documents-py/SKILL.md内容保持一致。下面进入核心实操。安装与环境变量安装 SDK 只需一条命令pip install azure-search-documents如需使用 Entra IDMicrosoft Entra托管身份认证与后续的 Agentic 检索能力建议一并安装pip install azure-search-documents azure-identity运行前需要配置三个核心环境变量技能文档给出了明确模板AZURE_SEARCH_ENDPOINThttps://service-name.search.windows.net AZURE_SEARCH_API_KEYyour-api-key AZURE_SEARCH_INDEX_NAMEyour-index-name要点说明AZURE_SEARCH_ENDPOINT是搜索服务的 REST 端点格式形如https://service-name.search.windows.netAZURE_SEARCH_API_KEY仅用于 API Key 认证技能文档明确标注not recommended for production生产环境不推荐AZURE_SEARCH_INDEX_NAME指定默认索引名后续所有示例均可通过os.environ[...]读取避免把密钥硬编码进源码。认证API Key 与 Entra ID方式一API Keyimport os from azure.search.documents import SearchClient from azure.core.credentials import AzureKeyCredential client SearchClient( endpointos.environ[AZURE_SEARCH_ENDPOINT], index_nameos.environ[AZURE_SEARCH_INDEX_NAME], credentialAzureKeyCredential(os.environ[AZURE_SEARCH_API_KEY]) )方式二Entra ID推荐import os from azure.search.documents import SearchClient from azure.identity import DefaultAzureCredential client SearchClient( endpointos.environ[AZURE_SEARCH_ENDPOINT], index_nameos.environ[AZURE_SEARCH_INDEX_NAME], credentialDefaultAzureCredential() )DefaultAzureCredential会自动尝试环境变量、托管身份、Azure CLI 登录等多种凭证来源免去密钥管理负担是技能文档在附加模式章节中反复强调的首选生产认证方式。两种方式的差异可概括为API Key 简单直接、适合本地验证Entra ID 具备轮换、条件访问与审计能力适合生产与多租户场景。客户端类型三个职责分明的入口技能文档用表格明确了三类客户端的职责分工ClientPurposeSearchClient搜索与文档操作查询、上传、更新、删除SearchIndexClient索引管理、同义词映射Index management, synonym mapsSearchIndexerClient索引器、数据源、技能集Indexers, data sources, skillsets在附加模式章节中技能文档还补充了第四类ClientPurposeKnowledgeBaseRetrievalClientAgentic 检索面向 LLM 的问答agentic retrieval with LLM-powered QA实战建议日常查询只使用SearchClient创建或修改索引、同义词映射用SearchIndexClient数据摄入管道数据源 → 技能集 → 索引器统一交给SearchIndexerClient。创建带向量字段的索引基础模式HNSW 算法 手动向量化向量索引的核心是声明一个Collection(Edm.Single)类型的向量字段并把它挂到配置好的向量搜索 Profile 上。from azure.search.documents.indexes import SearchIndexClient from azure.search.documents.indexes.models import ( SearchIndex, SearchField, SearchFieldDataType, VectorSearch, HnswAlgorithmConfiguration, VectorSearchProfile, SearchableField, SimpleField ) from azure.core.credentials import AzureKeyCredential endpoint os.environ[AZURE_SEARCH_ENDPOINT] key os.environ[AZURE_SEARCH_API_KEY] index_client SearchIndexClient(endpoint, AzureKeyCredential(key)) fields [ SimpleField(nameid, typeSearchFieldDataType.String, keyTrue), SearchableField(nametitle, typeSearchFieldDataType.String), SearchableField(namecontent, typeSearchFieldDataType.String), SearchField( namecontent_vector, typeSearchFieldDataType.Collection(SearchFieldDataType.Single), searchableTrue, vector_search_dimensions1536, vector_search_profile_namemy-vector-profile ) ] vector_search VectorSearch( algorithms[ HnswAlgorithmConfiguration(namemy-hnsw) ], profiles[ VectorSearchProfile( namemy-vector-profile, algorithm_configuration_namemy-hnsw ) ] ) index SearchIndex( namemy-index, fieldsfields, vector_searchvector_search ) index_client.create_or_update_index(index)关键参数拆解vector_search_dimensions必须与你的嵌入模型输出维度一致例如 OpenAItext-embedding-3-small1536 维或text-embedding-3-large3072 维HnswAlgorithmConfigurationHNSW 近似最近邻算法技能文档最佳实践指出它适合大规模向量检索VectorSearchProfile把算法配置与向量字段绑定起来的桥梁字段通过vector_search_profile_name引用建议使用create_or_update_index幂等而非create_index便于反复执行建表逻辑。进阶模式Azure OpenAI 集成向量化 语义配置技能文档的Index Creation Pattern章节展示了更完整的生产级索引在向量 Profile 中挂载AzureOpenAIVectorizer让服务在查询/索引时自动调用嵌入模型完成向量化同时声明语义排序配置from azure.search.documents.indexes import SearchIndexClient from azure.search.documents.indexes.models import ( SearchIndex, SearchField, VectorSearch, VectorSearchProfile, HnswAlgorithmConfiguration, AzureOpenAIVectorizer, AzureOpenAIVectorizerParameters, SemanticSearch, SemanticConfiguration, SemanticPrioritizedFields, SemanticField ) index SearchIndex( nameindex_name, fields[ SearchField(nameid, typeEdm.String, keyTrue), SearchField(namecontent, typeEdm.String, searchableTrue), SearchField(nameembedding, typeCollection(Edm.Single), vector_search_dimensions3072, vector_search_profile_namevector-profile), ], vector_searchVectorSearch( profiles[VectorSearchProfile( namevector-profile, algorithm_configuration_namehnsw-algo, vectorizer_nameopenai-vectorizer )], algorithms[HnswAlgorithmConfiguration(namehnsw-algo)], vectorizers[AzureOpenAIVectorizer( vectorizer_nameopenai-vectorizer, parametersAzureOpenAIVectorizerParameters( resource_urlaoai_endpoint, deployment_nameembedding_deployment, model_nameembedding_model ) )] ), semantic_searchSemanticSearch( default_configuration_namesemantic-config, configurations[SemanticConfiguration( namesemantic-config, prioritized_fieldsSemanticPrioritizedFields( content_fields[SemanticField(field_namecontent)] ) )] ) ) index_client SearchIndexClient(endpoint, credential) index_client.create_or_update_index(index)相比基础模式这套配置同时完成了三件事向量化由服务端托管无需客户端预生成嵌入、语义排序配置就绪default_configuration_name使查询无需每次显式传名、索引创建保持幂等。注意semantic_configuration_name引用的SemanticConfiguration必须在索引定义中先行存在否则查询会报错。文档操作写入、更新与删除单次/列表上传from azure.search.documents import SearchClient client SearchClient(endpoint, my-index, AzureKeyCredential(key)) documents [ { id: 1, title: Azure AI Search, content: Full-text and vector search service, content_vector: [0.1, 0.2, ...] # 1536 dimensions } ] result client.upload_documents(documents) print(fUploaded {len(result)} documents)上传的文档结构必须与索引字段对齐content_vector数组长度应等于索引声明的vector_search_dimensions否则索引会拒绝该文档。批量写入SearchIndexingBufferedSender技能文档特别推荐使用SearchIndexingBufferedSender它内置自动分批与重试from azure.search.documents import SearchIndexingBufferedSender with SearchIndexingBufferedSender(endpoint, index_name, credential) as sender: sender.upload_documents(documents)最佳实践给出的经验区间是每批 100–1000 个文档兼顾吞吐与失败重试成本。四类文档操作语义通过SearchClient可执行四类原子操作技能文档给出对照search_client SearchClient(endpoint, index_name, credential) search_client.upload_documents(documents) # 新增 search_client.merge_documents(documents) # 更新已存在按 key 合并 search_client.merge_or_upload_documents(documents) # Upsert存在则合并不存在则插入 search_client.delete_documents(documents) # 删除按 key搜索模式全景关键词全文搜索results client.search( search_textazure search, select[id, title, content], top10 ) for result in results: print(f{result[title]}: {result[search.score]})select用于裁剪返回字段top限制条数search.score是相关性评分字段。向量搜索VectorizedQueryfrom azure.search.documents.models import VectorizedQuery # 你的查询嵌入与索引维度一致如 1536 维 query_vector get_embedding(semantic search capabilities) vector_query VectorizedQuery( vectorquery_vector, k_nearest_neighbors10, fieldscontent_vector ) results client.search( vector_queries[vector_query], select[id, title, content] )k_nearest_neighbors控制返回的最近邻数量fields必须指向索引中声明的向量字段。混合搜索向量 关键词vector_query VectorizedQuery( vectorquery_vector, k_nearest_neighbors10, fieldscontent_vector ) results client.search( search_textazure search, vector_queries[vector_query], select[id, title, content], top10 )混合搜索同时传入search_text与vector_queries服务端会融合全文相关性得分与向量相似度。技能文档把为最佳相关性使用混合搜索列在最佳实践第一条。语义排序Semantic Rankingfrom azure.search.documents.models import QueryType results client.search( search_textwhat is azure search, query_typeQueryType.SEMANTIC, semantic_configuration_namemy-semantic-config, select[id, title, content], top10 ) for result in results: print(f{result[title]}) if result.get(search.captions): print(f Caption: {result[search.captions][0].text})开启语义排序后query_typeQueryType.SEMANTIC配合预先定义的semantic_configuration_name服务端会用语言模型对候选结果重新排序并通过search.captions返回高亮摘要文本——这是构建自然语言问答体验的关键能力。过滤器与排序results client.search( search_text*, filtercategory eq Technology and rating gt 4, order_by[rating desc], select[id, title, category, rating] )filter使用 OData 语法eq、gt、and等search_text*表示全量匹配。最佳实践建议先用过滤器缩小候选集再执行排序以降低语义/向量计算的成本。分面导航Facetsresults client.search( search_text*, facets[category,count:10, rating], top0 # 只取分面不返回文档 ) for facet_name, facet_values in results.get_facets().items(): print(f{facet_name}:) for facet in facet_values: print(f {facet[value]}: {facet[count]})top0时只返回聚合结果count:10限制每个分面的桶数量。分面结果通过results.get_facets()访问。自动补全与建议Autocomplete Suggest# Autocomplete输入前缀补全 results client.autocomplete( search_textsea, suggester_namemy-suggester, modetwoTerms ) # Suggest基于建议器返回完整候选项 results client.suggest( search_textsea, suggester_namemy-suggester, select[title] )注意技能文档最佳实践第 7 条的硬约束Suggester 必须在索引创建时定义之后无法追加。因此搜索框联想需求必须在一开始设计索引时就预留。索引器与技能集AI 富化管道当数据来自 Blob 等外部源时用SearchIndexerClient编排数据源 → 技能集 → 索引器三步管道。技能文档以实体识别EntityRecognitionSkill为例from azure.search.documents.indexes import SearchIndexerClient from azure.search.documents.indexes.models import ( SearchIndexer, SearchIndexerDataSourceConnection, SearchIndexerSkillset, EntityRecognitionSkill, InputFieldMappingEntry, OutputFieldMappingEntry ) indexer_client SearchIndexerClient(endpoint, AzureKeyCredential(key)) # 1. 创建数据源Azure Blob data_source SearchIndexerDataSourceConnection( namemy-datasource, typeazureblob, connection_stringconnection_string, container{name: documents} ) indexer_client.create_or_update_data_source_connection(data_source) # 2. 创建技能集从文档内容抽取组织实体 skillset SearchIndexerSkillset( namemy-skillset, skills[ EntityRecognitionSkill( inputs[InputFieldMappingEntry(nametext, source/document/content)], outputs[OutputFieldMappingEntry(nameorganizations, target_nameorganizations)] ) ] ) indexer_client.create_or_update_skillset(skillset) # 3. 创建索引器串联数据源、目标索引与技能集 indexer SearchIndexer( namemy-indexer, data_source_namemy-datasource, target_index_namemy-index, skillset_namemy-skillset ) indexer_client.create_or_update_indexer(indexer)要点技能输入用InputFieldMappingEntry指向文档内的字段路径/document/content输出用OutputFieldMappingEntry落到索引字段target_nameorganizations技能集是可扩展的实际生产常用技能还包括 OCR、关键词抽取、翻译、图像分析等索引器负责按调度把外部数据源增量同步进索引。Agentic Retrieval面向 LLM 的检索知识库技能文档的附加模式章节介绍了面向 Agent 场景的知识库检索能力核心概念三件套Knowledge Source知识源指向一个搜索索引Knowledge Base知识库包装知识源 LLM负责查询规划与答案合成输出模式EXTRACTIVE_DATA返回原始文本块或ANSWER_SYNTHESIS返回 LLM 生成的答案。在 AAS 这类 agent-first 控制平面语境下这意味着检索不再停留在返回 Top-K 文档而是进一步由 LLM 完成查询改写、多源融合与答案合成。技能文档给出的配套建议是为 Agentic 检索索引务必定义语义配置见进阶模式Azure OpenAI 集成向量化小节因为语义排序是答案质量的重要前提。异步模式SDK 提供完整的aio异步子模块适合高并发的 Agent 工作负载from azure.search.documents.aio import SearchClient async with SearchClient(endpoint, index_name, credential) as client: results await client.search(search_textquery) async for result in results: print(result[title])异步客户端同样支持上下文管理器自动关闭连接。字段类型参考技能文档给出 EDMEntity Data Model类型与 Python 类型的对照表设计索引时可直接查阅EDM TypePythonNotesEdm.Stringstr可搜索文本Edm.Int32int整数Edm.Int64int长整数Edm.Doublefloat浮点数Edm.Booleanbool布尔值Edm.DateTimeOffsetdatetimeISO 8601 时间Collection(Edm.Single)List[float]向量嵌入Collection(Edm.String)List[str]字符串数组注意Collection(Edm.Single)正是向量字段的 EDM 表示前面示例中SearchFieldDataType.Collection(SearchFieldDataType.Single)与之对应。错误处理技能文档给出基于azure.core.exceptions的典型处理模式from azure.core.exceptions import ( HttpResponseError, ResourceNotFoundError, ResourceExistsError ) try: result search_client.get_document(key123) except ResourceNotFoundError: print(Document not found) except HttpResponseError as e: print(fSearch error: {e.message})ResourceNotFoundError文档/索引不存在ResourceExistsError创建已存在的资源幂等逻辑下通常可忽略HttpResponseError兜底捕获所有 HTTP 层错误e.message含服务端返回的详细信息。批量场景中SearchIndexingBufferedSender的重试机制本身也是错误处理的一部分。最佳实践清单技能文档两处最佳实践可合并为一份可直接落地的检查清单用混合搜索关键词 向量获得最佳相关性启用语义排序处理自然语言查询按 100–1000 文档批量索引并优先使用SearchIndexingBufferedSender自动分批与重试用过滤器先收窄结果再排序向量维度与嵌入模型严格对齐1536 / 3072 等大规模向量检索用 HNSW 算法Suggester 必须在建索引时创建后续无法追加端点、密钥、部署名一律走环境变量生产环境优先DefaultAzureCredentialAPI Key 仅用于开发验证Agentic 检索索引务必配置语义配置用create_or_update_index保持幂等用上下文管理器或显式close()关闭客户端。仓库内的配套资源与后续深入方向在 agentic-awesome-skills 仓库中本技能相关的资产还包括技能入口 SKILL.md含激活条件、示例、安全约束与局限性声明以及镜像副本 plugins/agentic-awesome-skills/skills/azure-search-documents-py/SKILL.md索引登记信息位于 data/catalog.json其中记录了该技能的分类cloud、风险等级critical、来源community与触发词表是 Agent 自动发现与路由该技能的元数据依据技能参考指南 references/detailed-guide.md 即本文主体来源。若需继续深入可以围绕技能文档提及的进阶主题展开HNSW 参数调优与集成向量化、语义配置中的 captions/answers 与混合模式、多向量查询multi-vector queries以及面向 LLM 的 Agentic Retrieval 知识库设计——这些在本文已经覆盖的基础上构成了从会检索到检索得好的完整进阶路径。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考