Odkaz na cestu k obohaceným uzlům pomocí kontextových a zdrojových vlastností sady dovedností azure AI Search

Článek
01/19/2024

Během provádění sady dovedností vytvoří modul strom rozšiřování v paměti, který zachytí každé rozšiřování, jako jsou rozpoznané entity nebo přeložený text. V tomto článku se dozvíte, jak odkazovat na uzel rozšiřování ve stromu rozšiřování, abyste mohli předat výstup podřízeným dovednostem nebo zadat mapování výstupního pole pro pole indexu vyhledávání.

Tento článek používá příklady k ilustraci různých scénářů. Úplnou syntaxi najdete v tématu Jazyk pro kontext dovednosti a jazyk pro zadávání poznámek.

Koncepty na pozadí

Než si projdeme syntaxi, pojďme se podívat na několik důležitých konceptů, abychom lépe pochopili příklady uvedené dále v tomto článku.

Období	Popis
"obohacený dokument"	Obohacený dokument je struktura v paměti, která shromažďuje výstup dovedností při vytváření a uchovává všechny rozšiřování související s dokumentem. Obohacený dokument si můžete představit jako strom. Obecně platí, že strom začíná na úrovni kořenového dokumentu a každé nové rozšiřování se vytvoří z předchozího souboru jako jeho podřízeného.
"node"	V rozšířeném dokumentu se uzel (někdy označovaný jako "poznámka") vytvoří a naplní dovednostmi, jako je například text a layoutText v dovednostech OCR. Do rozšířeného dokumentu se doplní hodnoty obohacení i původní hodnoty zdrojových polí nebo metadata zkopírovaná ze zdroje.
"kontext"	Rozsah rozšiřování, což je buď celý dokument, část dokumentu, nebo pokud pracujete s obrázky, extrahované obrázky z dokumentu. Kontext rozšiřování je ve výchozím nastavení na `"/document"` úrovni vymezený na jednotlivé dokumenty obsažené ve zdroji dat. Když se dovednost spustí, výstupy této dovednosti se stanou vlastnostmi definovaného kontextu.

Cesty pro různé scénáře

Cesty se zadají ve vlastnostech "kontextu" a "zdroje" sady dovedností a ve výstupním mapování polí v indexeru.

Příklad na snímku obrazovky znázorňuje cestu položky v kolekci Azure Cosmos DB.

context cesta je /document/HotelId proto, že kolekce je rozdělena do dokumentů podle /HotelId pole.
source cesta je /document/Description proto, že dovednost je dovednost překladu a pole, které budete chtít, aby dovednost přeložil, je Description pole v každém dokumentu.

Všechny cesty začínají /documentna . Obohacený dokument se vytvoří ve fázi "prolomení dokumentu" spuštění indexeru, když indexer otevře dokument nebo přečte v řádku ze zdroje dat. Na začátku je jediným uzlem v rozšířeném dokumentu kořenový uzel (/document)a je to uzel, ze kterého probíhají všechny ostatní rozšiřování.

Následující seznam obsahuje několik běžných příkladů:

/document je kořenový uzel a označuje celý objekt blob ve službě Azure Storage nebo řádek v tabulce SQL.
/document/{key} je syntaxe dokumentu nebo položky v kolekci Azure Cosmos DB, kde {key} je skutečný klíč, například /document/HotelId v předchozím příkladu.
/document/content určuje vlastnost content objektu blob JSON.
/document/{field} je syntaxe pro operaci prováděnou u konkrétního pole, jako je například překlad /document/Description pole, jak je vidět v předchozím příkladu.
/document/pages/* nebo /document/sentences/* se stát kontextem, pokud rozdělíte velký dokument na menší bloky pro zpracování. Pokud je /document/pages/*"kontext", dovednost se provede jednou přes každou stránku v dokumentu. Protože může existovat více než jedna stránka nebo věta, připojíte /* je, abyste je všechny zachytili.
/document/normalized_images/* je vytvořen během prolomení dokumentu, pokud dokument obsahuje obrázky. Všechny cesty k obrázkům začínají normalized_images. Vzhledem k tomu, že v dokumentu je často vloženo více obrázků, připojte /*.

Ve zbývající části tohoto článku jsou příklady založené na poli "content" generovaného automaticky indexery objektů blob Azure v rámci fáze prolomení dokumentu. Při odkazování na dokumenty z kontejneru objektů blob použijte formát, například "/document/content", kde pole "obsah" je součástí "dokumentu".

Příklad 1: Jednoduchý odkaz na poznámky

Předpokládejme, že ve službě Azure Blob Storage máte celou řadu souborů obsahujících odkazy na jména lidí, které chcete extrahovat pomocí rozpoznávání entit. V následující definici "/document/content" dovednosti je textová reprezentace celého dokumentu a "lidé" je extrakce úplných jmen entit identifikovaných jako osob.

Vzhledem k tomu, že výchozí kontext je "/document", seznam lidí lze nyní odkazovat jako "/document/people". V tomto konkrétním případě "/document/people" je poznámka, která by teď mohla být namapována na pole v indexu nebo použita v jiné dovednosti ve stejné sadě dovedností.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Příklad 2: Odkazování na pole v dokumentu

Tento příklad vychází z předchozího kroku, který ukazuje, jak vyvolat krok rozšiřování vícekrát ve stejném dokumentu. Předpokládejme, že předchozí příklad vygeneroval pole řetězců s 10 jmény lidí z jednoho dokumentu. Rozumným dalším krokem může být druhé rozšiřování, které extrahuje příjmení z celého jména. Vzhledem k tomu, že existuje 10 jmen, chcete, aby tento krok byl v tomto dokumentu volána 10krát, jednou pro každou osobu.

Chcete-li vyvolat správný počet iterací, nastavte kontext jako "/document/people/*", kde hvězdička ("*") představuje všechny uzly v rozšířeném dokumentu jako potomky "/document/people". I když je tato dovednost definována pouze jednou v poli dovedností, volá se pro každého člena v dokumentu, dokud nebudou všichni členové zpracováni.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Pokud jsou poznámky matice nebo kolekce řetězců, můžete chtít cílit na konkrétní členy, nikoli na pole jako celek. Výše uvedený příklad vygeneruje poznámku volanou "last" pod každým uzlem reprezentovaným kontextem. Pokud chcete odkazovat na tuto řadu poznámek, můžete použít syntaxi "/document/people/*/last". Pokud chcete odkazovat na konkrétní poznámku, můžete použít explicitní index: "/document/people/1/last" k odkazování na příjmení první osoby identifikované v dokumentu. Všimněte si, že v těchto polích syntaxe je indexováno 0.

Příklad 3: Odkazování členů v rámci pole

Někdy potřebujete seskupit všechny poznámky určitého typu, abyste je předali určité dovednosti. Představte si hypotetickou vlastní dovednost, která identifikuje nejběžnější příjmení ze všech příjmení extrahovaných v příkladu 2. Chcete-li zadat pouze příjmení vlastní dovednosti, zadejte kontext jako "/document" a vstup jako "/document/people/*/lastname".

Všimněte si, že kardinalita dokumentu je větší než kardinalita "/document/people/*/lastname" dokumentu. Může existovat 10 uzlů příjmení, zatímco pro tento dokument je jenom jeden uzel dokumentu. V takovém případě systém automaticky vytvoří pole "/document/people/*/lastname" obsahující všechny prvky v dokumentu.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Tipy pro řešení potíží s cestou poznámek

Pokud máte potíže s určením vstupů dovedností, můžou vám tyto tipy pomoct posunout se dopředu:

Spusťte průvodce importem dat nad daty a zkontrolujte definice sady dovedností a mapování polí, které průvodce vygeneruje.
Spuštění ladicí relace v sadě dovedností pro zobrazení struktury rozšířeného dokumentu. Můžete upravit cesty a další části definice dovednosti a pak spustit dovednost k ověření změn.