將自定義技能新增至 Azure AI 搜尋擴充管線

  • 發行項

AI 擴充管線可以同時包含您個人建立和發佈的內建技能和自定義技能。 您的自定義程式代碼會在搜尋服務外部執行（例如，作為 Azure 函式），但接受輸入，並將輸出傳送至技能集，就像任何其他技能一樣。

自定義技能聽起來可能很複雜，但在實作方面可能很簡單且簡單明瞭。 如果您有提供模式比對或分類模型的現有套件，您可以從 Blob 擷取的內容會傳遞至這些模型進行處理。 由於 AI 擴充是以 Azure 為基礎，因此您的模型也應該位於 Azure 上。 一些常見的裝載方法包括使用 Azure Functions 或 容器。

如果您要建置自定義技能，本文將說明您用來將技能整合到管線中的介面。 主要需求是能夠接受輸入，並以整體技能集中消耗的方式發出輸出。 因此，本文的重點在於擴充管線所需的輸入和輸出格式。

自定義技能的優點

建置自訂技能可讓您插入內容獨有的轉換。 自訂技能會獨立執行，可套用在任何所需的擴充步驟。 例如，您可以建立自訂的分類模型以區分商務和財務合約及文件，或新增語音辨識技能以深入音訊檔案來了解相關內容。 如需逐步範例，請參閱 範例：建立 AI 擴充的自定義技能。

設定端點和逾時間隔

自定義技能的介面是透過 自定義 Web API 技能來指定。

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230 second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI 是函式或應用程式的 HTTPS 端點。 設定 URI 時，請確定 URI 是安全的 （HTTPS）。 如果您的程式代碼裝載於 Azure 函式應用程式中，URI 應該在 標頭中包含 API 金鑰，或作為 URI 參數 來授權要求。

如果您的函式或應用程式改用 Azure 受控識別和 Azure 角色進行驗證和授權，自定義技能可以在要求中包含驗證令牌。 下列幾點說明此方法的需求：

  • 代表索引器傳送要求的搜尋服務必須 設定為使用受控識別 （系統或使用者指派），讓呼叫者可由 Microsoft Entra ID 進行驗證。

  • 您的函式或應用程式必須 針對 Microsoft Entra ID 進行設定。

  • 您的 自定義技能定義 必須包含 「authResourceId」 屬性。 此屬性採用應用程式 （用戶端） 識別碼， 格式為： api://<appId>。

根據預設，如果回應未在 30 秒的視窗中傳回，則端點的連線逾時。 索引管線是同步的，如果回應未在該時間範圍內收到，索引就會產生逾時錯誤。 您可以藉由設定逾時參數，將間隔增加到最大值 230 秒：

格式化 Web API 輸入

Web API 必須接受要處理的記錄陣列。 每個記錄都必須包含屬性包，這是提供給 Web API 的輸入。

假設您想要建立基本擴充器，以識別合約文字中所提及的第一個日期。 在此範例中，自定義技能接受單一輸入 「contractText」 做為合約文字。 技能也有單一輸出，也就是合約的日期。 若要讓擴充器更有趣，請在多部分複雜類型的形狀中傳回這個 “contractDate”。

您的 Web API 應該已準備好接收一批輸入記錄。 “values” 陣列的每個成員都代表特定記錄的輸入。 每個記錄都需要有下列元素：

  • “recordId” 成員，這是特定記錄的唯一標識符。 當擴充器傳回結果時，它必須提供這個 「recordId」，才能讓呼叫端將記錄結果與輸入相符。

  • 「數據」成員，基本上是每個記錄的輸入欄位包。

產生的 Web API 要求可能如下所示：

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

實際上，您的程式代碼可能會以數百或數千筆記錄呼叫，而不只是此處顯示的三筆記錄。

格式化 Web API 輸出

輸出的格式是一組包含 「recordId」 和屬性包的記錄。 這個特定範例只有一個輸出，但您可以輸出多個屬性。 最佳做法是，如果無法處理記錄，請考慮傳回錯誤和警告訊息。

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2017 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

新增自訂技能至技能組

當您建立 Web API 擴充器時，您可以將 HTTP 標頭和參數描述為要求的一部分。 下列代碼段示範如何在技能集定義中包含要求參數和選擇性 HTTP 標頭。 如果您需要將組態設定傳遞至程式代碼，設定 HTTP 標頭會很有用。

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

觀看這段視訊

如需影片簡介和示範，請觀看下列示範。

下一步

本文涵蓋將自定義技能整合到技能集所需的介面需求。 請繼續進行這些連結，以深入瞭解自定義技能和技能集組合。