共用方式為

有效向外擴充自訂技能

  • 發行項

自訂技能是實作特定介面的 Web API。 自訂技能可以在任何可公開定址的資源上實作。 自訂技能最常見的實作如下：

  • 用於自訂邏輯技能的 Azure Function
  • 用於簡單容器化 AI 技能的 Azure Web 應用程式
  • 用於更複雜或更大技能的 Azure Kubernetes 服務。

技能集設定

下列自訂技能屬性用於調整。 檢閱自訂技能介面，以了解自訂技能應實作之輸入和輸出的簡介。

  1. 設定自訂技能的 batchSize，以設定傳送到單一技能叫用作業中的技能的記錄數。

  2. 設定 degreeOfParallelism，以校正索引子對您的技能發出的並行要求數。

  3. 將 timeout 設為足以讓技能可以使用有效的回應來回應的值。

  4. 在 indexer 定義中，將 batchSize 設為應從資料來源讀取並同時擴充的文件數。

考量

沒有「全體適用」的建議集合。 您應該規劃測試不同的組態，以達到最佳結果。 擴大策略是以較少大型要求或許多小型要求為基礎。

  • 技能較用基數：確定您知道自訂技能會針對每個文件執行一次 (/document/content)，還是針對每個文件執行多次 (/document/reviews_text/pages/*)。 如果針對每個文件執行多次，請停留在 batchSize 和 degreeOfParallelism 的下側以減少變換，並嘗試將索引子批次大小設定為遞增較高的值，以取得更大的規模。

  • 協調自訂技能 batchSize 和索引子 batchSize，並確定您不會造成瓶頸。 例如，如果索引子批次大小為 5，且技能批次大小為 50，則需要 10 個索引子批次來填入自訂技能要求。 在理想情況下，技能批次大小應該小於或等於索引子批次大小。

  • 針對 degreeOfParallelism，使用索引子批次可產生的平均要求數目，引導您決定如何設定此值。 如果裝載此技能的基礎結構 (例如 Azure 函式) 不支援高層級的並行存取，請考慮降低平行處理的程度。 您可使用一些文件來測試設定，以驗證您對平均要求數目的瞭解。

  • 雖然您的物件支援大量規模，但使用較小的文件樣本進行測試有助於量化不同的執行階段。 例如，您可以評估技能的執行時間 (相對於處理文件子集的整體時間)。 這有助於您回答問題：索引子是否花更多時間建置批次，或等候您的技能的回應？

  • 考慮平行處理原則的上游含意。 如果自訂技能的輸入是先前技能的輸出，技能集中的所有技能是否會有效地向外擴充，以將延遲降到最低？

自訂技能中的錯誤處理

當技能順利完成時，自訂技能應該會傳回一個成功狀態碼 HTTP 200。 如果批次中的一或多筆記錄導致錯誤，請考慮傳回多重狀態碼 207。 記錄的錯誤或警告清單應該包含適當的訊息。

批次中發生錯誤的任何項目都會導致相對應的文件失敗。 如果您需要文件成功，請傳回警告。

任何超過 299 的狀態碼都會評估為錯誤，而且所有擴充都會失敗，進而導致文件失敗。

常見的錯誤訊息

  • Could not execute skill because it did not execute within the time limit '00:00:30'. This is likely transient. Please try again later. For custom skills, consider increasing the 'timeout' parameter on your skill in the skillset. 在技能上設定逾時參數，以允許較長的執行持續時間。

  • Could not execute skill because Web Api skill response is invalid. 指出技能未以自訂技能回應格式傳回訊息。 這可能是技能中未攔截到例外狀況的結果。

  • Could not execute skill because the Web Api request failed. 最有可能是因為授權錯誤或例外狀況所造成。

  • Could not execute skill. 通常是將技能回應對應到文件階層中的現有屬性的結果。

測試自訂技能

首先，使用 REST API 用戶端來測試您的自訂技能，以驗證：

  • 技能會實作要求和回應的自訂技能介面

  • 技能會傳回具有 application/JSON MIME 類型的有效 JSON

  • 會傳回有效的 HTTP 狀態碼

建立一個偵錯工作階段，以將您的技能新增至技能集，並確定它會產生有效的擴充。 雖然偵錯工作階段不允許您調整技能的效能，但它可以讓您確保該技能已設定了有效值，並傳回預期的擴充物件。

最佳作法

  • 雖然技能可以接受並傳回較大的承載資料，但請考慮在傳回 JSON 時將回應限制為 150 MB 或更少。

  • 請考慮在索引子和技能上設定批次大小，以確保每個資料來源批次都會為您的技能產生完整的承載資料。

  • 對於長時間執行的工作，請將逾時設定為足夠的值，以確保索引子不會在同時處理文件時出錯。

  • 將索引子批次大小、技能批次大小和平行處理原則的技能程度最佳化，以產生技能所預期的負載模式、較少的大型要求或許多小型要求。

  • 透過詳細的失敗記錄檔來監視自訂技能，因為您可能會遇到特定要求因資料可變性而持續失敗的情況。