Delen via

Markdown-blobs en -bestanden indexeren in Azure AI Search

  • Artikel

Notitie

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt aangeboden zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.

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

  • Een-op-veel-parseringsmodus, waarbij u meerdere zoekdocumenten per Markdown-bestand maakt
  • Een-op-een-parseermodus, waarbij één zoekdocument per Markdown-bestand wordt gemaakt

Tip

Ga verder met de zelfstudie: Markdown-gegevens zoeken uit Azure Blob Storage nadat u dit artikel hebt bekeken.

Vereisten

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

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

    Azure Storage voor blob-indexeerfuncties en bestandsindexeerfuncties is een standaardexemplaren (algemeen gebruik v2) die dynamische en statische 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=2024-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"
    }
  },
}

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

parsingMode submode Document zoeken Beschrijving
markdown oneToMany Meerdere per blob (standaard) Hiermee wordt de Markdown opgesplitst in meerdere zoekdocumenten, die elk een inhoudssectie (niet-koptekst) van het Markdown-bestand vertegenwoordigen. U kunt submodus weglaten, tenzij u een-op-een-parseren wilt.
markdown oneToOne Eén per blob Parseert de Markdown in één zoekdocument, met secties die zijn toegewezen aan specifieke headers in het Markdown-bestand.

Voor oneToMany submodus moet u het indexeren van één blob controleren om veel zoekdocumenten te produceren om te begrijpen hoe de blobindexeerfunctie de ondubbelzinnigheid 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.

Parameternaam Toegestane waarden Beschrijving
markdownHeaderDepth h1, , h2h3, h4, , , h5h6(default) Deze parameter bepaalt het laagste headerniveau dat wordt overwogen bij het parseren, waardoor flexibele verwerking van documentstructuur mogelijk is (bijvoorbeeld wanneer markdownHeaderDepth deze is ingesteld h1, herkent de parser alleen kopteksten op het hoogste niveau die beginnen met '#', en alle kopteksten op lager niveau worden behandeld als tekst zonder opmaak). Als dit niet is opgegeven, wordt deze standaard ingesteld op h6.

Deze instelling kan worden gewijzigd na het maken van de indexeerfunctie, maar de structuur van de resulterende zoekdocumenten kan veranderen, afhankelijk van de Markdown-inhoud.

Ondersteunde Markdown-elementen

Met Markdown-parsering wordt alleen inhoud gesplitst op basis van headers. Alle andere elementen, zoals lijsten, codeblokken, tabellen enzovoort, 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 headers 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/h2enzovoort. Zie index- en indexeerfuncties in de volgende voorbeelden voor voorbeelden in context. De subvelden zijn:

    • h1 - Een tekenreeks met de h1-headerwaarde. 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 worden uitgelijnd, kan de blob-indexeerfunctie de toewijzing afleiden zonder expliciete veldtoewijzing in de aanvraag, zodat een indexeerfunctieconfiguratie die overeenkomt met de opgegeven indexconfiguratie er als volgt uitziet:

POST https://[service name].search.windows.net/indexers?api-version=2024-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" }
  },
}

Notitie

De submode instellingen hoeven hier niet expliciet te worden ingesteld omdat oneToMany dit de standaardinstelling is.

Indexeerfunctieuitvoer voor parseren van één-op-veel

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.

Dit wordt geïllustreerd in het volgende voorbeeldscenario. 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 optionele "markdown" markdownHeaderDepth parameter in en gebruik deze om de maximale kopdiepte voor segmentering te definiëren. Als dit niet is opgegeven, wordt h6standaard ingesteld op het vastleggen van alle mogelijke headerdiepten.

De Markdown wordt geparseerd op basis van headers 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 header (h1, h2, h3enzovoort) 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 dit een lege tekenreeks.

    • ordinal_position: Een geheel getal dat de positie van de sectie in de documenthiërarchie aangeeft. Dit veld wordt gebruikt voor het ordenen 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 elk inhoudsblok.

    • sections: Een matrix 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 header_levelook , header_nameen contentordinal_position eigenschappen, waardoor een recursieve structuur wordt ingeschakeld die de Markdown-inhoud vertegenwoordigt en hiërarchie.

Hier volgt het Markdown-voorbeeld dat we gebruiken om een indexschema uit te leggen dat is ontworpen rond elke parseringsmodus.

# 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 markdown met de twee secties en één subsectie, moet de index er ongeveer uitzien als in het volgende voorbeeld:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "document_content",
    "type": "Edm.String",
  {
    "name": "sections",
    "type": "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.Int"
    },
    {
      "name": "sections",
      "type": "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.Int"
      }]
    }]
  }
}

Definitie van indexeerfunctie voor een-op-een-parsering

POST https://[service name].search.windows.net/indexers?api-version=2024-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",
    }
  }
}

Indexeerfunctieuitvoer voor een-op-een parseren

Omdat de Markdown die we willen indexeren alleen naar een diepte van h2 ('##') gaat, hebben we velden nodig sections die zijn genest op een diepte van 2 om die te vinden. 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 rangtelpositie verhoogd op basis van de locatie van de inhoud in het document.

Er moet ook worden opgemerkt dat als koptekstniveaus in de inhoud worden overgeslagen, de structuur van het resulterende document de kopteksten weerspiegelt die aanwezig zijn in de Markdown-inhoud, niet noodzakelijkerwijs geneste secties bevatten voor h1 h6 opeenvolgende. Wanneer het document bijvoorbeeld begint h2, is h2het eerste element in de matrix met secties op het hoogste niveau.

Een-op-een-velden toewijzen in een zoekindex

Als u velden met aangepaste namen uit het document wilt extraheren, kunt u veldtoewijzingen gebruiken om dit te doen. 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."
}

Notitie

In deze voorbeelden wordt aangegeven hoe u deze parseringsmodi volledig kunt gebruiken met of zonder veldtoewijzingen, maar u kunt beide in één scenario gebruiken als dat aan uw behoeften voldoet.

Volgende stappen