ai-agents-for-beginners

Azure AI 搜尋設定指南

本指南將協助您透過 Azure 入口網站設定 Azure AI 搜尋。請依照以下步驟建立並設定您的 Azure AI 搜尋服務。

前置條件

在開始之前，請確保您擁有以下條件：

步驟1：建立 Azure 儲存帳戶

  1. 請參考這個說明，建立 Azure 儲存帳戶 來建立新的 Azure 儲存帳戶。 注意：請確定儲存帳戶類型為 Standard General Purpose V2。

步驟2：建立 Azure AI 搜尋服務

  1. 登入 Azure 入口網站。
  2. 在左側導覽窗格中，點選 建立資源。
  3. 在搜尋框中輸入「Azure AI 搜尋」，並從結果列表中選擇 Azure AI 搜尋。
  4. 點選 建立 按鈕。
  5. 在 基礎知識 標籤頁，提供以下資訊：
    • 訂閱：選擇您的 Azure 訂閱。
    • 資源群組：建立新的資源群組或選擇現有的。
    • 資源名稱：輸入搜尋服務的唯一名稱。
    • 區域：選擇最接近您的使用者的區域。
    • 定價層：選擇符合您需求的定價層。您可以從免費層開始進行測試。
  6. 點選 查看 + 建立。
  7. 檢查設定後，點選 建立 來建立搜尋服務。

步驟3：開始使用 Azure AI 搜尋

  1. 部署完成後，前往 Azure 入口網站中的您的搜尋服務。
  2. 在搜尋服務概觀窗格，複製其 URL。應該如下所示 https://<service-name>.search.windows.net。
  3. （建議） 啟用使用 Microsoft Entra ID (RBAC) 的無金鑰存取，如下方步驟4所示 — 無需金鑰。本指南的範例會建立/更新索引及上傳文件，這需要 搜尋服務參與者 與 搜尋索引資料參與者 角色（或針對金鑰驗證，使用 主要管理金鑰 — 非查詢金鑰）。如果您無法使用 RBAC，請開啟 設定 > 金鑰 頁面並複製 主要管理金鑰。
  4. 依照 快速入門指南 的步驟建立索引、上傳資料並執行搜尋。

步驟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 Identity for Python：

    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 角色型存取控制使用您的 `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 翻譯服務 Co-op Translator 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。

This site is open source. Improve this page.