將自訂技能加入 Azure AI 搜索增強管線

Note

Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

AI 強化流程可以包含內建技能和你創建並發布的自訂技能。 你的自訂程式碼會跑在搜尋服務之外（例如作為 Azure 函式），但它會像其他技能一樣接受輸入並傳送輸出到技能組。 你的資料會在模型部署的地理區域中處理。

自訂技能聽起來可能很複雜，但其實可以很簡單地實作。 如果你已有提供模式匹配或分類模型的套件，你可以將從 blob 中擷取的內容傳給這些模型進行處理。 因為 AI 強化是基於 Azure，你也應該把模型架設在 Azure 上。 常見的主機方案包括Azure Functions或containers。

如果您要建置自訂技能，本文會介紹用於將技能整合至管線中的介面， 首要要求是能夠以 技能集 整體可處理的方式接受輸入並產生輸出。 因此本文著重於說明擴充管線要求的輸入和輸出格式。

自訂技能的優點

建置自訂技能可讓您插入內容獨有的轉換。 例如，您可以建立自訂的分類模型以區分商務和財務合約及文件，或新增語音辨識技能以深入音訊檔案來了解相關內容。 如需逐步範例，請參閱範例：為 AI 增強建立自訂技能。

設定終點點與逾時區間

透過 自訂網頁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 金鑰來授權請求。

如果你的函式或應用程式使用 Azure 管理身份和 Azure 角色進行認證與授權，自訂技能可以在請求中加入認證權杖。 下列各點說明採用這種方法的需求：

確保 指向 uri 由 識別 authResourceId的應用程式端點。 數值不匹配可能導致認證失敗或請求傳送到非預期端點。 關於安全指引、建議做法及驗證設定的步驟，請參見 「管理身份驗證的安全考量」。

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

如果受 IP 存取限制保護的端點沒有回應，暫時設定 timeout 為短值， PT10S例如，以更快顯示逾時錯誤。 對於 Azure 函式應用程式，請在設定>>網路存取限制中管理入站 IP 規則。 關於允許的 IP 位址，請參見 「配置 IP 防火牆規則以允許索引器連線」。

格式化 Web API 輸入

網頁 API 必須接受一組記錄來處理。 在每筆紀錄中，提供一個屬性袋作為你的 Web API 輸入。

假設您想建立一個基本的擴充器，用來識別合約文字中提到的第一個日期。 在此範例中，自訂技能接受單一輸入。 contractText 這個技能也有單一輸出，即為合約日期。 為了讓擴充器更實用，請以多部分複雜類型的形式傳回 contractDate。

你的網頁 API 應該已經準備好接收一批輸入紀錄。 陣列中的 values 每個成員代表特定記錄的輸入。 每筆記錄都必須有下列元素：

  • 一個 recordId 成員，就是特定紀錄的唯一識別碼。 當你的增益器回傳結果時，必須提供這些 recordId 資訊，讓呼叫者能夠將記錄結果與輸入匹配。

  • data 成員，其中包含每筆記錄的輸入欄位集合。

最終產生的網路 API 請求可能如下：

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

實際上，您的程式碼可能會被呼叫以處理數百或數千筆記錄，而不是像此處所示僅處理三筆記錄。

格式化網頁 API 輸出

輸出格式是一組包含 a recordId 和 property bag 的記錄。 這個例子只有一個輸出，但你可以回傳多個屬性。 如果無法處理記錄，請考慮傳回錯誤和警告訊息這項最佳做法。

{
  "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" }  ]
      }
    ]
}

新增自訂技能至技能組

當你建立網頁 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"
          }
        ]
      }
  ]
}

Note

當您使用 GET 擷取技能時，服務會針對所有 <redacted> 值傳回 httpHeaders，以避免認證資訊外洩。 若要更新技能而不更改儲存的標頭值，請將每個值設為 <unchanged>。 詳情與範例請參見 自訂網頁API技能 — 技能參數。

觀看這段視訊

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

下一步

本文內容涵蓋將自訂技能整合至技能集的必要介面需求， 欲了解更多關於自訂技能與技能組合的資訊，請參閱以下資源：

  • Last updated on