將自訂技能新增至Azure 認知搜尋擴充管線

擴充管線可以包含您個人建立和發佈的內建技能和自訂技能。 例如,您的自訂程式碼會在搜尋服務外部執行 (作為 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 角色進行驗證和授權,自訂技能可以在要求中包含驗證權杖。 下列幾點說明此方法的需求:

根據預設,如果回應未在 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"
          }
        ]
      }
  ]
}

觀看這部影片

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

後續步驟

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