在 Azure AI 搜尋服務擴充管線中新增自訂技能

文章
10/16/2024

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 函數應用程式中，API 金鑰應位於 URI 標頭中或作為 URI 參數，藉此授權要求。

如果您的函數或應用程式改為使用 Azure 受控識別和 Azure 角色進行驗證和授權，自訂技能可以在要求中包含驗證權杖。下列各點說明採用這種方法的需求：

代表索引子傳送要求的搜尋服務必須設定為使用系統或使用者指派的受控識別 (機器翻譯)，如此呼叫者才能由 Microsoft Entra ID 驗證。
您的函數或應用程式必須設定為使用 Microsoft Entra ID (機器翻譯)。
您的自訂技能定義 (機器翻譯) 必須包含 authResourceId 屬性。此屬性採用支援格式的應用程式 (用戶端) 識別碼：api://<appId>。

根據預設，如果回應未在 30 秒內回傳，連至端點的連線便會逾時 (PT30S)。索引管線是同步的，如果未在該時段內收到回應，索引就會產生逾時錯誤。您可以藉由設定逾時參數，將間隔增加到最大值 230 秒 (PT230S)。

將 Web API 輸入格式化

Web API 必須接受要處理的記錄陣列。在每個記錄內，提供屬性包作為 Web API 的輸入。

假設您要建立基本的擴充程式，以識別合約文字中提及的第一個日期。在此範例中，自訂技能接受單一輸入「contractText」作為合約文字。技能也有單一輸出，也就是合約的日期。為了讓擴充程式更有趣，以多部分複雜類型的形式傳回此「contractDate」。

您的 Web API 應該準備好接收一批輸入記錄。「values」陣列的每個成員都代表特定記錄的輸入。每筆記錄都必須有下列元素：

「recordId」成員，此為特定記錄的唯一識別碼。當擴充程式傳回結果時，必須提供此「recordId」，才能讓呼叫者比對記錄結果與輸入。
「data」成員，基本上是每筆記錄的輸入欄位包。

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

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2023 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" : 2023 }                    
        }
      },
      {
        "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"
          }
        ]
      }
  ]
}

觀看這段視訊

如需影片介紹和示範，請觀看以下示範影片。

下一步

本文內容涵蓋將自訂技能整合至技能集的必要介面需求，如需進一步了解自訂技能和技能集組成，請繼續閱讀下列連結文章。

分享方式：