在 Azure AI 搜尋中建立技能集

indexer stages

技能集會定義作業,從包含影像或非結構化文字的檔產生文字內容和結構。 範例包括影像的 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 array,未排序 的技能集合。 技能可以是功利主義(例如分割文字)、轉換式(根據來自 Azure AI 服務的 AI),或您提供的自定義技能。 下一節會提供技能陣列的範例。

  • cognitiveServices 用於 呼叫 Azure AI 服務 API 的可計費技能 。 如果您未使用可計費的技能或自定義實體查閱,請移除本節。 如果您的話,請附加資源

  • knowledgeStore(選擇性) 會指定 Azure 儲存體 帳戶和設定,將技能集輸出投影到 Azure 儲存體 中的數據表、Blob 和檔案。 如果您不需要,請移除本節,否則 請指定知識存放區

  • encryptionKey(選擇性)指定技能集定義中用來加密敏感性內容(描述、連接字串、密鑰)的 Azure 金鑰保存庫 和客戶自控密鑰。 如果您未使用客戶管理的加密,請移除此屬性。

新增技能

在技能集定義內,技能陣列會指定要執行的技能。 三到五個技能很常見,但您可以視 服務限制新增所需數量的技能。

擴充管線的最終結果是搜尋索引或知識存放區中的文字內容。 因此,大部分技能都是從影像建立文字(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 指標路徑表示法為基礎,並進行了一些修改,以識別擴充樹狀結構中的節點。 "/"會周游樹狀結構中較低的層級,並"*"做為內容中每個運算子的 。 本文中的許多範例說明 語法

設定技能內容

每個技能都有一個 內容屬性 ,可決定作業發生的層級。 如果未明確設定 「context」 屬性,則預設值為 "/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,典型的技能輸入是文件的內容屬性。

每個技能的技能參考檔 會描述其可取用的輸入。 每個輸入都有識別特定輸入的「名稱」,以及指定擴充檔中數據位置的「來源」。 下列範例來自實體辨識技能:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]
  • 技能可以有多個輸入。 「名稱」是特定的輸入。 針對實體辨識,特定輸入為 「text」 和 「languageCode」。。

  • “source” 屬性會指定要處理的內容欄位或資料列。 針對以文字為基礎的技能,來源是提供文字的檔或數據列中的欄位。 針對影像型技能,提供輸入的節點是標準化影像。

    來源範例 描述
    “source”: “/document” 對於表格式數據集,檔會對應至數據列。
    “source”: “/document/content” 對於 Blob,來源通常是 Blob 的內容屬性。
    “source”: “/document/some-named-field” 對於以文字為基礎的技能,例如實體辨識或關鍵片語擷取,原點應該是包含要分析之足夠文字的字段,例如「描述」或「摘要」。
    "source": "/document/normalized_images/*" 針對影像內容,來源是檔破解期間已正規化的影像。

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

定義輸出

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

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

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]
  • 技能可以有多個輸出。 “name” 會識別特定的輸出。 例如,對於實體辨識,輸出可以是「人員」、「位置」、「組織」等等。

  • “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"。 如需範例,請參閱 參考註釋

第一個技能集的 提示

  • 在 Blob 儲存體 或其他支援的數據源中組合您內容的代表範例,然後執行匯入數據精靈

    精靈會自動化幾個步驟,第一次進行挑戰。 它會定義技能集、索引和索引器,包括字段對應和輸出字段對應。 如果您使用投影,也會在知識存放區中定義投影。 對於 OCR 或影像分析等某些技能,精靈會新增公用程式技能,以合併檔破解期間分隔的影像和文字內容。

    執行精靈之後,您可以在 Azure 入口網站 中開啟每個物件,以檢視其 JSON 定義。 您也可以使用偵錯會話來叫用目標檔的技能集執行。

  • 或者,您可以 匯入範例 Postman 集合 ,以提供評估技能所需的物件定義完整表達。

  • 當您準備好從頭開始進行新的技能集時,檢查初步結果很重要。 相較於知識存放區,建議您為內容驗證提供搜尋索引,因為設定起來比較簡單。

    針對每個技能輸出, 請在索引器中定義輸出欄位對應 ,以及搜尋索引中的欄位。

    Object diagram that shows the person entity as a skill output, indexer field mapping, and index field.

    執行索引器之後,請使用 搜尋 總管從索引傳回檔,並檢查每個欄位的內容,以判斷偵測或建立哪些技能集。

    此螢幕快照顯示實體辨識技能的結果,該技能偵測到文字區塊中的人員、位置、組織和其他實體。 您可以檢視結果,以決定技能是否會為您的解決方案增加價值。

    Screenshot of a document in Search Explorer.

下一步

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