Részletes példa a tudástárban lévő alakzatokra és leképezésre

Ez a cikk részletes példát mutat be, amely kiegészíti a magas szintű fogalmakat és szintaxisalapú cikkeket azáltal, hogy végigküldi a tudástárban található gazdag képességkészlet kimenetének teljes körű kialakításához és leképezéséhez szükséges lépéseken.

Ha az alkalmazáskövetelmények több képességre és leképezésre is szükség van, ez a példa jobb képet ad az alakzatok és az előrejelzések közötti járásról.

Mintadefiníciók letöltése

Ez a példa a Postman Desktop alkalmazást és a Search REST API-kat használja.

Klónozza vagy töltse le az azure-search-postman-samples GitHub, és importálja a Projections gyűjteményt, hogy ön is végigvezedje ezt a példát.

Mintaadatok előkészítése

A mintadokumentumok nincsenek kifejezetten a Leképezés gyűjteményben, de az azure-search-sample-data adattára AI-bővítő bemutató adatfájlja szöveget és képeket tartalmaz, és az ebben a példában ismertetett leképezésekkel fog működni.

Hozzon létre egy blobtárolót az Azure Storage és töltse fel mind a 14 elemet.

Az Azure Storage másolja ki a kapcsolati sztringet, hogy meg tudja adni a Postman-gyűjteményben.

Példa képességkészletre

Az alakzatok és leképezések közötti függőségek áttekintését az alábbi képességkészletben sajátítjuk el, amely bővített tartalmat hoz létre. Ez a képességkészlet feldolgozza a nyers képeket és a szöveget is, és olyan kimeneteket ad vissza, amelyekre alakzatokban és előrejelzésekben fog hivatkozni.

Fordítson különös figyelmet a képességkimenetre (targetNames). A bővített dokumentumfára írt kimenetek leképezésben és alakzatokban (alakzatokkal) hivatkoznak.

{
    "name": "projections-demo-ss",
    "description": "Skillset that enriches blob data found in "merged_content". The enrichment granularity is a document.",
    "skills": [
        {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "name": "#1",
            "description": null,
            "context": "/document/merged_content",
            "categories": [
                "Person",
                "Quantity",
                "Organization",
                "URL",
                "Email",
                "Location",
                "DateTime"
            ],
            "defaultLanguageCode": "en",
            "minimumPrecision": null,
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                },
                {
                    "name": "languageCode",
                    "source": "/document/language"
                }
            ],
            "outputs": [
                {
                    "name": "persons",
                    "targetName": "people"
                },
                {
                    "name": "organizations",
                    "targetName": "organizations"
                },
                {
                    "name": "locations",
                    "targetName": "locations"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
            "name": "#2",
            "description": null,
            "context": "/document/merged_content",
            "defaultLanguageCode": "en",
            "maxKeyPhraseCount": null,
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                },
                {
                    "name": "languageCode",
                    "source": "/document/language"
                }
            ],
            "outputs": [
                {
                    "name": "keyPhrases",
                    "targetName": "keyphrases"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
            "name": "#3",
            "description": null,
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                }
            ],
            "outputs": [
                {
                    "name": "languageCode",
                    "targetName": "language"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
            "name": "#4",
            "description": null,
            "context": "/document",
            "insertPreTag": " ",
            "insertPostTag": " ",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/content"
                },
                {
                    "name": "itemsToInsert",
                    "source": "/document/normalized_images/*/text"
                },
                {
                    "name": "offsets",
                    "source": "/document/normalized_images/*/contentOffset"
                }
            ],
            "outputs": [
                {
                    "name": "mergedText",
                    "targetName": "merged_content"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
            "name": "#5",
            "description": null,
            "context": "/document/normalized_images/*",
            "textExtractionAlgorithm": "printed",
            "lineEnding": "Space",
            "defaultLanguageCode": "en",
            "detectOrientation": true,
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                }
            ],
            "outputs": [
                {
                    "name": "text",
                    "targetName": "text"
                },
                {
                    "name": "layoutText",
                    "targetName": "layoutText"
                }
            ]
        }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "A Cognitive Services resource in the same region as Search.",
        "key": "<COGNITIVE SERVICES All-in-ONE KEY>"
    },
    "knowledgeStore": null
}

Példa formázó képesség

A Formázó képesség egy olyan segédprogram, amely új bővített tartalom létrehozása helyett meglévő bővített tartalommal való munkavégzésre használható. Ha alakzatot ad hozzá egy képességkészlethez, létrehozhat egy egyéni alakzatot, amely táblába vagy blobtárolóba vethet át. Egyéni alakzat nélkül a leképezés csak egyetlen csomópontra (kimenetenként egy leképezésre) hivatkozhat, amely nem alkalmas táblákhoz. Az egyéni alakzat létrehozása a különböző elemeket egy új logikai egészbe összesíti, amely egyetlen táblaként vethető ki, vagy egy táblagyűjteményre szeletelhető és terjeszthető.

Ebben a példában az egyéni alakzat a blobok metaadatait, valamint az azonosított entitásokat és kulcskifejezéseket kombinálja. Az egyéni alakzat neve és szülője a projectionShape /document következő: .

A formázás egyik célja annak biztosítása, hogy az összes bővítő csomópont jól formázott JSON-ként legyen kifejezve, ami a tudástárba való kivetítéshez szükséges. Ez különösen igaz akkor, ha a bővítőfa nem megfelelő JSON-formázó csomópontokat tartalmaz (például ha egy gazdagítás egy primitív, például egy sztring szülője).

Figyelje meg az utolsó két csomópontot, KeyPhrases a és Entities a csomópontot. Ezek érvényes JSON-objektumba vannak csomagolva a sourceContext következővel: . Ez a primitívek bővítőiként ésként szükséges, és érvényes JSON-fájlvá kell konvertálni, mielőtt azok keyphrases entities kivetíthetőek volna.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "ShaperForTables",
    "description": null,
    "context": "/document",
    "inputs": [
        {
            "name": "metadata_storage_content_type",
            "source": "/document/metadata_storage_content_type",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_storage_name",
            "source": "/document/metadata_storage_name",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_storage_path",
            "source": "/document/metadata_storage_path",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_content_type",
            "source": "/document/metadata_content_type",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "keyPhrases",
            "source": null,
            "sourceContext": "/document/merged_content/keyphrases/*",
            "inputs": [
                {
                    "name": "KeyPhrases",
                    "source": "/document/merged_content/keyphrases/*"
                }

            ]
        },
        {
            "name": "Entities",
            "source": null,
            "sourceContext": "/document/merged_content/entities/*",
            "inputs": [
                {
                    "name": "Entities",
                    "source": "/document/merged_content/entities/*/name"
                }

            ]
        }
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "projectionShape"
        }
    ]
}

Formázók hozzáadása képességkészlethez

A cikk elején bemutatott képességkészlet nem tartalmazta a Shaper képességet, de a Shaper-készség egy képességkészlethez tartozik, és gyakran a cél felé helyezi őket.

A képességkészleten belül a Shaper képesség a következő lehet:

    "name": "projections-demo-ss",
    "skills": [
        {
            <Shaper skill goes here>
            }
        ],
    "cognitiveServices":  "A key goes here",
    "knowledgeStore": []
}  

Táblákra való kivetítés

A fenti példák alapján a tábla-leképezésben hivatkozható számos bővített és adatalakzat is rendelkezésre áll. Az alábbi táblázat-leképezésben három tábla van meghatározva a , és tableName source tulajdonság generatedKeyName beállításával.

Mindhárom tábla a létrehozott kulcsokon és a megosztott szülőn keresztül kapcsolódik /document/projectionShape egymáshoz.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [
                {
                    "tableName": "tblDocument",
                    "generatedKeyName": "Documentid",
                    "source": "/document/projectionShape"
                },
                {
                    "tableName": "tblKeyPhrases",
                    "generatedKeyName": "KeyPhraseid",
                    "source": "/document/projectionShape/keyPhrases/*"
                },
                {
                    "tableName": "tblEntities",
                    "generatedKeyName": "Entityid",
                    "source": "/document/projectionShape/Entities/*"
                }
            ],
            "objects": [],
            "files": []
        }
    ]
}

A munka tesztelése

A leképezés definícióit az alábbi lépésekkel ellenőrizheti:

  1. Állítsa a tudástár storageConnectionString tulajdonságát egy érvényes V2 általános célú tárfiók kapcsolati sztringre.

  2. Frissítse a képességkészletet a PUT kérés kiadásával.

  3. A képességkészlet frissítése után futtassa az indexelőt.

Most már van egy működő leképezésünk három táblával. Ezeknek a tábláknak a Power BI importálásának a kapcsolatok Power BI automatikus felderítését kell eredményezze.

Mielőtt továbblépünk a következő példára, tértsük át a tábla leképezésének aspektusait, hogy megértsük az adatok szeletelésének és stb. mechanikát.

Tábla szeletelése több gyermektáblára

A szeletelés egy olyan technika, amely egy teljes összesített alakzatot összetevőkre bont. Az eredmény különálló, de kapcsolódó táblákból áll, amelyeken egyenként dolgozhat.

A példában projectionShape a az összesített alakzat (vagy a bővítő csomópont). A leképezés definíciójában a további táblákra van felszeletelve, így kiveszi az alakzat projectionShape részeit, keyPhrases és Entities . Ebben Power BI hasznos, mivel több entitás és keyPhrases van társítva az egyes dokumentumokhoz, és további információkhoz juthat, ha kategorizált adatokként látja az entitásokat és a keyPhrases adatokat.

A szeletelés implicit módon kapcsolatot hoz létre a szülő- és gyermektáblák között, a szülőtáblában a használatával létrehoz egy azonos nevű oszlopot generatedKeyName a gyermektáblában.

Kapcsolatok elnevezése

A és a tulajdonság az adatok táblák közötti, vagy akár generatedKeyName referenceKeyName leképezéstípusok közötti kapcsolatára használható. A gyermektábla minden sorának van egy tulajdonsága, amely a szülőre mutat. A gyermek oszlopának vagy tulajdonságának neve a referenceKeyName szülőtől származó. Ha a nincs megtéve, a szolgáltatás alapértelmezés szerint referenceKeyName a generatedKeyName szülőtől származó értéket használja.

Power BI a létrehozott kulcsokra támaszkodik a táblákon belüli kapcsolatok felderítése során. Ha a gyermektábla eltérő nevű oszlopára van szüksége, állítsa be a tulajdonságot referenceKeyName a szülőtáblán. Az egyik példa az, hogy a tblDocument táblában azonosítóként, a pedig generatedKeyName referenceKeyName DocumentID azonosítóként van beállítva. Ez a DocumentID nevű dokumentumazonosítót tartalmazó tblEntities és tblKeyPhrases táblák oszlopát eredményezné.

Blobdokumentumok kivetítés

Az objektumvetítések a bővítőfa JSON-leképezései, amelyek bármely csomópontról erednek. A táblavetületekkel összehasonlítva az objektumvetületeket egyszerűbb meghatározni, és teljes dokumentumok kivetítéskor használatosak. Az objektumvetítések egy tároló egyetlen leképezésében vannak korlátozva, és nem szeletelhetőek.

Objektumvetítés definiálása a leképezés tulajdonságban objects található tömb használatával.

A forrás a kigazdagítási fa egy olyan csomópontjának elérési útja, amely a leképezés gyökere. Bár ez nem kötelező, a csomópont elérési útja általában egy Shaper-képesség kimenete. Ennek az az oka, hogy a legtöbb képesség nem ad vissza érvényes JSON-objektumokat, ami azt jelenti, hogy valamilyen formázásra van szükség. Sok esetben ugyanaz a Shaper képesség használható objektum-leképezés létrehozásához, amely táblavetítést hoz létre. A forrás beállítható beágyazott formázással is egy csomópontra a struktúra kialakításához.

A célhely mindig egy blobtároló.

Az alábbi példa az egyes szállodai dokumentumokat (blobonként egy szállodai dokumentumot) egy nevű tárolóba hotels projektek.

"knowledgeStore": {
  "storageConnectionString": "an Azure storage connection string",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
        "storageContainer": "hotels",
        "source": "/document/objectprojection",
        }
      ]
    },
    {
        "files": [ ]
    }
  ]
}

A forrás egy "objectprojection" nevű Shaper-képesség kimenete. Minden blob JSON-ábrázolásban fog jelenni az egyes mezőbevitelek esetén.

    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "name": "#3",
      "description": null,
      "context": "/document",
      "inputs": [
        {
          "name": "HotelId",
          "source": "/document/HotelId"
        },
        {
          "name": "HotelName",
          "source": "/document/HotelName"
        },
        {
          "name": "Category",
          "source": "/document/Category"
        },
        {
          "name": "keyPhrases",
          "source": "/document/HotelId/keyphrases/*"
        },
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "objectprojection"
        }
      ]
    }

Képfájl kivetítés

A fájlvetítések mindig bináris, normalizált képek, ahol a normalizálás a képességkészlet végrehajtásában való használathoz szükséges lehetséges átméretezést és rotációt jelenti. Az objektum-leképezéshez hasonlóan a fájlvetítések is blobokként vannak létrehozva az Azure Storage, és tartalmazzák a képet.

Fájlvetület meghatározásához használja a files tömböt a projections (leképezés) tulajdonságban.

A forrás mindig /document/normalized_images/* . A fájlvetületek csak a gyűjteményre vannak normalized_images bevetve. Sem az indexelők, sem a képességkészletek nem haladnak át az eredeti, nem normalizált rendszerképen.

A célhely mindig egy blobtároló, amely a dokumentumazonosító base64 kódolású értékéhez egy mappaelőtaggal. A fájlvetületek nem osztoznak ugyanazon a tárolón, mint az objektumok leképezései, ezért egy másik tárolóba kell őket kivetítenünk.

Az alábbi példa egy bővített dokumentum dokumentumcsomópontján kinyert összes normalizált rendszerképet egy nevű tárolóba myImages projekteli.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [ ],
            "objects": [ ],
            "files": [
                {
                    "storageContainer": "myImages",
                    "source": "/document/normalized_images/*"
                }
            ]
        }
    ]
}

Több típusra való kivetítés

Egy összetettebb forgatókönyv esetében szükség lehet a tartalom leképezéstípusok közötti kivetítésére. Például kulcskifejezések és entitások kivetítése táblákba, szöveg és elrendezés szöveg OCR-eredményeinek objektumként való mentése, majd a képek fájlként való kivetítése.

Több leképezéstípus lépései:

  1. Hozzon létre egy táblát minden dokumentumhoz egy-egy sorgal.
  2. Hozzon létre egy, a dokumentumtáblához kapcsolódó táblát, amely tartalmazza a táblázat sorként azonosított kulcskifejezését.
  3. Hozzon létre egy, a dokumentumtáblához kapcsolódó táblát, amely minden entitást sorként azonosít ebben a táblában.
  4. Hozzon létre egy objektumvetületet az egyes képek elrendezési szövegét használva.
  5. Hozzon létre egy fájlvetületet, amely kivetíti az egyes kinyert képeket.
  6. Hozzon létre egy kereszthivatkozási táblát, amely a dokumentumtáblára, az objektumvetületre és az elrendezés szövegére és a fájlvetületre mutató hivatkozásokat tartalmaz.

Adatok alakítása keresztbe vetítéshez

Az ezekhez a leképezéshez szükséges alakzatok lekért formában először adja hozzá a Shaper új képességét, amely létrehoz egy nevű, formázott crossProjection objektumot.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "ShaperForCrossProjection",
    "description": null,
    "context": "/document",
    "inputs": [
        {
            "name": "metadata_storage_name",
            "source": "/document/metadata_storage_name",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "keyPhrases",
            "source": null,
            "sourceContext": "/document/merged_content/keyphrases/*",
            "inputs": [
                {
                    "name": "KeyPhrases",
                    "source": "/document/merged_content/keyphrases/*"
                }

            ]
        },
        {
            "name": "entities",
            "source": null,
            "sourceContext": "/document/merged_content/entities/*",
            "inputs": [
                {
                    "name": "Entities",
                    "source": "/document/merged_content/entities/*/name"
                }

            ]
        },
        {
            "name": "images",
            "source": null,
            "sourceContext": "/document/normalized_images/*",
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                },
                {
                    "name": "layoutText",
                    "source": "/document/normalized_images/*/layoutText"
                },
                {
                    "name": "ocrText",
                    "source": "/document/normalized_images/*/text"
                }
                ]
        }
 
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "crossProjection"
        }
    ]
}

Tábla-, objektum- és fájlvetületek meghatározása

Az összevont crossProjection objektumból szeletelje az objektumot több táblára, rögzítse az OCR kimenetét blobokként, majd mentse a képet fájlokként (szintén Blob Storage-tárolóban).

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
            {
            "tables": [
                {
                    "tableName": "crossDocument",
                    "generatedKeyName": "Id",
                    "source": "/document/crossProjection"
                },
                {
                    "tableName": "crossEntities",
                    "generatedKeyName": "EntityId",
                    "source": "/document/crossProjection/entities/*"
                },
                {
                    "tableName": "crossKeyPhrases",
                    "generatedKeyName": "KeyPhraseId",
                    "source": "/document/crossProjection/keyPhrases/*"
                },
                {
                    "tableName": "crossReference",
                    "generatedKeyName": "CrossId",
                    "source": "/document/crossProjection/images/*"
                }
                    
            ],
            "objects": [
                {
                    "storageContainer": "crossobject",
                    "generatedKeyName": "crosslayout",
                    "source": null,
                    "sourceContext": "/document/crossProjection/images/*/layoutText",
                    "inputs": [
                        {
                            "name": "OcrLayoutText",
                            "source": "/document/crossProjection/images/*/layoutText"
                        }
                    ]
                }
            ],
            "files": [
                {
                    "storageContainer": "crossimages",
                    "generatedKeyName": "crossimages",
                    "source": "/document/crossProjection/images/*/image"
                }
            ]
        }
    ]
}

Az objektumvetítések mindegyik leképezéshez egy tárolónevet igényelnek. Az objektum-leképezés és a fájl-leképezés nem osztozhat a tárolón.

A tábla-, objektum- és fájlvetületek közötti kapcsolatok

Ez a példa egy másik leképezés-jellemzőt is kiemel. Ha több leképezéstípust definiál egy leképezésobjektumon belül, akkor a különböző típusokon (táblákon, objektumokon, fájlokon) belül és között kapcsolat van kifejezve. Ez lehetővé teszi, hogy egy dokumentum táblázatsorával kezdjen, és megkeresi a dokumentumban lévő képek ocr-karakterfelismerési szövegét az objektum leképezésében.

Ha nem szeretné, hogy az adatok egymáshoz kapcsolódnak, definiálja a leképezéseket különböző leképezéscsoportokban. Az alábbi kódrészlet például azt eredményezi, hogy a táblák kapcsolatban lesznek, de a táblák és az objektum (OCR-szöveg) leképezései közötti kapcsolatok nélkül.

A leképezéscsoportok akkor hasznosak, ha ugyanazt az adatot különböző formában szeretné kivetítni különböző igények szerint. Például egy leképezéscsoportot az Power BI irányítópulthoz, és egy másik leképezéscsoportot egy egyéni képességbe csomagolt gépi tanulási modell betanítására használt adatok rögzítéséhez.

A különböző típusú leképezéseket a rendszer először fájl- és objektum-leképezésekkel generálja, és az útvonalakat hozzáadja a táblákhoz.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [
                {
                    "tableName": "unrelatedDocument",
                    "generatedKeyName": "Documentid",
                    "source": "/document/projectionShape"
                },
                {
                    "tableName": "unrelatedKeyPhrases",
                    "generatedKeyName": "KeyPhraseid",
                    "source": "/document/projectionShape/keyPhrases"
                }
            ],
            "objects": [
                
            ],
            "files": []
        }, 
        {
            "tables": [],
            "objects": [
                {
                    "storageContainer": "unrelatedocrtext",
                    "source": null,
                    "sourceContext": "/document/normalized_images/*/text",
                    "inputs": [
                        {
                            "name": "ocrText",
                            "source": "/document/normalized_images/*/text"
                        }
                    ]
                },
                {
                    "storageContainer": "unrelatedocrlayout",
                    "source": null,
                    "sourceContext": "/document/normalized_images/*/layoutText",
                    "inputs": [
                        {
                            "name": "ocrLayoutText",
                            "source": "/document/normalized_images/*/layoutText"
                        }
                    ]
                }
            ],
            "files": []
        }
    ]
}

Következő lépések

A cikkben a leképezés létrehozására vonatkozó gyakori mintákat mutatunk be. Most, hogy már jól érti a fogalmakat, jobban fel van szerelve arra, hogy leképezéseket készítsen az adott forgatókönyvhöz.