Sdílet prostřednictvím

Vytvoření nebo aktualizace sady dovedností (ROZHRANÍ REST API verze Preview)

  • Článek

Platí pro: 2023-07-01-Preview, 2021-04-30-Preview

Důležité

2023-07-01-Preview (beze změn).

Verze 2021-04-30-Preview přidává podporu spravovaných identit pro připojení související se sadou dovedností:

  • StorageConnectionString v úložišti znalostí přijímá ID prostředku Azure pro ověřování Azure AD.
  • Identita přijímá spravovanou identitu přiřazenou uživatelem. Tato vlastnost se nachází v úložišti znalostí. Nachází se také v části encryptionKey pro načtení klíče spravovaného zákazníkem v Azure Key Vault.

Toto rozhraní API verze Preview také podporuje připojení spravované identity z vlastní dovednosti. Podrobnosti najdete v referenčních informacích k vlastnímu webovému rozhraní API .

Sada dovedností je kolekce kognitivních dovedností , které se používají k obohacení AI, s možností vytvořit také externí úložiště znalostí ve službě Azure Storage. Dovednosti vyvolávají zpracování přirozeného jazyka a další procesy strojového učení, jako je rozpoznávání entit, extrakce klíčových frází, rozdělení textu na logické stránky a další.

Sada dovedností je připojená k indexeru. Pokud chcete sadu dovedností použít, odkažte na ni v indexeru a pak spusťte indexer pro import dat, vyvolání rozšiřování a odeslání výstupu do indexu. Sada dovedností je prostředek vysoké úrovně, ale funguje pouze v rámci zpracování indexeru. Jako prostředek vysoké úrovně na něj můžete odkazovat ve více indexerech.

V žádosti o vytvoření můžete použít post nebo PUT. U obou z nich text požadavku poskytuje definici objektu.

POST https://[service name].search.windows.net/skillsets?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

V případě žádostí o aktualizaci použijte PUT a v identifikátoru URI zadejte název sady dovedností.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
  Content-Type: application/json  
  api-key: [admin key]

Https se vyžaduje pro všechny žádosti o služby.

Vytvořením sady dovedností se přidá do vyhledávací služby.

Aktualizace sady dovedností zcela přepíše stávající sadu dovedností obsahem datové části požadavku. Osvědčeným postupem pro aktualizace je načíst definici sady dovedností pomocí get, upravit ji a pak aktualizovat pomocí PUT.

Poznámka

Sady dovedností jsou základem rozšiřování AI. Bezplatný prostředek je k dispozici pro omezené zpracování, ale pro větší nebo častější úlohy připojte fakturovatelný prostředek Služeb Cognitive Services.

Parametry identifikátoru URI

Parametr Popis
název služby Povinná hodnota. Nastavte tuto vlastnost na jedinečný, uživatelem definovaný název vaší vyhledávací služby.
název sady dovedností Vyžaduje se u identifikátoru URI, pokud používáte PUT. Název musí být malé, musí začínat písmenem nebo číslicí, nesmí obsahovat lomítka ani tečky a musí být kratší než 128 znaků. Jakmile začnete jméno písmenem nebo číslicí, může zbytek názvu obsahovat libovolné písmeno, číslo a pomlčky, pokud pomlčky nejsou po sobě jdoucí.
verze-api Povinná hodnota. Aktuální verze Preview je 2023-07-01-Preview. Další verze najdete v tématu Verze rozhraní API .
disableCacheReprocessingChangeDetection Volitelné (false ve výchozím nastavení). Platí pro scénáře aktualizací a použití rozšíření v mezipaměti během provádění sady dovedností. true Pokud chcete zabránit aktualizacím stávajících dokumentů na základě aktuální akce, například pokud chcete aktualizovat sadu dovedností bez spuštění sady dovedností, nastavte na hodnotu . Další informace najdete v tématu Obcházení vyhodnocení sady dovedností.

Hlavičky požadavku

Následující tabulka popisuje požadovanou a volitelnou hlavičku požadavku.

Pole Description
Typ obsahu Povinná hodnota. Nastavte tuto vlastnost na application/json
klíč rozhraní API Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Klíč api-key je jedinečný, systémem vygenerovaný řetězec, který ověřuje požadavek na vaši vyhledávací službu. Požadavky na vytvoření musí obsahovat hlavičku nastavenou api-key na klíč správce (na rozdíl od klíče dotazu). Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Text požadavku

Tělo požadavku obsahuje definici sady dovedností. Dovednosti jsou buď samostatné, nebo zřetězí prostřednictvím přidružení vstupu a výstupu, kdy se výstup jedné transformace stane vstupem do jiné. Sada dovedností musí mít alespoň jednu dovednost. Neexistuje žádné teoretické omezení maximálního počtu dovedností, ale běžnou konfigurací je tři až pět.

Následující kód JSON představuje základní reprezentaci hlavních částí definice.

{   
  "name" : (optional on PUT; required on POST) "Name of the skillset",  
  "description" : (optional) "Anything you want, or nothing at all",   
  "skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
  "cognitiveServices": 
      {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "Optional. Anything you want, or null",
        "key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
      },
  "knowledgeStore": (optional) { ... },
  "encryptionKey": (optional) { }
}

Požadavek obsahuje následující vlastnosti:

Vlastnost Popis
name Povinná hodnota. Název sady dovedností. Název musí být malé, musí začínat písmenem nebo číslicí, nesmí obsahovat lomítka ani tečky a musí být kratší než 128 znaků. Jakmile začnete jméno písmenem nebo číslicí, může zbytek názvu obsahovat libovolné písmeno, číslo a pomlčky, pokud pomlčky nejsou po sobě jdoucí.
Dovednosti Pole dovedností. Každá dovednost má odata.type, název, kontext a vstupní a výstupní parametry. Referenční informace o dovednostech najdete v koncepční dokumentaci. Pole může zahrnovat předdefinované dovednosti a vlastní dovednosti. Vyžaduje se alespoň jedna dovednost. Pokud používáte úložiště znalostí, zahrňte dovednost Shaper , pokud v rámci projekce nedefinujete datový tvar.
cognitiveServices Klíč vše v jednom se vyžaduje pro fakturovatelné dovednosti, které volají rozhraní API služeb Cognitive Services na více než 20 dokumentů denně na indexer. Klíč musí být pro prostředek ve stejné oblasti jako vyhledávací služba. Další informace najdete v tématu Připojení prostředku služeb Cognitive Services.

Klíč a tuto část můžete vynechat, pokud se vaše sada dovedností skládá pouze z vlastních dovedností, užitkové dovednosti (podmíněné, tvarovač, sloučení textu, rozdělení textu) nebo dovednosti extrakce dokumentů.

Pokud používáte dovednost Vlastní vyhledávání entit , zahrňte tuto část a klíč, abyste povolili transakce nad 20 transakcí denně na indexer.
úložiště knowledgeStore Nepovinný parametr. Cíl pro výstup rozšíření do Azure Storage. Vyžaduje připojovací řetězec k účtu služby Azure Storage a projekcím.
šifrovací klíč Nepovinný parametr. Používá se k šifrování citlivých dat v definici sady dovedností s vlastními klíči spravovanými ve službě Azure Key Vault. Další informace najdete v tématu Šifrování služby Azure AI Search pomocí klíčů spravovaných zákazníkem v Azure Key Vault.

Odpověď

V případě úspěšného požadavku by se měl zobrazit stavový kód 201 Vytvořeno.

Ve výchozím nastavení bude text odpovědi obsahovat json pro definici sady dovedností, která byla vytvořena. Pokud je ale hlavička žádosti Prefer nastavená na return=minimal, text odpovědi bude prázdný a stavový kód úspěchu bude "204 Žádný obsah" místo "201 Vytvořeno". To platí bez ohledu na to, jestli se k vytvoření sady dovedností používá PUT nebo POST.

Příklady

Příklad: Sada dovedností, která rozpozná obchodní entity a mínění v zákaznických recenzích

Tato sada dovedností používá dvě dovednosti asynchronně, nezávisle na zpracování /document/content jako dvě různé transformace. Dovednosti jsou Rozpoznávání entit a Mínění. Ve stromu /document/content rozšiřování poskytuje obsah (nebo recenze zákazníků) z externího zdroje dat.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
      "context": "/document/content",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companyName"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
      "inputs": [
           {
              "name": "text",
              "source": "/document/content"
           },
          {
               "name": "languageCode",
               "source": "/document/languageCode"
           }
        ],
      "outputs": [
        {
            "name": "sentiment",
            "targetName": "reviewSentiment"
        },
        {
            "name": "confidenceScores",
            "targetName": "sentimentScore"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { },
  "encryptionKey": { }
}

Příklad: Úložiště znalostí s úplným přístupem připojovací řetězec a tvarovanými vstupy

Úložiště znalostí vyžaduje připojovací řetězec k účtu Azure Storage a projekce, které určují, jestli se obohacený obsah dostane do úložiště tabulek nebo objektů blob (jako objektů nebo souborů).

Projekce, zejména projekce tabulek, vyžadují upstreamovou dovednost Shaper , která shromažďuje uzly ze stromu rozšiřování jako vstup a vypíše jeden obrazec, který lze předat do projekce. Tvarovač je obvykle poslední dovedností, která se má zpracovat. V projekci tabulky určují pole v tabulce uzly v dovednostech shaperu.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    { ... },
    { ... },
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [
        {
            "name": "Company",
            "source": "/document/content/companyName"
        },
        {
            "name": "Sentiment_Score",
            "source": "/document/content/sentimentScore"
        },
        {
            "name": "Sentiment_Label",
            "source": "/document/content/reviewSentiment"
        }
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "shapeCustomerReviews"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { 
      "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net;", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

Příklad: Připojení pomocí spravované identity

Spravované identity je možné použít při připojeních k úložišti znalostí a k externímu kódu z vlastní dovednosti. Tento příklad ukazuje oba scénáře. Pro úložiště znalostí další vlastnost identity určuje spravovanou identitu přiřazenou uživatelem vyhledávací služby, kterou Azure AD používá k ověření požadavku. Pokud vynecháte identitu, použije se spravovaná identita přiřazená systémem vyhledávací služby. Aby bylo možné ověřit volajícího Azure AD, musí být vyhledávací služba nakonfigurovaná pro spravovanou identitu. Identita vyhledávání musí mít oprávnění Přispěvatel dat v objektech blob služby Storage pro zápis do služby Azure Storage.

Vlastní dovednost může spravovanou identitu použít k ověřování ve funkci Azure nebo v aplikaci, která hostuje váš vlastní kód. Obsahuje vlastnost "authResourceId", která označuje, že připojení je ověřeno pomocí spravované identity. Hodnota authResourceId je ID aplikace vytvořené zprostředkovatelem identity Microsoftu. Tato hodnota se použije k ověření ověřovacího tokenu načteného indexerem a odešle se spolu s vlastním požadavkem rozhraní API pro webové dovednosti.

{
  "name": "reviews-ss",
  "description": "A short description",
  "skills":
  [
    { ... },
    { ... },
    {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "sampleCustomSkill",
        "description": "A custom skill that requests an access token for the application ID specified in authResourceID",
        "context": "/document",
        "uri": "https://[your-app-name].azurewebsites.net/api/EntitySearch",
        "authResourceId": "api://xyz*****-****-****-****-********9876",
        "batchSize": 4,
        "degreeOfParallelism": null,
        "inputs": [
          {
            "name": "text",
            "source": "/document/content"
          },
          {
            "name": "language",
            "source": "/document/languageCode"
          },
          {
            "name": "phraseList",
            "source": "/document/keyphrases"
          }
        ],
        "outputs": [
          {
            "name": "<customSkillOutput>"
          }
        ]
      }
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [ ... ],
      "outputs": [ ...]
    }
  ],
  "cognitiveServices": { ... },
  "knowledgeStore": { 
      "storageConnectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;",
      "identity": {
          "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
          "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]",
      "projections": [ 
          { 
            "tables": [ ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  }
  "encryptionKey": { }
}

Příklad: Šifrovací klíče

Šifrovací klíče jsou klíče spravované zákazníkem, které slouží k doplňkovému šifrování citlivého obsahu. Tento příklad ukazuje, jak zadat šifrování spravované zákazníkem v sadě dovedností.

{
    "name": "reviews-ss",
    "description": "A brief description of the skillset",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
    "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
        "keyVaultKeyVersion": "Version of the Azure Key Vault key",
        "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
        "accessCredentials": (optional, only if not using managed system identity) {
            "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
            "applicationSecret": "Authentication key of the specified Azure AD application)"}
    }
}

Definice

Odkaz Description
knowledgeStore Konfiguruje připojení ke službě Azure Storage a projekty rozšířeného obsahu ve formě objektů, souborů a tabulek pro použití scénářů dolování znalostí a zpracování dat.
šifrovací klíč Konfiguruje připojení k Azure Key Vault pro šifrování spravované zákazníkem.

knowledgeStore

Úložiště znalostí je úložištěm obohacených dat vytvořeným kanálem sady dovedností a rozšíření AI. Nachází se ve službě Azure Storage a skládá se z projekcí dat ve formě objektů, souborů a tabulek. Používá se pro scénáře bez vyhledávání, jako je dolování znalostí, zkoumání dat v Power BI, nebo jako jímka dat pro další zpracování jinými aplikacemi.

Připojení ke službě Azure Storage je buď úplná přístupová připojovací řetězec, která obsahuje klíč, nebo ID prostředku úložiště za předpokladu, že vyhledávací služba běží pod spravovanou identitou a má přiřazenou roli Azure, která uděluje přístup zápisu ke koncovému bodu úložiště znalostí.

Atribut Popis
storageConnectionString Povinná hodnota. Řetězec v jednom z těchto formátů:

"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net"

"ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
identity Nepovinný parametr. Obsahuje typ #Microsoft.Azure.Search.DataUserAssignedIdentity a určuje spravovanou userAssignedIdentity identitu vyhledávací služby přiřazenou uživatelem. Tato vlastnost závisí na storageConnectionString připojovací řetězec, která určuje ID prostředku vašeho účtu úložiště.

identity Pokud je vlastnost null, připojení k ID prostředku se vytvoří pomocí vlastnosti spravované systémem.

Pokud je tato vlastnost přiřazena typu #Microsoft.Azure.Search.DataNoneIdentity, vymaže se jakákoli explicitní identita, která byla dříve zadána.
Projekce Povinná hodnota. Pole projekcí skládajících se z tables, objectsfiles, které jsou buď zadané, nebo null.

Projekce

Projekce jsou definice datových struktur v úložišti znalostí. Všechna jména jsou definovaná uživatelem. Můžete přijmout zásady vytváření názvů, které vám pomůžou identifikovat související obsah ve službě Azure Storage.

Atribut Popis
V tabulkách Promítá datové obrazce do jedné nebo více tabulek ve službě Azure Table Storage, kde se prvky z každého dokumentu promítají do řádků v tabulce. Každá tabulka může mít následující tři vlastnosti.

Nejprve (povinné) určí tabulku, name která se má vytvořit nebo použít ve službě Azure Table Storage.

Druhý ( generatedKeyName volitelný) je název sloupce, který jednoznačně identifikuje dokument. Hodnoty pro tento sloupec budou generovány během rozšiřování. Pokud ho vynecháte, vyhledávací služba vytvoří výchozí sloupec klíče na základě názvu tabulky.

Třetí , source (povinné) je cesta k uzlu stromu rozšiřování, který poskytuje tvar projekce. Obvykle je to výstup dovednosti Shaper. Cesty začínají na /document/, což představuje kořenový rozšířený dokument a pak se rozšíří na /document/<shaper-output>/, nebo /document/content/nebo na jiný uzel ve stromu rozšiřování. Příklady: /document/countries/* (všechny země) nebo /document/countries/*/states/* (všechny státy ve všech zemích).
– objekty Projekty dokumentů jako objektů blob v Azure Blob Storage. Každý objekt má dvě požadované vlastnosti.

První je název kontejneru, storageContainer který se má vytvořit nebo použít v Azure Blob Storage.

source Za druhé je cesta k uzlu stromu rozšiřování, který poskytuje tvar projekce. Musí to být platný kód JSON. Uzel musí poskytnout objekt JSON, a to buď z dovednosti, která vygeneruje platný kód JSON, nebo z výstupu dovednosti Shaper.
files Každá položka souboru definuje úložiště binárních obrázků ve službě Blob Storage.

Projekce souborů mají dvě požadované vlastnosti. První je název kontejneru, storageContainer který se má vytvořit nebo použít v Azure Blob Storage.

source Za druhé je cesta k uzlu stromu rozšiřování, který je kořenem projekce. Platná hodnota této vlastnosti je "/document/normalized_images/*" pro obrázky, které byly pořízeny ze služby Blob Storage.

šifrovací klíč

Konfiguruje připojení k Azure Key Vault pro dodatečné šifrovací klíče spravované zákazníkem (CMK). Šifrování pomocí klíčů spravovaných zákazníkem není k dispozici pro bezplatné služby. U fakturovatelných služeb je k dispozici jenom pro vyhledávací služby vytvořené 1. 1. 2019 nebo později.

Připojení k trezoru klíčů musí být ověřené. K tomuto účelu můžete použít buď "accessCredentials", nebo spravovanou identitu.

Spravované identity můžou být přiřazené systémem nebo uživatelem (Preview). Pokud má vyhledávací služba spravovanou identitu přiřazenou systémem i přiřazení role, které uděluje přístup pro čtení trezoru klíčů, můžete vynechat identity i accessCredentials a požadavek se ověří pomocí spravované identity. Pokud má vyhledávací služba identitu a přiřazení role přiřazenou uživatelem, nastavte vlastnost identity na ID prostředku této identity.

Atribut Popis
keyVaultKeyName Povinná hodnota. Název klíče azure Key Vault použitého k šifrování
keyVaultKeyVersion Povinná hodnota. Verze klíče azure Key Vault.
keyVaultUri Povinná hodnota. Identifikátor URI azure Key Vault (označovaný také jako název DNS), který poskytuje klíč. Příkladem identifikátoru URI může být https://my-keyvault-name.vault.azure.net.
accessCredentials Pokud používáte spravovanou identitu, tuto možnost nepoužívejte. Jinak vlastnosti accessCredentials include applicationId (ID aplikace Azure Active Directory, které má přístupová oprávnění k zadané Key Vault Azure) a applicationSecret (ověřovací klíč zadané Azure AD aplikace).
identity Volitelné, pokud pro připojení Vyhledávací služby k Azure Key Vault nepoužíváte spravovanou identitu přiřazenou uživatelem. Formát je "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Viz také