Sdílet prostřednictvím

Ladění sady dovedností Azure AI Search na webu Azure Portal

  • Článek

Spusťte ladicí relaci založenou na portálu pro identifikaci a řešení chyb, ověření změn a nasdílení změn existující sadě dovedností v Search Azure AI.

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 uložit změny sady dovedností.

Pozadí toho, jak ladicí relace funguje, najdete v tématu Ladicí relace ve službě Azure AI Search. Pokud si chcete procvičit ladicí pracovní postup s ukázkovým dokumentem, přečtěte si kurz : Ladicí relace.

Požadavky

  • Azure AI Search, libovolnou oblast nebo úroveň.

  • Účet Služby Azure Storage, který se používá k uložení stavu relace.

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

Zabezpečení a oprávnění

  • Pokud chcete uložit ladicí relaci do úložiště Azure, musí mít identita vyhledávací služby oprávnění Přispěvatel dat objektů blob služby Storage ve službě Azure Storage. Jinak naplánujte volbu úplného přístupu připojovací řetězec pro připojení relace ladění ke službě Azure Storage.

  • Pokud se účet Azure Storage nachází za bránou firewall, nakonfigurujte ho tak, aby umožňoval přístup k vyhledávací službě.

Omezení

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

  • Indexer SharePointu Online

  • Indexer služby Azure Cosmos DB pro MongoDB

  • V případě selhání řádku během indexu ve službě Azure Cosmos DB for NoSQL a neexistuje žádná odpovídající metadata, nemusí ladicí relace vybrat správný řádek.

  • Pokud byla dříve dělená kolekce rozdělená do oddílů, relace ladění pro rozhraní SQL API služby Azure Cosmos DB nenajde dokument.

  • Pro vlastní dovednosti se spravovaná identita přiřazená uživatelem nepodporuje pro připojení relace ladění ke službě Azure Storage. Jak je uvedeno v požadavcích, můžete použít spravovanou identitu systému nebo zadat úplný přístup připojovací řetězec, který obsahuje klíč. Další informace najdete v tématu Připojení vyhledávací služby k jiným prostředkům Azure pomocí spravované identity.

Vytvoření ladicí relace

  1. Přihlaste se k webu Azure Portal a vyhledejte vyhledávací službu.

  2. V nabídce vlevo vyberte Relace ladění správy>vyhledávání.

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

    Snímek obrazovky s příkazy relací ladění na stránce webu Azure Portal

  4. V části Název ladicí relace zadejte název, který vám pomůže zapamatovat si, o které sadě dovedností, indexeru a zdroji dat se ladicí relace týká.

  5. V šabloně Indexeru vyberte indexer, který řídí sadu dovedností, kterou chcete ladit. Kopie indexeru i sady dovedností se používají k inicializaci relace.

  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.

    Pokud je váš konkrétní dokument objektem blob, zadejte identifikátor URI objektu blob. Identifikátor URI najdete na stránce vlastností objektu blob na webu Azure Portal.

    Snímek obrazovky s vlastností identifikátoru URI v úložišti objektů blob

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

  8. Vyberte Možnost Ověřit pomocí spravované identity , pokud jste dříve přiřadili oprávnění Přispěvatel dat objektů blob služby Storage k identitě spravované systémem vyhledávací služby. Pokud toto políčko nezaškrtnete, služba Search se připojí pomocí úplného přístupu připojovací řetězec.

  9. Zvolte Uložit.

    • Azure AI Search vytvoří kontejner objektů blob ve službě 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í ladicí relaci.

Ladicí relace začíná spuštěním indexeru a sady dovedností ve vybraném dokumentu. Obsah a metadata dokumentu jsou viditelné a dostupné v relaci.

Ladicí relaci je možné během provádění zrušit. 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 spouštění indexeru na webu 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í relace 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ů.

Snímek obrazovky s tlačítky chyby a upozornění v horní části stránky

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ě relace vyvoláte spuštění sady dovedností pomocí upravené definice.

  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

Kanály rozšiřování AI extrahují nebo odvozují informace a strukturu ze zdrojových dokumentů a vytvářejí v procesu obohacený dokument. 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í v vyhodnocovaci 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ím relaci rozbalte modrou šipku a zobrazte podrobnosti citlivé na kontext. 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.

    Snímek obrazovky znázorňující modrou šipku použitou k zobrazení podrobností citlivých na kontext

  2. Vyberte dovednost.

    Snímek obrazovky s podoknem podrobností dovedností s podrobnostmi o podrobnostech podrobností o dovednostech pro další informace

  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.

    Snímek obrazovky znázorňující podokno podrobností dovedností s vyhodnocovačem výrazů pro daný výstup

Kontrola 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čují, jak se obsah přesune z kanálu a do indexu vyhledávání.

Snímek obrazovky s oblastí mapování indexů pracovního postupu

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

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

  • Mapování výstupníchpolích 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 rozšiřování.

  • 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 mapování projekce. Kód JSON můžete upravit a opravit případné problémy s mapováním.

Snímek obrazovky s uzlem Mapování výstupních polí a podrobnostmi

Ú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 k kontextové a vstupní syntaxi najdete v tématu Referenční rozšíření v sadě dovedností Azure AI Search. 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 bloky textu. Tento uzel se naplní vlastností obsahu objektu blob.
    • /document/merged_content pro bloky textu v dovednostech, které obsahují dovednosti sloučení textu.
    • /document/normalized_images/* pro text rozpoznaný nebo odvozený z obrázků.

Místní ladění vlastní dovednosti

Vlastní dovednosti můžou být pro ladění náročnější, protože kód běží externě, takže se relace ladění nedá použít k ladění. Tato část popisuje, jak místně ladit dovednosti vlastního webového rozhraní API, ladicí relaci, Visual Studio Code a ngrok nebo Tunnelmole. Tato technika funguje s vlastními dovednostmi, které se spouštějí ve službě Azure Functions , nebo s jakoukoli jinou webovou architekturou, 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í dovednost.

Použití tunelového propojení

Tunnelmole je opensourcový nástroj pro tunelové propojení, který umožňuje vytvořit veřejnou adresu URL, která předává požadavky místnímu počítači 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ý NodeJS, stáhněte si předkompilovaný soubor .exe pro Windows a někam ho vložte do cesty.

  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 https://m5hdpb-ip-49-183-170-144.tunnelmole.net se přesměruje na port 7071 na místním počítači, což je výchozí port, kde jsou funkce Azure vystavené.

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 můžete předávat požadavky z kanálu rozšiřování ve vyhledávací službě na váš počítač, aby se povolilo 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 funkce Azure zpřístupněné na verzi 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.

    Snímek obrazovky terminálu ngrok

Konfigurace na webu 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 spouš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 vaší ladicí relace měly posílat do vaší místní funkce Azure Functions. Pomocí zarážek v editoru Visual Studio Code můžete kód ladit nebo krok za krokem spustit.

Další kroky

Teď, když rozumíte rozložení a možnosti vizuálního editoru ladicích relací, vyzkoušejte kurz praktického prostředí.

Kurz: Prozkoumání ladicích relací