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

技能會定義作業，從包含影像或非結構化文字的文件產生文字內容和結構。 範例包括影像的光學字元辨識（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 的可計費技能。 如果您未使用可計費技能或自訂實體查閱，請移除本區段。 如果您是，請連結 Azure AI 多服務資源。

• 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"
            }
        ]
    }
]

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

設定技能內容

每個技能都有內容屬性，可決定作業發生的層級。 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 通常會設定為下列其中一個範例：

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

定義輸入

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

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

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

• 技能可以有多個輸入。 name是特定的輸入。 對於實體辨識，特定輸入是 文字 和 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 函式，接著會叫用您提供的模型或轉換。 如需詳細資訊，請參閱 將自定義技能新增至 Azure AI 搜尋擴充管線。

雖然自定義技能會執行管線外部的程序代碼，但在技能數位列中，這隻是另一個技能。 如同內建技能，其具有類型、內容、輸入和輸出。 也會讀取和寫入擴充樹狀結構，就像內建技能一樣。 請注意，context欄位是使用星號設定為 "/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 定義。

• 嘗試偵錯工作階段來叫用目標文件上的技能集執行，並檢查技能集所建立的擴充文件。 您可以檢視和修改輸入和輸出設定和值。 本教學課程是一個很好的起點：教學課程：使用偵錯工作階段對技能集進行偵錯。

後續步驟

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