Azure AI Search .NET 开发技能
为 .NET 应用提供 Azure AI Search 的全文、向量、语义和混合检索实现指南。
文档提供 Entra 凭据与 API key 两种路径，并建议生产环境优先使用 DefaultAzureCredential；仓库有 MIT 许可证和安全报告入口。扣分原因是未明确最小 RBAC 权限、用户确认、敏感数据/密钥托管、删除与索引变更的回滚策略，也未充分披露数据流和外部 Azure 影响。
涵盖安装、认证、索引、CRUD、基础/向量/语义/混合搜索及错误处理，主路径结构基本一致。扣分原因是仅静态阅读，未执行验证；版本适配、环境变量为空、服务能力/配额限制和若干 API 细节缺少可诊断说明，因此不超过静态上限10分。
触发词、目标 SDK、客户端选择和主要使用场景描述清楚，覆盖搜索应用的多种模式。扣分原因是未明确非适用场景、输入输出契约、服务层级/区域限制、中文查询支持和中国大陆网络可达性；对需要完整部署或索引运维的用户边界说明不足。
采用安装、认证、客户端选择、操作模式、最佳实践和 references 的分层结构，含 MIT、作者及 1.0.0 版本元数据，并链接两个参考文件。扣分原因是没有变更日志、维护责任和更新路径的明确说明，当前版本声明缺少日期/来源，FAQ、故障排查和依赖兼容矩阵不足。
示例直接覆盖常见 Azure.Search.Documents .NET 任务，包含可改写的 C# 代码和错误处理，静态上可支持核心编码工作。扣分原因是示例缺少完整可运行项目、embedding 来源、索引前置配置和服务端权限/计费说明，直接使用前仍需较多环境适配；按静态校准最高不超过7分。
技能文件包含具体 API、版本、代码和相对参考文件，仓库还提供 CI/evaluation 工作流及测试基础设施。扣分原因是所给材料没有该技能专属的已提交测试或第三方执行结果，仓库级测试不能证明此路径的关键示例，且缺少逐项来源与事实/推断分离；静态评估不超过5分。
- 不要将示例视为已验证的可运行代码；应针对锁定的 Azure.Search.Documents 版本编译并测试关键路径。
- 生产环境应使用最小 RBAC 和安全的密钥托管，删除文档或修改索引前应有明确确认、备份和恢复方案。
- 需单独确认目标 Azure 区域、服务层级、语义/向量功能、中文检索效果以及中国大陆网络可达性。
它能做什么 & 适用场景
该技能面向使用 Azure.Search.Documents SDK 构建搜索应用的 .NET 开发者。它涵盖 SearchClient、SearchIndexClient 和 SearchIndexerClient，涉及索引管理、文档操作、全文搜索、向量搜索、语义搜索和混合搜索。内容还包括 Microsoft Entra 身份验证与 API 密钥认证、字段定义、自动补全、建议、分面和错误处理。适合已经拥有 Azure AI Search 服务、需要快速编写 C# 搜索代码的项目；它不负责创建 Azure 资源或完整部署应用。
指导安装 Azure.Search.Documents 和 Azure.Identity 包，配置搜索终结点、索引名称及认证变量；使用 C# 创建 SearchClient、SearchIndexClient 和 SearchIndexerClient；定义和更新索引字段、向量配置及语义配置；上传、合并、删除文档并执行批量操作；编写带筛选、排序、分页、字段选择和分面的查询；实现自动补全、建议、纯向量、语义及关键词加向量的混合搜索；处理 RequestFailedException，包括索引不存在的 404 情况。
- 使用 C# 开发酒店、产品或内容目录，需要全文检索、筛选、排序和分面导航的后端开发者。
- 已有文本嵌入并希望在 Azure AI Search 中实现近邻向量检索的 .NET 团队。
- 需要将关键词搜索、向量搜索和语义排序结合起来改善自然语言查询结果的应用开发者。
- 需要通过 SearchIndexClient 管理索引、字段、同义词映射或向量配置的 Azure 开发者。
- 需要通过 SearchIndexerClient 管理数据源、索引器和技能集的 .NET 工程师。
优缺点一览
- 覆盖从索引创建到查询和文档维护的完整 SDK 代码路径。
- 同时提供全文、向量、语义和混合搜索示例。
- 同时说明 DefaultAzureCredential 和 AzureKeyCredential 两种认证方式。
- 包含 FieldBuilder、批量操作、分面、自动补全、建议和常见错误处理。
- 仅面向 Azure.Search.Documents 的 .NET/C# 开发，不覆盖其他语言 SDK。
- 不提供 Azure AI Search 资源创建、网络配置或应用部署流程。
- 向量搜索和语义搜索的详细参考文件内容未包含在给定材料中。
- 材料没有说明该技能在具体编码代理或运行环境中的版本兼容范围。
如何安装
在项目中运行：
dotnet add package Azure.Search.Documents
dotnet add package Azure.Identity
若安装整个 Agent Skills 集合，可运行：
npx skills add microsoft/skills
随后在选择的 Agent 配置目录中选择所需技能。该技能位于 .github/plugins/azure-sdk-dotnet/skills/azure-search-documents-dotnet/SKILL.md。
如何使用
在支持 Agent Skills 的编码代理中，将该技能目录放入代理的技能目录，然后使用类似以下提示触发："使用 Azure.Search.Documents 为我的 C# 酒店目录实现混合搜索，包含索引定义、文档批量上传和语义配置。" 使用时需要提供 SEARCH_ENDPOINT 和 SEARCH_INDEX_NAME；使用 DefaultAzureCredential 时还需按环境配置 AZURE_TOKEN_CREDENTIALS，使用 API 密钥认证时配置 SEARCH_API_KEY。具体 Azure 资源创建和部署步骤未在该技能中说明。