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

Spusťte ladicí relaci založenou na portálu pro identifikaci a řešení chyb, ověření změn a nasdílení změn do publikované sady dovedností ve vašem 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. 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

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

• Přiřazení role Přispěvatel ve vyhledávací službě

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

• Přiřazení role Přispěvatel dat objektů blob služby Storage ve službě Azure Storage, pokud používáte spravovanou identitu systému. Jinak naplánujte použití ú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. Následující seznam uvádí výjimky:

• Azure Cosmos DB pro MongoDB se v současné době nepodporuje.

• 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žbě do jiných prostředků Azure pomocí spravované identity.

Portál nepodporuje šifrování klíčů spravované zákazníkem (CMK), což znamená, že prostředí portálu, jako jsou ladicí relace, nemohou mít šifrované připojovací řetězec CMK ani jiná šifrovaná metadata. Pokud je vyhledávací služba nakonfigurovaná pro vynucení klíče CMK, relace ladění nebudou fungovat.

Vytvoření ladicí relace

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

2. Na levé navigační stránce vyberte Ladicí relace.

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

   

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 připojení k úložišti vyhledejte účet úložiště pro obecné účely pro ukládání do mezipaměti ladicí relace. Zobrazí se výzva k výběru a volitelnému vytvoření kontejneru objektů blob ve službě Blob Storage nebo Azure Data Lake Storage Gen2. Stejný kontejner můžete znovu použít pro všechny následné ladicí relace, které vytvoříte. Užitečný název kontejneru může být cognitive-search-debug-sessions.

6. Pokud připojení ke službě Azure Storage nepoužívá spravovanou identitu, zvolte v části Ověřování spravovaných identit možnost Žádné . V opačném případě zvolte spravovanou identitu, ke které jste udělili oprávnění Přispěvatel dat v objektech blob služby Storage.

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

8. 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 portálu.

   

9. Volitelně můžete v nastavení indexeru zadat všechna nastavení spuštění indexeru použitá k vytvoření relace. Nastavení by měla napodobovat nastavení používaná skutečným indexerem. Všechny možnosti indexeru, které zadáte v ladicí relaci, nemají žádný vliv na samotný indexer.

10. Vaše konfigurace by měla vypadat podobně jako na tomto snímku obrazovky. Začněte výběrem možnosti Uložit relaci .

    

Ladicí relace začíná spuštěním indexeru a sady dovedností ve vybraném dokumentu. Vytvořený obsah a metadata dokumentu budou viditelné a dostupné v relaci.

Ladicí relaci můžete během provádění zrušit pomocí tlačítka 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 portálu poskytuje úplný seznam chyb a upozornění pro všechny dokumenty. V relaci ladění budou chyby a upozornění omezeny na jeden dokument. Tento seznam si projdete, provedete změny a pak se vrátíte do seznamu, abyste ověřili, jestli jsou problémy vyřešené.

Pokud chcete zobrazit zprávy, vyberte dovednost v grafu dovedností rozšiřování > AI a pak v podokně podrobností vyberte Chyby nebo upozornění.

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. Seznam se neaktualizuje, dokud kartu neotevřete.

Zobrazení obsahu uzlů rozšiřování

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.

Rozšířené dokumenty jsou interní, ale ladicí relace umožňuje přístup k obsahu vytvořenému během provádění dovedností. Pokud chcete zobrazit obsah nebo výstup jednotlivých dovedností, postupujte takto:

1. Začněte s výchozími zobrazeními: AI enrichment > Skill Graph s typem grafu nastaveným na Graf závislostí.

2. Vyberte dovednost.

3. V podokně podrobností vpravo vyberte Spuštění, vyberte výstup a pak otevřete vyhodnocovač výrazů (</>) a zobrazte výraz a jeho výsledek.

   

4. Případně otevřete rozšířenou > datovou strukturu AI a posuňte se dolů v seznamu uzlů. Seznam obsahuje potenciální a skutečné uzly se sloupcem pro výstup a další sloupec, který označuje nadřazený objekt použitý k vytvoření výstupu.

   

Ú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. V grafu dovedností pro > rozšiřování AI vyberte dovednost. Vpravo se otevře podokno Podrobnosti o dovednostech.

2. Upravte definici dovednosti pomocí některého z těchto přístupů:

   • Dovednost Nastavení, pokud dáváte přednost vizuálnímu editoru
   • Editor dovedností JSON pro přímé úpravy dokumentu JSON

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ů.

Kontrola mapování polí

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í.

1. Začněte s výchozími zobrazeními: AI enrichment > Skill Graph s typem grafu nastaveným na Graf závislostí.

2. Vyberte mapování polí v horní části. Měli byste najít alespoň klíč dokumentu, který jednoznačně identifikuje a přidruží každý vyhledávací dokument v indexu vyhledávání k jeho zdrojovému dokumentu ve zdroji dat.

   Pokud importujete nezpracovaný obsah přímo ze zdroje dat a vynecháte rozšiřování, měli byste tato pole najít v mapování polí.

3. Vyberte mapování výstupních polí v dolní části grafu. Tady najdete mapování z výstupů dovedností na cílová pole v indexu vyhledávání. Pokud jste nepoužili průvodce importem dat, mapování výstupních polí jsou definována ručně a můžou být neúplná nebo chybně zatypovaná.

   Ověřte, že pole v mapování výstupních polí existují v indexu vyhledávání, jak je zadáno, a zkontrolujte syntaxi cesty uzlu kontroly pravopisu a rozšiřování.

   

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

Použití tunnelmole

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.

   

Konfigurace na webu Azure Portal

V rámci ladicí relace upravte identifikátor URI dovednosti vlastního webového rozhraní API tak, aby volal adresu URL přesměrování Tunnelmole nebo ngrok. Ujistěte se, že při použití funkce Azure Functions k provádění kódu sady dovedností připojíte "/api/FunctionName".

Definici dovednosti můžete upravit na portálu.

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í