Tworzenie zestawu umiejętności (interfejs API REST usługi Azure AI Search)
Zestaw umiejętności to zbiór umiejętności poznawczych używanych do wzbogacania sztucznej inteligencji z opcjonalną specyfikacją tworzenia zewnętrznego magazynu wiedzy w usłudze Azure Storage. Umiejętności wywołują przetwarzanie języka naturalnego i inne przekształcenia, takie jak rozpoznawanie jednostek, wyodrębnianie kluczowych fraz, dzielenie tekstu na strony logiczne, między innymi.
Zestaw umiejętności jest dołączony do indeksatora. Aby użyć zestawu umiejętności, odwoływanie się do niego w indeksatorze, a następnie uruchamianie indeksatora w celu importowania danych, wywoływania przekształceń i wzbogacania oraz mapowania pól wyjściowych na indeks. Zestaw umiejętności jest zasobem wysokiego poziomu, ale działa tylko w ramach przetwarzania indeksatora. Jako zasób wysokiego poziomu można zaprojektować zestaw umiejętności raz, a następnie odwołać się do niego w wielu indeksatorach.
Możesz użyć polecenia POST lub PUT w żądaniu. W przypadku każdej z nich dokument JSON w treści żądania zawiera definicję obiektu.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Protokół HTTPS jest wymagany dla wszystkich żądań obsługi. Jeśli zestaw umiejętności nie istnieje, zostanie utworzony. Jeśli już istnieje, zostanie zaktualizowana do nowej definicji.
Uwaga
Zestawy umiejętności są podstawą wzbogacania sztucznej inteligencji. Bezpłatny zasób jest dostępny do ograniczonego przetwarzania, ale w przypadku większych lub częstszych obciążeń wymagany jest rozliczany zasób usług Cognitive Services .
Parametry identyfikatora URI
| Parametr | Opis |
|---|---|
| nazwa usługi | Wymagane. Ustaw tę wartość na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania. |
| nazwa zestawu umiejętności | Wymagane w identyfikatorze URI, jeśli używasz funkcji PUT. Nazwa musi mieć małe litery, zaczyna się literą lub cyfrą, nie ma ukośników ani kropek i ma mniej niż 128 znaków. Nazwa musi zaczynać się literą lub cyfrą, ale reszta nazwy może zawierać dowolną literę, cyfrę i kreski, o ile kreski nie są kolejne. |
| api-version | Wymagane. Zobacz Wersje interfejsu API , aby uzyskać listę obsługiwanych wersji. |
Nagłówki żądań
W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.
| Pola | Opis |
|---|---|
| Content-Type | Wymagane. Ustaw tę wartość na application/json |
| api-key | Opcjonalnie, jeśli używasz ról platformy Azure , a token elementu nośnego jest udostępniany w żądaniu, w przeciwnym razie wymagany jest klucz. Tworzenie żądań musi zawierać api-key nagłówek ustawiony na klucz administratora (w przeciwieństwie do klucza zapytania). Aby uzyskać szczegółowe informacje, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza . |
Treść żądania
Treść żądania zawiera definicję zestawu umiejętności. Umiejętności są autonomiczne lub połączone razem za pomocą skojarzeń wejściowych wyjściowych, w których dane wyjściowe jednej transformacji stają się danymi wejściowymi. Zestaw umiejętności musi mieć co najmniej jedną umiejętność. Nie ma teoretycznego limitu maksymalnej liczby umiejętności, ale trzy do pięciu jest wspólną konfiguracją.
Poniższy kod JSON jest wysoką reprezentacją głównych części definicji.
{
"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) { }
}
Żądanie zawiera następujące właściwości:
| Właściwość | Opis |
|---|---|
| name | Wymagane. Nazwa zestawu umiejętności. Nazwa musi mieć małe litery, zaczyna się literą lub cyfrą, nie ma ukośników ani kropek i ma mniej niż 128 znaków. Nazwa musi zaczynać się literą lub cyfrą, ale reszta nazwy może zawierać dowolną literę, cyfrę i kreski, o ile kreski nie są kolejne. |
| Umiejętności | Tablica umiejętności. Każda umiejętność ma parametry odata.type, name, context i input i output. Tablica może zawierać wbudowane umiejętności i umiejętności niestandardowe. Wymagana jest co najmniej jedna umiejętność. Jeśli używasz magazynu wiedzy, dołącz umiejętności kształtowania , chyba że definiujesz kształt danych w projekcji. |
| cognitiveServices | Klucz all-in-one jest wymagany w przypadku umiejętności rozliczalnych, które nazywają interfejsy API usług Cognitive Services więcej niż 20 dokumentów dziennie, na indeksator. Klucz musi być przeznaczony dla zasobu w tym samym regionie co usługa wyszukiwania. Aby uzyskać więcej informacji, zobacz Dołączanie zasobu usług Cognitive Services. Jeśli używasz umiejętności wyszukiwania jednostek niestandardowych , uwzględnij tę sekcję i klucz, aby włączyć transakcje przekraczające 20 transakcji dziennie na indeksator. Nie potrzebujesz klucza usług Cognitive Services i dlatego możesz wykluczyć cognitiveServices sekcję, jeśli twój zestaw umiejętności składa się tylko z umiejętności niestandardowych, umiejętności narzędziowych (warunkowe, kształtator, scalanie tekstu, dzielenie tekstu) lub umiejętności wyodrębniania dokumentów. Jeśli chcesz usunąć dołączony zasób usługi Cognitive Service z zestawu umiejętności (aby przywrócić użycie "domyślnych" limitów) określ @odata.type jako #Microsoft.Azure.Search.DefaultCognitiveServices, zobacz ten przykład , aby uzyskać więcej informacji. |
| knowledgeStore | Opcjonalny. Miejsce docelowe dla danych wyjściowych wzbogacania do usługi Azure Storage. Wymaga parametry połączenia do konta usługi Azure Storage i projekcji.
storageConnectionString (wymagane) Ciąg w tym formacie: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".
projections (wymagane) Tablica obiektów projekcji składających się z tables, objects, filesktóre są określone lub null.
tables
Tworzy co najmniej jedną tabelę w usłudze Azure Table Storage, projektując zawartość z każdego dokumentu jako wiersze w tabeli. Każda tabela może mieć następujące trzy właściwości:
objects
Projektuje dokumenty jako obiekty blob w Azure Blob Storage. Każdy obiekt ma dwie wymagane właściwości:
files
Każdy wpis pliku definiuje magazyn obrazów binarnych w usłudze Blob Storage. Projekcje plików mają dwie wymagane właściwości:
|
| encryptionKey | Opcjonalny. Służy do szyfrowania definicji zestawu umiejętności magazynowanych przy użyciu własnych kluczy zarządzanych w usłudze Azure Key Vault. Dostępne dla rozliczanych usług wyszukiwania utworzonych w dniach lub po 2019-01-01.
Sekcja encryptionKey zawiera zdefiniowaną przez keyVaultKeyName użytkownika (wymaganą), wygenerowaną keyVaultKeyVersion przez system (wymaganą keyVaultUri ) i podając klucz (wymagany, nazywany również nazwą DNS). Przykładowy identyfikator URI może być "https://my-keyvault-name.vault.azure.net".
Opcjonalnie możesz określić accessCredentials , czy nie używasz tożsamości systemu zarządzanego. Właściwości dołączania accessCredentialsapplicationId (identyfikator aplikacji Tożsamość Microsoft Entra, który otrzymał uprawnienia dostępu do określonej Key Vault platformy Azure) i applicationSecret (klucz uwierzytelniania zarejestrowanej aplikacji). Przykład w następnej sekcji ilustruje składnię. |
Reakcja
W przypadku pomyślnego żądania powinien zostać wyświetlony kod stanu "201 Utworzony".
Domyślnie treść odpowiedzi będzie zawierać kod JSON dla utworzonej definicji zestawu umiejętności.
Prefer Jeśli jednak nagłówek żądania ma wartość return=minimal, treść odpowiedzi jest pusta, a kod stanu powodzenia to "204 Brak zawartości" zamiast "201 Utworzono". Jest to prawdziwe niezależnie od tego, czy put czy POST jest używany do tworzenia zestawu umiejętności.
Przykłady
Przykład: zestaw umiejętności, który rozpoznaje jednostki biznesowe i tonację w recenzjach klientów
Ten zestaw umiejętności korzysta z dwóch umiejętności asynchronicznie, niezależnie przetwarza /document/content się jako dwie różne przekształcenia. Umiejętności to rozpoznawanie jednostek i tonacja. W drzewie /document/content wzbogacania zawartość (lub przeglądy klientów) z zewnętrznego źródła danych.
{
"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": { }
}
Przykład: magazyn wiedzy
Zestaw umiejętności może opcjonalnie wysyłać dane wyjściowe do magazynu wiedzy w usłudze Azure Storage. Wymaga parametry połączenia do konta usługi Azure Storage i projekcji, które określają, czy wzbogacona zawartość ląduje w magazynie tabel lub obiektów blob (jako obiekty lub pliki). Projekcje zwykle wymagają nadrzędnej umiejętności kształtowania , która zbiera węzły z drzewa wzbogacania jako dane wejściowe, generując pojedynczy kształt, który można przekazać do projekcji. Kształtator jest zazwyczaj ostatnią umiejętnością do przetworzenia.
{
"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": { }
}
Przykład: klucze szyfrowania
Klucze szyfrowania to klucze zarządzane przez klienta używane do dodatkowego szyfrowania poufnej zawartości. W tym przykładzie pokazano, jak określić szyfrowanie zarządzane przez klienta na zestawie umiejętności.
{
"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)"}
}
}
Zobacz też
- Definiowanie zestawu umiejętności
- Omówienie wzbogacania sztucznej inteligencji
- Omówienie zestawu umiejętności
- Omówienie magazynu wiedzy
- Omówienie projekcji
- Samouczek: generowanie zawartości z możliwością wyszukiwania na podstawie obiektów blob przy użyciu interfejsu REST i sztucznej inteligencji
- Wbudowane umiejętności