Indexování objektů blob a souborů Markdownu v Azure AI Vyhledávač

V Azure AI Vyhledávač podporují indexery pro Azure Blob Storage, Azure Files a Microsoft OneLake režim analýzy souborů Markdown markdown. Soubory Markdownu je možné indexovat dvěma způsoby:

• Režim analýzy „jeden k mnoha“, který vytvoří více vyhledávacích dokumentů pro každý soubor Markdown.
• Režim analýzy 1:1, který vytvoří jeden vyhledávací dokument pro každý soubor Markdownu.

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 blobů a indexery souborů (verze Preview) je instance se standardním výkonem (Pro obecné účely v2), která podporuje úrovně přístupu hot a cool.

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=2026-04-01
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ýstupní struktury vyhledávacích dokumentů. Parsovací režim Markdownu nabízí následující podrežimy:

V oneToMany případě pod-režimu byste měli zkontrolovat indexování jednoho blobu pro vytvoření mnoha vyhledávacích dokumentů , abyste pochopili, jak indexer blobů zpracovává rozlišení klíče dokumentu u více vyhledávacích dokumentů vytvořených ze stejného blobu.

Následující části popisují jednotlivé podmódy podrobněji. Pokud neznáte klienty a koncepty indexeru, přečtěte si téma Vytvoření indexeru vyhledávání. 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 jsou citlivé na velikost písmen.

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

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 a tabulky, se považují za prostý text a předávají 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 analýzy typu 1:N

Režim analýzy 1:N parsuje soubory Markdownu do více vyhledávacích dokumentů, kde každý dokument odpovídá určitému oddílu obsahu souboru Markdownu na základě metadat záhlaví v tomto okamžiku v 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 nezpracovaný Markdown nalezený v určitém umístění, na základě metadat záhlaví v tomto okamžiku v dokumentu.

• sections: Objekt, který obsahuje podpole pro metadata záhlaví až do požadované úrovně záhlaví. Pokud je například nastavena markdownHeaderDepth hodnota h3, obsahuje řetězcová pole h1, h2a 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 konfiguracích indexu a indexeru v následujících ukázkách. Obsažená dílčí pole jsou:

  • h1 – Řetězec obsahující hodnotu hlavičky h1. Prázdný řetězec, pokud není v tomto okamžiku v dokumentu nastaven.
  • (Volitelné) h2– Řetězec obsahující hodnotu záhlaví h2. Prázdný řetězec, pokud není v tomto okamžiku v dokumentu nastaven.
  • (Volitelné) h3– Řetězec obsahující hodnotu hlavičky h3. Prázdný řetězec, pokud není v tomto okamžiku v dokumentu nastaven.
  • (Volitelné) h4– Řetězec obsahující hodnotu hlavičky h4. Prázdný řetězec, pokud není v tomto okamžiku v dokumentu nastaven.
  • (Volitelné) h5– Řetězec obsahující hodnotu hlavičky h5. Prázdný řetězec, pokud není v tomto okamžiku v dokumentu nastaven.
  • (Volitelné) h6– Řetězec obsahující hodnotu záhlaví h6. Prázdný řetězec, pokud není v tomto okamžiku v dokumentu nastaven.

• ordinal_position: Celočíselná hodnota označující pozici oddílu v hierarchii dokumentů. Toto pole slouží k uspořádání sekcí v jejich původní sekvenci, jak se objevují v dokumentu, počínaje pořadovou pozicí 1 a postupným zvyšováním pro každou hlavičku.

Schéma indexu pro parsování jedno k mnoha.

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 indexátoru pro parsování typu jedna ku mnoha

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=2026-04-01
Content-Type: application/json
api-key: [admin key]

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

Výstup indexeru pro parsování typu jedna k mnoha

Výsledkem tohoto souboru Markdownu jsou tři dokumenty pro vyhledávání po zaindexování, a to kvůli třem sekcím obsahu. 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
  }
}

Mapování polí jednoho k mnoha 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.

Následující příklad ukazuje tento 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žijte režim 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 použijte volitelný parametr markdownHeaderDepth k definování maximální hloubky nadpisu pro rozdělování. Pokud není zadáno, ve výchozím nastavení se použije h6, zachycující 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, h2h3, atd.) v syntaxi Markdownu. Toto pole pomáhá porozumět hierarchii a strukturování obsahu.

  • header_name: Řetězec obsahující text nadpisu, jak se zobrazuje v dokumentu Markdown. 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 slouží k uspořádání oddílů v původní sekvenci, jak se zobrazují v dokumentu, počínaje pořadovým číslem 1 a dále sekvenčně 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 dílčího oddílu také obsahuje vlastnosti header_level, header_name, content a ordinal_position, které umožňují rekurzivní strukturu představující hierarchii obsahu v 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 mapování polí nepoužíváte, měl by tvar indexu odrážet obrazec obsahu Markdownu. Vzhledem ke 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=2026-04-01
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, přejde jenom do hloubky 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řadové číslo se zvyšuje na základě umístění obsahu v dokumentu.

Pokud jsou úrovně záhlaví v obsahu přeskočeny, struktura výsledného dokumentu odráží záhlaví přítomná v obsahu Markdownu a nemusí nutně zahrnovat po sobě jdoucí vnořené sekce od h1 do h6. Například když dokument začíná na h2, první prvek v poli oddílů nejvyšší úrovně je h2.

Mapování polí 1:1 v indexu vyhledávání

K extrakci polí s vlastními názvy z dokumentu můžete použít mapování polí. Použijte stejnou ukázku Markdownu jako dříve a 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",
    }
  ]
}

Extrahování konkrétních polí z analyzovaného Markdownu se provádí podobně jako cesty k dokumentu ve outputFieldMappings, s výjimkou že cesta začíná /sections místo /document. Například by /sections/0/content namapoval na obsah pod položkou na pozici 0 v poli oddílů.

Příklad silného případu použití může vypadat nějak takto: všechny soubory Markdown 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" },
]

V této části 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."
}

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

Když použijete režim parsování 1:N, může opětovné indexování upraveného Markdownového souboru vést k zastaralým nebo duplicitním dokumentům, pokud jsou oddíly odebrány. Toto chování je specifické pro režim jeden-ku-mnohým a nevztahuje se na analyzování jeden-na-jednoho.

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é smazání s metadaty

Tato metoda používá nepermanentní odstranění k odstranění dokumentů přidružených ke konkrétnímu blobu. Další informace najdete v tématu detekce změn a odstranění pomocí indexerů pro Azure Storage v Azure AI Vyhledávač.

Kroky:

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 objektu blob.
3. Odstraňte 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ůžete provést jednu z těchto akcí:

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

Kroky:

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 nebo chunk_id) pro všechny dokumenty svázané s určitým souborem. Nahraďte metadata_storage_path příslušné pole v indexu, které se mapuje na cestu k souboru nebo identifikátor URI objektu blob. Toto pole musí být klíčem.

   GET https://[service name].search.windows.net/indexes/[index name]/docs?api-version=2026-04-01
   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=2026-04-01
   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

• Konfigurace indexerů objektů blob
• Definování mapování polí
• Přehled indexerů
• Jak indexovat objekty blob CSV pomocí indexeru objektů blob
• Tutorial: Vyhledávání dat Markdownu z Azure Blob Storage