原文出处：Azure AI Search Setup 原作者：Microsoft · 许可证：MIT License 中文译本由诸葛AI学院整理，仅供学习参考，版权归原作者与微软所有。
Azure AI 搜索配置指南
这份指南会帮你在 Azure 门户（Azure portal）里配置 Azure AI 搜索。按下面的步骤创建并配置你的 Azure AI 搜索服务。
前置条件
开始之前，请确认你已经具备：
- 一个 Azure 订阅。如果没有 Azure 订阅，可以在 Azure 免费账户 注册一个。
第 1 步：创建 Azure 存储账户
- 按照 创建 Azure 存储账户 这份说明，新建一个 Azure 存储账户（Azure Storage Account）。
注意：请确保存储账户的类型是 Standard General Purpose V2（标准常规用途 V2）。
第 2 步：创建 Azure AI 搜索服务
- 登录 Azure 门户。
- 在左侧导航栏中点击 Create a resource（创建资源）。
- 在搜索框中输入 "Azure AI Search"，然后从结果列表里选择 Azure AI Search。
- 点击 Create（创建）按钮。
- 在 Basics（基本）选项卡中填写以下信息： - Subscription（订阅）：选择你的 Azure 订阅。 - Resource group（资源组）：新建一个资源组，或者选择已有的。 - Resource name（资源名称）：为你的搜索服务输入一个唯一的名字。 - Region（区域）：选择离你的用户最近的区域。 - Pricing tier（定价层）：选择符合你需求的定价层。测试阶段可以先用 Free（免费）层。
- 点击 Review + create（查看 + 创建）。
- 检查设置，然后点击 Create 完成搜索服务的创建。
第 3 步：上手 Azure AI 搜索
- 部署完成后，在 Azure 门户中进入你的搜索服务。
- 在搜索服务的概览页里复制 URL。它看起来像
https://<service-name>.search.windows.net。 - （推荐） 按下面第 4 步所示，用 Microsoft Entra ID（RBAC，基于角色的访问控制）开启免密钥访问——不需要密钥。本指南的示例会创建/更新索引（index）并上传文档，这需要 Search Service Contributor（搜索服务参与者）和 Search Index Data Contributor（搜索索引数据参与者）两个角色；如果你走基于密钥的认证，则需要 primary admin key（主管理员密钥）——而不是 query key（查询密钥）。只有在无法使用 RBAC 时，才打开 Settings > Keys（设置 > 密钥）页面并复制 primary admin key（主管理员密钥）。
- 按照 快速入门指南 页面的步骤，创建一个索引、上传数据，并执行一次检索（retrieval）。
第 4 步：使用 Azure AI 搜索工具
Azure AI 搜索可以和多种工具集成，用来增强你的搜索能力。你可以用 Azure CLI、Python SDK、.NET SDK 以及其他工具做更高级的配置和操作。
使用 Azure CLI
- 按照 安装 Azure CLI 的说明安装 Azure CLI。
- 用下面的命令登录 Azure CLI：
bash
az login
3. （推荐）用 Microsoft Entra ID（RBAC）开启免密钥访问：
```bash
az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey
az role assignment create --assignee <your-user-or-principal-id> --role "Search Service Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
az role assignment create --assignee <your-user-or-principal-id> --role "Search Index Data Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
# az search service show 没有 "endpoint" 字段，用服务名拼出 URL。
export AZURE_SEARCH_SERVICE_ENDPOINT="https://<service-name>.search.windows.net"
```
开启 RBAC 后，下面 Python 和 .NET SDK 的示例都用 `DefaultAzureCredential` 认证。本地开发时，它会直接使用你的 `az login` 会话——不需要管理员密钥。参见 [使用角色连接 Azure AI 搜索](https://learn.microsoft.com/azure/search/search-security-rbac)。
- （备选方案）基于密钥的认证 —— 只有在无法使用 RBAC 时，才把管理员密钥一并存好：
把 Azure AI 搜索实例的 endpoint 和 API key 都存到环境变量里。
```bash
# zsh/bash
# az search service show 没有 "endpoint" 字段，用服务名拼出 URL。
export AZURE_SEARCH_SERVICE_ENDPOINT="https://<service-name>.search.windows.net"
export AZURE_SEARCH_API_KEY=$(az search admin-key show -g <resource-group> --service-name <service-name> --query "primaryKey" -o tsv)
```
```powershell
# PowerShell
# az search service show 没有 "endpoint" 字段，用服务名拼出 URL。
$env:AZURE_SEARCH_SERVICE_ENDPOINT = "https://<service-name>.search.windows.net"
$env:AZURE_SEARCH_API_KEY = $(az search admin-key show -g <resource-group> --service-name <service-name> --query "primaryKey" -o tsv)
```
使用 Python SDK
- 安装 Azure Cognitive Search 客户端库和用于 Python 的 Azure Identity：
bash
pip install azure-search-documents azure-identity
-
用下面的 Python 代码创建索引并上传文档：
```python import os from azure.identity import DefaultAzureCredential from azure.search.documents import SearchClient from azure.search.documents.indexes import SearchIndexClient from azure.search.documents.indexes.models import SearchIndex, SimpleField, edm
service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT") index_name = "sample-index"
免密钥（推荐）：通过 Entra ID RBAC 使用你 az login 的身份。
需要 "Search Service Contributor" 和 "Search Index Data Contributor" 两个角色。
credential = DefaultAzureCredential()
备选方案（基于密钥的认证）：
from azure.core.credentials import AzureKeyCredential
credential = AzureKeyCredential(os.getenv("AZURE_SEARCH_API_KEY"))
index_client = SearchIndexClient(service_endpoint, credential)
fields = [ SimpleField(name="id", type=edm.String, key=True), SimpleField(name="content", type=edm.String, searchable=True), ]
index = SearchIndex(name=index_name, fields=fields)
index_client.create_index(index)
search_client = SearchClient(service_endpoint, index_name, credential)
documents = [ {"id": "1", "content": "Hello world"}, {"id": "2", "content": "Azure Cognitive Search"} ]
search_client.upload_documents(documents) ```
使用 .NET SDK
-
运行下面的命令来创建索引并上传文档：
bash dotnet run ./AzureSearch.cs下面的 .NET 示例使用
DefaultAzureCredential，本地开发时它可以复用你通过az login完成的 Azure CLI 登录。 -
这是
AzureSearch.cs的 .NET 代码：```csharp
:package Azure.Search.Documents@11.*
:package Azure.Identity@1.21.0
:property PublishAot=false
using Azure; using Azure.Identity; using Azure.Search.Documents; using Azure.Search.Documents.Indexes; using Azure.Search.Documents.Indexes.Models;
var serviceEndpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_SEARCH_SERVICE_ENDPOINT")!); var indexName = "sample-index";
// 免密钥（推荐）：通过 Entra ID RBAC 使用你 az login 的身份。 // 需要 "Search Service Contributor" 和 "Search Index Data Contributor" 两个角色。 var credential = new DefaultAzureCredential(); // 备选方案（基于密钥的认证）：上面的
using Azure;指令已经引入了 // AzureKeyCredential；把上面的 credential 那一行替换成： // var credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_SEARCH_API_KEY")!); var indexClient = new SearchIndexClient(serviceEndpoint, credential);var fields = new List
() { new SimpleField("id", SearchFieldDataType.String) { IsKey = true }, new SearchableField("content") }; var index = new SearchIndex(name: indexName, fields: fields);
var response = await indexClient.CreateOrUpdateIndexAsync(index); Console.WriteLine($"Index '{response.Value.Name}' ready.");
var searchClient = new SearchClient(serviceEndpoint, indexName, credential);
var documents = new[] { new { id = "1", content = "Hello world" }, new { id = "2", content = "Azure Cognitive Search" } };
var result = await searchClient.UploadDocumentsAsync(documents); Console.WriteLine($"Uploaded {result.Value.Results.Count} documents to index '{response.Value.Name}'."); ```
想看更详细的信息，请参考以下文档：
小结
你已经用 Azure 门户和集成工具完成了 Azure AI 搜索的配置。接下来可以继续探索 Azure AI 搜索更高级的特性和能力，把你的搜索方案做得更好。
需要更多帮助，请访问 Azure Cognitive Search 文档。