Azure AI 搜尋服務豐富管線中的 AML 技能

文章
09/01/2024

重要

支援對 Azure AI Studio 模型目錄的索引器連線，在補充使用規定下處於公開預覽狀態。預覽 REST API 支援此技能。

AML 技能可讓您使用自訂 Azure Machine Learning (AML) 模型來擴充 AI 擴充。在 AML 模型定型並部署後，AML 技能就會將其整合到 AI 擴充中。

與其他內建技能一樣，AML 技能也有輸入和輸出。輸入作為 JSON 物件傳送至已部署的 AML 線上端點，JSON 物件輸出 JSON 承載作為回應以及成功狀態碼。您的數據會在部署模型的地理位置中處理。預期回應應具有您的 AML 技能所指定的輸出。任何其他的回應會被視為錯誤，並且不會執行任何擴充。

您可以使用 2024-07-01 穩定 API 版本或 2024-05-01-preview API 版本呼叫 AML 技能，以連線到 Azure AI Studio 中的模型目錄。

從 2024-05-01-preview REST API 和 Azure 入口網站開始（亦以 2024-05-01-preview 為目標），Azure AI 搜尋服務引進了 Azure AI Studio 模型目錄向量化工具，以便查詢時間連線至 Azure AI Studio 中的模型目錄。如果您想要使用該向量化程序進行查詢， AML 技能是 使用 Azure AI Studio 模型目錄中模型產生內嵌的索引 對應專案。

在編製索引期間， AML 技能可以連線到模型目錄，以產生索引的向量。查詢時，查詢可以使用向量化程式來連線到相同的模型，以向量化向量查詢的文字字串。在此工作流程中， 應該同時使用 AML 技能與模型目錄向量化程式，以便您將相同的內嵌模型用於編製索引和查詢。如需此工作流程的詳細資訊，請參閱如何使用 Azure AI Studio 的模型實作整合向量化。

注意

對於從 AML 線上端點傳回的某些標準 HTTP 狀態碼，索引子將重試兩次。這些 HTTP 狀態碼為：

503 Service Unavailable
429 Too Many Requests

必要條件

AML 工作區
此工作區中的線上端點 (即時)。

@odata.type

Microsoft.Skills.Custom.AmlSkill

技能參數

這些參數會區分大小寫。您選擇的使用參數，取決於您的 AML 線上端點所需的驗證 (如有)

參數名稱	描述
`uri`	(金鑰驗證需要) JSON 承載傳送至的 AML 線上端點之評分 URI。僅允許 https URI 配置。
`key`	(金鑰驗證需要) AML 線上端點的金鑰。
`resourceId`	(權杖驗證需要)。 AML 線上端點的 Azure Resource Manager 資源識別碼。其格式應為 subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}。
`region`	(權杖驗證的選用項目)。 AML 線上端點所部署的區域。
`timeout`	(選擇性) 指定時，表示進行 API 呼叫的 http 用戶端逾時。其必須格式化為 XSD "dayTimeDuration" 值 ( ISO 8601 持續時間值的受限子集)。例如，`PT60S` 為 60 秒。如果沒有設定，則選擇的預設值為 30 秒。逾時最高可設定為 230 秒，最低 1 秒。
`degreeOfParallelism`	(選用) 指定時，指示索引子與您提供的端點平行進行的呼叫數。如果端點在過高的要求負載下失敗，則可以减小此值。如果您的端點能够接受更多的要求，並且您希望提高索引子的效能，則可以增加它。若未設定，將會使用預設值 0.5。 degreeOfParallelism 最高可設定為 10，最低為 1。

要使用哪些技能參數

需要哪些 AML 技能參數取決於您的 AML 線上端點使用的驗證 (如有)。 AML 線上端點提供兩個驗證選項：

金鑰式驗證。提供靜態金鑰，驗證來自 AML 技能的評分要求
- 使用 uri 和 key 參數
權杖式驗證。 AML 線上端點服務使用權杖式驗證進行部署。必須啟用 Azure AI 搜尋服務的受控識別。 AML 技能然後使用服務的受控識別對 AML 線上端點進行驗證，而不需要靜態金鑰。身分識別必須獲指派擁有者或參與者角色。
- 使用 resourceId 參數。
- 如果搜尋服務位於與 AML 工作區不同的區域，請使用區域參數來設定 AML 線上端點所部署的區域

技能輸入

此技能沒有任何「預先定義的」輸入。您可以選擇在此技能執行時已可用的一或多個欄位作為輸入，且傳送至 AML 線上端點的 JSON 承載將會有不同的欄位。

技能輸出

此技能沒有任何「預先定義的」輸出。根據您的 AML 線上端點傳回的回應，加入輸出欄位，以便可從 JSON 回應中加以挑選。

範例定義

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

範例輸入 JSON 結構

此 JSON 結構表示傳送至 AML 線上端點的承載。結構的最上層欄位將對應至技能定義的 inputs 區段中指定的「名稱」。那些欄位的值來自其 source (可能來自文件中的某個欄位，也可能來自另一個技能)

{
  "text": "Este es un contrato en Inglés"
}

範例輸出 JSON 結構

輸出與 AML 線上端點傳回的回應相對應。 AML 線上端點應該只會傳回 JSON 承載 (藉由查看 Content-Type 回應標頭來驗證)，且應為如下的物件：欄位是與 output 中的「名稱」相符的擴充，且其值被視為擴充。

{
    "detected_language_code": "es"
}

內嵌塑形範例定義

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

內嵌塑形輸入 JSON 結構

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

內嵌塑形範例輸出 JSON 結構

{
    "detected_language_code": "es"
}

錯誤案例

除了您的 AML 無法使用或傳送不成功的狀態碼以外，下列情況也會被視為錯誤：

如果 AML 線上端點傳回成功狀態碼，但回應指出它不是 application/json，則回應被視為無效，且不會執行任何擴充。
如果 AML 線上端點傳回無效 json

對於 AML 線上端點無法使用或傳回 HTTP 錯誤的情況，將在索引子執行歷程記錄中加入有關 HTTP 錯誤的任何可用詳細資料的易懂錯誤。

分享方式：