Vytvoření sady dovedností ve službě Azure AI Search

Článek
01/10/2024

Sada dovedností definuje operace, které generují textový obsah a strukturu z dokumentů, které obsahují obrázky nebo nestrukturovaný text. Příklady jsou OCR pro obrázky, rozpoznávání entit pro nefferentiated text a překlad textu. Sada dovedností se spustí po extrakci textu a obrázků z externího zdroje dat a po zpracování mapování polí.

Tento článek vysvětluje, jak vytvořit sadu dovedností pomocí rozhraní REST API, ale stejné koncepty a kroky platí pro jiné programovací jazyky.

Mezi pravidla pro definici sady dovedností patří:

Jedinečný název v kolekci sad dovedností. Sada dovedností je prostředek nejvyšší úrovně, který může používat jakýkoli indexer.
Alespoň jednu dovednost. Tři až pět dovedností jsou typické. Maximum je 30.
Sada dovedností může opakovat dovednosti stejného typu (například více dovedností Shaper).
Sada dovedností podporuje řetězené operace, smyčky a větvení.

Indexery řídí provádění sady dovedností. Před otestování sady dovedností potřebujete indexer, zdroj dat a index .

Tip

Povolte ukládání do mezipaměti pro rozšiřování, abyste mohli opakovaně používat obsah, který jste už zpracovali, a snížit náklady na vývoj.

Přidání definice sady dovedností

Začněte základní strukturou. V rozhraní REST API pro vytvoření sady dovedností se text požadavku vytvoří ve formátu JSON a obsahuje následující části:

{
   "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":{ }
}

Po názvu a popisu má sada dovedností čtyři hlavní vlastnosti:

skills pole, neseřazená kolekce dovedností. Dovednosti můžou být utilitární (například rozdělení textu), transformace (na základě umělé inteligence ze služeb Azure AI) nebo vlastní dovednosti, které poskytujete. Příklad pole dovedností je k dispozici v další části.
cognitiveServices slouží k fakturovatelným dovednostem , které volají rozhraní API služeb Azure AI. Pokud nepoužíváte fakturovatelné dovednosti nebo vlastní vyhledávání entit, odeberte tuto část. Pokud jste, připojte prostředek .
knowledgeStore (volitelné) určuje účet azure Storage a nastavení pro projektování výstupu sady dovedností do tabulek, objektů blob a souborů ve službě Azure Storage. Pokud ho nepotřebujete, odeberte tento oddíl, jinak zadejte úložiště znalostí.
encryptionKey(volitelné) určuje azure Key Vault a klíče spravované zákazníkem používané k šifrování citlivého obsahu (popisy, připojovací řetězec, klíče) v definici sady dovedností. Tuto vlastnost odeberte, pokud nepoužíváte šifrování spravované zákazníkem.

Přidání dovedností

V definici sady dovedností určuje pole dovedností, které se mají provést. Tři až pět dovedností jsou společné, ale podle limitů služeb můžete přidat tolik dovedností, kolik potřebujete.

Konečným výsledkem kanálu rozšiřování je textový obsah v indexu vyhledávání nebo ve znalostním úložišti. Z tohoto důvodu většina dovedností vytváří text z obrázků (text OCR, popis s, značky) nebo analyzuje existující text a vytváří nové informace (entity, klíčové fráze, mínění). Dovednosti, které fungují nezávisle, se zpracovávají paralelně. Dovednosti, které na sobě závisejí, určují výstup jedné dovednosti (například klíčové fráze) jako vstup druhé dovednosti (například překlad textu). Vyhledávací služba určuje pořadí provádění dovedností a spouštěcího prostředí.

Všechny dovednosti mají typ, kontext, vstupy a výstupy. Dovednost může mít volitelně název a popis. Následující příklad ukazuje dvě nesouvisející předdefinované dovednosti , abyste mohli porovnat základní strukturu.

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

Každá dovednost je jedinečná z hlediska vstupních hodnot a parametrů, které přebírá. Referenční dokumentace dovedností popisuje všechny parametry a vlastnosti dané dovednosti. I když existují rozdíly, většina dovedností sdílí společnou sadu a podobně se vzoruje.

Poznámka:

Pomocí podmíněné dovednosti můžete vytvářet složité sady dovedností pomocí smyčky a větvení a vytvářet výrazy. Syntaxe je založená na zápisu cesty ukazatele JSON s několika úpravami pro identifikaci uzlů ve stromu rozšiřování. Procházení "/" prochází úrovní nižší ve stromu a "*" funguje jako operátor pro každý operátor v kontextu. Syntaxi ilustruje celá řada příkladů v tomto článku.

Nastavení kontextu dovedností

Každá dovednost má kontextovou vlastnost , která určuje úroveň, na které se provoz provádí. Pokud vlastnost "context" není explicitně nastavena, výchozí hodnota je "/document", kde kontext je celý dokument (dovednost se volá jednou pro každý dokument).

"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": []
  }
]

Kontext je obvykle nastavený na jeden z následujících příkladů:

Příklad kontextu	Popis
"context": "/document"	(Výchozí) Vstupy a výstupy jsou na úrovni dokumentu.
"context": "/document/pages/*"	Některé dovednosti, jako je analýza mínění, fungují lépe než menší bloky textu. Pokud rozdělujete velké pole obsahu na stránky nebo věty, měl by být kontext přes každou část komponenty.
"context": "/document/normalized_images/*"	U obsahu obrázku jsou vstupy a výstupy jedna na obrázek v nadřazeném dokumentu.

Kontext také určuje, kde se výstupy vytvářejí ve stromu rozšiřování. Například dovednost Rozpoznávání entit vrací vlastnost s názvem "organizations", zachycena jako orgs. Pokud je "/document"kontext , přidá se uzel "organizace" jako podřízený uzel "/document". Pokud byste pak chtěli odkazovat na tento uzel v podřízených dovednostech, cesta by byla "/document/orgs".

Definování vstupů

Dovednosti čtené z a zápisu do rozšířeného dokumentu. Vstupy dovedností určují původ příchozích dat. Často se jedná o kořenový uzel rozšířeného dokumentu. U objektů blob je typickým vstupem dovednosti vlastnost obsahu dokumentu.

Referenční dokumentace ke dovednostem pro každou dovednost popisuje vstupy, které může využívat. Každý vstup má "název", který identifikuje určitý vstup, a "zdroj", který určuje umístění dat v rozšířeném dokumentu. Následující příklad pochází z dovednosti Rozpoznávání entit:

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

Dovednosti můžou mít více vstupů. "name" je konkrétní vstup. Pro rozpoznávání entit jsou konkrétní vstupy "text" a "languageCode".

Vlastnost "zdroj" určuje, které pole nebo řádek poskytují obsah, který se má zpracovat. Pro textové dovednosti je zdrojem pole v dokumentu nebo řádku, které poskytuje text. V případě dovedností založených na imagích je uzel poskytující vstup normalizovanými obrázky.

Příklad zdroje	Popis
"source": "/document"	Pro tabulkovou datovou sadu odpovídá dokument řádku.
"source": "/document/content"	U objektů blob je zdrojem obvykle vlastnost obsahu objektu blob.
"source": "/document/some-named-field"	Pro textové dovednosti, jako je rozpoznávání entit nebo extrakce klíčových frází, by měl být původ pole, které obsahuje dostatečný text k analýze, například "popis" nebo "souhrn".
"source": "/document/normalized_images/*"	Pro obsah obrázku je zdrojem obrázek, který byl normalizován během prolomení dokumentu.

Pokud dovednost prochází polem, měl by kontext i vstupní zdroj obsahovat /* správné pozice.

Definování výstupů

Každá dovednost je navržená tak, aby vygenerovala konkrétní druhy výstupu, na které se odkazuje podle názvu v sadě dovedností. Výstup dovednosti má "název" a volitelný "targetName".

Referenční dokumentace dovedností pro každou dovednost popisuje výstupy, které může vytvořit. Následující příklad pochází z dovednosti Rozpoznávání entit:

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

Dovednosti můžou mít více výstupů. Název identifikuje konkrétní výstup. Výstupem pro rozpoznávání entit může být například "persons", "locations" (umístění), "organizations" (organizace).
"targetName" určuje název, který má mít tento uzel v rozšířeném dokumentu. To je užitečné, pokud výstupy dovedností mají stejný název. Pokud máte více dovedností, které vracejí stejný výstup, použijte "targetName" pro název nejednoznačnost v cestách uzlů rozšiřování. Pokud není zadaný cílový název, použije se pro obě vlastnosti název.

V některých situacích je potřeba odkazovat na každý prvek pole samostatně. Předpokládejme například, že chcete předat každý prvek"/document/orgs" samostatně jiné dovednosti. Uděláte to tak, že do cesty přidáte hvězdičku: "/document/orgs/*".

Výstup dovednosti se zapíše do rozšířeného dokumentu jako nový uzel ve stromu rozšiřování. Může to být jednoduchá hodnota, například skóre mínění nebo kód jazyka. Může to být také kolekce, například seznam organizací, lidí nebo umístění. Výstup dovednosti může být také složitá struktura, stejně jako u dovednosti Shaper. Vstupy dovednosti určují složení obrazce, ale výstup je pojmenovaný objekt, na který lze odkazovat v indexu vyhledávání, projekci úložiště znalostí nebo jiné dovednosti podle názvu.

Přidání vlastní dovednosti

Tato část obsahuje příklad vlastní dovednosti. Identifikátor URI odkazuje na funkci Azure Functions, která zase vyvolá model nebo transformaci, kterou zadáte. Další informace najdete v tématu Definování vlastního rozhraní.

I když vlastní dovednost provádí kód, který je pro kanál externí, v poli dovedností je to jen další dovednost. Podobně jako předdefinované dovednosti má typ, kontext, vstupy a výstupy. Také čte a zapisuje do stromu rozšiřování, stejně jako předdefinované dovednosti. Všimněte si, že pole "context" je nastaveno na "/document/orgs/*" hvězdičku, což znamená, že krok rozšiřování se volá pro každou organizaci v rámci "/document/orgs".

Výstup, například popis společnosti v tomto příkladu, se vygeneruje pro identifikovanou organizaci. Při odkazování na uzel v podřízeném kroku (například při extrakci klíčových frází) byste k tomu použili cestu "/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"
    }
  ]
}

Odeslání výstupu do cíle

I když se výstup dovednosti může volitelně ukládat do mezipaměti pro účely opakovaného použití, je obvykle dočasný a existuje pouze v době, kdy probíhá provádění dovedností.

Pokud chcete odeslat výstup do pole v indexu vyhledávání, vytvořte v indexeru mapování výstupního pole.
Pokud chcete odeslat výstup do úložiště znalostí, vytvořte projekci.
Pokud chcete odeslat výstup do podřízené dovednosti, odkazujte na výstup podle názvu uzlu, například "/document/organization", ve vstupní vlastnosti zdroje podřízené dovednosti. Příklady najdete v tématu Odkazování na poznámku .

Tipy pro první sadu dovedností

Zkuste průvodce importem dat.

Průvodce automatizuje několik kroků, které můžou být poprvé náročné. Definuje sadu dovedností, index a indexer, včetně mapování polí a mapování výstupních polí. Definuje také projekce v úložišti znalostí, pokud ho používáte. Pro některé dovednosti, jako je OCR nebo analýza obrázků, průvodce přidá pomocné dovednosti, které sloučí obrázek a textový obsah, který byl oddělen během prolomení dokumentu.

Po spuštění průvodce můžete každý objekt otevřít na webu Azure Portal a zobrazit jeho definici JSON.
Zkuste ladicí relace vyvolat spuštění sady dovedností v cílovém dokumentu a zkontrolovat obohacený dokument, který sada dovedností vytvoří. Můžete zobrazit a upravit vstupní a výstupní nastavení a hodnoty. Tento kurz je dobrým místem, kde začít: Kurz: Ladění sady dovedností pomocí ladicích relací.

Další kroky

Kontextová a vstupní zdrojová pole jsou cesty k uzlům ve stromu rozšiřování. V dalším kroku se dozvíte více o syntaxi cesty pro uzly ve stromu rozšiřování.

Odkazování na poznámky v sadě dovedností