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

發行項
04/15/2024

自訂 Web API 技能可讓您呼叫提供自訂作業的 Web API 端點來擴充 AI 擴充。與內建技能類似， 自定義 Web API 技能具有輸入和輸出。根據輸入，Web API 會在索引器執行時收到 JSON 承載，並輸出 JSON 承載作為回應，以及成功狀態代碼。回應預期會有自定義技能所指定的輸出。任何其他回應都會被視為錯誤，而且不會執行擴充。本檔會進一步說明 JSON 承載的結構。

自定義 Web API 技能也會用於實作 Azure OpenAI On 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>`。這個值用來限定索引器所擷取的驗證令牌範圍，並將自定義 Web 技能 API 要求一起傳送至函式或應用程式。設定此屬性時，您的搜尋服務必須針對受控識別進行設定，且您的 Azure 函式應用程式已針對 Microsoft Entra 登入進行設定。若要使用此參數，請使用 `api-version=2023-10-01-Preview`呼叫 API。
`httpMethod`	傳送承載時要使用的方法。允許的方法為 `PUT` 或 `POST`
`httpHeaders`	索引鍵/值組的集合，其中索引鍵代表標頭名稱和值代表傳送至 Web API 以及承載的標頭值。下列標頭禁止在此集合中：`Accept`、、、`Accept-CharsetContent-TypeAccept-EncodingContent-Length`、`Cookie`、、`Host`、、、。`TEUpgradeVia`
`timeout`	（選擇性）指定時，表示發出 API 呼叫之 HTTP 用戶端的逾時。其必須格式化為 XSD "dayTimeDuration" 值 ( ISO 8601 持續時間值的受限子集)。例如， `PT60S` 60 秒。如果未設定，則會選擇預設值 30 秒。逾時可以設定為最多 230 秒和至少 1 秒。
`batchSize`	（選擇性）指出每個 API 呼叫都會傳送多少「數據記錄」（請參閱下面的 JSON 承載結構）。如果未設定，則會選擇預設值 1000。建議您使用此參數來達成 API 上索引輸送量和負載之間的適當取捨。
`degreeOfParallelism`	（選擇性）指定時，表示索引器與您提供的端點平行發出的呼叫數目。如果您的端點在壓力下失敗，或如果您的端點可以處理負載，您可以降低此值。如果未設定，則會使用預設值 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 錯誤的任何可用詳細資料新增至索引器執行歷程記錄的易記錯誤。