Povolení ukládání do mezipaměti pro přírůstkové rozšiřování ve službě Azure AI Search

Článek
12/18/2024

Důležité

Tato funkce je ve verzi Public Preview v rámci doplňkových podmínek použití. Tato funkce podporuje rozhraní REST API ve verzi Preview.

Tento článek vysvětluje, jak přidat ukládání do mezipaměti do kanálu rozšiřování, abyste mohli upravit kroky podřízeného rozšiřování bez nutnosti opětovného sestavení v plném rozsahu. Ve výchozím nastavení je sada dovedností bezstavová a změna jakékoli části jeho složení vyžaduje úplné opětovné spuštění indexeru. S mezipamětí rozšiřování může indexer určit, které části stromu dokumentů je potřeba aktualizovat, na základě změn zjištěných v sadě dovedností nebo definicích indexeru. Stávající zpracovaný výstup se zachová a znovu použije, kdykoli je to možné.

Obsah uložený v mezipaměti se umístí do služby Azure Storage pomocí informací o účtu, které zadáte. Kontejner s názvem ms-az-search-indexercache-<alpha-numerc-string>se vytvoří při spuštění indexeru. Měla by se považovat za interní komponentu spravovanou vyhledávací službou a nesmí být upravena.

Požadavky

Azure Storage pro ukládání rozšíření uložených v mezipaměti. Účet úložiště musí být pro obecné účely verze 2.
Pro indexování objektů blob stačí, když potřebujete synchronizované odebrání dokumentu z mezipaměti i indexu, když se objekty blob odstraní z vašeho zdroje dat, povolte v indexeru zásadu odstranění. Bez této zásady není odstranění dokumentu z mezipaměti podporované.

Měli byste být obeznámeni s nastavením indexerů. Začněte přehledem indexeru a pokračujte v sadách dovedností a seznamte se s kanály rozšiřování. Další informace o klíčových konceptech najdete v tématu přírůstkové rozšiřování.

Upozornění

Pokud používáte indexer SharePointu Online (Preview), měli byste se vyhnout přírůstkovým rozšiřováním. Za určitých okolností se mezipaměť stane neplatnou a vyžaduje resetování a spuštění indexeru, pokud se rozhodnete ji znovu načíst.

Povolit u nových indexerů

K povolení mezipaměti rozšiřování v indexeru můžete použít Azure Portal, rozhraní API ve verzi Preview nebo beta sady Azure SDK.

Azure Portal
REST

Vlevo vyberte Indexery a pak vyberte Přidat indexer.
Zadejte název indexeru a existující index, zdroj dat a sadu dovedností.
Povolte přírůstkové ukládání do mezipaměti a nastavte účet služby Azure Storage.

U nových indexerů přidejte vlastnost "cache" do datové části definice indexeru při volání Create nebo Update Indexer.

Můžete použít rozhraní API verze Preview 2021-04-30-preview a novější. Doporučujeme nejnovější verzi Preview pro vytvoření nebo aktualizaci Indexeru (2024-05-01-preview).

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

Povolit u existujících indexerů

Pro stávající indexery, které už sadu dovedností mají, přidejte ukládání do mezipaměti pomocí následujícího postupu. Jako jednorázovou operaci obnovte indexer a znovu ho spusťte, aby se načetla mezipaměť.

Krok 1: Získání definice indexeru

Začněte platným pracovním indexerem, který má tyto komponenty: zdroj dat, sadu dovedností, index. Pomocí klienta rozhraní API odešlete požadavek GET Indexeru pro načtení indexeru. Pokud k indexeru GET použijete verzi rozhraní API ve verzi Preview, automaticky se do definice přidá vlastnost cache nastavená na hodnotu null.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Krok 2: Nastavení vlastnosti mezipaměti

V definici indexu upravte mezipaměť tak, aby obsahovala následující povinné a volitelné vlastnosti:

(Povinné) storageConnectionString musí být nastavená na připojovací řetězec služby Azure Storage.
(Volitelné) enableReprocessing logická vlastnost (true ve výchozím nastavení) značí, že je povolené přírůstkové rozšiřování. Nastavte, false jestli chcete pozastavit přírůstkové zpracování, zatímco jiné operace náročné na prostředky, jako je indexování nových dokumentů, probíhají a pak se vraťte zpět na true později.

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Krok 3: Resetování indexeru

Resetování indexeru se vyžaduje při nastavování přírůstkového rozšiřování stávajících indexerů, aby se zajistilo, že všechny dokumenty jsou v konzistentním stavu. Pro tuto úlohu můžete použít Azure Portal nebo klienta rozhraní API.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Krok 4: Uložení indexeru

Aktualizujte Indexer pomocí požadavku PUT, kde text požadavku obsahuje "mezipaměť".

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

Pokud teď v indexeru vydáte další požadavek GET, bude odpověď ze služby obsahovat ID vlastnost v objektu mezipaměti. Řetězec se připojí k názvu kontejneru obsahujícího všechny výsledky uložené v mezipaměti a zprostředkující stav každého dokumentu zpracovaného tímto indexerem. ID slouží k jedinečnému pojmenování mezipaměti v úložišti objektů blob.

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

Krok 5: Spuštění indexeru

Ke spuštění indexeru můžete použít Azure Portal nebo rozhraní API. Na webu Azure Portal v seznamu indexerů vyberte indexer a vyberte Spustit. Jednou z výhod použití webu Azure Portal je, že můžete monitorovat stav indexeru, poznamenat dobu trvání úlohy a počet zpracovávaných dokumentů. Stránky portálu se aktualizují každých několik minut.

Případně můžete použít REST ke spuštění indexeru:

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Poznámka:

Obnovení a opětovné spuštění indexeru způsobí úplné opětovné sestavení, aby bylo možné obsah uložit do mezipaměti. Všechny kognitivní obohacení se znovu spustí ve všech dokumentech. Opětovné využití rozšířeného obsahu z mezipaměti začíná po načtení mezipaměti.

Kontrola výstupu uloženého v mezipaměti

V části Kontejner objektů blob najděte mezipaměť ve službě Azure Storage. Název kontejneru je ms-az-search-indexercache-<some-alphanumeric-string>.

Mezipaměť se vytvoří a používá indexer. Jeho obsah není čitelný člověkem.

Pokud chcete ověřit, jestli je mezipaměť funkční, upravte sadu dovedností a spusťte indexer a potom porovnejte metriky před a po pro dobu provádění a počty dokumentů.

Sady dovedností, které zahrnují analýzu obrázků a optické rozpoznávání znaků (OCR) naskenovaných dokumentů, dělají dobré testovací případy. Pokud upravíte dovednosti podřízeného textu nebo jakoukoli dovednost, která nesouvisí s obrázkem, indexer může načíst veškerý dříve zpracovaný obsah obrázku a OCR z mezipaměti, aktualizovat a zpracovat pouze změny související s textem, které jsou označené vašimi úpravami. Můžete očekávat, že v počtu dokumentů provádění indexeru, kratší době provádění a méně poplatků na faktuře uvidíte méně dokumentů.

Sada souborů používaná v kurzech cog-search-demo je užitečný testovací případ, protože obsahuje 14 souborů různých formátů JPG, PNG, HTML, DOCX, PPTX a dalších typů. Změna en jazyka es v dovednosti překladu textu pro testování konceptu přírůstkového rozšiřování

Běžné chyby

K následující chybě dochází v případě, že zapomenete zadat verzi rozhraní API ve verzi Preview na požadavku:

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

Chyba 400 Chybný požadavek se zobrazí také v případě, že chybí požadavek indexeru. Chybová zpráva určuje chybějící závislosti.

Další kroky

Přírůstkové rozšiřování se dá použít u indexerů, které obsahují sady dovedností a poskytují opakovaně použitelný obsah pro indexy i úložiště znalostí. Následující odkazy obsahují další informace o ukládání do mezipaměti a sadách dovedností.

Sdílet prostřednictvím