Képességkészlet létrehozása (Azure AI Search REST API)
A képességkészlet az AI-bővítéshez használt kognitív képességek gyűjteménye, amely opcionális specifikációval rendelkezik egy külső tudástár létrehozásához az Azure Storage-ban. A készségek többek között természetes nyelvi feldolgozást és más átalakításokat, például entitásfelismerést, kulcskifejezés-kinyerést, szöveg logikai oldalakra való feldarabolását hívják meg.
Egy képességcsoport egy indexelőhöz van csatolva. A képességkészlet használatához hivatkozzon rá egy indexelőben, majd futtassa az indexelőt adatok importálásához, átalakítások és bővítés meghívásához, valamint a kimeneti mezők indexhez való leképezéséhez. A képességcsoport magas szintű erőforrás, de csak az indexelőfeldolgozáson belül működik. Magas szintű erőforrásként egyszer tervezhet meg egy képességcsoportot, majd hivatkozhat rá több indexelőben.
A kérelemhez használhatJA a POST vagy a PUT elemet. Mindkét esetben a kérelem törzsében található JSON-dokumentum biztosítja az objektumdefiníciót.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
MINDEN szolgáltatáskéréshez HTTPS szükséges. Ha a képességcsoport nem létezik, létrejön. Ha már létezik, az új definícióra frissül.
Megjegyzés
A képességkészletek képezik az AI-bővítés alapjait. Egy ingyenes erőforrás korlátozott feldolgozáshoz érhető el, de nagyobb vagy gyakoribb számítási feladatokhoz számlázható Cognitive Services-erőforrásra van szükség.
URI-paraméterek
| Paraméter | Leírás |
|---|---|
| szolgáltatásnév | Kötelező. Állítsa be ezt a keresési szolgáltatás egyedi, felhasználó által definiált nevére. |
| képességkészlet neve | Put használata esetén az URI-n kötelező megadni. A névnek kisbetűnek kell lennie, betűvel vagy számmal kell kezdődnie, nincsenek perjelei vagy pontjai, és 128 karakternél kevesebbnek kell lennie. A névnek betűvel vagy számmal kell kezdődnie, de a többi név tartalmazhat bármilyen betűt, számot és kötőjelet, feltéve, hogy a kötőjelek nem egymást követőek. |
| api-verzió | Kötelező. A támogatott verziók listáját lásd: API-verziók . |
Kérelemfejlécek
Az alábbi táblázat a szükséges és nem kötelező kérésfejléceket ismerteti.
| Mezők | Description |
|---|---|
| Content-Type | Kötelező. Állítsa a következőre: application/json |
| api-key | Nem kötelező , ha Azure-szerepköröket használ, és egy tulajdonosi jogkivonatot ad meg a kéréshez, ellenkező esetben kulcsra van szükség. A létrehozási kérelmeknek tartalmazniuk kell egy api-key , a rendszergazdai kulcsra beállított fejlécet (a lekérdezési kulcs helyett). A részletekért lásd: Csatlakozás az Azure AI Search szolgáltatáshoz kulcshitelesítés használatával . |
Kérelem törzse
A kérelem törzse tartalmazza a képességcsoport definícióját. A készségek önállóak vagy össze vannak kötve bemeneti-kimeneti társításokon keresztül, ahol az egyik átalakítás kimenete egy másikba kerül. Egy képességcsoportnak legalább egy képességgel kell rendelkeznie. A képességek maximális számának nincs elméleti korlátja, de a 3–5.
A következő JSON a definíció fő részeinek magas szintű ábrázolása.
{
"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) { }
}
A kérelem a következő tulajdonságokat tartalmazza:
| Tulajdonság | Leírás |
|---|---|
| name | Kötelező. A képességcsoport neve. A névnek kisbetűnek kell lennie, betűvel vagy számmal kell kezdődnie, nincsenek perjelei vagy pontjai, és 128 karakternél kevesebbnek kell lennie. A névnek betűvel vagy számmal kell kezdődnie, de a többi név tartalmazhat bármilyen betűt, számot és kötőjelet, feltéve, hogy a kötőjelek nem egymást követőek. |
| Készségek | Képességek tömbje. Minden képesség rendelkezik egy odata.type, name, context, and input and output parameters (odata.type, name, context, and input and output parameters) paraméterekkel. A tömb beépített készségeket és egyéni képességeket tartalmazhat. Legalább egy képesség szükséges. Ha tudástárat használ, adjon meg egy Shaper-képességet , hacsak nem definiálja az adatalakzatot a kivetítésen belül. |
| cognitiveServices | A Cognitive Services API-k naponta több mint 20 dokumentumon hívható számlázható képességekhez minden indexelőhöz szükség van egy all-in-one kulcsra. A kulcsnak a keresési szolgáltatással azonos régióban lévő erőforráshoz kell lennie. További információ: Cognitive Services-erőforrás csatolása. Ha az egyéni entitáskeresési képességet használja, adja meg ezt a szakaszt és egy kulcsot, a 20 tranzakciót meghaladó tranzakciók indexelőnkénti engedélyezéséhez. Nincs szüksége Cognitive Services-kulcsra, így kizárhatja cognitiveServices a szakaszt, ha a képességcsoport csak egyéni készségekből, segédprogram-készségekből (feltételes, alakzatos, szövegegyesítési, szöveg felosztási) vagy dokumentumkinyerési képességből áll. Ha el szeretné távolítani a csatolt cognitive service-erőforrást egy képességcsoportból (az "alapértelmezett" korlátok használatára való visszaállításhoz) adja meg a következőt @odata.type : #Microsoft.Azure.Search.DefaultCognitiveServices, További információt ebben a példában talál. |
| knowledgeStore | Választható. Az Azure Storage-ba irányuló bővítési kimenet célja. Egy Azure Storage-fiókhoz és -előrejelzésekhez kapcsolati karakterlánc szükséges. storageConnectionString (kötelező) A következő formátumú sztring: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections(kötelező) Egy, a , objectsfiles, vagy megadott vagy null értékű vetületobjektumokból álló tablestömb. tablesLétrehoz egy vagy több táblát az Azure Table Storage-ban, és az egyes dokumentumokból származó tartalmakat egy tábla soraiként kivetíti. Minden tábla a következő három tulajdonsággal rendelkezhet:
objectsBlobként projekteket Azure Blob Storage. Mindegyik objektumnak két szükséges tulajdonsága van:
filesMinden fájlbejegyzés meghatározza a bináris lemezképek tárolóját a Blob Storage-ban. A fájlvetületek két szükséges tulajdonsággal rendelkeznek:
|
| encryptionKey | Választható. Egy inaktív képességcsoport-definíció titkosítására szolgál a saját kulcsaival, amelyeket az Azure Key Vault kezel. A 2019-01-01-en vagy azt követően létrehozott számlázható keresési szolgáltatásokhoz érhető el. A encryptionKey szakasz tartalmaz egy felhasználó által definiált keyVaultKeyName (kötelező), egy rendszer által létrehozott keyVaultKeyVersion (kötelező) és egy keyVaultUri kulcsot (kötelező, más néven DNS-nevet). Példa URI-ra: "https://my-keyvault-name.vault.azure.net". Igény szerint megadhatja accessCredentials , hogy nem felügyelt rendszeridentitást használ-e. accessCredentials A következők applicationId tulajdonságai: (Microsoft Entra ID alkalmazásazonosító, amely hozzáférési engedélyeket kapott a megadott Azure-Key Vault) és applicationSecret (a regisztrált alkalmazás hitelesítési kulcsa). A következő szakaszban egy példa szemlélteti a szintaxist. |
Reagálás
Sikeres kérés esetén a "201 Létrehozva" állapotkódnak kell megjelennie.
Alapértelmezés szerint a választörzs tartalmazza a létrehozott képességcsoport-definíció JSON-ját. Ha azonban a kérés fejléce Prefer értékre return=minimalvan állítva, a válasz törzse üres, a sikerességi állapotkód pedig "204 Nincs tartalom" a "201 Létrehozva" helyett. Ez attól függetlenül igaz, hogy a PUT vagy a POST használatával hozza létre a képességcsoportot.
Példák
Példa: Olyan képességcsoport, amely felismeri az üzleti entitásokat és a hangulatot az ügyfélértékelésekben
Ez a képességcsoport két készséget használ aszinkron módon, egymástól függetlenül két /document/content különböző átalakításként. A képességek az entitások felismerése és hangulata. A bővítési fában /document/content adja meg a külső adatforrásból származó tartalmat (vagy ügyfélértékeléseket).
{
"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élda: Tudástár
A képességcsoportok igény szerint elküldhetik a kimenetet az Azure Storage-beli tudástárba . Ehhez kapcsolati karakterlánc kell egy Azure Storage-fiókhoz és -előrejelzésekhez, amelyek meghatározzák, hogy a gazdagított tartalom tábla- vagy blobtárolóba (objektumként vagy fájlként) található-e. A leképezésekhez általában olyan felsőbb rétegbeli Shaper-képesség szükséges, amely bemenetként gyűjti a csomópontokat egy bővítési fából, és egyetlen, a leképezésnek átadható alakzatot ad ki. A formázó általában az utolsó feldolgozandó képesség.
{
"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élda: Titkosítási kulcsok
A titkosítási kulcsok az ügyfél által kezelt kulcsok, amelyek a bizalmas tartalmak további titkosításához használatosak. Ez a példa bemutatja, hogyan adhatja meg az ügyfél által felügyelt titkosítást egy képességcsoporton.
{
"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)"}
}
}