使用 Azure.Search.Documents（.NET）构建 Azure AI Search 应用：全文、向量、语义与混合搜索实战指南

AI 技能AI 插件【免费下载链接】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点击查看免费下载导读本文基于 AAS 仓库中azure-search-documents-dotnet技能文档系统讲解如何在 .NET 应用中集成 Azure AI Search 官方 SDKAzure.Search.Documents覆盖环境准备、两种认证方式、索引建模、文档增删改查、全文搜索、分面导航、自动补全、向量检索、语义排序与混合检索等完整能力。读完本文你将能够用类型安全的方式搭建一套支持关键词、向量与自然语言语义检索的生产级搜索服务并理解底层 SDK 的设计取舍与最佳实践。该技能在仓库目录体系中被归类为cloud类别、风险等级为critical主要面向需要以编码方式管理 Azure AI Search 服务的场景参见 data/catalog.json 与 data/skills_index.json 中的技能元数据。一、技能定位与适用场景azure-search-documents-dotnet是 AAS 技能体系中面向 Azure AI Search 的 .NET 实现技能其核心职责是使用Azure.Search.DocumentsSDK 构建具备**全文检索full-text、向量检索vector、语义检索semantic与混合检索hybrid**能力的搜索应用。该技能元数据表明它适用于需要实现搜索索引生命周期管理与查询编排的任务包括但不限于电商、文档站、知识库等场景的关键词搜索与筛选filter / orderby / facet基于嵌入向量的相似度检索RAG 应用检索层面向自然语言提问的语义排序、字幕captions与答案answers将关键词、向量与语义三种信号融合的混合检索。技能文档同时给出明确的使用边界仅当任务与上述范围清晰匹配时才启用输出不能替代环境相关的验证、测试与专家评审当关键输入、权限、安全边界或成功标准缺失时应暂停并向用户澄清。这与 AAS 对critical风险技能的通用要求一致。二、环境准备与安装2.1 安装 NuGet 包在 .NET 项目建议 .NET 6中执行dotnet add package Azure.Search.Documents dotnet add package Azure.IdentityAzure.Search.DocumentsAzure AI Search 官方客户端 SDK提供索引、文档与查询的完整 APIAzure.Identity提供DefaultAzureCredential等托管身份认证组件配合服务端无密钥认证使用。文档标注的版本参考稳定版 v11.7.0预览版 v11.8.0-beta.1。以实际可用 NuGet 版本为准生产环境应优先使用稳定版本。2.2 环境变量约定技能文档约定通过环境变量注入服务配置便于本地开发与容器化部署时切换环境SEARCH_ENDPOINThttps://search-service.search.windows.net SEARCH_INDEX_NAMEindex-name # For API key auth (not recommended for production) SEARCH_API_KEYapi-key其中SEARCH_ENDPOINT对应 Azure AI Search 服务的终结点形如https://服务名.search.windows.netSEARCH_INDEX_NAME指定目标索引名称SEARCH_API_KEY仅在采用 API Key 认证时使用文档明确注明不推荐在生产环境使用。三、认证方式默认凭据优先SDK 支持两种凭据类型对应的客户端构造方式不同其底层接口均实现Azure.Core.TokenCredential或AzureKeyCredential。3.1 DefaultAzureCredential推荐DefaultAzureCredential会依次尝试环境变量、托管身份、Azure CLI、Visual Studio 等多种身份来源实现本地开发与云端运行的无缝切换using Azure.Identity; using Azure.Search.Documents; var credential new DefaultAzureCredential(); var client new SearchClient( new Uri(Environment.GetEnvironmentVariable(SEARCH_ENDPOINT)), Environment.GetEnvironmentVariable(SEARCH_INDEX_NAME), credential);3.2 API Key不推荐用于生产using Azure; using Azure.Search.Documents; var credential new AzureKeyCredential( Environment.GetEnvironmentVariable(SEARCH_API_KEY)); var client new SearchClient( new Uri(Environment.GetEnvironmentVariable(SEARCH_ENDPOINT)), Environment.GetEnvironmentVariable(SEARCH_INDEX_NAME), credential);两种认证方式在查询、索引管理、索引器管理三类客户端上的使用方式一致区别仅在于凭据的构造与安全语义。生产环境应优先DefaultAzureCredential将密钥管理交给托管身份与 Azure RBAC。四、三类客户端的选择Azure.Search.Documents将服务能力划分为三个职责清晰的客户端客户端用途SearchClient查询索引上传 / 更新 / 删除文档SearchIndexClient创建 / 管理索引、同义词映射synonym mapsSearchIndexerClient管理索引器indexers、技能组skillsets、数据源data sources工程上的一般约定索引结构变更使用SearchIndexClient文档与查询使用SearchClientETL 与 AI 扩充使用SearchIndexerClient。三者均支持通过SearchClientOptions等配置对象控制重试、传输与请求头等行为。五、索引创建两种建模方式5.1 方式一FieldBuilder 模型特性推荐先以 C# 类描述文档结构通过特性标注字段行为再由FieldBuilder反射生成索引字段集合实现类型安全的索引定义using Azure.Search.Documents.Indexes; using Azure.Search.Documents.Indexes.Models; // Define model with attributes public class Hotel { [SimpleField(IsKey true, IsFilterable true)] public string HotelId { get; set; } [SearchableField(IsSortable true)] public string HotelName { get; set; } [SearchableField(AnalyzerName LexicalAnalyzerName.EnLucene)] public string Description { get; set; } [SimpleField(IsFilterable true, IsSortable true, IsFacetable true)] public double? Rating { get; set; } [VectorSearchField(VectorSearchDimensions 1536, VectorSearchProfileName vector-profile)] public ReadOnlyMemoryfloat? DescriptionVector { get; set; } } // Create index var indexClient new SearchIndexClient(endpoint, credential); var fieldBuilder new FieldBuilder(); var fields fieldBuilder.Build(typeof(Hotel)); var index new SearchIndex(hotels) { Fields fields, VectorSearch new VectorSearch { Profiles { new VectorSearchProfile(vector-profile, hnsw-algo) }, Algorithms { new HnswAlgorithmConfiguration(hnsw-algo) } } }; await indexClient.CreateOrUpdateIndexAsync(index);关键点VectorSearchDimensions 1536对应 OpenAItext-embedding-ada-002等常见嵌入模型的输出维度需与实际嵌入模型保持一致否则写入向量将失败VectorSearchProfileName必须引用VectorSearch.Profiles中定义的配置名本示例选用 HNSW 算法HnswAlgorithmConfiguration适用于对召回质量要求高、数据集规模适中的场景SDK 同样支持ExhaustiveKnnAlgorithmConfiguration暴力全量计算适合小规模精确验证CreateOrUpdateIndexAsync具备幂等语义重复执行不会报错适合作为迁移脚本反复运行。5.2 方式二手动字段定义不依赖模型类直接以对象初始化器构造字段集合适合动态建模或由外部 schema 驱动索引的场景var index new SearchIndex(hotels) { Fields { new SimpleField(hotelId, SearchFieldDataType.String) { IsKey true, IsFilterable true }, new SearchableField(hotelName) { IsSortable true }, new SearchableField(description) { AnalyzerName LexicalAnalyzerName.EnLucene }, new SimpleField(rating, SearchFieldDataType.Double) { IsFilterable true, IsSortable true }, new SearchField(descriptionVector, SearchFieldDataType.Collection(SearchFieldDataType.Single)) { VectorSearchDimensions 1536, VectorSearchProfileName vector-profile } } };注意向量字段在手动定义时必须使用SearchField而非SimpleField并以SearchFieldDataType.Collection(SearchFieldDataType.Single)声明为 float 集合类型。该索引对象随后同样通过SearchIndexClient.CreateOrUpdateIndexAsync提交。六、文档操作上传、合并与删除SearchClient提供细粒度的文档写入 API并支持批量事务式提交var searchClient new SearchClient(endpoint, indexName, credential); // Upload (add new) var hotels new[] { new Hotel { HotelId 1, HotelName Hotel A } }; await searchClient.UploadDocumentsAsync(hotels); // Merge (update existing) await searchClient.MergeDocumentsAsync(hotels); // Merge or Upload (upsert) await searchClient.MergeOrUploadDocumentsAsync(hotels); // Delete await searchClient.DeleteDocumentsAsync(hotelId, new[] { 1, 2 }); // Batch operations var batch IndexDocumentsBatch.Create( IndexDocumentsAction.Upload(hotel1), IndexDocumentsAction.Merge(hotel2), IndexDocumentsAction.Delete(hotel3)); await searchClient.IndexDocumentsAsync(batch);语义对照UploadDocumentsAsync按主键新增主键已存在则报错或覆盖取决于索引配置与 API 语义MergeDocumentsAsync仅更新已存在的文档字段需确保传入对象包含主键MergeOrUploadDocumentsAsync存在则合并、不存在则新增即幂等的 upsertDeleteDocumentsAsync可传主键集合或完整文档对象集合IndexDocumentsBatch允许在一次请求中混用 upload / merge / delete 动作显著降低往返次数、提升吞吐。技能文档的 Best Practices 明确建议批量文档操作以获得更高吞吐Batch document operations for better throughput这正是IndexDocumentsBatch的用途。七、搜索模式详解7.1 基础搜索过滤、排序、投影与分页var options new SearchOptions { Filter rating ge 4, OrderBy { rating desc }, Select { hotelId, hotelName, rating }, Size 10, Skip 0, IncludeTotalCount true }; SearchResultsHotel results await searchClient.SearchAsyncHotel(luxury, options); Console.WriteLine($Total: {results.TotalCount}); await foreach (SearchResultHotel result in results.GetResultsAsync()) { Console.WriteLine(${result.Document.HotelName} (Score: {result.Score})); }参数说明FilterOData 风格$filter表达式配合字段的IsFilterable特性使用OrderBy排序字段配合IsSortable使用可叠加多个字段Select仅返回指定字段减少传输与反序列化成本配合IsHidden可进一步控制可见性Size/Skip服务端分页$top/$skipIncludeTotalCount返回命中总数用于 UI 展示共 N 条结果。7.2 分面导航Faceted Search分面用于在电商与门户类站点中呈现可聚合的筛选维度var options new SearchOptions { Facets { rating,count:5, category } }; var results await searchClient.SearchAsyncHotel(*, options); foreach (var facet in results.Value.Facets[rating]) { Console.WriteLine($Rating {facet.Value}: {facet.Count}); }rating,count:5表示对rating字段分面并最多返回 5 个分面桶查询词使用*时表示匹配全部文档配合分面即可实现无关键词的目录浏览体验分面字段必须预先声明IsFacetable true。7.3 自动补全与建议Autocomplete Suggestions自动补全与建议依赖索引中配置的建议器suggester即索引定义中的Suggesters集合// Autocomplete var autocompleteOptions new AutocompleteOptions { Mode AutocompleteMode.OneTermWithContext }; var autocomplete await searchClient.AutocompleteAsync(lux, suggester-name, autocompleteOptions); // Suggestions var suggestOptions new SuggestOptions { UseFuzzyMatching true }; var suggestions await searchClient.SuggestAsyncHotel(lux, suggester-name, suggestOptions);AutocompleteMode.OneTermWithContext基于上文补全单个词项另有OneTerm无上下文与TwoTerms双词模式SuggestAsync返回结构化建议结果UseFuzzyMatching true可容忍拼写错误如 luxry → luxury两者均以建议器名称示例中的suggester-name定位建议器覆盖的字段需先声明为SearchableField。八、向量搜索相似度检索向量搜索适用于 RAG、相似内容推荐等场景需要预先为每个文档生成嵌入向量并写入索引的向量字段using Azure.Search.Documents.Models; // Pure vector search var vectorQuery new VectorizedQuery(embedding) { KNearestNeighborsCount 5, Fields { descriptionVector } }; var options new SearchOptions { VectorSearch new VectorSearchOptions { Queries { vectorQuery } } }; var results await searchClient.SearchAsyncHotel(null, options);VectorizedQuery接收调用方计算好的嵌入向量ReadOnlyMemoryfloat对应索引中VectorSearchField字段KNearestNeighborsCount 5返回 Top-K 近邻Fields指定参与向量匹配的向量字段可多个查询文本传null表示纯向量检索、不混入关键词查询除VectorizedQuery向量查询外SDK 还支持VectorizableTextQuery文本查询由服务端内联向量化需要配置内置向量化器技能文档在参考文件中将其归入向量搜索、混合搜索、向量化器专题。九、语义搜索自然语言排序与答案语义排序semantic ranker使用语言模型对候选结果重排并可生成字幕captions与答案answers。启用前需在索引定义中配置SemanticConfigurationvar options new SearchOptions { QueryType SearchQueryType.Semantic, SemanticSearch new SemanticSearchOptions { SemanticConfigurationName my-semantic-config, QueryCaption new QueryCaption(QueryCaptionType.Extractive), QueryAnswer new QueryAnswer(QueryAnswerType.Extractive) } }; var results await searchClient.SearchAsyncHotel(best hotel for families, options); // Access semantic answers foreach (var answer in results.Value.SemanticSearch.Answers) { Console.WriteLine($Answer: {answer.Text} (Score: {answer.Score})); } // Access captions await foreach (var result in results.Value.GetResultsAsync()) { var caption result.SemanticSearch?.Captions?.FirstOrDefault(); Console.WriteLine($Caption: {caption?.Text}); }QueryType SearchQueryType.Semantic是开启语义排序的开关SemanticConfigurationName指向索引中定义的语义配置含标题、内容、关键词字段映射QueryCaptionType.Extractive与QueryAnswerType.Extractive分别启用抽取式字幕与抽取式答案结果中的SemanticSearch.Answers为服务端生成的直接答案Captions为每条结果的高亮摘要二者均带置信度分数。十、混合搜索关键词 向量 语义的融合混合检索在同一请求中同时携带全文查询、向量查询与语义排序配置是文档推荐的最佳相关性组合var vectorQuery new VectorizedQuery(embedding) { KNearestNeighborsCount 5, Fields { descriptionVector } }; var options new SearchOptions { QueryType SearchQueryType.Semantic, SemanticSearch new SemanticSearchOptions { SemanticConfigurationName my-semantic-config }, VectorSearch new VectorSearchOptions { Queries { vectorQuery } } }; // Combines keyword search, vector search, and semantic ranking var results await searchClient.SearchAsyncHotel(luxury beachfront, options);执行链路说明全文检索引擎按关键词luxury beachfront召回候选向量查询按embedding的相似度召回 Top-K服务端将两类候选合并后交给语义排序器按查询意图重排输出最终结果。三者协同既保留了精确关键词命中又具备语义泛化与近邻召回能力是当前 RAG 类应用检索层的常见落地方案。十一、字段特性参考技能文档将索引建模中的核心特性整理为对照表此处完整保留并补充使用要点特性用途说明SimpleField不可搜索字段用于过滤、排序、分面不参与全文检索适合 ID、数值、枚举类字段SearchableField全文可搜索字段默认参与分词与全文匹配可配合AnalyzerName指定分析器VectorSearchField向量嵌入字段需同时指定VectorSearchDimensions与VectorSearchProfileNameIsKey true文档主键每个索引必填且唯一对应文档中的key字段用于 upsert / delete 定位IsFilterable true启用$filter表达式未开启的字段无法在 Filter 中使用IsSortable true启用$orderby未开启的字段无法参与 OrderByIsFacetable true启用分面导航未开启的字段不会出现在 Facets 结果中IsHidden true从搜索结果中排除常用于descriptionVector等不直接展示的内部字段AnalyzerName指定文本分析器如LexicalAnalyzerName.EnLucene英文 Lucene 分析器可替换为标准、语言特定或自定义分析器IsHidden与Select配合可同时实现参与检索但不出现在默认结果投影中的字段管理。十二、错误处理SDK 统一通过RequestFailedException暴露服务端错误可依据 HTTP 状态码与错误码做精细化分支using Azure; try { var results await searchClient.SearchAsyncHotel(query); } catch (RequestFailedException ex) when (ex.Status 404) { Console.WriteLine(Index not found); } catch (RequestFailedException ex) { Console.WriteLine($Search error: {ex.Status} - {ex.ErrorCode}: {ex.Message}); }ex.StatusHTTP 状态码404 常见于索引不存在或终结点拼写错误403 常见于认证失败或 RBAC 未授权ex.ErrorCode服务端返回的结构化错误码可用于程序化告警建议在重试策略之外再叠加业务级降级逻辑如索引未就绪时回退到备选数据源。十三、最佳实践总结技能文档给出的 7 条最佳实践是生产环境落地的直接依据生产环境使用DefaultAzureCredential替代 API Key避免密钥泄露面使用FieldBuilder与模型特性获得类型安全的索引定义编译期即可发现字段声明错误使用CreateOrUpdateIndexAsync保证索引创建的幂等性便于脚本化与重复执行批量文档操作提升写入吞吐优先使用IndexDocumentsBatch使用Select只返回所需字段降低传输与内存开销配合IsHidden控制投影为自然语言查询配置语义搜索提升长句、口语化查询的相关性组合向量 关键词 语义以获得最佳检索相关性即本文第十节的混合搜索。十四、参考文件与后续深入方向技能文档声明了两个专题参考文件文件内容references/vector-search.md向量搜索、混合搜索、向量化器references/semantic-search.md语义排序、字幕、答案在当前仓库副本中该技能目录仅包含 SKILL.md 单文件skill 目录布局以仓库实际内容为准上述参考文件可理解为技能的后续深入阅读清单。若需进一步探索仓库内其他语言实现可对照阅读同系列的 azure-search-documents-py 与 azure-search-documents-ts 技能文档它们在索引、查询与语义配置模型上高度对应便于多语言团队保持一致的实现口径。十五、使用时机与限制使用时机当任务与使用 Azure AI Search 构建搜索能力明确匹配索引管理、文档写入、全文/向量/语义/混合检索、建议器与分面配置等时启用本技能。限制与边界仅在任务范围与本技能描述清晰一致时使用避免误用于其他搜索服务技能输出不能替代针对具体环境的验证、测试与专家评审索引性能、配额、区域可用性等需在真实服务上确认当关键输入终结点、凭据、索引名、权限、安全边界或成功标准缺失时应停止并请求澄清而非臆测默认值。赞分享AI 技能AI 插件【免费下载链接】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点击查看免费下载相关推荐Azure AI Search TypeScript SDK 实战指南用 azure/search-documents 构建向量、混合与语义搜索应用Azure AI Search TypeScript SDK 实战指南用 azure/search documents 构建向量、混合与语义搜索应用 本指南AI 技能AI 插件使用 Azure AI Search Python SDK 构建向量、混合与语义检索基于 agentic-awesome-skills 的技能实战指南使用 Azure AI Search Python SDK 构建向量、混合与语义检索基于 agentic awesome skills 的技能实战指南 导读AI 技能AI 插件Convex 向量搜索实战指南基于 vector-search 示例应用从零构建语义搜索Convex 向量搜索实战指南基于 vector search 示例应用从零构建语义搜索 本文以本仓库 npm packages/demos/vector s数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考