ai-agents-for-beginners

Azure AI 搜索设置指南

本指南将帮助您使用 Azure 门户设置 Azure AI 搜索。请按照以下步骤创建并配置您的 Azure AI 搜索服务。

先决条件

在开始之前，请确保您拥有以下内容：

第一步：创建 Azure 存储帐户

  1. 按照此指南，创建 Azure 存储帐户，创建一个新的 Azure 存储帐户。 注意：确保存储帐户的类型为 Standard General Purpose V2。

第二步：创建 Azure AI 搜索服务

  1. 登录 Azure 门户。
  2. 在左侧导航窗格中，点击 创建资源。
  3. 在搜索框中输入 “Azure AI Search”，并从结果列表中选择 Azure AI Search。
  4. 点击 创建 按钮。
  5. 在 基本信息 选项卡中，填写以下信息：
    • 订阅：选择您的 Azure 订阅。
    • 资源组：创建新的资源组或选择现有的资源组。
    • 资源名称：输入您的搜索服务的唯一名称。
    • 区域：选择离您的用户最近的区域。
    • 定价层：选择适合您需求的定价层。测试阶段可以选择免费层。
  6. 点击 查看 + 创建。
  7. 审核设置后，点击 创建 以创建搜索服务。

第三步：开始使用 Azure AI 搜索

  1. 部署完成后，导航到 Azure 门户中的您的搜索服务。
  2. 在搜索服务概览窗格中，复制 URL。格式应为 https://<service-name>.search.windows.net。
  3. （推荐） 启用使用 Microsoft Entra ID（基于角色的访问控制，RBAC）的无密钥访问，如下第 4 步所示 —— 无需访问密钥。本指南中的示例创建/更新索引并上传文档，这些操作需要 搜索服务贡献者 和 搜索索引数据贡献者 角色（或者，对于基于密钥的身份验证，需要 主管理员密钥 —— 不是查询密钥）。仅当您无法使用 RBAC 时，打开 设置 > 密钥 页面并复制 主管理员密钥。
  4. 按照 快速入门指南 页面中的步骤，创建索引、上传数据并执行搜索。

第四步：使用 Azure AI 搜索工具

Azure AI 搜索集成了多种工具以增强您的搜索功能。您可以使用 Azure CLI、Python SDK、.NET SDK 及其他工具进行高级配置和操作。

使用 Azure CLI

  1. 按照 安装 Azure CLI 的说明安装 Azure CLI。

  2. 使用以下命令登录 Azure CLI：

    az login

  3. （推荐）启用使用 Microsoft Entra ID（RBAC）的无密钥访问：

     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 搜索。

  4. （回退方案）基于密钥的身份验证 —— 仅当您无法使用 RBAC 时，才存储管理员密钥：

将 Azure AI 搜索实例的端点和 API 密钥存储到环境变量。

```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

  1. 安装 Azure 认知搜索客户端库和 Azure 身份验证库：

    pip install azure-search-documents azure-identity

  2. 使用以下 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` 身份。
 # 需要“搜索服务贡献者”和“搜索索引数据贡献者”角色。
 credential = DefaultAzureCredential()
 # 备用（基于密钥的认证）：
 # 来自 azure.core.credentials 的 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

  1. 运行以下命令创建索引并上传文档：

     dotnet run ./AzureSearch.cs

    下面的 .NET 示例使用 DefaultAzureCredential，可使用您在本地开发期间通过 az login 登录 Azure CLI 的身份。

  2. 这是 AzureSearch.cs 的 .NET 代码：

     #: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";

 // Keyless (recommended): uses your `az login` identity via Entra ID RBAC.
 // Requires the "Search Service Contributor" and "Search Index Data Contributor" roles.
 var credential = new DefaultAzureCredential();
 // Fallback (key-based auth): the `using Azure;` directive above already imports
 // AzureKeyCredential; replace the credential line above with:
 // var credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_SEARCH_API_KEY")!);
 var indexClient = new SearchIndexClient(serviceEndpoint, credential);

 var fields = new List<SearchField>()
 {
     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 认知搜索文档。

免责声明： 本文件由 AI 翻译服务 Co-op Translator 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。

This site is open source. Improve this page.