Markdown-blobok és fájlok indexelése a Azure AI Keresés

A Azure AI Keresés Azure Blob Storage, Azure Files és Microsoft OneLake indexelői támogatják a Markdown-fájlok markdown elemzési módját. A Markdown-fájlok kétféleképpen indexelhetők:

• Egy-a-többhöz elemzési mód, amely Markdown-fájlonként több keresési dokumentumot hoz létre.
• Egy az egyhez elemzési mód, amely Markdown-fájlonként egy keresési dokumentumot hoz létre.

Előfeltételek

• Támogatott adatforrás: Azure Blob Storage, Azure File Storage, Microsoft OneLake.

  A OneLake esetében győződjön meg arról, hogy megfelel a OneLake indexelő összes követelményének.

  A blobindexelőkhöz és fájlindexelőkhöz (előzetes verzió) készült Azure Storage egy standard teljesítményű (általános célú v2-es) fiók, amely támogatja a gyakori és ritka elérésű szinteket.

Markdown-elemzési mód paraméterei

Az elemzési mód paraméterei indexelő definícióban vannak megadva indexelő létrehozásakor vagy frissítésekor.

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"
    }
  },
}

A blobindexelő egy paramétert submode biztosít a keresési dokumentumok kimeneti szerkezetének meghatározásához. A Markdown-elemzési mód a következő almód-beállításokat biztosítja:

Az oneToMany szubmód esetében érdemes áttekinteni az Indexelés egy blobról több keresési dokumentum létrehozásához cikket, hogy megértse, hogyan kezeli a blob indexelő a dokumentumkulcs egyértelműsítését az ugyanabból a blobból származó több keresési dokumentum számára.

A későbbi szakaszok részletesebben ismertetik az egyes almódokat. Ha nem ismeri az indexelő ügyfeleket és a fogalmakat, olvassa el a Keresési indexelő létrehozása című témakört. Ismernie kell az alapszintű blobindexelő konfiguráció részleteit is, amelyek itt nem ismétlődnek.

Választható Markdown-elemzési paraméterek

A paraméterek megkülönböztetik a kis- és nagybetűket.

Ez a beállítás az indexelő létrehozása után módosítható. Az eredményként kapott keresési dokumentumok struktúrája azonban a Markdown-tartalomtól függően változhat.

Támogatott Markdown-elemek

A Markdown-elemzés csak a fejlécek alapján osztja fel a tartalmat. Minden más elem, például listák, kódblokkok és táblázatok egyszerű szövegként lesznek kezelve, és egy tartalommezőbe kerülnek.

Minta Markdown tartalom

Az alábbi Markdown-tartalmakat használjuk az oldalon található példákhoz:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Egy-a-többhöz elemzési mód használata

Az egy-több elemzési mód úgy elemzi a Markdown-fájlokat, hogy több keresési dokumentumot hoz létre belőlük. Minden dokumentum a Markdown-fájl egy meghatározott tartalomszakaszának felel meg, az adott szakasz fejlécének metaadatai alapján. A Markdown fejlécek alapján van elemezve a keresési dokumentumokban, amelyek a következő tartalmat tartalmazzák:

• content: Egy karakterlánc, amely a dokumentum egy adott pontján található fejléc metaadatai alapján meghatározott helyen lévő nyers Markdown szöveget tartalmazza.

• sections: Olyan objektum, amely a fejléc metaadatainak almezőit tartalmazza a kívánt fejlécszintig. Például, amikor a markdownHeaderDepth be van állítva h3, akkor sztringmezőket tartalmaz, mint például h1, h2 és h3. Ezeket a mezőket a rendszer úgy indexeli, hogy tükrözi ezt a struktúrát az indexben, vagy a formátumbeli /sections/h1/sections/h2mezőleképezéseken keresztül stb. A kontextusban szereplő példákért tekintse meg az index és indexelő konfigurációkat a következő mintákban. Az almezők a következők:

  • h1 - h1 fejlécértéket tartalmazó string. Üres karaktersor, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h2- Egy h2 fejlécértéket tartalmazó karakterlánc. Üres karaktersor, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h3- Egy karakterlánc, amely a h3 fejlécértéket tartalmazza. Üres karaktersor, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h4- A h4 fejlécértéket tartalmazó sztring. Üres karaktersor, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező), h5- A h5 fejléc értékét tartalmazó karakterlánc. Üres karaktersor, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező)h6 - A h6 fejlécértéket tartalmazó karakterlánc. Üres karaktersor, ha a dokumentum ezen a pontján nincs beállítva.

• ordinal_position: A szakasz dokumentumhierarchián belüli pozícióját jelző egész szám. Ez a mező arra szolgál, hogy a szakaszokat az eredeti sorrendben rendezze, ahogy azok megjelennek a dokumentumban, kezdve az 1 sorszámmal, és az egyes fejlécekhez egymás után növekvő sorrendbe.

Index séma egyhez-több elemzéshez

Egy példa indexkonfiguráció a következőképpen nézhet ki:

{
  "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"
    }]
  }]
}

Indexelődefiníció egy-a-többhöz elemzéshez

Ha a mezőnevek és az adattípusok egymáshoz igazodnak, a blobindexelő a kérelemben található explicit mezőleképezés nélkül is következtethet a leképezésre, így a megadott indexkonfigurációnak megfelelő indexelő konfiguráció a következőképpen nézhet ki:

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" }
  },
}

Indexelő eredménye egyre-több elemzés számára

Ez a Markdown-fájl három keresési dokumentumot eredményezne az indexelés után a három tartalomszakasz miatt. A megadott Markdown-dokumentum első tartalomszakaszából származó keresési dokumentum a következő értékeket contentsectionsh1h2tartalmazza:

{
  {
    "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
  }
}

Egy-több mezők térképezése egy keresési indexben

A mezőleképezések egy forrásmezőt társítanak egy célmezőhöz olyan helyzetekben, amikor a mezőnevek és a típusok nem azonosak. A mezőleképezések azonban a Markdown-dokumentumok részeinek egyeztetésére és a keresési dokumentum legfelső szintű mezőibe való "felemelésére" is használhatók.

Az alábbi példa ezt a forgatókönyvet szemlélteti. A mezőleképezésekkel kapcsolatos általános információkért lásd a mezőleképezéseket.

Tegyük fel, hogy a keresési index a következő mezőkkel rendelkezik: raw_content típus Edm.String, h1_header típus Edm.Stringés h2_header típus Edm.String. A Markdown kívánt alakzatba való leképezéséhez használja a következő mezőleképezéseket:

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

Az eredményként kapott keresési dokumentum az indexben a következőképpen nézne ki:

{
  {
    "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": "",
  }
}

Egy az egyhez elemzési mód használata

Az egy-az-egyhez elemzési módban a teljes Markdown-dokumentum egyetlen keresési dokumentumként lesz indexelve, megőrizve az eredeti tartalom hierarchiáját és szerkezetét. Ez a mód akkor hasznos, ha az indexelendő fájlok közös struktúrát használnak, így az indexben ezt a közös struktúrát használva kereshetővé teheti a releváns mezőket.

Az indexelő definícióban állítsa be a parsingMode értékét "markdown"-re, és használja az opcionális markdownHeaderDepth paramétert a daraboláshoz tartozó maximális címsormélység meghatározásához. Ha nincs megadva, az alapértelmezett beállítás az h6összes lehetséges fejlécmélység rögzítése.

A Markdown fejlécek alapján van elemezve a keresési dokumentumokban, amelyek a következő tartalmat tartalmazzák:

• document_content: A teljes Markdown-szöveget egyetlen sztringként tartalmazza. Ez a mező nyersen jeleníti meg a bemeneti dokumentumot.

• sections: Objektumtömb, amely a Markdown-dokumentumban lévő szakaszok hierarchikus ábrázolását tartalmazza. Minden szakasz objektumként jelenik meg ebben a tömbben, és beágyazott módon rögzíti a dokumentum struktúráját az élőfejeknek és azok tartalmának megfelelően. A mezők a mezőleképezéseken keresztül érhetők el, például /sections/contentaz elérési útra való hivatkozással. A tömb objektumai a következő tulajdonságokkal rendelkeznek:

  • header_level: Egy sztring, amely a Markdown szintaxisában a fejléc szintjét jelzi (h1, h2, h3 stb.). Ez a mező segít megérteni a tartalom hierarchiáját és szerkezetét.

  • header_name: A Markdown-dokumentumban megjelenő fejléc szövegét tartalmazó sztring. Ez a mező a szakasz címkéjét vagy címét tartalmazza.

  • content: Szöveges tartalmat tartalmazó sztring, amely azonnal követi a fejlécet, egészen a következő fejlécig. Ez a mező a fejléchez tartozó részletes információkat vagy leírásokat rögzíti. Ha nincs közvetlenül a fejléc alatt tartalom, az érték egy üres sztring.

  • ordinal_position: A szakasz dokumentumhierarchián belüli pozícióját jelző egész szám. Ez a mező arra szolgál, hogy az eredeti sorrendben rendezze a szakaszokat, ahogy azok megjelennek a dokumentumban, kezdve az 1 sorszámmal és az egyes tartalomblokkok sorrendjének növelésével.

  • sections: Az aktuális szakasz alá beágyazott alszakaszokat képviselő objektumokat tartalmazó tömb. Ez a tömb ugyanazt a struktúrát követi, mint a legfelső szintű sections tömb, amely lehetővé teszi a beágyazott tartalom több szintjének megjelenítését. Minden alszakasz-objektum tartalmaz header_level, header_name, contentés ordinal_position tulajdonságokat is, amelyek lehetővé teszik a Markdown-tartalom hierarchiáját képviselő rekurzív struktúrát.

Az alábbi Markdown-minta segítségével ismertetjük az egyes elemzési módok köré tervezett indexsémákat.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Index séma az egy az egyhez elemzéshez

Ha nem használ mezőleképezéseket, az index alakjának tükröznie kell a Markdown-tartalom alakját. Tekintettel a Markdown minta két szakaszára és egyetlen alszakaszára, az indexnek az alábbi példához hasonlóan kell kinéznie:

{
  "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"
      }]
    }]
  }]
}

Indexelődefiníció az egy-az-egyhez elemzéshez

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",
    }
  }
}

Indexelő kimenet az egy-az-egyhez elemzéshez

Mivel az indexelni kívánt Markdown csak a h2 (##) mélységig megy, két szint mélységbe ágyazott sections mezőkre van szükség ennek megfelelően. Ez a konfiguráció a következő adatokat eredményezné az indexben:

  "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": []
    }]
  }

Amint látható, a sorszám a dokumentumban lévő tartalom pozíciója alapján növekszik.

Ha a fejlécszintek kimaradnak a tartalomból, az eredményül kapott dokumentum struktúrája a Markdown-tartalomban található fejléceket tükrözi, és nem feltétlenül tartalmaz egymást követő beágyazott szakaszokat h1h6. Például, amikor a dokumentum a h2-nél kezdődik, a legfelső szintű szakaszok tömbjének első eleme a h2.

Egy-az-egyhez mezők leképezése keresési indexben

Ha egyéni neveket tartalmazó mezőket szeretne kinyerni a dokumentumból, használhat mezőleképezéseket. Az előzővel megegyező Markdown-mintát használva vegye figyelembe az alábbi indexkonfigurációt:

{
  "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",
    }
  ]
}

Az elemzett Markdown adott mezőinek kinyerése ugyanúgy történik, mint a dokumentum elérési útjai az outputFieldMappings fájlban, kivéve, hogy az elérési út ahelyett /sectionskezdődik/document. Így például /sections/0/content a szakaszok tömbjének 0. helyén lévő elem alatti tartalomra térképezi fel.

Egy erős használati eset például így nézhet ki: az összes Markdown-fájlnak van egy dokumentumcíme az elsőben h1, egy alszakaszcím az elsőben h2, és egy összegzés az utolsó bekezdés tartalmában az utolsó h1alatt. A következő mezőleképezésekkel csak az adott tartalmat indexelheti:

"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" },
]

Itt csak a dokumentum releváns részeit nyerheti ki. A funkció leghatékonyabb használatához az indexelni kívánt dokumentumoknak ugyanazzal a hierarchikus fejlécstruktúrával kell rendelkeznie.

Az eredményként kapott keresési dokumentum az indexben a következőképpen nézne ki:

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

Elavult dokumentumok kezelése a Markdown újraindexeléséből

Az egy-a-többhöz elemzési mód használatakor a módosított Markdown-fájlok újraindexelése elavult vagy duplikált dokumentumokat eredményezhet, ha a szakaszok el lettek távolítva. Ez a viselkedés az egy-a-többhöz módra vonatkozik, és nem vonatkozik az egy-az-egyhez elemzésre.

Viselkedés áttekintése

Egy-az-többhöz elemzési mód

Módban oneToMany az egyes Markdown-szakaszok (fejlécek alapján) külön keresési dokumentumként lesznek indexelve. A fájl újraindexelése esetén:

• Nincs automatikus törlés: Az indexelő felülírja a meglévő dokumentumokat újakkal, de nem törli azokat a dokumentumokat, amelyek már nem felelnek meg a frissített fájl tartalmának.
• Ismétlődések lehetősége: Ez a probléma csak akkor jelentkezik, ha több szakaszt törölnek, mint amennyit az indexelési futtatások közé szúrnak be. Ilyen esetekben az előző verzióból származó dokumentumok továbbra is az indexben maradnak, ami elavult bejegyzéseket eredményez, amelyek már nem tükrözik a forrásfájl aktuális állapotát.

Egy az egyhez elemzési mód

Módban oneToOne a rendszer a teljes Markdown-fájlt egyetlen keresési dokumentumként indexeli. A fájl újraindexelése esetén:

• Felülírás viselkedése: A meglévő dokumentum teljes egészében az új verzióra lesz lecserélve.
• Nincsenek elavult szakaszok: A fájl újraindexelésekor a meglévő dokumentumot lecseréli a frissített verzióra, és az eltávolított tartalom már nem szerepel benne. Az egyetlen kivétel az, ha a fájl elérési útja vagy a blob URI-ja megváltozik, ami egy új dokumentum létrehozását eredményezheti a régivel együtt.

Áthidaló lehetőségek

Annak érdekében, hogy az index tükrözze a Markdown-fájlok aktuális állapotát, fontolja meg az alábbi módszerek egyikét:

1. lehetőség. Lágy törlés metaadatokkal

Ez a módszer egy helyreállítható törlést használ egy adott blobhoz társított dokumentumok törléséhez. További információért lásd: Az Azure Storage módosítás- és törlésészlelése indexelőkkel az Azure AI Keresés-ben.

Lépések:

1. A blob töröltként való megjelölése egy metaadat mező beállításával történik.
2. Futtassa az indexelőt. Törli az adott blobhoz társított index összes dokumentumát.
3. Távolítsa el a helyreállítható törlési jelölőt, és indexelje újra a fájlt.

2. lehetőség. A delete API használata

A módosított Markdown-fájlok újraindexelése előtt explicit módon törölje a fájlhoz társított meglévő dokumentumokat a delete API használatával. A következőkre van lehetőség:

• Az egyes elavult dokumentumok manuális azonosításához az indexben törlésre kerülő duplikációkat kell azonosítani. Ez kis, jól érthető változások esetén megvalósítható, de időigényes lehet.
• (Ajánlott) Az újraindexelés előtt távolítsa el az ugyanazon szülőfájlból létrehozott összes dokumentumot, így elkerülhetők az inkonzisztenciák.

Lépések:

1. Azonosítsa a fájlhoz társított dokumentumok azonosítóját. Az alábbi példához hasonló lekérdezéssel lekérheti a dokumentumkulcs azonosítóit (például idchunk_id) az adott fájlhoz kapcsolódó összes dokumentumhoz. Cserélje le a metadata_storage_path mezőt az index azon megfelelő mezőjére, amely a fájl elérési útjára vagy a blob URI-jára képez le. Ennek a mezőnek kulcsnak kell lennie.

   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. Adjon ki törlési kérelmet a dokumentumokhoz az azonosított kulcsokkal.

   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. Indexelje újra a frissített fájlt.

Következő lépések

• Blobindexerek konfigurálása
• Mezőleképezések definiálása
• Indexelők áttekintése
• CSV-blobok indexelése blobindexelővel
• Tutorial: Markdown-adatok keresése az Azure Blob Storage-ből