Sdílet prostřednictvím

Indexování objektů blob a souborů Markdownu ve službě Azure AI Search

Poznámka:

Tato funkce je aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučuje se pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Indexery pro Azure Blob Storage, Azure Files a Microsoft OneLake ve službě Azure AI Search podporují markdown režim analýzy souborů Markdown. Soubory Markdownu je možné indexovat dvěma způsoby:

  • Režim analýzy typu jeden-na-více, tvorba více vyhledávacích dokumentů na jeden soubor ve formátu Markdown
  • Režim analýzy 1:1, vytvoření jednoho vyhledávacího dokumentu na soubor Markdownu

Návod

Po zkontrolování tohoto článku pokračujte na kurz: Vyhledávání dat Markdown ze služby Azure Blob Storage.

Požadavky

  • Podporovaný zdroj dat: Azure Blob Storage, Azure File Storage, Microsoft OneLake.

    V případě OneLake se ujistěte, že splňujete všechny požadavky indexeru OneLake.

    Azure Storage pro indexery objektů blob a indexery souborů je standardní instance výkonu (pro obecné účely v2), která podporuje horkou a studenou úroveň přístupu.

Parametry režimu analýzy Markdownu

Parametry režimu analýzy se zadají v definici indexeru při vytváření nebo aktualizaci indexeru.

POST https://[service name].search.windows.net/indexers?api-version=2025-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h6"
    }
  },
}

Indexer objektů blob poskytuje submode parametr pro určení výstupu struktury vyhledávacích dokumentů. Režim zpracování Markdownu nabízí následující možnosti podréžimů:

režim parsování dílčí vid Hledat v dokumentu Description
markdown oneToMany Více objektů blob na objekt blob (výchozí) Rozdělí Markdown do více prohledávacích dokumentů, z nichž každý představuje oddíl obsahu (neheader) souboru Markdownu. Dílčí režim můžete vynechat, pokud nechcete parsovat 1:1.
markdown oneToOne Jeden na datový objekt Parsuje Markdown do jednoho vyhledávacího dokumentu s oddíly namapovanými na konkrétní záhlaví v souboru Markdownu.

U oneToMany podrežimu byste měli zkontrolovat indexování jednoho objektu blob k produkci mnoha hledacích dokumentů, abyste pochopili, jak indexer objektů blob zpracovává nejasnost klíče dokumentu pro více hledacích dokumentů vytvořených ze stejného objektu blob.

Další části popisují jednotlivé podmódy podrobněji. Pokud nejste obeznámeni s klienty indexeru a jeho koncepty, viz Vytvoření vyhledávacího indexeru. Měli byste být také obeznámeni s podrobnostmi základní konfigurace indexeru objektů blob, která se zde neopakuje.

Volitelné parametry analýzy Markdownu

Parametry rozlišují malá a velká písmena.

Název parametru Povolené hodnoty Description
markdownHeaderDepth h1, h2, h3, h4, , h5h6(default) Tento parametr určuje nejnižší úroveň záhlaví, která se při analýze považuje, což umožňuje flexibilní zpracování struktury dokumentu (například pokud markdownHeaderDepth je nastavená h1hodnota , analyzátor rozpoznává pouze hlavičky nejvyšší úrovně, které začínají na "#", a všechny hlavičky nižší úrovně se považují za prostý text). Pokud není zadáno, výchozí hodnota h6je .

Toto nastavení lze po počátečním vytvoření indexeru změnit, ale struktura výsledných vyhledávacích dokumentů se může v závislosti na obsahu Markdownu změnit.

Podporované prvky Markdownu

Analýza Markdownu rozděluje obsah pouze na základě záhlaví. Všechny ostatní prvky, jako jsou seznamy, bloky kódu, tabulky atd., se považují za prostý text a předají se do pole obsahu.

Ukázkový obsah Markdownu

Následující obsah Markdownu se používá pro příklady na této stránce:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Použijte režim parsování 1:N

Režim analýzy typu jeden-ku-mnoha parsuje soubory Markdown do více vyhledávacích dokumentů, kde každý dokument odpovídá určité části obsahu souboru Markdown na základě metadat hlaviček v daném bodě dokumentu. Markdown se analyzuje na základě hlaviček do vyhledávacích dokumentů, které obsahují následující obsah:

  • content: Řetězec, který obsahuje surový Markdown nalezený v určitém umístění, na základě metadat záhlaví v daném bodě v dokumentu.

  • sections: Objekt, který obsahuje podpole pro metadata záhlaví až do požadované úrovně záhlaví. Pokud je například markdownHeaderDepth nastaveno na h3, obsahuje řetězcová pole h1, h2 a h3. Tato pole jsou indexována zrcadlením této struktury v indexu, nebo prostřednictvím mapování polí ve formátu /sections/h1, sections/h2atd. Příklady v kontextu najdete v následujících ukázkách v konfiguracích indexu a indexeru. Obsažená dílčí pole jsou:

    • h1 – Řetězec obsahující hodnotu hlavičky h1. Řetězec je prázdný, pokud není nastaven v této části dokumentu.
    • (Volitelné) h2– Řetězec obsahující hodnotu záhlaví h2. Řetězec je prázdný, pokud není nastaven v této části dokumentu.
    • (Volitelné) h3– Řetězec obsahující hodnotu hlavičky h3. Řetězec je prázdný, pokud není nastaven v této části dokumentu.
    • (Volitelné) h4– Řetězec obsahující hodnotu hlavičky h4. Řetězec je prázdný, pokud není nastaven v této části dokumentu.
    • (Volitelné) h5– Řetězec obsahující hodnotu hlavičky h5. Řetězec je prázdný, pokud není nastaven v této části dokumentu.
    • (Volitelné) h6– Řetězec obsahující hodnotu záhlaví h6. Řetězec je prázdný, pokud není nastaven v této části dokumentu.

  • ordinal_position: Celočíselná hodnota označující pozici oddílu v hierarchii dokumentů. Toto pole slouží k řazení sekcí v jejich původním pořadí tak, jak se zobrazují v dokumentě, počínaje pořadovým číslem 1 a postupně navyšující se pro každou nadpis.

Schéma indexu pro parsování 1:N

Příklad konfigurace indexu může vypadat nějak takto:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "content",
    "type": "Edm.String",
  },
  {
    "name": "ordinal_position",
    "type": "Edm.Int32"
  },
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "h1",
      "type": "Edm.String"
    },
    {
      "name": "h2",
      "type": "Edm.String"
    }]
  }]
}

Definice indexeru pro analýzu typu 'jeden na více'

Pokud jsou názvy polí a datové typy zarovnané, může indexer objektů blob odvodit mapování bez explicitního mapování polí, které je přítomné v požadavku, takže konfigurace indexeru odpovídající zadané konfiguraci indexu může vypadat takto:

POST https://[service name].search.windows.net/indexers?api-version=2025-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": { "parsingMode": "markdown" }
  },
}

Poznámka:

Tady submode není potřeba explicitně nastavit, protože oneToMany je to výchozí.

Výstup indexovacího programu pro parsování typu jedna k mnoha

Výsledkem tohoto Markdownového souboru budou po indexování tři vyhledávací dokumenty, kvůli třem obsahovým sekcím. Vyhledávací dokument, který je výsledkem prvního oddílu obsahu poskytnutého dokumentu Markdownu, by obsahoval následující hodnoty pro content, sectionsh1a h2:

{
  {
    "content": "Content for section 1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": ""
    },
    "ordinal_position": 1
  },
  {
    "content": "Content for subsection 1.1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": "Subsection 1.1"
    },
    "ordinal_position": 2
  },
  {
    "content": "Content for section 2.\r\n",
    "sections": {
      "h1": "Section 2",
      "h2": ""
    },
    "ordinal_position": 3
  }
}

Namapujte pole jednoho-na-mnoho v indexu vyhledávání

Mapování polí přidruží zdrojové pole k cílovému poli v situacích, kdy názvy a typy polí nejsou identické. Mapování polí se ale dá použít také ke shodě částí dokumentu Markdownu a jejich "zvednutí" do polí nejvyšší úrovně hledaného dokumentu.

Ilustruje to následující vzorový scénář. Další informace o mapování polí obecně naleznete v tématu mapování polí.

Předpokládejme index vyhledávání s následujícími poli: raw_content typu Edm.String, h1_header typu Edm.Stringa h2_header typu Edm.String. K namapování Markdownu na požadovaný obrazec použijte následující mapování polí:

"fieldMappings" : [
    { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
    { "sourceFieldName" : "/sections/h1", "targetFieldName" : "h1_header" },
    { "sourceFieldName" : "/sections/h2", "targetFieldName" : "h2_header" },
  ]

Výsledný vyhledávací dokument v indexu by vypadal takto:

{
  {
    "raw_content": "Content for section 1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "",
  },
  {
    "raw_content": "Content for section 1.1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "Subsection 1.1",
  },
  {
    "raw_content": "Content for section 2.\r\n",
    "h1_header": "Section 2",
    "h2_header": "",
  }
}

Použití režimu analýzy 1:1

V režimu analýzy 1:1 se celý dokument Markdownu indexuje jako jeden vyhledávací dokument a zachová hierarchii a strukturu původního obsahu. Tento režim je nejužitečnější, když soubory, které se mají indexovat, sdílejí společnou strukturu, abyste mohli tuto společnou strukturu v indexu použít k prohledání příslušných polí.

V definici indexeru nastavte parsingMode na "markdown" a pomocí volitelného parametru markdownHeaderDepth definujte maximální hloubku nadpisu pro rozdělení obsahu. Pokud není zadáno, ve výchozím nastavení se používá h6, který zachytí všechny možné hloubky záhlaví.

Markdown se analyzuje na základě hlaviček do vyhledávacích dokumentů, které obsahují následující obsah:

  • document_content: Obsahuje celý text Markdownu jako jeden řetězec. Toto pole slouží jako nezpracovaná reprezentace vstupního dokumentu.

  • sections: Pole objektů, které obsahuje hierarchické znázornění oddílů v dokumentu Markdownu. Každý oddíl je reprezentován jako objekt v rámci tohoto pole a zachycuje strukturu dokumentu vnořeným způsobem, který odpovídá záhlavím a jejich příslušnému obsahu. Pole jsou přístupná prostřednictvím mapování polí odkazováním na cestu, například /sections/content. Objekty v tomto poli mají následující vlastnosti:

    • header_level: Řetězec, který označuje úroveň záhlaví (h1, h2, h3atd.) v syntaxi Markdownu. Toto pole pomáhá porozumět hierarchii a strukturování obsahu.

    • header_name: Řetězec obsahující text záhlaví tak, jak se vyskytuje v Markdown dokumentu. Toto pole obsahuje popisek nebo název oddílu.

    • content: Řetězec obsahující textový obsah, který bezprostředně následuje za záhlavím, až do další hlavičky. Toto pole zachycuje podrobné informace nebo popis přidružený k hlavičce. Pokud není žádný obsah přímo pod záhlavím, hodnota je prázdný řetězec.

    • ordinal_position: Celočíselná hodnota označující pozici oddílu v hierarchii dokumentů. Toto pole se používá k uspořádání sekcí v jejich původním pořadí tak, jak se zobrazují v dokumentu, počínaje pozicí 1 a postupně navyšující číslo pro každý obsahový blok.

    • sections: Pole, které obsahuje objekty představující pododdíly vnořené pod aktuálním oddílem. Toto pole se řídí stejnou strukturou jako pole nejvyšší úrovně sections , což umožňuje znázornění více úrovní vnořeného obsahu. Každý objekt pododdílu obsahuje vlastnosti header_level, header_name, content a ordinal_position, které umožňují rekurzivní strukturu reprezentující hierarchii obsahu Markdownu.

Tady je ukázkový Markdown, který používáme k vysvětlení schémat indexů navržených pro každý režim analýzy.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Schéma indexu pro analýzu 1:1

Pokud nepoužíváte mapování polí, měl by tvar indexu odrážet tvar obsahu Markdownu. Vzhledem k struktuře ukázkového Markdownu se dvěma oddíly a jedním dílčím oddílem by měl index vypadat podobně jako v následujícím příkladu:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "document_content",
    "type": "Edm.String"
  },
  {
    "name": "sections",
    "type": "Collection(Edm.ComplexType)",
    "fields": [
    {
      "name": "header_level",
      "type": "Edm.String"
    },
    {
      "name": "header_name",
      "type": "Edm.String"
    },
    {
      "name": "content",
      "type": "Edm.String"
    },
    {
      "name": "ordinal_position",
      "type": "Edm.Int32"
    },
    {
      "name": "sections",
      "type": "Collection(Edm.ComplexType)",
      "fields": [
      {
        "name": "header_level",
        "type": "Edm.String"
      },
      {
        "name": "header_name",
        "type": "Edm.String"
      },
      {
        "name": "content",
        "type": "Edm.String"
      },
      {
        "name": "ordinal_position",
        "type": "Edm.Int32"
      }]
    }]
  }]
}

Definice indexeru pro analýzu 1:1

POST https://[service name].search.windows.net/indexers?api-version=2025-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToOne",
    }
  }
}

Výstup indexeru pro parsování 1:1

Protože Markdown, který chceme indexovat, má hloubku pouze h2 (##), potřebujeme sections pole vnořená do hloubky 2, aby se shodovala. Výsledkem této konfigurace by byla následující data v indexu:

  "document_content": "# Section 1\r\nContent for section 1.\r\n## Subsection 1.1\r\nContent for subsection 1.1.\r\n# Section 2\r\nContent for section 2.\r\n",
  "sections": [
    {
      "header_level": "h1",
      "header_name": "Section 1",
      "content": "Content for section 1.",
      "ordinal_position": 1,
      "sections": [
        {
          "header_level": "h2",
          "header_name": "Subsection 1.1",
          "content": "Content for subsection 1.1.",
          "ordinal_position": 2,
        }]
    }],
    {
      "header_level": "h1",
      "header_name": "Section 2",
      "content": "Content for section 2.",
      "ordinal_position": 3,
      "sections": []
    }]
  }

Jak vidíte, pořadí se posouvá podle umístění v dokumentu.

Je také třeba poznamenat, že pokud jsou úrovně nadpisů vynechány v obsahu, struktura výsledného dokumentu odráží nadpisy, které jsou přítomné v obsahu Markdownu, ale nemusí nutně obsahovat vnořené sekce postupně od h1 přes h6. Například když dokument začíná s h2, pak prvním prvkem v poli oddílů nejvyšší úrovně je h2.

Mapujte pole 1:1 v indexu vyhledávání

Pokud chcete z dokumentu extrahovat pole s vlastními názvy, můžete k tomu použít mapování polí. Při použití stejné ukázky Markdownu jako dříve, zvažte následující konfiguraci indexu:

{
  "name": "my-markdown-index",
  "fields": [
    {
      "name": "document_content",
      "type": "Edm.String",
    },
    {
      "name": "document_title",
      "type": "Edm.String",
    },
    {
      "name": "opening_subsection_title"
      "type": "Edm.String",
    }
    {
      "name": "summary_content",
      "type": "Edm.String",
    }
  ]
}

K extrahování konkrétních polí z analyzovaného Markdownu dochází podobně jako u dokumentových cest ve outputFieldMappings, kromě toho, že cesta začíná /sections místo /document. Například by /sections/0/content mapoval na obsah položky na pozici 0 v poli oddílů.

Příklad silného případu použití může vypadat nějak takto: všechny soubory Markdownu mají název dokumentu v prvním h1, název pododdílu v prvním h2 a souhrn v obsahu konečného odstavce pod posledním h1. K indexování pouze tohoto obsahu můžete použít následující mapování polí:

"fieldMappings" : [
  { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
  { "sourceFieldName" : "/sections/0/header_name", "targetFieldName" : "document_title" },
  { "sourceFieldName" : "/sections/0/sections/header_name", "targetFieldName" : "opening_subsection_title" },
  { "sourceFieldName" : "/sections/1/content", "targetFieldName" : "summary_content" },
]

Tady byste z tohoto dokumentu extrahovali jenom relevantní části. Aby bylo možné tuto funkci efektivně používat, měly by dokumenty, které plánujete indexovat, sdílet stejnou hierarchickou strukturu záhlaví.

Výsledný vyhledávací dokument v indexu by vypadal takto:

{
  "content": "Content for section 1.\r\n",
  "document_title": "Section 1",
  "opening_subsection_title": "Subsection 1.1",
  "summary_content": "Content for section 2."
}

Poznámka:

Tyto příklady určují, jak tyto režimy analýzy používat zcela s mapováním polí nebo bez nich, ale obojí můžete použít v jednom scénáři, pokud vyhovuje vašim potřebám.

Správa zastaralých dokumentů z opětovného indexování Markdownu

Při použití režimu parsování jedna ku mnoha může opětovné indexování upraveného souboru Markdown vést ke vzniku zastaralých nebo duplicitních dokumentů, pokud jsou sekce odebrány. Toto chování je specifické pro režim jedna k mnoha a nevztahuje se na parsování jedna k jedné.

Přehled chování

Režim analýzy 1:N

V oneToMany režimu se každý oddíl Markdownu (na základě záhlaví) indexuje jako samostatný vyhledávací dokument. Při opětovném indexování souboru:

  • Žádné automatické odstranění: Indexer přepíše stávající dokumenty novými dokumenty, ale neodstraní dokumenty, které již neodpovídají žádnému obsahu v aktualizovaném souboru.
  • Potenciál duplicit: K tomuto problému konkrétně dochází pouze v případě, že se odstraní více oddílů, než se vloží mezi spuštění indexování. V takových případech zůstávají zbývající dokumenty z předchozí verze v indexu, což vede k zastaralým položkám, které už neodráží aktuální stav zdrojového souboru.

Režim analýzy 1:1

V oneToOne režimu se celý soubor Markdownu indexuje jako jeden vyhledávací dokument. Při opětovném indexování souboru:

  • Chování při přepsání: Stávající dokument se zcela nahradí novou verzí.
  • Žádné zastaralé oddíly: Při opětovném indexování souboru se stávající dokument nahradí aktualizovanou verzí a odebraný obsah se už nezahrne. Jedinou výjimkou je, pokud se změní cesta k souboru nebo identifikátor URI objektu blob, což může vést k vytvoření nového dokumentu společně se starým dokumentem.

Možnosti alternativního řešení

Pokud chcete zajistit, aby index odrážel aktuální stav souborů Markdownu, zvažte jeden z následujících přístupů:

Možnost 1. Měkké odstranění s metadaty

Tato metoda používá měkké odstranění k odstranění dokumentů přidružených ke konkrétnímu blobu. Další informace najdete v tématu Změna a odstranění detekce pomocí indexerů pro Azure Storage ve službě Azure AI Search.

Schody:

  1. Označte objekt blob jako odstraněný nastavením pole metadat.
  2. Nechte indexer běžet. Odstraní všechny dokumenty v indexu přidruženém k danému blobu.
  3. Odeberte značku soft-delete a znovu indexujte soubor.

Možnost 2. Použití rozhraní API pro odstranění

Před opětovným indexováním upraveného souboru Markdownu explicitně odstraňte existující dokumenty přidružené k danému souboru pomocí rozhraní API pro odstranění. Máte tyto možnosti:

  • Ručně identifikujte jednotlivé zastaralé dokumenty identifikací duplicit v indexu, které se mají odstranit. To může být možné u malých, dobře pochopitelných změn, ale může to být časově náročné.
  • (Doporučeno) Před opětovným indexováním odeberte všechny dokumenty vygenerované ze stejného nadřazeného souboru, abyste se vyhnuli nekonzistence.

Schody:

  1. Identifikujte ID dokumentů přidružených k souboru. Pomocí dotazu jako v následujícím příkladu můžete načíst ID klíčů dokumentu (například id, chunk_idatd.) pro všechny dokumenty svázané s určitým souborem. Nahraďte metadata_storage_path příslušným polem v indexu, které se mapuje na cestu k souboru nebo URI blobu. Toto pole musí být klíčem.

    GET https://[service name].search.windows.net/indexes/[index name]/docs?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]


  {  
      "filter": "metadata_storage_path eq 'https://<storage-account>.blob.core.windows.net/<container-name>/<file-name>.md'",
      "select": "id"
  }

  2. Vyřešte žádost o odstranění dokumentů s identifikovanými klíči.

    POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "aHR0c...jI1"  
    },
    {  
      "@search.action": "delete",  
      "id": "aHR0...MQ2"  
    }  
  ]  
}

  3. Znovu indexujte aktualizovaný soubor.

Další kroky

  • Last updated on