Index Markdown-blobs och filer i Azure AI-sökning

I Azure AI-sökning stöder indexerare för Azure Blob Storage, Azure Files och Microsoft OneLake ett markdown parsningsläge för Markdown-filer. Markdown-filer kan indexeras på två sätt:

• En-till-många-parsningsläge, vilket skapar flera sökdokument per Markdown-fil.
• En-till-en-parsningsläge, vilket skapar ett sökdokument per Markdown-fil.

Förutsättningar

• En datakälla som stöds: Azure Blob Storage, Azure File Storage Microsoft OneLake.

  För OneLake kontrollerar du att du uppfyller alla krav för OneLake-indexeraren.

  Azure Storage för blobindexerare och filindexerare (förhandsversion) är en standardprestandainstans (generell användning v2) som stöder frekvent och lågfrekvent åtkomstnivå.

Parametrar för Markdown-parsningsläge

Parsningslägesparametrar anges i en indexeraredefinition när du skapar eller uppdaterar en indexerare.

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

Blobindexeraren innehåller en submode parameter för att fastställa utdatastrukturen för sökdokumenten. Markdown-parsningsläge innehåller följande alternativ för undermodes:

För oneToMany undermod bör du granska Indexering av en blob för att skapa många sökdokument för att förstå hur indexeraren hanterar dokumentnyckels tvetydighet för flera sökdokument som skapats från samma blob.

I senare avsnitt beskrivs varje undersätt mer detaljerat. Om du inte känner till indexerarklienter och begrepp kan du läsa Skapa en sökindexerare. Du bör också känna till informationen om grundläggande blobindexeringskonfiguration, som inte upprepas här.

Valfria Markdown-parsningsparametrar

Parametrar är skiftlägeskänsliga.

Den här inställningen kan ändras när indexeraren har skapats. Strukturen för de resulterande sökdokumenten kan dock ändras beroende på Markdown-innehållet.

Markdown-element som stöds

Markdown-parsning delar bara upp innehåll baserat på rubriker. Alla andra element, till exempel listor, kodblock och tabeller, behandlas som oformaterad text och skickas till ett innehållsfält.

Exempel på Markdown-innehåll

Följande Markdown-innehåll används för exemplen på den här sidan:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Använda en-till-många-parsningsläge

I en-till-många-parsningsläget parsas Markdown-filer i flera sökdokument, där varje dokument motsvarar ett specifikt innehållsavsnitt i Markdown-filen baserat på rubrikmetadata vid den tidpunkten i dokumentet. Markdown parsas baserat på rubriker i sökdokument, som innehåller följande innehåll:

• content: En sträng som innehåller den råa Markdown som finns på en specifik plats, baserat på huvudmetadata vid den tidpunkten i dokumentet.

• sections: Ett objekt som innehåller underfält för rubrikmetadata upp till önskad rubriknivå. När markdownHeaderDepth är inställt på h3, innehåller den strängfält som h1, h2 och h3. Dessa fält indexeras genom att spegla den här strukturen i indexet eller genom fältmappningar i formatet /sections/h1, /sections/h2och så vidare. Se index- och indexeringskonfigurationerna i följande exempel för sammanhangsexempel. De underfält som ingår är:

  • h1 – En sträng som innehåller h1-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
  • (Valfritt) h2– En sträng som innehåller h2-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
  • (Valfritt) h3– En sträng som innehåller h3-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
  • (Valfritt) h4– En sträng som innehåller värdet för h4-huvudet. Tom sträng om den inte har angetts just nu i dokumentet.
  • (Valfritt) h5– En sträng som innehåller h5-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
  • (Valfritt) h6– En sträng som innehåller h6-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.

• ordinal_position: Ett heltalsvärde som anger positionen för avsnittet i dokumenthierarkin. Det här fältet används för att sortera avsnitten i den ursprungliga ordningen som de visas i dokumentet, med början på en ordinalposition på 1 och ökas successivt för varje rubrik.

Indexschema för en-till-många-parsning

Ett exempel på en indexkonfiguration kan se ut ungefär så här:

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

Indexerarens definition för en-till-många-parsning

Om fältnamn och datatyper justeras kan blobindexeraren härleda mappningen utan en explicit fältmappning som finns i begäran, så en indexerarkonfiguration som motsvarar den angivna indexkonfigurationen kan se ut så här:

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

Indexerarens utdata för en-till-många-parsning

Den här Markdown-filen skulle resultera i tre sökdokument efter indexering på grund av de tre innehållsavsnitten. Sökdokumentet från det första innehållsavsnittet i det angivna Markdown-dokumentet innehåller följande värden för content, sections, h1och 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
  }
}

Mappa ett-till-många-fält i ett sökindex

Fältmappningar associerar ett källfält med ett målfält i situationer där fältnamnen och typerna inte är identiska. Men fältmappningar kan också användas för att matcha delar av ett Markdown-dokument och "lyfta" dem till fält på den översta nivån i sökdokumentet.

I följande exempel visas det här scenariot. Mer information om fältmappningar i allmänhet finns i fältmappningar.

Anta ett sökindex med följande fält: raw_content av typen Edm.String, h1_header av typen Edm.Stringoch h2_header av typen Edm.String. Om du vill mappa Markdown till önskad form använder du följande fältmappningar:

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

Det resulterande sökdokumentet i indexet skulle se ut så här:

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

Använda en-till-en-parsningsläge

I en-till-en-parsningsläget indexeras hela Markdown-dokumentet som ett enda sökdokument, vilket bevarar hierarkin och strukturen för det ursprungliga innehållet. Det här läget är mest användbart när filerna som ska indexeras delar en gemensam struktur, så att du kan använda den här gemensamma strukturen i indexet för att göra relevanta fält sökbara.

I indexerarens definition anger du parsingMode till "markdown" och använder den valfria markdownHeaderDepth parametern för att definiera det maximala rubrikdjupet för segmentering. Om inget anges, används h6 som standard, vilket fångar alla möjliga sidhuvuddjup.

Markdown parsas baserat på rubriker i sökdokument, som innehåller följande innehåll:

• document_content: Innehåller den fullständiga Markdown-texten som en enda sträng. Det här fältet fungerar som en rå representation av indatadokumentet.

• sections: En matris med objekt som innehåller den hierarkiska representationen av avsnitten i Markdown-dokumentet. Varje avsnitt representeras som ett objekt i den här matrisen och avbildar dokumentets struktur på ett kapslat sätt som motsvarar rubrikerna och deras respektive innehåll. Fälten är tillgängliga via fältmappningar genom att referera till sökvägen, till exempel /sections/content. Objekten i den här matrisen har följande egenskaper:

  • header_level: En sträng som anger nivån för rubriken (h1, , h2h3och så vidare) i Markdown-syntaxen. Det här fältet hjälper dig att förstå hierarkin och strukturering av innehållet.

  • header_name: En sträng som innehåller texten i rubriken som den visas i Markdown-dokumentet. Det här fältet innehåller en etikett eller rubrik för avsnittet.

  • content: En sträng som innehåller textinnehåll som omedelbart följer rubriken, upp till nästa rubrik. Det här fältet innehåller detaljerad information eller beskrivning som är associerad med rubriken. Om det inte finns något innehåll direkt under en rubrik är värdet en tom sträng.

  • ordinal_position: Ett heltalsvärde som anger positionen för avsnittet i dokumenthierarkin. Det här fältet används för att ordna avsnitten i den ursprungliga sekvensen som de visas i dokumentet, med början med en ordningsposition på 1 och öka sekventiellt för varje innehållsblock.

  • sections: En matris som innehåller objekt som representerar underavsnitt kapslade under det aktuella avsnittet. Den här matrisen följer samma struktur som matrisen på den översta nivån sections , vilket möjliggör representation av flera nivåer av kapslat innehåll. Varje underavsnittsobjekt innehåller egenskaperna header_level, header_name, content, och ordinal_position, vilket möjliggör en rekursiv struktur som representerar hierarkin i Markdown-innehållet.

Här är markdown-exemplet som vi använder för att förklara indexscheman som utformats runt varje parsningsläge.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Indexschema för en-till-en-parsning

Om du inte använder fältmappningar bör indexets form återspegla markdown-innehållets form. Med tanke på strukturen för Markdown-exemplet med dess två avsnitt och enstaka underavsnitt bör indexet se ut ungefär som i följande exempel:

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

Indexerarens definition för en-till-en-parsning

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

Indexerarens utdata för en-till-en-parsning

Eftersom Markdown som vi vill indexa bara går till ett djup av h2 ("##"), behöver sections vi fält kapslade till ett djup av 2 för att matcha det. Den här konfigurationen skulle resultera i följande data i indexet:

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

Som du kan se, ökar den ordnade positionen beroende på innehållets placering i dokumentet.

Om rubriknivåerna hoppas över i innehållet, återspeglar strukturen i det resulterande dokumentet rubrikerna som finns i Markdown-innehållet och innehåller nödvändigtvis inte efterföljande, konsekutiva kapslade avsnitt från h1 till och med h6. När dokumentet till exempel börjar på h2är h2det första elementet i matrisen för de översta avsnitten .

Mappa ett-till-ett-fält i ett sökindex

Om du vill extrahera fält med anpassade namn från dokumentet kan du använda fältmappningar. Med samma Markdown-exempel som tidigare bör du överväga följande indexkonfiguration:

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

Att extrahera specifika fält från den tolkade Markdown hanteras på liknande sätt som i dokumentsökvägarna i outputFieldMappings, förutom att sökvägen börjar med /sections i stället för /document. Så skulle till exempel /sections/0/content mappa till innehållet under objektet på plats 0 i avsnittsmatrisen.

Ett exempel på ett starkt användningsfall kan se ut ungefär så här: alla Markdown-filer har en dokumentrubrik i den första h1, en underavsnittsrubrik i den första h2och en sammanfattning i innehållet i det sista stycket under den sista h1. Du kan använda följande fältmappningar för att endast indexera det innehållet.

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

Här extraherar du bara relevanta delar från dokumentet. Om du vill använda den här funktionen mest effektivt bör dokument som du planerar att indexeras dela samma hierarkiska rubrikstruktur.

Det resulterande sökdokumentet i indexet skulle se ut så här:

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

Hantera inaktuella dokument från Markdown-omindexering

När du använder en-till-många-parsningsläge kan omindexering av en ändrad Markdown-fil resultera i inaktuella eller duplicerade dokument om avsnitt tas bort. Det här beteendet är specifikt för ett-till-många-läge och gäller inte för en-till-en-parsning.

Beteendeöversikt

En-till-många-parsningsläge

I oneToMany läget indexeras varje Markdown-avsnitt (baserat på rubriker) som ett separat sökdokument. När filen indexeras på nytt:

• Ingen automatisk borttagning: Indexeraren skriver över befintliga dokument med nya, men den tar inte bort dokument som inte längre motsvarar något innehåll i den uppdaterade filen.
• Potential för dubbletter: Det här problemet uppstår bara när fler avsnitt tas bort än vad som infogas mellan indexeringar. I sådana fall finns överblivna dokument från den tidigare versionen kvar i indexet, vilket leder till inaktuella poster som inte längre återspeglar källfilens aktuella tillstånd.

En-till-en-parsningsläge

I oneToOne läget indexeras hela Markdown-filen som ett enda sökdokument. När filen indexeras på nytt:

• Överskrivningsbeteende: Det befintliga dokumentet ersätts helt med den nya versionen.
• Inga inaktuella avsnitt: När filen indexeras på nytt ersätts det befintliga dokumentet med den uppdaterade versionen och borttaget innehåll ingår inte längre. Det enda undantaget är om filsökvägen eller blob-URI:n ändras, vilket kan leda till att ett nytt dokument skapas tillsammans med det gamla.

Lösningsalternativ

För att säkerställa att indexet återspeglar det aktuella tillståndet för dina Markdown-filer bör du överväga någon av följande metoder:

Alternativ 1. Mjuk borttagning med metadata

Den här metoden använder en mjuk borttagning för att ta bort dokument som är associerade med en specifik blob. Mer information finns i Ändera och ta bort identifiering med hjälp av indexerare för Azure Storage i Azure AI-sökning.

Steg:

1. Markera bloben som borttagen genom att ange ett metadatafält.
2. Låt indexeraren köras. Den tar bort alla dokument i indexet som är associerade med den bloben.
3. Ta bort markören för mjuk borttagning och indexering av filen igen.

Alternativ 2. Använda borttagnings-API:et

Innan du indexerar om en ändrad Markdown-fil tar du uttryckligen bort de befintliga dokument som är associerade med filen med hjälp av borttagnings-API:et. Du kan antingen:

• Identifiera enskilda inaktuella dokument manuellt genom att identifiera dubbletter i indexet som ska tas bort. Detta kan vara möjligt för små, välförstådda ändringar men kan vara tidskrävande.
• (Rekommenderas) Ta bort alla dokument som genereras från samma överordnade fil innan du indexerar igen, vilket säkerställer att inkonsekvenser undviks.

Steg:

1. Identifiera ID:t för de dokument som är associerade med filen. Använd en fråga som i följande exempel för att hämta dokumentnyckel-ID:t (till exempel id eller chunk_id) för alla dokument som är knutna till en specifik fil. Ersätt metadata_storage_path med lämpligt fält i ditt index som mappar till filsökvägen eller blob-URI:n. Det här fältet måste vara en nyckel.

   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. Utfärda en borttagningsbegäran för dokumenten med de identifierade nycklarna.

   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. Indexera den uppdaterade filen på nytt.

Nästa steg

• Konfigurera blobindexerare
• Definiera fältmappningar
• Översikt över indexerare
• Så här indexar du CSV-blobar med en blobindexerare
• Tutorial: Sök efter Markdown-data från Azure Blob Storage