Markdown-blobs en bestanden indexeren in Azure AI Zoeken

In Azure AI Zoeken ondersteunen indexeerfuncties voor Azure Blob Storage, Azure Files en Microsoft OneLake een markdown-parseermodus voor Markdown-bestanden. Markdown-bestanden kunnen op twee manieren worden geïndexeerd:

• Een-op-veel-parseringsmodus, waarmee meerdere zoekdocumenten per Markdown-bestand worden gemaakt.
• Een-op-een-parseringsmodus, waarmee één zoekdocument per Markdown-bestand wordt gemaakt.

Voorwaarden

• Een ondersteunde gegevensbron: Azure Blob Storage, Azure File Storage Microsoft OneLake.

  Voor OneLake moet u voldoen aan alle vereisten van de OneLake-indexeerfunctie.

  Azure Storage voor blob-indexeerders en bestandsindexeerders (preview) is een exemplaar met Standard-prestaties (voor algemeen gebruik v2) dat hot- en cool-toegangslagen ondersteunt.

Parameters voor de Markdown-parseringsmodus

Parameters voor de parseermodus worden opgegeven in een indexeerfunctiedefinitie wanneer u een indexeerfunctie maakt of bijwerkt.

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

De blob-indexeerfunctie biedt een submode parameter om de uitvoerstructuur van de zoekdocumenten te bepalen. De Markdown-parseringsmodus biedt de volgende opties voor submode:

Voor oneToMany submodus moet u het indexeren van één blob verkennen voor het produceren van meerdere zoekdocumenten om te begrijpen hoe de blobindexeerder de conflictoplossing van de documentsleutel afhandelt voor meerdere zoekdocumenten die zijn geproduceerd uit dezelfde blob.

In latere secties wordt elke submodus gedetailleerder beschreven. Als u niet bekend bent met indexeerfunctieclients en -concepten, raadpleegt u Een zoekindexeerfunctie maken. U moet ook bekend zijn met de details van de basisconfiguratie van de blob-indexeerfunctie, die hier niet wordt herhaald.

Optionele Markdown-parseringsparameters

Parameters zijn hoofdlettergevoelig.

Deze instelling kan worden gewijzigd nadat de indexeerfunctie is gemaakt. De structuur van de resulterende zoekdocumenten kan echter veranderen, afhankelijk van de Markdown-inhoud.

Ondersteunde Markdown-elementen

Markdown parseert alleen inhoud op basis van kopteksten. Alle andere elementen, zoals lijsten, codeblokken en tabellen, worden behandeld als tekst zonder opmaak en doorgegeven aan een inhoudsveld.

Voorbeeld van Markdown-inhoud

De volgende Markdown-inhoud wordt gebruikt voor de voorbeelden op deze pagina:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Een-op-veel-parsingmodus gebruiken

De een-op-veel-parseringsmodus parseert Markdown-bestanden in meerdere zoekdocumenten, waarbij elk document overeenkomt met een specifieke inhoudssectie van het Markdown-bestand op basis van de metagegevens van de koptekst op dat moment in het document. De Markdown wordt geparseerd op basis van kopteksten in zoekdocumenten, die de volgende inhoud bevatten:

• content: Een tekenreeks die de onbewerkte Markdown bevat die op een specifieke locatie is gevonden, op basis van de metagegevens van de header op dat moment in het document.

• sections: Een object met subvelden voor de metagegevens van de header tot het gewenste headerniveau. Wanneer markdownHeaderDepth bijvoorbeeld is ingesteld op h3, bevat tekenreeksvelden h1en h2h3. Deze velden worden geïndexeerd door deze structuur in de index te spiegelen, of door veldtoewijzingen in de indeling/sections/h1/sections/h2, enzovoort. Zie de index- en indexeerfunctieconfiguraties in de volgende voorbeelden voor voorbeelden in context. De subvelden zijn:

  • h1 - Een tekenreeks met de h1-kopwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
  • (Optioneel) h2- Een tekenreeks met de h2-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
  • (Optioneel) h3- Een tekenreeks die de h3-headerwaarde bevat. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
  • (Optioneel) h4- Een tekenreeks met de h4-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
  • (Optioneel) h5- Een tekenreeks met de h5-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
  • (Optioneel) h6- Een tekenreeks met de h6-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.

• ordinal_position: Een geheel getal dat de positie van de sectie in de documenthiërarchie aangeeft. Dit veld wordt gebruikt voor het rangschikken van de secties in de oorspronkelijke volgorde zoals ze worden weergegeven in het document, beginnend met een rangschikking van 1 en het sequentieel verhogen van elke koptekst.

Indexschema voor een-op-veel-parsering

Een voorbeeld van een indexconfiguratie ziet er ongeveer als volgt uit:

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

Definitie van indexeerfunctie voor een-op-veel-parsering

Als veldnamen en gegevenstypen op elkaar afgestemd zijn, kan de blob-indexeerder de toewijzing afleiden zonder expliciete veldtoewijzing in de aanvraag, zodat een indexeerconfiguratie die bij de opgegeven indexconfiguratie past er als volgt uitziet:

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

Uitvoer van de indexeerfunctie voor het parseren van een-op-veel verhoudingen

Dit Markdown-bestand zou resulteren in drie zoekdocumenten na het indexeren, vanwege de drie inhoudssecties. Het zoekdocument dat het resultaat is van de eerste inhoudssectie van het opgegeven Markdown-document, bevat de volgende waarden voorcontent, sectionsenh1h2:

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

Een-op-veel-velden toewijzen in een zoekindex

Veldtoewijzingen koppelen een bronveld aan een doelveld in situaties waarin de veldnamen en -typen niet identiek zijn. Veldtoewijzingen kunnen echter ook worden gebruikt om delen van een Markdown-document te vergelijken en ze op te tillen in velden op het hoogste niveau van het zoekdocument.

In het volgende voorbeeld ziet u dit scenario. Zie veldtoewijzingen voor meer informatie over veldtoewijzingen in het algemeen.

Stel dat u een zoekindex gebruikt met de volgende velden: raw_content van het type Edm.String, h1_header van het type Edm.Stringen h2_header van het type Edm.String. Als u uw Markdown wilt toewijzen aan de gewenste vorm, gebruikt u de volgende veldtoewijzingen:

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

Het resulterende zoekdocument in de index ziet er als volgt uit:

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

Een-op-een-parseermodus gebruiken

In de een-op-een-parseermodus wordt het hele Markdown-document geïndexeerd als één zoekdocument, waarbij de hiërarchie en structuur van de oorspronkelijke inhoud behouden blijven. Deze modus is het handigst wanneer de bestanden die moeten worden geïndexeerd een gemeenschappelijke structuur delen, zodat u deze gemeenschappelijke structuur in de index kunt gebruiken om de relevante velden doorzoekbaar te maken.

Stel in de definitie van de indexeerfunctie de parsingMode in op "markdown" en gebruik de optionele parameter markdownHeaderDepth om de maximale kopdiepte voor chunking te definiëren. Als niet opgegeven, is h6 standaard ingesteld voor het vastleggen van alle mogelijke kopdiepten.

De Markdown wordt geparseerd op basis van kopteksten in zoekdocumenten, die de volgende inhoud bevatten:

• document_content: Bevat de volledige Markdown-tekst als één tekenreeks. Dit veld fungeert als een onbewerkte weergave van het invoerdocument.

• sections: Een matrix met objecten die de hiërarchische weergave van de secties in het Markdown-document bevatten. Elke sectie wordt weergegeven als een object in deze matrix en legt de structuur van het document vast op een geneste manier die overeenkomt met de kopteksten en de bijbehorende inhoud. De velden zijn toegankelijk via veldtoewijzingen door bijvoorbeeld /sections/contentte verwijzen naar het pad. De objecten in deze matrix hebben de volgende eigenschappen:

  • header_level: Een tekenreeks die het niveau van de koptekst (h1, h2enzovoort h3) aangeeft in de Markdown-syntaxis. Dit veld helpt bij het begrijpen van de hiërarchie en het structureren van de inhoud.

  • header_name: Een tekenreeks die de tekst van de koptekst bevat zoals deze wordt weergegeven in het Markdown-document. Dit veld bevat een label of titel voor de sectie.

  • content: Een tekenreeks met tekstinhoud die direct volgt op de koptekst, tot aan de volgende koptekst. In dit veld worden de gedetailleerde informatie of beschrijving vastgelegd die aan de koptekst is gekoppeld. Als er geen inhoud rechtstreeks onder een koptekst staat, is de waarde een lege tekenreeks.

  • ordinal_position: Een geheel getal dat de positie van de sectie in de documenthiërarchie aangeeft. Dit veld wordt gebruikt om de secties in hun oorspronkelijke volgorde te rangschikken zoals ze worden weergegeven in het document, beginnend met een ordinale positie van 1 en vervolgens sequentieel verhoogd voor elk inhoudsblok.

  • sections: Een array die objecten bevat die subsecties vertegenwoordigen die zijn genest onder de huidige sectie. Deze matrix volgt dezelfde structuur als de matrix op het hoogste niveau sections , zodat u meerdere niveaus van geneste inhoud kunt weergeven. Elk subsectieobject bevat ook header_level, header_name, content en ordinal_position eigenschappen, waardoor een recursieve structuur wordt ingeschakeld die de hiërarchie van de Markdown-inhoud vertegenwoordigt.

Hier volgt het Markdown-voorbeeld dat we gebruiken om de indexschema's uit te leggen die zijn ontworpen rond elke parseermodus.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Indexschema voor een-op-een-parsering

Als u geen veldtoewijzingen gebruikt, moet de vorm van de index de vorm van de Markdown-inhoud weerspiegelen. Gezien de structuur van de Markdown-steekproef met de twee secties en één subsectie, moet de index er ongeveer als volgt uitzien:

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

Definitie van indexeerfunctie voor een-op-een-parsering

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

Uitvoer van de indexeerfunctie voor één-op-één parsing

Omdat de Markdown die we willen indexeren alleen naar een diepte van h2 ('##') gaat, hebben we velden nodig sections die tot een diepte van 2 zijn genest om dat aan te passen. Deze configuratie resulteert in de volgende gegevens in de index:

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

Zoals u kunt zien, wordt de volgorde verhoogd op basis van de locatie van de inhoud in het document.

Als koptekstniveaus in de inhoud worden overgeslagen, weerspiegelt de structuur van het resulterende document de kopteksten die aanwezig zijn in de Markdown-inhoud en bevat deze niet noodzakelijkerwijs opeenvolgende geneste secties van h1 tot en met h6. Wanneer het document bijvoorbeeld begint h2, is h2het eerste element in de matrix met secties op het hoogste niveau.

Een-op-een-relaties tussen velden toewijzen in een zoekindex

Als u velden met aangepaste namen uit het document wilt extraheren, kunt u veldtoewijzingen gebruiken. Houd rekening met de volgende indexconfiguratie met hetzelfde Markdown-voorbeeld als voorheen:

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

Het extraheren van specifieke velden uit de geparseerde Markdown wordt verwerkt op dezelfde manier als de documentpaden in outputFieldMappings, behalve het pad begint met /sections in plaats van /document. Zo wordt bijvoorbeeld /sections/0/content toegewezen aan de inhoud onder het item op positie 0 in de sectiematrix.

Een voorbeeld van een sterk gebruiksvoorbeeld kan er ongeveer als volgt uitzien: alle Markdown-bestanden hebben een documenttitel in de eerste h1, een subsectietitel in de eerste h2en een samenvatting in de inhoud van de laatste alinea onder de laatste alinea h1. U kunt de volgende veldtoewijzingen gebruiken om alleen die inhoud te indexeren:

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

Hier haalt u alleen de relevante stukken uit dat document op. Als u deze functionaliteit het effectiefst wilt gebruiken, moeten documenten die u wilt indexeren dezelfde hiërarchische headerstructuur delen.

Het resulterende zoekdocument in de index ziet er als volgt uit:

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

Verouderde documenten beheren vanuit opnieuw indexeren van Markdown

Wanneer u een-op-veel-parseermodus gebruikt, kan het opnieuw indexeren van een gewijzigd Markdown-bestand leiden tot verouderde of dubbele documenten als secties worden verwijderd. Dit gedrag is specifiek voor een-op-veel-modus en is niet van toepassing op één-op-één parsering.

Overzicht van gedrag

Een-op-veel-parsingmodus

In oneToMany de modus wordt elke Markdown-sectie (op basis van kopteksten) geïndexeerd als een afzonderlijk zoekdocument. Wanneer het bestand opnieuw wordt geïndexeerd:

• Geen automatische verwijdering: de indexeerfunctie overschrijft bestaande documenten met nieuwe documenten, maar verwijdert geen documenten die niet langer overeenkomen met inhoud in het bijgewerkte bestand.
• Potentieel voor duplicaten: dit probleem doet zich specifiek voor wanneer er meer secties worden verwijderd dan ingevoegd tussen indexeringsuitvoeringen. In dergelijke gevallen blijven de restdocumenten van de vorige versie in de index staan, wat leidt tot verouderde vermeldingen die niet langer de huidige status van het bronbestand weerspiegelen.

Een-op-een-parseermodus

In oneToOne de modus wordt het hele Markdown-bestand geïndexeerd als één zoekdocument. Wanneer het bestand opnieuw wordt geïndexeerd:

• Gedrag overschrijven: het bestaande document wordt volledig vervangen door de nieuwe versie.
• Geen verouderde secties: wanneer het bestand opnieuw wordt geïndexeerd, wordt het bestaande document vervangen door de bijgewerkte versie en wordt de verwijderde inhoud niet meer opgenomen. De enige uitzondering is als het bestandspad of de blob-URI wordt gewijzigd, wat kan leiden tot een nieuw document dat naast het oude document wordt gemaakt.

Tijdelijke oplossingsopties

Overweeg een van de volgende benaderingen om ervoor te zorgen dat de index de huidige status van uw Markdown-bestanden weerspiegelt:

Optie 1. Voorlopig verwijderen met metagegevens

Deze methode maakt gebruik van zacht verwijderen om documenten te verwijderen die zijn gekoppeld aan een specifieke blob. Zie Detectie wijzigen en verwijderen met indexeerfuncties voor Azure Storage in Azure AI Zoeken voor meer informatie.

Stappen:

1. Markeer de blob als verwijderd door een metagegevensveld in te stellen.
2. Laat de indexeerfunctie uitvoeren. Alle documenten in de index die aan die blob zijn gekoppeld, worden verwijderd.
3. Verwijder de markering voor voorlopig verwijderen en indexeer het bestand opnieuw.

Optie 2. De verwijder-API gebruiken

Voordat u een gewijzigd Markdown-bestand opnieuw indexeert, verwijdert u expliciet de bestaande documenten die aan dat bestand zijn gekoppeld met behulp van de delete-API. U kunt het volgende doen:

• Identificeer afzonderlijke verouderde documenten handmatig door duplicaten in de index te identificeren die moeten worden verwijderd. Dit kan haalbaar zijn voor kleine, goed begrepen wijzigingen, maar kan tijdrovend zijn.
• (Aanbevolen) Verwijder alle documenten die zijn gegenereerd uit hetzelfde bovenliggende bestand voordat u het opnieuw indexeert, zodat inconsistenties worden vermeden.

Stappen:

1. Identificeer de id van de documenten die aan het bestand zijn gekoppeld. Gebruik een query zoals in het volgende voorbeeld om de documentsleutel-id's (bijvoorbeeld id of chunk_id) op te halen voor alle documenten die zijn gekoppeld aan een specifiek bestand. Vervang metadata_storage_path door het juiste veld in uw index dat is toegewezen aan het bestandspad of de blob-URI. Dit veld moet een sleutel zijn.

   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. Geef een verwijderaanvraag uit voor de documenten met de geïdentificeerde sleutels.

   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. Indexeer het bijgewerkte bestand opnieuw.

Volgende stappen

• Blob-indexers configureren
• Veldtoewijzingen definiëren
• Overzicht van indexeerfuncties
• CSV-blobs indexeren met een blob-indexeerfunctie
• Tutorial: Markdown-gegevens zoeken uit Azure Blob Storage