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

發行項
12/18/2024

重要

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

AML 技能可讓您使用自定義 Azure 機器學習（AML）模型擴充 AI 擴充，或在 Azure AI Foundry 上部署的基底內嵌模型。一旦定型和部署 AML 模型，AML 技能就會將其整合到技能集。

AML 技能使用方式

如同其他內建技能，自定義 AML 技能具有輸入和輸出。輸入會以 JSON 物件的形式傳送至已部署的 AML 在線端點。端點的輸出必須是回應中的 JSON 承載，以及成功狀態代碼。您的資料會在模型部署所在的地理位置中處理。回應預期會提供 AML 技能定義所指定的輸出。任何其他的回應會被視為錯誤，並且不會執行任何擴充。

注意

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

503 Service Unavailable
429 Too Many Requests

您可以使用 2024-07-01 穩定 API 版本或對等 Azure SDK 或 2024-05-01-preview API 版本呼叫 AML 技能，以聯機到 Azure AI Foundry 入口網站中的模型目錄。

Azure AI Foundry 中模型的 AML 技能

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

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

建議您使用匯 入和向量化數據 精靈來產生技能集，其中包含在 Azure AI Foundry 上部署內嵌模型的 AML 技能。精靈會產生輸入、輸出和對應的 AML 技能定義，讓您在撰寫任何程式碼之前輕鬆測試模型。

必要條件

您建立之自定義模型的 AML 工作區，或從類別目錄部署內嵌模型時，於 Azure AI Foundry 中建立專案。
自定義模型的此工作區中的在線端點（即時），或內嵌從目錄部署的模型端點。

@odata.type

Microsoft.Skills.Custom.AmlSkill

技能參數

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

參數名稱	描述
`uri`	(金鑰驗證需要) JSON 承載傳送至的 AML 線上端點之評分 URI。僅允許 https URI 配置。若要在 Azure AI Foundry 模型目錄中內嵌模型，這是目標 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 技能的評分要求。設定此連線的 uri 和 key 參數。
令牌型驗證，其中 AML 在線端點是使用令牌型驗證來部署的。必須啟用 Azure AI 搜尋服務的受控識別，並在工作區上指派角色。 AML 技能然後使用服務的受控識別對 AML 線上端點進行驗證，而不需要靜態金鑰。搜尋服務身分識別必須是 擁有者 或 參與者。 resourceId設定參數，如果搜尋服務位於與 AML 工作區不同的區域，請設定 region 參數。

技能輸入

技能輸入是檔破解期間所建立之擴充文件的節點。例如，可能是根文件、標準化影像或 Blob 的內容。此技能沒有預先定義的輸入。針對輸入，您應該指定在 AML 技能執行時填入的一或多個節點。

技能輸出

技能輸出是技能所建立擴充檔的新節點。此技能沒有預先定義的輸出。針對輸出，您應該提供可從 AML 技能的 JSON 回應填入的節點。

範例定義

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.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://language-model.models.contoso.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 錯誤的任何可用詳細資料新增至索引器執行歷程記錄的易記錯誤。

共用方式為