Vytvoření sady dovedností (rozhraní REST API služby Azure AI Search)
Sada dovedností je kolekce kognitivních dovedností , které se používají k rozšiřování AI, s volitelnou specifikací pro vytvoření externího úložiště znalostí ve službě Azure Storage. Dovednosti vyvolávají zpracování přirozeného jazyka a další transformace, jako je rozpoznávání entit, extrakce klíčových frází, rozdělení textu do logických stránek 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í transformací a rozšiřování a mapování výstupních polí na index. Sada dovedností je prostředek vysoké úrovně, ale funguje pouze v rámci zpracování indexeru. Jako prostředek vysoké úrovně můžete sadu dovedností navrhnout jednou a pak na ni odkazovat v několika indexerech.
Na žádost můžete použít post nebo PUT. U obou z nich dokument JSON v textu požadavku poskytuje definici objektu.
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. Pokud sada dovedností neexistuje, vytvoří se. Pokud už existuje, aktualizuje se na novou definici.
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 se vyžaduje fakturovatelný prostředek Služeb Cognitive Services .
Parametry identifikátoru URI
| Parametr | Popis |
|---|---|
| název služby | Povinná hodnota. Nastavte ho 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ů. Název musí začínat písmenem nebo číslicí, ale zbytek názvu může obsahovat jakékoli písmeno, číslice a pomlčky, pokud pomlčky nejsou po sobě jdoucí. |
| verze-api | Povinná hodnota. Seznam podporovaných verzí najdete v tématu Verze rozhraní API . |
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 možnost 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íč. 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ů. Název musí začínat písmenem nebo číslicí, ale zbytek názvu může obsahovat jakékoli písmeno, číslice 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. 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ý obrazec. |
| 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. Pokud používáte dovednost Vlastní vyhledávání entit , zahrňte tuto část a klíč pro povolení transakcí nad rámec 20 transakcí denně na indexer. Nepotřebujete klíč služeb Cognitive Services, takže můžete vyloučit cognitiveServices oddíl, pokud se vaše sada dovedností skládá pouze z vlastních dovedností, užitkové dovednosti (podmíněné, tvarovací, sloučení textu, rozdělení textu) nebo dovednosti extrakce dokumentů. Pokud chcete odebrat připojený prostředek kognitivní služby ze sady dovedností (abyste se vrátili k používání "výchozích" limitů), zadejte @odata.type jako #Microsoft.Azure.Search.DefaultCognitiveServices, Další informace najdete v tomto příkladu . |
| ú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. storageConnectionString (povinné) Řetězec v tomto formátu: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections (povinné) Pole objektů projekce, které se skládají z tables, objects, fileskteré jsou buď zadané, nebo null. tablesVytvoří jednu nebo více tabulek ve službě Azure Table Storage a promítá obsah z každého dokumentu jako řádky tabulky. Každá tabulka může mít následující tři vlastnosti:
objectsDokumenty projektů jako objekty blob v Azure Blob Storage. Každý objekt má dvě požadované vlastnosti:
filesKaž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:
|
| šifrovací klíč | Nepovinný parametr. Používá se k šifrování neaktivních uložených definic sady dovedností pomocí vlastních klíčů spravovaných ve službě Azure Key Vault. K dispozici pro fakturovatelné vyhledávací služby vytvořené 1. 1. 2019 nebo později. Oddíl encryptionKey obsahuje uživatelem definovaný (povinné), systémově vygenerovaný keyVaultKeyNamekeyVaultKeyVersion (povinné) a klíč s poskytnutím keyVaultUri (povinný, označovaný také jako název DNS). Příkladem identifikátoru URI může být "https://my-keyvault-name.vault.azure.net". Volitelně můžete určit accessCredentials , jestli nepoužíváte identitu spravovaného systému. accessCredentials Vlastnosti zahrnují applicationId (Microsoft Entra ID ID aplikace, kterému byla udělena přístupová oprávnění k zadanému Key Vault Azure) a applicationSecret (ověřovací klíč registrované aplikace). Příklad v další části znázorňuje syntaxi. |
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 Prefer požadavku nastavená na return=minimal, text odpovědi je prázdný a stavový kód úspěchu je "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í
Sada dovedností může volitelně odesílat výstup do úložiště znalostí ve službě Azure Storage. Vyžaduje připojovací řetězec k účtu služby 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 obvykle 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.
{
"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": "<your storage account connection string>",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
Příklad: Šifrovací klíče
Šifrovací klíče jsou klíče spravované zákazníkem, které slouží k další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)"}
}
}