建立 Azure AI 搜尋服務中的技能

文章
09/03/2024

技能會定義作業，從包含影像或非結構化文字的文件產生文字內容和結構。範例包括影像的 OCR、未區分文字的實體辨識，以及文字翻譯。技能會在從外部資料來源擷取文字和影像之後，以及在處理欄位對應之後執行。

本文說明如何使用 REST API 建立技能，但相同的概念和步驟也適用於其他程式設計語言。

技能定義的規則包括：

技能合內的唯一名稱。技能為可供任何索引子使用的頂層資源。
至少一個技能。典型為三到五個技能。上限為 30 個。
技能中可以重複存在相同類型的技能 (例如多個 Shaper 技能)。
技能支援鏈結作業、迴圈和分支。

索引子可推動技能執行。您必須先有索引子、資料來源和索引，才能測試技能。

提示

啟用擴充快取以重複使用已處理的內容，並降低開發成本。

新增技能定義

從基本結構開始。在建立技能 REST API中，要求主體是以 JSON 撰寫，並具有下列各區段：

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

在名稱和描述之後，技能有四個主要屬性：

skills 陣列，技能的未排序集合。技能可以是實用技能 (例如分割文字)、轉換技能 (根據 Azure AI 服務的 AI)，或您提供的自訂技能。下一個區段會提供技能陣列的範例。
cognitiveServices 用於呼叫 Azure AI 服務 API 的可計費技能。如果您未使用可計費技能或自訂實體查閱，請移除本區段。如果您有使用，請附加資源。
knowledgeStore (選擇性) 會指定 Azure 儲存體帳戶，以及將技能輸出投射到 Azure 儲存體中資料表、Blob 和檔案的設定。如果您不需要，請移除本區段，否則，請指定知識存放區。
encryptionKey (選擇性) 會指定 Azure Key Vault，以及用來在技能定義中加密敏感性內容 (描述、連接字串、金鑰) 的客戶自控金鑰。如果您未使用客戶自控的加密，請移除此屬性。

新增技能

在技能定義內，技能陣列會指定要執行的技能。一般會指定三到五個技能，但您可以視服務限制來新增更多技能。

擴充管線的最終結果是搜尋索引或知識存放區中的文字內容。因此，大部分技能都是從影像建立文字 (OCR 文字、標題、標記)，或分析現有的文字來建立新的資訊 (實體、關鍵片語、情感)。獨立運作的技能會以平行方式處理。彼此相依的技能會將一個技能的輸出 (例如關鍵片語) 指定為第二個技能的輸入 (例如文字翻譯)。搜尋服務會決定技能執行和執行環境的順序。

所有技能都有類型、內容、輸入和輸出。技能可能會選擇性地具有名稱和描述。下列範例顯示兩個不相關的內建技能，以便您比較基本結構。

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

每個技能在其輸入值及所採用參數方面都是唯一的。技能參考文件中描述了指定技能的所有參數和屬性。雖然有差異，但大部分的技能會共用一個通用集合，而且模式皆類似。

注意

您可以使用條件式技能來建立運算式，以建立具有迴圈和分支的複雜技能。語法會使用 JSON 指標路徑標記法，並進行一些修改，來識別擴充樹狀結構中的節點。 "/" 會在樹狀結構中向下周遊一個層級，而 "*" 則會作為內容中的 for-each 運算子。本文中有許多說明語法的範例。

設定技能內容

每個技能都有內容屬性，可決定作業發生的層級。如果未明確設定「內容」屬性，則預設值為 "/document"，其中內容是整個文件 (每個文件一次技能呼叫)。

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

內容通常會設定為下列其中一個範例：

內容範例	描述
"context": "/document"	(預設) 輸入和輸出位在文件層級上。
"context": "/document/pages/*"	某些技能 (例如情感分析) 在較小的文字區塊上執行時，成效較好。如果您要將大型內容欄位分割成頁面或句子，則內容應該以每個元件部分為基礎。
"context": "/document/normalized_images/*"	針對影像內容，父文件中的每個影像各有一組輸入和輸出。

內容也會決定輸出在擴充樹狀結構中產生的位置。例如，實體辨識技能會傳回名為 "organizations" 的屬性，並擷取以作為 orgs。如果內容為 "/document"，則會將「組織」節點新增為 "/document" 的子系。如果您接著想要在下游技能中參考此節點，路徑會是 "/document/orgs"。

定義輸入

對擴充文件讀取和寫入技能。技能輸入會指定傳入資料的來源。通常是擴充文件的根節點。對於 Blob，典型的技能輸入是文件的內容屬性。

每個技能的技能參考文件都會描述其可取用的輸入。每個輸入都有可識別特定輸入的 "name"，以及指定擴充文件中資料位置的 "source"。下列範例來自實體辨識技能：

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

技能可以有多個輸入。 "name" 是特定的輸入。對於實體辨識，特定輸入為 "text" 和 "languageCode"。

"source" 屬性會指定哪些欄位或資料列提供要處理的內容。針對文字型技能，來源是文件或資料列中提供文字的欄位。針對影像型技能，提供輸入的節點是標準化影像。

來源範例	描述
"source": "/document"	對於表格式資料集，文件會對應至資料列。
"source": "/document/content"	對於 Blob，來源通常是 Blob 的內容屬性。
"source": "/document/some-named-field"	對於文字型技能，例如實體辨識或關鍵片語擷取，來源應是內含足夠文字可供分析的欄位，例如 "description" 或 "summary"。
"source": "/document/normalized_images/*"	針對影像內容，來源是文件破解期間已標準化的影像。

如果技能會逐一查看陣列，則內容和輸入來源都應該在正確的位置中包含 /*。

定義輸出

每個技能都是設計來發出特定種類的輸出，這些輸出會依技能中的名稱來參考。技能輸出會具有 "name" 和選擇性的 "targetName"。

每個技能的技能參考文件都會描述其可產生的輸出。下列範例來自實體辨識技能：

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

技能可以有多個輸出。 "name" 會識別特定的輸出。例如，針對實體辨識，輸出可能是 "persons"、"locations" 和 "organizations" 等等。
"targetName" 會指定您想要此節點在擴充文件中擁有的名稱。如果技能輸出的名稱相同，這將非常有用。如果您有多個傳回相同輸出的技能，請在擴充節點路徑中使用 "targetName" 來避免模棱两可的名稱。如果未指定目標名稱，則會針對這兩者使用 name 屬性。

某些情況下，會需要個別參考陣列的每個元素。例如，假設您想要個別將 "/document/orgs" 的每個元素傳遞至另一項技能。若要這樣做，請將星號新增至路徑："/document/orgs/*"。

技能輸出會以擴充樹狀結構中的新節點形式寫入擴充文件。這可能是簡單的值，例如情感分數或語言代碼。也可能是集合，例如組織、人員或位置的清單。技能輸出也可以是複雜的結構，如同 Shaper 技能的案例。技能的輸入會決定圖形的組成，但輸出是具名物件，可在搜尋索引、知識存放區投影或其他技能中，依名稱加以參考。

新增自訂技能

本節包含自訂技能的範例。 URI 會指向 Azure 函式，接著會叫用您提供的模型或轉換。如需詳細資訊，請參閱定義自訂介面。

雖然自訂技能正在執行管線外部的程式碼，但在技能陣列中，這只是另一個技能。如同內建技能，其具有類型、內容、輸入和輸出。也會讀取和寫入擴充樹狀結構，就像內建技能一樣。請注意，[內容] 欄位設定為附有星號的 "/document/orgs/*"，這表示擴充步驟是對 "/document/orgs" 下的「每個」組織而呼叫的。

輸出，例如此範例中的公司描述，會針對所識別的每個組織產生。在下游步驟中參照節點時 (例如，在擷取關鍵片語時)，您會使用路徑 "/document/orgs/*/companyDescription" 來執行。

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

將輸出傳送至目的地

雖然技能輸出可以選擇性地快取以供重複使用，但通常是暫時性的，而且只有在技能執行正在進行時才會存在。

若要將輸出傳送至搜尋索引中的欄位，請在索引子中建立輸出欄位對應。
若要將輸出傳送至知識存放區，請建立投影。
若要將輸出傳送至下游技能，請在下游技能的輸入來源屬性中依節點名稱參考輸出，例如 "/document/organization"。如需範例，請參閱參考註釋。

第一個技能的秘訣

嘗試匯入資料精靈。

精靈會自動化多個初次執行較為困難的步驟。精靈會定義技能、索引和索引子，包括欄位對應和輸出欄位對應。如果您使用知識存放區，它也會在知識存放區中定義投影。對於 OCR 或影像分析等某些技能，精靈會新增公用程式技能，以合併文件破解期間分隔的影像和文字內容。

執行精靈之後，您可以在 Azure 入口網站中開啟每個物件，以檢視其 JSON 定義。
嘗試偵錯工作階段來叫用目標文件上的技能集執行，並檢查技能集所建立的擴充文件。您可以檢視和修改輸入和輸出設定和值。本教學課程是一個很好的起點：教學課程：使用偵錯工作階段對技能集進行偵錯。

下一步

內容和輸入來源欄位是擴充樹狀結構中節點的路徑。在下一個步驟中，深入了解擴充樹狀結構中節點的路徑語法。

參考技能中的註釋

分享方式：