Képességkészlet létrehozása az Azure AI Keresésben

A képességkészlet olyan műveleteket határoz meg, amelyek vektoros és szöveges tartalmat és struktúrát hoznak létre képeket vagy nyers tartalmakat tartalmazó dokumentumokból. Ilyenek például az adatbeosztási képességek, a beágyazási (vektorizálási) képességek, a képi verbicializálás és más folyamatok, például a képek optikai karakterfelismerése (OCR), a nem differenciált szövegek entitásfelismerése és a szövegfordítás. A képességkészletek a nyers tartalom külső adatforrásból való kinyerése és a mezőleképezések feldolgozása után hajthatók végre.

Ez a cikk bemutatja, hogyan hozhat létre készségkészletet REST API-k használatával, de ugyanezek a fogalmak és lépések érvényesek más programozási nyelvekre is.

A képességkészlet-definícióra vonatkozó szabályok a következők:

• A készségkészlet-gyűjteményben egyedi névvel kell rendelkeznie. A készségkészlet egy legfelső szintű erőforrás, amelyet bármely indexelő használhat.
• Legalább egy képességgel kell rendelkeznie. 3-5 képesség jellemző. A maximális érték 30.
• A képességkészletek azonos típusú készségeket képesek megismételni. Egy készségkészlet például több Shaper-képességgel is rendelkezhet.
• A képességkészlet támogatja a láncolt műveleteket, a hurkokat és az elágaztatást.

Készségkészlet csatolása az indexelőhöz. A képességkészlet használatához hivatkozzon rá egy indexelőben , majd futtassa az indexelőt az adatok importálásához, a készségek feldolgozásának meghívásához és a kimenet indexbe való küldéséhez. A készségkészlet egy magas szintű erőforrás, de csak az indexelő feldolgozásán belül működik. Magas szintű erőforrásként több indexelőben is hivatkozhat rá.

Képességkészlet-definíció hozzáadása

Amikor létrehoz egy készségkészletet, hozzáadja azt a keresési szolgáltatáshoz. Amikor frissít egy készségkészletet, teljesen felülírja a meglévő készségkészletet a kérés hasznos adataiban szereplő tartalommal. Egy készségkészlet frissítéséhez kérje le a skillset definícióját a GET használatával, módosítsa, majd frissítse a PUT használatával.

Kezdje az alapstruktúrával. A Create Skillset REST API-ban hozza létre a kérés törzsét a JSON-ban. A következő szakaszokból áll:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"A Microsoft Foundry resource in the same region as Azure AI Search",
      "key":"<Your-Microsoft-Foundry-Resource-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

A név és a leírás után egy készségkészlet négy fő tulajdonsággal rendelkezik:

• skillstömb, a készségek rendezetlen gyűjteménye. A készségek önállóak vagy össze vannak kötve bemeneti-kimeneti társításokon keresztül, ahol az átalakítás kimenete egy másikba kerül. A készségek lehetnek haszonelvűek (például szöveg felosztása), átalakítási (az Azure OpenAI-ból vagy a Foundry Toolsból származó AI-n alapuló) vagy az Ön által megadott egyéni készségek. A következő szakaszban egy készségtömböt mutatunk be.

• cognitiveServices a Foundry Tools API-kat hívó számlázható képességekhez használható. Távolítsa el ezt a szakaszt, ha nem számlázható készségeket vagy egyéni entitáskeresést használ. Ha így van, csatoljon egy Öntödei erőforrást.

• knowledgeStore (nem kötelező) egy Azure Storage-fiókot és a képességkészlet kimenetének az Azure Storage-ban lévő táblákba, blobokba és fájlokba való kivetítését szolgáló beállításokat adja meg. Ha nincs rá szüksége, távolítsa el ezt a szakaszt. Ellenkező esetben adjon meg egy tudástárat.

• encryptionKey(nem kötelező) egy Azure Key Vaultot és ügyfél által felügyelt kulcsokat határoz meg, amelyek bizalmas tartalmak (leírások, kapcsolati sztring, kulcsok) titkosítására szolgálnak egy képességkészlet-definícióban. Távolítsa el ezt a tulajdonságot, ha nem ügyfél által felügyelt titkosítást használ.

Készségek hozzáadása

A képességkészlet-definíción belül a képességtömb határozza meg, hogy mely képességeket kell végrehajtani. A háromtól ötig terjedő készségek gyakoriak, de a szolgáltatási korlátoktól függően annyi készséget adhat hozzá, amennyi szükséges.

A bővítési folyamat végeredménye szöveges tartalom egy keresési indexben vagy egy tudástárban. Ezért a legtöbb képesség vagy képekből (OCR-szöveg, feliratok, címkék) hoz létre szöveget, vagy elemzi a meglévő szöveget új információk (entitások, kulcskifejezések, hangulat) létrehozásához. Az önállóan működő készségek feldolgozása párhuzamosan történik. Az egymástól függő készségek egy képesség kimenetét (például kulcskifejezéseket) határozzák meg egy második készség bemeneteként (például szövegfordítás). A keresési szolgáltatás határozza meg a képesség végrehajtásának sorrendjét és a végrehajtási környezetet.

Minden készség típussal, környezettel, bemenetekkel és kimenetekkel rendelkezik. Előfordulhat, hogy egy képességnek neve és leírása is van. Az alábbi példa két egymástól független beépített képességet mutat be, hogy összehasonlíthassa az alapszintű struktúrát.

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

Minden képesség egyedi a bemeneti értékek és a szükséges paraméterek szempontjából. A szakértelemre vonatkozó referenciadokumentáció egy adott képesség összes paraméterét és tulajdonságát ismerteti. Bár vannak különbségek, a legtöbb készség közös halmazt használ, és hasonló mintázatú.

Készségkörnyezet beállítása

Minden képesség rendelkezik egy környezeti tulajdonságokkal , amelyek meghatározzák a műveletek végrehajtásának szintjét. Ha a context tulajdonság nincs explicit módon beállítva, az alapértelmezett érték "/document"az, ahol a környezet a teljes dokumentum (a képesség dokumentumonként egyszer van meghívva).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Állítsa be a context tulajdonságot az alábbi példák egyikére:

A környezet azt is meghatározza, hogy hol jönnek létre kimenetek a bővítőfán. Az Entitásfelismerési képesség például egy organizations nevű tulajdonságot ad vissza, amely orgs néven van rögzítve. Ha a "/document" környezet, akkor hozzáadunk egy organizations csomópontot a "/document" gyermekeként. Ha ezután hivatkozni szeretne erre a csomópontra az alsóbb rétegbeli készségekben, az elérési út az "/document/orgs".

Bemenetek definiálása

A képességek egy gazdagított dokumentumból olvasnak és írnak. A készségbemenetek határozzák meg a bejövő adatok eredetét. Ez gyakran a bővített dokumentum gyökércsomópontja. A blobok esetében a jellemző képességbevitel a dokumentum tartalomtulajdonsága.

Az egyes képességek képesség-referenciadokumentációja leírja, hogy milyen bemeneteket használhat fel. Minden bemenet rendelkezik egy name adott bemenettel, és egy source olyan bemenettel, amely meghatározza az adatok helyét a bővített dokumentumban. A következő példa az Entitásfelismerési képességből származik:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

• A készségek több bemenettel is rendelkezhetnek. Az adott bemenet a name. Az Entitásfelismerés esetében a konkrét bemenetek a szöveg és a languageCode.

• A source tulajdonság megadja, hogy melyik mező vagy sor biztosítja a feldolgozandó tartalmat. A szövegalapú képességekhez a forrás a dokumentum vagy a sor egy olyan mezője, amely szöveget biztosít. A képalapú képességekhez a bemenetet biztosító csomópont normalizált képeket tartalmaz.

  Példa forrásra	Description
  source: /document	Táblázatos adathalmaz esetén a dokumentum egy sornak felel meg.
  source: /document/content	Blobok esetén a forrás általában a blob tartalomtulajdonságai.
  source: /document/some-named-field	A szövegalapú készségek, például az entitásfelismerés vagy a kulcskifejezések kinyerése esetén a forrásnak olyan mezőnek kell lennie, amely elegendő elemezni kívánt szöveget tartalmaz, például leírást vagy összegzést.
  source: /document/normalized_images/*	A képtartalmak esetében a forrás a dokumentumtörés során normalizált kép.

Ha a képesség egy tömbön keresztül iterál, a környezetnek és a bemeneti forrásnak is szerepelnie /* kell a megfelelő pozíciókban. A teljes szintaxissal kapcsolatos további információkért lásd: Skill context and input annotation language.

Kimenetek definiálása

Az egyes képességeket úgy tervezték, hogy meghatározott kimeneteket bocsátanak ki, amelyekre a képességkészlet név szerint hivatkozik. A képességkimenetnek van egy name és egy opcionális targetName.

Az egyes képességek képesség-referenciadokumentációja leírja az általa előállított kimeneteket. A következő példa az Entitásfelismerési képességből származik:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

• A készségek több kimenettel is rendelkezhetnek. A name tulajdonság egy adott kimenetet azonosít. Az Entitásfelismerés esetében például a kimenet lehet többek között személyek, helyek, szervezetek.

• A targetName tulajdonság megadja a csomópont nevét a bővített dokumentumban. Ez a tulajdonság akkor hasznos, ha a képességkimenetek neve megegyezik. Ha több olyan képessége van, amelynek azonos a kimenete, használja a targetName a nevek pontosítására a feldúsítási csomópontok útvonalain. Ha nem adja meg a célnevet, a névtulajdonság mindkét esetben használatos.

Bizonyos helyzetekben a tömb minden elemére külön hivatkozni kell. Tegyük fel például, hogy az egyes elemeketegy másik képességnek. Ehhez adjon hozzá csillagot az elérési úthoz: "/document/orgs/*".

A képességkimenet a bővített dokumentumba lesz beírva új csomópontként a bővítési fában. Ez lehet egy egyszerű érték, például hangulatpont vagy nyelvi kód. Gyűjtemény is lehet, például szervezetek, személyek vagy helyek listája. A képességkimenet összetett struktúra is lehet, ahogyan az Shaper-képesség esetében is. A képesség bemenetei határozzák meg az alakzat összetételét, de a kimenet az elnevezett objektum, amelyre hivatkozhat egy keresési indexben, egy tudástár-vetítésben vagy egy másik képességben a neve alapján.

Egyéni képesség hozzáadása

Ez a szakasz egy egyéni képesség példáját tartalmazza. Az URI egy Azure-függvényre mutat, amely viszont meghívja a megadott modellt vagy átalakítást. További információ: Egyéni képesség hozzáadása azure AI Search-bővítési folyamathoz.

Bár az egyéni képesség végrehajtja a folyamaton kívüli kódot, egy képességtömbben ez csak egy újabb képesség. A beépített képességekhez hasonlóan típussal, környezettel, bemenetekkel és kimenetekkel is rendelkezik. Olvasást és írást is végez egy bővítőfán, ahogyan a beépített képességek teszik. Figyelje meg, hogy a context mező csillaggel van beállítva "/document/orgs/*", ami azt jelenti, hogy a dúsítási lépés minden "/document/orgs" végrehajtásra kerül.

A kimenet, mint például a jelen példában szereplő cégleírás, minden azonosított szervezethez létrehozásra kerül. Ha egy alsóbb rétegbeli lépésben (például a kulcskifejezések kinyerésekor) hivatkozik a csomópontra, használja az elérési utat "/document/orgs/*/companyDescription" .

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=<YOUR-FUNCTION-KEY>",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "<YOUR-APIM-KEY>"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Kimenet küldése célhelyre

Bár opcionálisan gyorsítótárazhatja a képességkimenetet az újrafelhasználáshoz, ez általában ideiglenes, és csak akkor létezik, ha a képesség végrehajtása folyamatban van.

• Ha egy keresési index egy mezőjébe szeretne kimenetet küldeni, hozzon létre egy kimeneti mezőleképezést egy indexelőben.

• Ha kimenetet szeretne küldeni egy tudástárba, hozzon létre egy előrejelzést.

• Ha kimenetet szeretne küldeni egy alsóbb rétegbeli képességnek, hivatkozzon a kimenetre a csomópont neve alapján, például "/document/organization"az alsóbb rétegbeli képesség bemeneti forrástulajdonságában. Példákért lásd : Hivatkozás egy jegyzetre .

Tippek az első képességkészlethez

• Próbálja ki az Adatok importálása varázslót.

  A varázsló számos olyan lépést automatizál, amelyek első alkalommal kihívást jelenthetnek. Meghatározza a képességkészletet, az indexet és az indexelőt, beleértve a mezőleképezéseket és a kimeneti mezőleképezéseket. Emellett a tudástárban lévő előrejelzéseket is definiálja, ha használ egyet. Bizonyos készségek, például az OCR vagy a képelemzés esetében a varázsló olyan segédprogram-képességeket ad hozzá, amelyek egyesítik a dokumentumtörés során elválasztott képet és szöveges tartalmat.

  A varázsló futtatása után megnyithatja az egyes objektumokat az Azure Portalon a JSON-definíció megtekintéséhez.

• Próbálja ki a hibakeresési munkameneteket , hogy meghívja a képességkészlet végrehajtását egy céldokumentumon keresztül, és vizsgálja meg a képességkészlet által létrehozott bővített dokumentumot. Megtekintheti és módosíthatja a bemeneti és kimeneti beállításokat és értékeket. Ez az oktatóanyag jó kiindulópont: Oktatóanyag: Képességkészlet hibakeresése Hibakeresési munkamenetek használatával.

Következő lépés

A környezet és a bemeneti forrásmezők a csomópontok elérési útjai egy bővítőfán. A következő lépésben többet is megtudhat a csomópontok elérési útszintaxisáról egy bővítőfán.