Ladění sady dovedností Azure AI Vyhledávač v Azure portal

Spusťte ladicí relaci založenou na portálu pro identifikaci a řešení chyb, ověření změn a propagaci změn existující sadě dovedností ve službě Azure AI Vyhledávač.

Ladicí relace je indexer uložený v mezipaměti a provádění sady dovedností s oborem na jeden dokument, který můžete použít k interaktivní úpravě a otestování změn sady dovedností. Po dokončení ladění můžete své změny uložit do sady schopností.

Základní informace o tom, jak funguje ladicí relace, najdete v tématu Ladicí relace v Azure AI Vyhledávač. Abychom si procvičili ladicí pracovní postup s ukázkovým dokumentem, podívejte se na Tutoriál: ladicí relace.

Požadavky

• Libovolná služba Azure AI Vyhledávač, libovolnou oblast nebo úroveň.

• Účet Azure Storage používaný k ukládání stavu sezení.

• Existující kanál rozšiřování, včetně zdroje dat, sady dovedností, indexeru a indexu.

Omezení

Ladicí relace fungují se všemi obecně dostupnými zdroji dat indexeru a většinou zdrojů dat ve verzi Preview, s následujícími výjimkami:

• Indexer SharePointu.

• Azure Cosmos DB indexer pro MongoDB.

• Pokud v případě Azure Cosmos DB for NoSQL selže řádek během indexu a neexistuje žádná odpovídající metadata, nemusí ladicí relace vybrat správný řádek.

• Pokud byla dříve nedělená kolekce rozhraní API NoSQL Azure Cosmos DB převedena na dělenou, relace ladění dokument nenajde.

• Pro vlastní dovednosti není uživatelsky přiřazená spravovaná identita podporována pro ladicí připojení k Azure Storage. Jak je uvedeno v požadavcích, můžete použít spravovanou identitu systému nebo zadat úplný access připojovací řetězec, který obsahuje klíč. Další informace najdete v tématu Pojení search service k jiným prostředkům Azure pomocí spravované identity.

Zabezpečení a oprávnění

• Pokud chcete uložit ladicí relaci do Azure Storage, musí mít identita služby search oprávnění Přispěvatel dat k objektům BLOB úložiště pro Azure Storage. Jinak plánujte zvolit připojovací řetězec s plným přístupem pro připojení relace ladění k Azure Storage.

• Pokud je účet Azure Storage za bránou firewall, nakonfigurujte ho tak, aby povolil přístup vyhledávací služby.

• Pokud je Azure AI Vyhledávač nakonfigurovaný tak, aby používal šifrovací klíč spravovaný zákazníkem (CMK), při zachování dat se citlivé informace v ladicí relaci zašifrují s tímto klíčem.

Vytvořit ladicí relaci

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V nabídce vlevo vyberte Správa vyhledávání>, Relace ladění.

3. Na panelu akcí v horní části vyberte Přidat ladicí relaci.

   

4. Ve Název ladicí relace zadejte název, který vám pomůže snadno identifikovat, které sady dovedností, indexeru a zdroje dat se ladicí relace týká.

5. V šabloně indexeru vyberte indexer, který řídí sadu dovedností, kterou chcete odladit. K inicializaci relace se používají kopie jak indexeru, tak sady dovedností.

6. V dokumentu, který chcete ladit, zvolte první dokument v indexu nebo vyberte konkrétní dokument. Pokud vyberete konkrétní dokument v závislosti na zdroji dat, zobrazí se výzva k zadání identifikátoru URI nebo ID řádku.

   Pro konkrétní dokument v Blob storage: zadejte identifikátor URI objektu blob. Identifikátor URI najdete na stránce vlastností objektu blob v Azure portal.

   

   Pro konkrétní dokument v Azure Cosmos DB for NoSQL: zadejte klíč dokumentu v indexu vyhledávání pro hodnotu a ID entity ve službě Cosmos DB pro klíč oddílu.

   

   Tady je konfigurace relace ladění pro příklad služby Cosmos DB.

   

7. V účtu úložiště zvolte obecný účet úložiště pro ukládání relace ladění do mezipaměti.

8. Vyberte Ověřit pomocí spravované identity, pokud jste dříve přiřadili oprávnění Přispěvatel dat úložiště blob k systémem spravované identitě služby vyhledávání. Pokud toto políčko nezaškrtnete, vyhledávací služba se připojí pomocí neomezeného přístupového řetězce pro připojení.

9. Zvolte Uložit.

   • Azure AI Vyhledávač vytvoří kontejner objektů blob na Azure Storage s názvem ms-az-cognitive-search-debugsession.
   • V rámci daného kontejneru vytvoří složku s názvem, který jste zadali pro název relace.
   • Spustí vaši ladicí relaci.

Ladicí relace začíná spuštěním indexátoru a sady schopností pro vybraný dokument. Obsah a metadata dokumentu jsou viditelné a dostupné během relace.

Ladění lze zrušit během jeho provádění. Pokud kliknete na tlačítko Storno , měli byste být schopni analyzovat částečné výsledky.

Očekává se, že spuštění ladicí relace trvá déle než indexer, protože prochází dalším zpracováním.

Začínáme s chybami a upozorněními

Historie spuštění indexeru v Azure portal poskytuje úplný seznam chyb a upozornění pro všechny dokumenty. V ladicí relaci jsou chyby a upozornění omezeny na jeden dokument. Tento seznam můžete procházet, provádět změny a pak se vrátit do seznamu, abyste ověřili, jestli jsou problémy vyřešené.

Nezapomeňte, že ladicí sezení je založené na jednom dokumentu z celého indexu. Pokud vstup nebo výstup vypadá špatně, může být problém specifický pro daný dokument. Můžete zvolit jiný dokument, abyste ověřili, jestli jsou chyby a upozornění pervasivní nebo specifické pro jeden dokument.

Vyberte chyby nebo upozornění pro seznam problémů.

Osvědčeným postupem je vyřešit problémy se vstupy před přechodem na výstupy.

Pokud chcete ověřit, jestli úprava vyřeší chybu, postupujte takto:

1. Výběrem možnosti Uložit v podokně podrobností dovedností zachováte změny.

2. Výběrem možnosti Spustit v okně sezení zahájíte spuštění provádění sady dovedností pomocí upraveného nastavení.

3. Vraťte se k chybám nebo upozorněním, abyste zjistili, jestli se počet snížil.

Zobrazení rozšířeného nebo generovaného obsahu

Obohacující AI procesy extrahují nebo odvozují informace a strukturu ze zdrojových dokumentů a vytvářejí přitom obohacené dokumenty. Obohacený dokument se nejprve vytvoří během prolomení dokumentu a naplní se kořenovým uzlem (/document), plus uzly pro veškerý obsah, který se zvedne přímo ze zdroje dat, jako jsou metadata a klíč dokumentu. Další uzly jsou vytvořeny dovednostmi během provádění dovedností, kde každý výstup dovednosti přidá do stromu rozšiřování nový uzel.

Veškerý obsah vytvořený nebo používaný sadou dovedností se zobrazí ve vyhodnocovači výrazů. Najeďte myší na odkazy, abyste zobrazili každou vstupní nebo výstupní hodnotu ve stromu rozšířeného dokumentu. Pokud chcete zobrazit vstup nebo výstup jednotlivých dovedností, postupujte takto:

1. V ladicí relaci rozbalte modrou šipku a zobrazte kontextově citlivé podrobnosti. Ve výchozím nastavení je podrobností rozšířená datová struktura dokumentů. Pokud ale vyberete dovednost nebo mapování, podrobnosti se týkají daného objektu.

   

2. Vyberte dovednost.

   

3. Pokud chcete přejít k podrobnostem o zpracování dovedností, postupujte podle odkazů. Například následující snímek obrazovky ukazuje výstup první iterace dovednosti Rozdělení textu.

   

Zkontrolujte mapování indexů

Pokud dovednosti vytvářejí výstup, ale index vyhledávání je prázdný, zkontrolujte mapování polí. Mapování polí určuje, jak se obsah přesune z potrubí do vyhledávacího indexu.

Vyberte jednu z možností mapování a rozbalte zobrazení podrobností a zkontrolujte definice zdroje a cíle.

• Projekční mapy se nacházejí v dovednostních sadách, které poskytují integrovanou vektorizaci, například dovednosti vytvořené průvodcem importem dat. Tato mapování určují mapování polí typu nadřazený-podřízený (blok) a zda se vytvoří sekundární index pouze pro obsah v bloku.

• Mapování výstupních polí se nachází v indexerech a používají se, když sady dovedností vyvolávají vestavěné nebo vlastní dovednosti. Tato mapování slouží k nastavení cesty k datům z uzlu ve stromu rozšiřování na pole v indexu vyhledávání. Další informace o cestách najdete v tématu syntaxe cesty k uzlu obohacení.

• Mapování polí se nachází v definicích indexeru a navazují cestu k datům z nezpracovaného obsahu ve zdroji dat a pole v indexu. Mapování polí můžete použít také k přidání kroků kódování a dekódování.

Tento příklad ukazuje podrobnosti pro projekční mapování. Kód JSON můžete upravit a opravit případné problémy s mapováním.

Úprava definic dovedností

Pokud je mapování polí správné, zkontrolujte jednotlivé dovednosti týkající se konfigurace a obsahu. Pokud dovednost nevygeneruje výstup, může chybět vlastnost nebo parametr, který se dá určit prostřednictvím chybových a ověřovacích zpráv.

Jiné problémy, jako je neplatný kontext nebo vstupní výraz, mohou být obtížnější vyřešit, protože chyba vám řekne, co je špatně, ale ne jak ho opravit. Nápovědu ke kontextové a vstupní syntaxi najdete v Odkazy na obohacení v sadě dovedností Azure AI Vyhledávač. Nápovědu k jednotlivým zprávám najdete v tématu Řešení běžných chyb a upozornění indexeru.

Následující kroky ukazují, jak získat informace o dovednostech.

1. Vyberte dovednost na pracovní ploše. Vpravo se otevře podokno podrobností o dovednostech.

2. Upravte definici dovednosti pomocí nastavení dovedností. Json můžete upravit přímo.

3. Zkontrolujte syntaxi cesty pro odkazování na uzly ve stromu rozšiřování. Tady jsou některé z nejběžnějších vstupních cest:

   • /document/content pro kusy textu. Tento uzel se naplní vlastností obsahu blobu.
   • /document/merged_content pro části textu ve modulech, které obsahují dovednost sloučení textu.
   • /document/normalized_images/* pro text rozpoznaný nebo odvozený z obrázků.

Ladit a odstraňovat chyby vlastní schopnosti místně

Vlastní dovednosti mohou být při ladění náročnější, protože kód je spuštěn externě, což znemožňuje použití relace ladění. Tato část popisuje, jak místně ladit vlastní rozhraní webového API, ladicí relaci, Visual Studio Code a ngrok nebo Tunnelmole. Tato technika pracuje s vlastními dovednostmi, které se spouštějí v Azure Functions nebo v jakémkoli jiném webovém frameworku, který běží místně (například FastAPI).

Získání veřejné adresy URL

Tato část popisuje dva přístupy k získání veřejné adresy URL pro vlastní funkci.

Použijte Tunnelmole

Tunnelmole je nástroj pro tunelové propojení open source, který umožňuje vytvořit veřejnou adresu URL, která předává požadavky na místní počítač prostřednictvím tunelu.

1. Nainstalujte Tunnelmole:

   • 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: Nainstalujte pomocí npm. Nebo pokud nemáte nainstalované Node.js, stáhněte předkompilovaný soubor .exe pro Windows a přidejte ho do své cesty PATH.

2. Spuštěním tohoto příkazu vytvořte nový tunel:

   tmole 7071
   

   Měla by se zobrazit odpověď, která vypadá takto:

   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
   

   V předchozím příkladu se https://m5hdpb-ip-49-183-170-144.tunnelmole.net přesměruje na port 7071 na místním počítači, což je výchozí port, na kterém jsou vystaveny Azure functions.

Použití nástroje ngrok

ngrok je oblíbená, uzavřená zdrojová aplikace pro různé platformy, která může vytvořit tunelovou nebo předávací adresu URL, aby se internetové požadavky dostaly na místní počítač. Pomocí nástroje ngrok přeposílejte požadavky z obohacovacího kanálu ve vaší vyhledávací službě do počítače, abyste umožnili místní ladění.

1. Nainstalujte nástroj ngrok.

2. Otevřete terminál a přejděte do složky se spustitelným souborem ngrok.

3. Spuštěním příkazu ngrok vytvořte nový tunel:

   ngrok http 7071 
   

   Poznámka:

   Ve výchozím nastavení jsou Azure Functions vystaveny na portu 7071. Jiné nástroje a konfigurace můžou vyžadovat, abyste zadali jiný port.

4. Při spuštění ngrok zkopírujte a uložte veřejnou adresu URL pro předávání pro další krok. Adresa URL pro předávání se náhodně vygeneruje.

   

Konfigurace v Azure portal

Jakmile budete mít veřejnou adresu URL pro vlastní dovednost, upravte identifikátor URI dovednosti vlastního webového rozhraní API v rámci ladicí relace tak, aby volal adresu URL pro přesměrování Tunnelmole nebo ngrok. Při použití funkce Azure pro spuštění kódu sady dovedností nezapomeňte připojit /api/FunctionName.

Definici dovednosti můžete upravit v části Nastavení dovedností v podokně Podrobností o dovednostech.

Testování kódu

V tuto chvíli by se nové požadavky z relace ladění měly odesílat do lokální Azure funkce. V editoru Visual Studio Code můžete použít breakpointy k ladění kódu nebo provádění krok za krokem.

Další kroky

Teď, když rozumíte rozložení a funkcím vizuálního editoru ladicích relací, vyzkoušejte tutoriál pro interaktivní zkušenost.