agentic-awesome-skills 中的 azure-search-documents-py用 Python 玩转 Azure AI Search 全文、向量与混合检索【免费下载链接】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,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills本技能azure-search-documents-py封装了 Azure AI Search Python SDK 的完整用法从索引设计、文档写入到关键词/向量/混合/语义四种检索模式再到索引器与 AI 技能集Skillset的流水线搭建。阅读本文后你将能够在 agentic-awesome-skills 的插件体系中快速落地一个可检索、可排序、可增强的 Azure 搜索服务并理解其底层客户端模型与推荐实践。技能定位什么时候该用这个 Skillazure-search-documents-py是 agentic-awesome-skills 社区插件中面向Azure AI Search原名 Azure Cognitive Search的 Python 技能其元数据定义位于 SKILL.md核心描述为Use for vector search, hybrid search, semantic ranking, indexing, and skillsets.在仓库索引 skills_index.json 中该技能被归类为cloud类别risk级别为critical涉及云资源与生产级配置source为community并同时声明支持codex与claude两种目标 Agentsetup类型为none即无需额外安装脚本。技能激活遵循以下边界适用任务明确属于 Azure AI Search 的索引管理、文档 CRUD、向量/混合/语义检索、索引器与技能集编排不适用与上述范围无关的任务不应触发该技能强制前置执行前必须先阅读详细指南见下节当输入参数、权限边界、安全约束或成功标准缺失时技能要求停止并询问澄清而不是擅自假设。完整的操作流程与参考材料被抽取到 detailed-guide.md 中本文的所有代码与配置均以此文件为骨架并结合 Python SDK 的对象模型进行纵深讲解。安装与环境变量三步进入可运行状态pip install azure-search-documents如需使用推荐的身份认证方式Azure Identity一并安装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_API_KEY在采用 Entra ID 认证时并非必需AZURE_SEARCH_INDEX_NAME用于定位目标索引也可在构造客户端时直接以字符串参数覆盖。认证API Key 与 Entra ID 两条路径方式一API Key快速起步import 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 / DefaultAzureCredential生产推荐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 登录等多种凭据来源免去手工管理密钥的负担技能文档明确将其标注为 Recommended并在进阶最佳实践中再次强调生产环境优先使用DefaultAzureCredential而非 API Key。从 SDK 对象模型看两类凭据最终都被包装为统一的TokenCredential/KeyCredential协议因此SearchClient、SearchIndexClient、SearchIndexerClient的构造签名完全一致切换认证方式只需替换credential参数。客户端模型三个核心客户端 一个 Agentic 客户端客户端用途SearchClient查询索引、上传/更新/删除文档azure.search.documentsSearchIndexClient索引管理、同义词映射、知识源/知识库azure.search.documents.indexesSearchIndexerClient索引器、技能集、数据源管理azure.search.documents.indexesKnowledgeBaseRetrievalClient面向 LLM 的 Agentic 检索知识源 知识库 问答合成前三者构成经典查询 / 管理 / 摄取三角查询走SearchClient索引结构与向量配置走SearchIndexClient从外部数据源Blob、SQL 等持续同步走SearchIndexerClient。第四类客户端服务于知识库Knowledge Base场景是技能文档Agentic Retrieval一节的落点后续单独展开。创建带向量字段的索引HNSW 算法与向量配置向量检索的前提是在索引中声明向量字段并挂载向量算法配置。核心代码如下完整示例见 detailed-guide.mdfrom azure.search.documents.indexes import SearchIndexClient from azure.search.documents.indexes.models import ( SearchIndex, SearchField, SearchFieldDataType, VectorSearch, HnswAlgorithmConfiguration, VectorSearchProfile, SearchableField, SimpleField ) 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)关键参数说明SimpleField基础字段SearchableField可全文检索的文本字段向量字段类型固定为Collection(Edm.Single)Python 中即List[float]vector_search_dimensions必须与你使用的 Embedding 模型输出维度一致——技能文档以 1536 维OpenAItext-embedding-ada-002系列为例若使用其他模型如 3072 维的 embedding 模型必须在建索引时同步修改且维度在索引创建后不可修改HnswAlgorithmConfigurationHNSWHierarchical Navigable Small World图算法是 Azure AI Search 面向大规模向量检索的默认算法VectorSearchProfile将算法与字段绑定字段通过vector_search_profile_name引用 profileprofile 通过algorithm_configuration_name引用算法配置。进阶的集成式建索引模式详见进阶模式一节还会在VectorSearch中追加vectorizers把 Embedding 生成也托管给 Azure OpenAI形成检索即向量化。上传文档单次与缓冲批量两种姿势单次上传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)生产级批量上传则推荐SearchIndexingBufferedSenderSDK 会自动完成分块batching与失败重试retries避免手工拆批from azure.search.documents import SearchIndexingBufferedSender with SearchIndexingBufferedSender(endpoint, index_name, credential) as sender: sender.upload_documents(documents)SearchClient的文档操作还包括四个语义明确的动词upload_documents新增、merge_documents更新已有字段、merge_or_upload_documentsUpsert、delete_documents删除。技能文档的最佳实践建议按 100–1000 条一批进行索引写入以平衡吞吐与失败回滚成本。四种检索模式关键词、向量、混合、语义1. 关键词检索Full-textresults client.search( search_textazure search, select[id, title, content], top10 ) for result in results: print(f{result[title]}: {result[search.score]})search.score是服务端计算的相关性分数select控制返回字段top控制返回条数。2. 向量检索Vectorfrom azure.search.documents.models import VectorizedQuery # Your query embedding (1536 dimensions) 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] )VectorizedQuery的三个参数含义vector为查询向量由外部 Embedding 模型生成维度必须与索引字段一致、k_nearest_neighbors为近邻数量、fields指定要检索的向量字段。此处search_text不传即纯向量召回。3. 混合检索Hybrid向量 关键词results client.search( search_textazure search, vector_queries[vector_query], select[id, title, content], top10 )同时提供search_text与vector_queries服务端将关键词召回与向量召回结果融合后统一打分。技能文档将其列为相关性最佳的默认选择。4. 语义排序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})语义排序面向自然语言问题需要索引预先定义语义配置SemanticConfiguration见进阶模式返回结果中search.captions提供语义摘要Caption适合直接喂给 LLM 或展示给用户。技能文档建议在混合检索之上叠加query_typesemantic形成关键词召回 向量召回 语义重排的三级流水线。筛选、分面、自动补全与建议OData 筛选与排序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等在相关性排序之前收窄候选集order_by指定排序键。技巧对已筛字段建立可筛选索引属性可显著提升过滤性能。分面导航Facetsresults client.search( search_text*, facets[category,count:10, rating], top0 # Only get facets, no documents ) 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表示只取聚合结果不返回文档分面语法category,count:10表示对category字段做分面统计最多返回 10 个分面桶。适用于电商/文档库的左侧筛选栏。自动补全与建议Autocomplete / Suggest# Autocomplete results client.autocomplete( search_textsea, suggester_namemy-suggester, modetwoTerms ) # Suggest results client.suggest( search_textsea, suggester_namemy-suggester, select[title] )两者都需要Suggester建议器支撑而技能文档特别强调Suggester 只能在索引创建时定义事后无法添加——因此凡是可能用到补全/建议的索引必须在建索引阶段一并声明。modetwoTerms表示按两个词进行补全。索引器与技能集AI 增强的端到端摄取索引器Indexer把外部数据源如 Azure Blob到搜索索引的同步自动化技能集Skillset则在此过程中叠加 AI 技能如实体识别实现数据进、增强后文档出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. 创建数据源 data_source SearchIndexerDataSourceConnection( namemy-datasource, typeazureblob, connection_stringconnection_string, container{name: documents} ) indexer_client.create_or_update_data_source_connection(data_source) # 2. 创建技能集对 /document/content 做实体识别输出 organizations 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)三个对象的装配关系是SearchIndexer通过data_source_name、skillset_name、target_index_name把数据源 → 技能集 → 索引串成一条流水线。InputFieldMappingEntry的source使用文档解析后的 JSON 指针路径如/document/contentOutputFieldMappingEntry的target_name对应索引中的目标字段。技能文档中的EntityRecognitionSkill只是示例同类技能还包括关键短语提取、翻译、OCR 等。进阶模式集成向量化、语义配置与 Agentic 检索集成向量化Integrated Vectorization把向量生成内嵌进索引配置查询时无需自行调用 Embedding 模型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)要点AzureOpenAIVectorizerAzureOpenAIVectorizerParameters声明向量化来源resource_url为 Azure OpenAI 端点deployment_name/model_name为 Embedding 部署示例中向量维度为 3072对应更新一代的 Embedding 模型再次印证维度必须匹配模型这一约束SemanticSearchSemanticConfigurationSemanticPrioritizedFields为语义排序配置优先字段content_fields语义排序请求里的semantic_configuration_name必须指向这里的某个配置名使用create_or_update_index而非create_index可保证幂等重复执行不报错。面向 LLM 的 Agentic 检索Knowledge Bases技能文档将其作为知识库场景的入口核心概念包括Knowledge Source指向一个搜索索引作为可检索的数据来源Knowledge Base包装知识源 LLM负责查询规划query planning与答案合成synthesis输出模式EXTRACTIVE_DATA返回原始切片/原文片段或ANSWER_SYNTHESIS返回 LLM 生成的答案。这层能力对应客户端模型中的KnowledgeBaseRetrievalClient使 Agent 可以直接基于 Azure AI Search 索引完成检索增强问答而无需自行拼装 RAG 管道。技能文档提示为 Agentic 检索设计的索引务必定义语义配置否则答案合成质量会受限。异步模式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])通过azure.search.documents.aio导入同名异步客户端配合async with上下文管理器使用适合嵌入 asyncio 的 Agent 工作流。字段类型参考EDM ↔ Python 映射EDM 类型Python说明Edm.Stringstr可检索文本Edm.Int32int32 位整数Edm.Int64int64 位长整数Edm.Doublefloat浮点数Edm.Booleanbool布尔值Edm.DateTimeOffsetdatetimeISO 8601 时间Collection(Edm.Single)List[float]向量嵌入Collection(Edm.String)List[str]字符串数组注意Collection(Edm.Single)与 PythonList[float]的对应关系——向量字段的上传值必须与该类型严格一致。错误处理从 SDK 异常模型中恢复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})azure-core的异常层级覆盖了绝大多数云服务错误ResourceNotFoundError文档/索引不存在、ResourceExistsError资源已存在、HttpResponseError服务端返回非 2xx 的兜底类型。技能文档建议在批量写入与索引器调用处捕获这些异常并记录上下文便于快速定位是哪一类资源问题。最佳实践汇总来自 detailed-guide.md 的两组建议合并如下默认混合检索向量 关键词融合相关性最佳开启语义排序面向自然语言查询配合 Caption 提升可读性按 100–1000 条分批索引或直接使用SearchIndexingBufferedSender自动分块 重试先用filter收窄再做相关性排序向量维度与 Embedding 模型严格对齐建索引后不可更改大规模向量检索使用 HNSW算法Suggester 必须在建索引时创建事后无法补救环境变量管理端点与密钥不硬编码生产环境优先DefaultAzureCredentialAgentic 检索索引务必定义语义配置用create_or_update_index保证幂等用上下文管理器或显式close()释放客户端。在 agentic-awesome-skills 中如何落地该技能属于cloud分类、critical风险级别Agent 触发前必须确认任务与 Azure AI Search 范围吻合、输入与权限齐全。仓库内该技能的另一份平行副本位于 agentic-awesome-skills 插件目录其详细指南与本文引用的 detailed-guide.md 内容一致技能元数据中的setup.type为none说明无需额外安装脚本即可在支持codex/claude的 Agent 环境中直接使用。本文给出的全部代码可直接复制为 Python 脚本运行先设置三个环境变量索引与查询配置均可对照上面的字段类型表与错误处理模式做生产级加固。说明技能文档Reference Files一节提及的references/vector-search.md、references/semantic-ranking.md、scripts/setup_vector_index.py等补充材料在当前仓库副本中未随附如需完整参考以本指南与官方azure-search-documentsSDK 文档为准。【免费下载链接】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,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考