使用 Azure CLI 管理您的 Foundry IQ(Azure AI 搜尋服務)服務

備註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

您可以在 Windows、macOS、Linux 或 Azure Cloud Shell 上執行 Azure CLI 指令與腳本,以建立並設定 Foundry IQ(Azure AI 搜尋服務)。

使用 az search module 執行下列工作:

以下資訊回答了關於前述清單中未提及的常見問題。

您無法以程式設計方式或在 Azure 入口網站中變更服務的名稱或區域。 建立服務時會配置專用資源,因此變更基礎硬體(位置或節點類型)需要新的服務。

備註

搜尋管理 REST API 和 Azure 入口網站支援變更定價層。 目前,您只能在基本層與標準層 (S1、S2 和 S3) 之間切換。

您無法使用工具或 API 在服務之間傳輸索引之類的內容。 若要在服務中以程式化方式建立內容,必須透過搜尋服務 REST API 或類似的 Azure SDK for .NET 等 SDK。 雖然內容移轉沒有專用命令,您仍可撰寫呼叫 REST API 或用戶端程式庫的指令碼,在新服務上建立並載入索引。

az search 模組通常無法使用預覽管理功能。 如果您想使用預覽功能,請使用管理 REST API 和預覽的 API 版本。

必要條件

Azure CLI 版本會在 GitHub 上列出。

az search 模組會擴充 Azure CLI,使其與穩定版本的搜尋管理 REST API 完全同等。

列出訂閱中的服務

下列來自az resource的命令會傳回有關已在您的訂閱中佈建的現有資源和服務的資訊。 如果您不知道已建立多少 Foundry IQ 服務,這些指令會回傳相關資訊,省去您前往 Azure 入口網站的麻煩。

第一個指令會回傳所有 Foundry IQ 服務。

az resource list --resource-type Microsoft.Search/searchServices --output table

從服務清單中返回特定資源的資訊。

az resource list --name <search-service-name>

列出所有 az search 命令

您可以從 CLI 中檢視 az search (機器翻譯) 內可用的子群組和命令資訊。 或者,您也可以檢閱這份文件。

若要檢視 az search 內可用的子群組,請執行以下命令。

az search --help

回應看起來應該類似以下輸出。

Group
    az search : Manage Azure AI Search.

Subgroups:
    admin-key                    : Manage Azure AI Search admin keys.
    offering                     : Manage Azure AI Search offerings.
    private-endpoint-connection  : Manage Azure AI Search private endpoint connections.
    private-link-resource        : Manage Azure AI Search private link resources.
    query-key                    : Manage Azure AI Search query keys.
    service                      : Manage Service.
    shared-private-link-resource : Manage Azure AI Search shared private link resources.
    usage                        : Manage Usage.

每個子群組中有多個命令可供使用, 執行下方這一行即可查看 service 子群組可用的命令。

az search service --help

您也可以查看特定命令可使用的引數。

az search service create --help

取得 Foundry IQ 服務資訊

如果您知道包含 Foundry IQ 服務的資源群組,請執行 az 搜尋服務 show 以回傳服務定義,包括名稱、區域、層級,以及複本與分割區數。 在此指令中,請提供包含 Foundry IQ 服務的資源群組。

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

建立或刪除服務

若要 建立新的 Foundry IQ 服務,請使用 az search service create 指令。

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

結果看起來應該類似以下輸出:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete 會移除 Foundry IQ 服務及其資料。

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

使用 IP 規則建立服務

根據您的安全需求,您可能想建立一個已 設定 IP 防火牆的 Foundry IQ 服務。 做法是將公用 IP (v4) 位址或 CIDR 範圍傳遞給 ip-rules 引數,如下所示。 規則必須以半形逗號 (,) 或半形分號 (;) 分隔。

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

使用系統指派的受控識別建立服務

在部分情況下,例如使用受控識別連線至資料來源時,您必須啟用系統指派的受控識別。 做法是將 --identity-type SystemAssigned 新增至命令。

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

使用私人端點建立服務

Foundry IQ 的私有端點允許虛擬網路上的用戶端透過 Private Link 安全地存取搜尋索引中的資料。 私有端點會使用來自 虛擬網路位址空間 的一個 IP 位址供您的 Foundry IQ 服務使用。 用戶端與 Foundry IQ 服務之間的網路流量會經過虛擬網路以及 Microsoft 骨幹網路上的私有連結,從而消除來自公共網際網路的暴露。 欲了解更多資訊,請參閱為 Foundry IQ 建立私有端點的文件。

以下範例示範如何建立帶有私有端點的 Foundry IQ 服務。

首先,部署一個 Foundry IQ 服務,設定 PublicNetworkAccess 為 Disabled。

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

接下來,建立虛擬網路和私人端點。

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>  

最後,建立私人 DNS 區域。

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

如需深入了解如何在 Azure CLI 中建立私人端點,請參閱私人連結快速入門。

管理私人端點連線

除了建立私人端點連線,您還可以 show、update 並 delete 連線。

若要取得私有端點連線並查看其狀態,請使用 az search private-endpoint-connection show。

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

若要更新連線,請使用az search private-endpoint-connection update。 下列範例將私人端點連線設定為已拒絕:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

若要刪除專用端點連線,請使用 az search private-endpoint-connection delete。

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

使用機密運算建立服務

機密運算 是一種可選的計算類型,用於保護正在使用的資料。 設定完成後,您的 Foundry IQ 服務會部署在機密虛擬機(DCasv5 或 DCesv5)上,而非標準虛擬機。 此計算類型也會針對計費層級產生 10% 附加費。 如需詳細資訊,請參閱價格網頁。

對於日常使用,不需要機密運算。 我們只建議針對嚴格的法規、合規性或安全性需求使用此運算類型。 如需詳細資訊,請參閱 機密運算使用案例。

計算類型在您的 Foundry IQ 服務生命週期內固定不變。 若要永久設定機密運算,請將屬性設定 compute-type 為 confidential 在新服務上。

az search service create \
  --name <search-service-name> \
  --resource-group <search-service-resource-group-name> \
  --location <search-service-region> \
  --sku basic \
  --compute-type confidential

重新產生系統管理金鑰

若要變換系統管理 API 金鑰 (機器翻譯),請使用 az search admin-key renew (機器翻譯)。 每項服務各會建立兩個系統管理金鑰來進行已驗證的存取。 每項要求都必須使用金鑰。 這兩個管理金鑰在功能上等同,賦予 Foundry IQ 服務完全寫入權限,並能擷取任何資訊,或建立與刪除任何物件。 之所以產生兩個金鑰,是為了能在使用其中之一的期間更換另一個金鑰。

您每次只能重新產生一個金鑰,可以是 primary 或 secondary 金鑰。 若要讓服務不受中斷,請記得更新所有用戶端程式碼,藉此在主要金鑰變換期間使用次要金鑰。 請避免於作業進行時變更金鑰。

您可能也料想得到,如果您在沒有更新用戶端程式碼的情況下重新產生金鑰,使用舊金鑰的要求就會失敗。 重新產生所有新金鑰並不會永久鎖定您的服務,您仍然可以透過 Azure 入口網站 存取服務。 重新產生主要和次要金鑰後,您就可更新用戶端程式碼來使用新的金鑰,作業也能因此繼續進行。

該服務會產生 API 金鑰的值。 你無法提供供 Foundry IQ 使用的自訂金鑰。 同樣地,管理員 API 金鑰也沒有使用者定義的名稱。 金鑰的參考對象都是固定字串,不是 primary 就是 secondary。

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

結果看起來應該會類似以下的輸出。 即使您一次只變更一個金鑰,系統依然會傳回兩個金鑰。

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

建立或刪除查詢金鑰

若要建立查詢 API 金鑰,以從用戶端應用程式對 Foundry IQ 索引進行唯讀存取,請使用 az search query-key create。 查詢金鑰是用來驗證特定索引,以便擷取搜尋結果。 查詢金鑰無法授與服務上其他項目 (例如索引、資料來源或索引子) 唯讀存取權。

你不能提供 Foundry IQ 要使用的金鑰。 API 金鑰會由服務產生。

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

調整複本和分割區

若要增加或減少複本和分割區,請使用 az search service update。 增加複本或分割區會提高帳單費用,包括固定和變動費用。 如果您暫時需要額外的處理能力,可增加複本和分割區來處理工作負載。 入口網站 [概觀] 頁面的監視區域有查詢延遲、每秒查詢和節流的圖格,會指出目前的容量是否足夠。

新增或移除資源處理需要一些時間來完成。 調整容量的過程會於背景進行,使現有的工作負載不受干擾。 一旦額外容量準備就緒,就會立即用於傳入的要求,無需進一步設定。

移除容量可能會造成中斷, 建議於減少容量前停下所有編製索引和索引子工作,避免要求遭到捨棄。 如果無法這麼做,建議您以漸進式方法減少容量,一次減少一個複本和分割區,直到達到新的目標層級為止。

命令一經提交,即無法中途終止。 您必須等候命令完成,才能修改計數。

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

除了更新複本和分割區計數之外,您也可以更新 ip-rules、public-access 和 identity-type。

透過 Foundry IQ API 建立的安全資源私有端點稱為 共享 Private Link 資源。 這是因為您已針對與 Azure Private Link 服務整合的資源 (例如儲存體帳戶)「共用」存取權。

如果你在 Foundry IQ 中使用索引器來索引資料,且資料來源位於私人網路上,你可以建立一個外發 私有端點連線 來存取資料。

您可以在這裡找到可從 Foundry IQ 建立外發私有端點的 Azure 資源完整清單,以及相關的群組 ID 值。

若要建立共用私密連結資源,請使用 az search shared-private-link-resource create。 請記住,執行此命令前,可能須先為資料來源進行部分設定。

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve" 

若要檢索共用私人連結資源並檢視其狀態,請使用 az search shared-private-link-resource list。

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

您必須先使用下列命令來核准連線,之後才能使用。 私人端點連線的識別碼必須從子資源擷取。 在這種情況下,我們會從 az storage 取得連線識別碼。

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

若要刪除共享的私有連結資源,請使用 az search shared-private-link-resource delete。

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

如需設定共用私人連結資源的詳細資料,請參閱透過私人端點建立索引子連線。

下一步

建置索引,使用 Azure 入口網站、REST API 或 .NET SDK 查詢索引。