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

發行項
10/21/2024

「自訂 Web API」技能可讓您透過呼叫提供自訂作業的 Web API 端點來延伸 AI 擴充。與內建的技能類似，自訂 Web API 技能具有輸入和輸出。根據輸入，您的 Web API 會在索引子執行時接收 JSON 承載，並輸出 JSON 承載以及成功狀態碼作為回應。預期回應應該具有您的自訂技能所指定的輸出。任何其他的回應會被視為錯誤，並且不會執行任何擴充。 JSON 承載的結構會在本文件中進一步描述。

自訂 Web API 技能也用於實作 Azure OpenAI On Your Data 功能。如果 Azure OpenAI 已針對角色型存取進行設定，而且您在建立向量索引時收到 403 Forbidden 呼叫，請驗證 Azure AI 搜尋是否具有系統指派的身分識別，並在 Azure OpenAI 上以信任的服務形式執行。

注意

針對從 Web API 傳回的特定標準 HTTP 狀態碼，索引子會重試兩次。這些 HTTP 狀態碼為：

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

技能參數

這些參數會區分大小寫。

參數名稱	描述
`uri`	JSON 承載會傳送的目標 Web API URI。僅允許 https URI 配置。
`authResourceId`	(選用) 如果設定字串，則指出此技能應該在裝載程式碼的函數或應用程式連線上使用系統受控身分識別。此屬性會採用 Microsoft Entra ID 中的應用程式 (用戶端) 識別碼或應用程式的註冊 (採用以下任一格式：`api://<appId>`、`<appId>/.default`、`api://<appId>/.default`)。此值會用來設定索引子所擷取的驗證權杖範圍，並與自訂 Web 技能 API 要求一起傳送至函數或應用程式。設定此屬性需要您的搜尋服務已針對受控身分識別進行設定，而且您的 Azure 函數應用程式已針對 Microsoft Entra 登入進行設定。若要使用此參數，請使用 `api-version=2023-10-01-Preview` 呼叫 API。
`authIdentity`	(選擇性) 搜尋服務用來連線至裝載程式碼之函式或應用程式的使用者受控識別。您可以使用系統或使用者受控的識別。若要使用系統管理身分識別，請將 `authIdentity` 保留為空白。
`httpMethod`	傳送承載時使用的方法。允許的方法為 `PUT` 和 `POST`
`httpHeaders`	機碼值組的集合，其中機碼代表標頭名稱，而值代表將與承載一起傳送至 Web API 的標頭值。下列標頭禁止加入此集合：`Accept`、`Accept-Charset`、`Accept-Encoding`、`Content-Length`、`Content-Type`、`Cookie`、`Host`、`TE`, `Upgrade`、`Via`。
`timeout`	(選擇性) 指定時，表示進行 API 呼叫的 http 用戶端逾時。其必須格式化為 XSD "dayTimeDuration" 值 ( ISO 8601 持續時間值的受限子集)。例如，`PT60S` 為 60 秒。如果沒有設定，則選擇的預設值為 30 秒。逾時最高可設定為 230 秒，最低 1 秒。
`batchSize`	(選用) 指出每個 API 呼叫會傳送多少「資料記錄」(請參閱下面的 JSON 承載結構)。如果未設定，則選擇的預設值為 1000。建議您使用此參數在編製索引的輸送量與 API 負載之間達到適當的取捨。
`degreeOfParallelism`	(選用) 指定時，指示索引子與您所提供的端點平行進行的呼叫數。如果您的端點因壓力而失敗，則可以減少此值，或者，如果您的端點可以處理負載，則請增加此值。若未設定，將會使用預設值 0.5。 `degreeOfParallelism` 最高可以設定為 10，最低為 1。

技能輸入

此技能沒有預先定義的輸入。輸入是任何現有欄位，或您想要傳遞至自訂技能之擴充樹狀結構中的任何節點。

技能輸出

此技能沒有預先定義的輸出。如果技能的輸出應該傳送至搜尋索引中的欄位，則請務必在索引子中定義輸出欄位對應。

範例定義

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

範例輸入 JSON 結構

此 JSON 結構代表會傳送至您的 Web API 的承載。它一律會遵循下列這些條件約束：

最上層的實體稱為 values，且是物件的陣列。這類物件的數目最多為 batchSize。
values 陣列中的每個物件都具有：
- recordId 屬性，它是唯一字串，用來識別該記錄。
- data 屬性，它是 JSON 物件。屬性的 data 欄位會對應至技能定義區 inputs 段中指定的「名稱」。那些欄位的值來自其 source (可能來自文件中的某個欄位，也可能來自另一個技能)。

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

範例輸出 JSON 結構

「輸出」對應至從您的 Web API 傳回的回應。 Web API 應該只傳回 JSON 承載 (透過查看 Content-Type 回應標頭進行驗證)，並且應該滿足下列限制式：

應該有一個名為 values 的最上層實體，它應該是物件陣列。
陣列中的物件數目應該與傳送至 Web API 的物件數目相同。
每個物件都應該有：
- recordId 屬性。
- data 屬性，它是一個物件，其中的欄位是與 output 中的「名稱」相符的擴充，其值會被視為擴充。
- errors 屬性，一個會新增至索引子執行歷程記錄中的陣列，其中列出發生的任何錯誤。此屬性是必要的，但可以具有 null 值。
- warnings 屬性，一個會新增至索引子執行歷程記錄中的陣列，其中列出發生的任何警告。此屬性是必要的，但可以具有 null 值。
要求或回應中 values 內的物件順序並不重要。不過，recordId 用於相互關聯，因此包含 recordId (不是 Web API 的原始要求的一部分) 的回應中的任何記錄都會捨棄。

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

錯誤案例

除了您的 Web API 無法使用或傳送不成功的狀態碼之外，下列各項被視為錯誤情況：

如果 Web API 傳回成功狀態碼，但回應指出它不是 application/json，則回應被視為無效，並且不會執行任何擴充。
如果回應 values 陣列中具有無效記錄 (例如，recordId 遺漏或重複)，則不會針對無效記錄執行擴充。開發自訂技能時，請務必遵守 Web API 技能合約。您可以參考此範例，其提供於遵循預期合約的 Power Skill 存放庫。

針對 Web API 無法使用或傳回 HTTP 錯誤的情況，會在索引子執行歷程記錄中新增 HTTP 錯誤之任何可用詳細資料的易懂錯誤。

共用方式為