Azure AI Search-készségkészlet hibakeresése az Azure Portalon

Portálalapú hibakeresési munkamenet indítása a hibák azonosításához és megoldásához, a módosítások érvényesítéséhez és a módosítások leküldéséhez az Azure AI-Search szolgáltatás közzétett képességkészletbe.

A hibakeresési munkamenet egy gyorsítótárazott indexelő és képességkészlet végrehajtása, amely egyetlen dokumentumra terjed ki, amellyel interaktívan szerkesztheti és tesztelheti a módosításokat. Ha végzett a hibakereséssel, mentheti a módosításokat a képességkészletbe.

A hibakeresési munkamenetek működésével kapcsolatos háttérért tekintse meg az Azure AI Search hibakeresési munkameneteit. Ha egy hibakeresési munkafolyamatot mintadokumentummal szeretne gyakorolni, tekintse meg az oktatóanyagot: Hibakeresési munkamenetek.

Előfeltételek

• Meglévő bővítési folyamat, beleértve egy adatforrást, egy készségkészletet, egy indexelőt és egy indexet.

• Közreműködői szerepkör-hozzárendelés a keresési szolgáltatásban.

• Egy Azure Storage-fiók, amely a munkamenet állapotának mentésére szolgál.

• A Storage Blob Data Közreműködő szerepkör-hozzárendelése az Azure Storage-ban, ha rendszer által felügyelt identitást használ. Ellenkező esetben tervezze meg, hogy teljes hozzáférésű kapcsolati sztring használ az Azure Storage-hoz való hibakeresési munkamenet-kapcsolathoz.

• Ha az Azure Storage-fiók tűzfal mögött található, konfigurálja úgy, hogy engedélyezze a keresési szolgáltatás elérését.

Korlátozások

A hibakeresési munkamenetek az összes általánosan elérhető indexelő adatforrással és a legtöbb előzetes verziójú adatforrással működnek. Az alábbi lista a kivételeket jegyezi fel:

• A MongoDB-hez készült Azure Cosmos DB jelenleg nem támogatott.

• Az Azure Cosmos DB for NoSQL esetében, ha egy sor meghiúsul az index során, és nincsenek megfelelő metaadatok, előfordulhat, hogy a hibakeresési munkamenet nem a megfelelő sort választja.

• Az Azure Cosmos DB SQL API-ja esetében, ha egy particionált gyűjteményt korábban nem particionáltak, a hibakeresési munkamenet nem fogja megtalálni a dokumentumot.

• Egyéni képességek esetén a felhasználó által hozzárendelt felügyelt identitások nem támogatottak az Azure Storage-hoz való hibakeresési munkamenet-kapcsolat esetében. Az előfeltételekben leírtaknak megfelelően használhatja a rendszer által felügyelt identitást, vagy megadhat egy kulcsokat tartalmazó teljes hozzáférésű kapcsolati sztring. További információ: Keresési szolgáltatás csatlakoztatása más Azure-erőforrásokhoz felügyelt identitás használatával.

A portál nem támogatja az ügyfél által felügyelt kulcstitkosítást (CMK), ami azt jelenti, hogy a portálon a hibakeresési munkamenetek nem tartalmazhatnak CMK-titkosítású kapcsolati sztring vagy más titkosított metaadatokat. Ha a keresési szolgáltatás a CMK-kényszerítéshez van konfigurálva, a hibakeresési munkamenetek nem fognak működni.

Hibakeresési munkamenet létrehozása

1. Jelentkezzen be az Azure Portalra , és keresse meg a keresési szolgáltatást.

2. A bal oldali navigációs lapon válassza a Hibakeresési munkamenetek lehetőséget.

3. A felső műveletsávon válassza a Hibakeresési munkamenet hozzáadása lehetőséget.

   

4. A Hibakeresési munkamenet nevében adjon meg egy nevet, amely segít megjegyezni, hogy a hibakeresési munkamenet mely képességkészletről, indexelőről és adatforrásról szól.

5. Tárolókapcsolatban keressen egy általános célú tárfiókot a hibakeresési munkamenet gyorsítótárazására. A rendszer kérni fogja, hogy válasszon ki és hozzon létre egy blobtárolót a Blob Storage-ban vagy az Azure Data Lake Storage Gen2-ben. Ugyanazt a tárolót minden további létrehozott hibakeresési munkamenethez újra felhasználhatja. Hasznos tárolónév lehet a "cognitive-search-debug-sessions".

6. A felügyelt identitáshitelesítésben válassza a Nincs lehetőséget, ha az Azure Storage-kapcsolat nem használ felügyelt identitást. Ellenkező esetben válassza ki azt a felügyelt identitást, amelyhez tárolási blobadat-közreműködői engedélyeket adott.

7. Az Indexer-sablonban válassza ki azt az indexelőt, amely a hibakereséshez használni kívánt képességkészletet vezérli. Az indexelő és a képességkészlet másolatai a munkamenet inicializálására szolgálnak.

8. A hibakereséshez válassza ki az index első dokumentumát, vagy válasszon ki egy adott dokumentumot. Ha kiválaszt egy adott dokumentumot az adatforrástól függően, a rendszer URI-t vagy sorazonosítót kér.

   Ha az adott dokumentum egy blob, adja meg a blob URI-ját. Az URI a portál Blob tulajdonságlapján található.

   

9. Az Indexelő beállításai között megadhatja a munkamenet létrehozásához használt indexelő végrehajtási beállításait. A beállításoknak a tényleges indexelő által használt beállításokat kell utánozniuk. A hibakeresési munkamenetben megadott indexelőbeállítások nem befolyásolják az indexelőt.

10. A konfigurációnak ehhez a képernyőképhez hasonlóan kell kinéznie. Első lépésként válassza a Munkamenet mentése lehetőséget.

    

A hibakeresési munkamenet azzal kezdődik, hogy végrehajtja az indexelőt és a készségkészletet a kijelölt dokumentumon. A dokumentum létrehozott tartalma és metaadatai láthatók és elérhetők lesznek a munkamenetben.

A hibakeresési munkamenet a Mégse gombra kattintva megszakítható a végrehajtás során. Ha a Mégse gombra kattint, elemezni kell a részleges eredményeket.

A hibakeresési munkamenet végrehajtása várhatóan hosszabb időt vesz igénybe, mint az indexelő, mivel további feldolgozáson megy keresztül.

Kezdés hibákkal és figyelmeztetésekkel

Az Indexelőzmények portálon az összes dokumentum teljes hiba- és figyelmeztetési listáját tartalmazza. Hibakeresési munkamenetben a hibák és figyelmeztetések egy dokumentumra lesznek korlátozva. Végig fogja dolgozni ezt a listát, elvégezheti a módosításokat, majd visszatérhet a listához, és ellenőrizheti, hogy a problémák megoldódtak-e.

Az üzenetek megtekintéséhez válasszon ki egy képességet az AI-bővítési > képesség grafikonján , majd válassza a Hibák/Figyelmeztetések lehetőséget a részletek panelen.

Ajánlott eljárásként oldja meg a bemenetekkel kapcsolatos problémákat, mielőtt továbblépne a kimenetekre.

Annak ellenőrzéséhez, hogy egy módosítás megoldja-e a hibát, kövesse az alábbi lépéseket:

1. A módosítások megőrzéséhez válassza a Mentés lehetőséget a képesség részletei panelen.

2. Válassza a Futtatás lehetőséget a munkamenetablakban a skillset-végrehajtás meghívásához a módosított definícióval.

3. Térjen vissza a hibákhoz /figyelmeztetésekhez , és ellenőrizze, hogy csökkent-e a szám. A lista csak akkor frissül, ha megnyitja a lapot.

Bővítési csomópontok tartalmának megtekintése

Az AI-bővítési folyamatok információt és struktúrát nyernek ki vagy vonnak ki a forrásdokumentumokból, és egy bővített dokumentumot hoznak létre a folyamatban. A bővített dokumentum először a dokumentum feltörésekor jön létre, és egy gyökércsomóponttal (/document), valamint az adatforrásból közvetlenül felemelt tartalom csomópontjaival( például metaadatokkal és a dokumentumkulcsmal) tölti fel. A képesség végrehajtása során további csomópontok jönnek létre, ahol minden képességkimenet új csomópontot ad hozzá a bővítési fához.

A bővített dokumentumok belsőek, de a hibakeresési munkamenet hozzáférést biztosít a képesség végrehajtása során létrehozott tartalomhoz. Az egyes képességek tartalmának vagy kimenetének megtekintéséhez kövesse az alábbi lépéseket:

1. Kezdje az alapértelmezett nézetekkel: AI-bővítési > képesség grafikonja, a gráf típusa Függőségi gráfra van állítva.

2. Válasszon ki egy képességet.

3. A jobb oldali részletek panelen válassza a Végrehajtások lehetőséget, válasszon ki egy KIMENETet, majd nyissa meg a Kifejezésértékelőt (</>) a kifejezés és az eredmény megtekintéséhez.

   

4. Másik lehetőségként nyissa meg az AI Enrichments > Enriched Data Structure elemet a csomópontok listájának görgetéséhez. A lista tartalmazza a lehetséges és a tényleges csomópontokat, a kimenethez tartozó oszlopot, valamint egy másik oszlopot, amely a kimenet előállításához használt felsőbb rétegbeli objektumot jelzi.

   

Képességdefiníciók szerkesztése

Ha a mezőleképezések helyesek, ellenőrizze a konfiguráció és a tartalom egyéni készségeit. Ha egy képesség nem tud kimenetet létrehozni, előfordulhat, hogy hiányzik egy tulajdonság vagy paraméter, amely hiba- és érvényesítési üzenetek segítségével határozható meg.

Más problémák, például egy érvénytelen környezet vagy beviteli kifejezés, nehezebben megoldhatók, mert a hiba meg fogja állapítani, hogy mi a probléma, de nem azt, hogyan lehet kijavítani. A környezettel és a bemeneti szintaxissal kapcsolatos segítségért tekintse meg az Azure AI Search-képességek referenciáinak bővítését ismertető témakört. Az egyes üzenetekkel kapcsolatos segítségért tekintse meg az indexelők gyakori hibáinak és figyelmeztetéseinek hibaelhárítását.

Az alábbi lépések bemutatják, hogyan kérhet le információkat egy képességről.

1. Az AI-bővítési > képességgráfban válasszon ki egy képességet. Jobbra megnyílik a Szakértelem részletei panel.

2. Képességdefiníció szerkesztése bármelyik módszerrel:

   • Képességbeállítások , ha inkább vizualizációszerkesztőt szeretne használni
   • JSON-szerkesztő a JSON-dokumentum közvetlen szerkesztéséhez

3. Ellenőrizze az elérési út szintaxisát a csomópontokra való hivatkozáshoz egy bővítőfán. Az alábbiakban a leggyakoribb bemeneti útvonalakat mutatjuk be:

   • /document/content szövegtömbökhöz. Ez a csomópont a blob tartalomtulajdonságából van feltöltve.
   • /document/merged_content a Szövegegyesítési készséget tartalmazó készségkészletekben lévő szövegrészek esetében.
   • /document/normalized_images/* a képekből felismert vagy kikövetkezett szövegek esetében.

Mezőleképezések ellenőrzése

Ha a készségek kimenetet hoznak létre, de a keresési index üres, ellenőrizze a mezőleképezéseket. A mezőleképezések meghatározzák, hogy a tartalom hogyan mozdul el a folyamatból és egy keresési indexbe.

1. Kezdje az alapértelmezett nézetekkel: AI-bővítési > képesség grafikonja, a gráf típusa Függőségi gráfra van állítva.

2. Válassza ki a mezőleképezéseket a tetején. Legalább azt a dokumentumkulcsot kell megtalálnia, amely egyedileg azonosítja és társítja a keresési indexben lévő egyes keresési dokumentumokat az adatforrás forrásdokumentumával.

   Ha nyers tartalmat importál közvetlenül az adatforrásból, megkerülve a bővítést, ezeket a mezőket a mezőleképezésekben kell megtalálnia.

3. Válassza ki a kimeneti mezőleképezéseket a gráf alján. Itt a képességkimenetek és a keresési index célmezői közötti leképezéseket találja. Ha nem használta az Adatok importálása varázslót, a kimeneti mezőleképezések manuálisan vannak definiálva, és hiányosak vagy hibásak lehetnek.

   Ellenőrizze, hogy a kimeneti mezőleképezések mezői a megadott keresési indexben találhatók-e, és ellenőrizze a helyesírási és bővítési csomópont elérési útjának szintaxisát.

   

Egyéni képesség helyi hibakeresése

Az egyéni képességek hibakeresése nagyobb kihívást jelenthet, mivel a kód külsőleg fut, így a hibakeresési munkamenet nem használható a hibakeresésre. Ez a szakasz azt ismerteti, hogyan lehet helyileg hibakeresést végezni az Egyéni webes API-képesség, a hibakeresési munkamenet, a Visual Studio Code és az ngrok vagy az tunnelmole használatával. Ez a technika olyan egyéni készségekkel működik, amelyek az Azure Functionsben vagy bármely más, helyileg futó webes keretrendszerben (például FastAPI) futnak.

Nyilvános URL-cím lekérése

Tunnelmole használata

A tunnelmole egy nyílt forráskód bújtatási eszköz, amely létrehozhat egy nyilvános URL-címet, amely egy alagúton keresztül továbbítja a kéréseket a helyi gépnek.

1. A Tunnelmole telepítése:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: Telepítés npm használatával. Vagy ha nincs telepítve a NodeJS, töltse le az előre összeállított .exe fájlt a Windowshoz , és helyezze el valahol a PATH-ban.

2. Futtassa ezt a parancsot egy új alagút létrehozásához:

   tmole 7071
   

   A következőhöz hasonló választ kell látnia:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   Az előző példában https://m5hdpb-ip-49-183-170-144.tunnelmole.net továbbít egy portot 7071 a helyi gépen, amely az alapértelmezett port, ahol az Azure-függvények elérhetők.

Az ngrok használata

Az ngrok egy népszerű, zárt forráskódú, platformfüggetlen alkalmazás, amely létrehozhat egy bújtatási vagy továbbítási URL-címet, hogy az internetes kérések elérjék a helyi gépet. Az ngrok használatával továbbíthatja a keresési szolgáltatás egyik bővítési folyamatából érkező kéréseket a gépére a helyi hibakeresés engedélyezéséhez.

1. Telepítse az ngrokot.

2. Nyisson meg egy terminált, és lépjen a mappába az ngrok végrehajtható fájljával.

3. Futtassa az ngrokot az alábbi paranccsal egy új alagút létrehozásához:

   ngrok http 7071 
   

   Feljegyzés

   Alapértelmezés szerint az Azure-függvények a 7071-en vannak közzétéve. Más eszközök és konfigurációk esetében előfordulhat, hogy egy másik portot kell megadnia.

4. Az ngrok indításakor másolja és mentse a következő lépéshez tartozó nyilvános továbbítási URL-címet. A továbbítási URL-cím véletlenszerűen jön létre.

   

Konfigurálás az Azure Portalon

A hibakeresési munkameneten belül módosítsa a Custom Web API Skill URI-t, hogy meghívja az tunnelmole vagy ngrok továbbítási URL-címet. Győződjön meg arról, hogy hozzáfűzi az "/api/FunctionName" kifejezést, amikor az Azure-függvényt használja a skillset-kód végrehajtásához.

A készségdefiníciót a portálon szerkesztheti.

A kód tesztelése

Ezen a ponton a hibakeresési munkamenetből érkező új kéréseket most el kell küldeni a helyi Azure-függvénynek. A Visual Studio Code-ban töréspontok használatával hibakeresést végezhet a kódban, vagy lépésről lépésre futtathatja a kódot.

Következő lépések

Most, hogy megismerte a Hibakeresési munkamenetek vizualizációszerkesztőjének elrendezését és képességeit, próbálja ki az oktatóanyagot a gyakorlati élmény érdekében.

Oktatóanyag: Hibakeresési munkamenetek felfedezése