Freigeben über

Indizieren von Markdownblobs und -Dateien in Azure KI Search

  • Artikel

Hinweis

Dieses Feature ist zurzeit als öffentliche Preview verfügbar. Diese Vorschau wird ohne Vereinbarung zum Servicelevel bereitgestellt und nicht für Produktionsworkloads empfohlen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

In Azure AI Search unterstützen Indexer für Azure Blob Storage, Azure Files und OneLake einen markdown-Analysemodus für Markdowndateien. Markdowndateien können auf zwei Arten indiziert werden:

  • 1:n-Analysemodus, Erstellen mehrerer Suchdokumente pro Markdowndatei
  • 1:1-Analysemodus, Erstellen eines Suchdokuments pro Markdowndatei

Voraussetzungen

  • Eine unterstützte Datenquelle: Azure Blob Storage, Azure File Storage, OneLake in Microsoft Fabric.

    Stellen Sie für OneLake sicher, dass Sie alle Anforderungen des OneLake-Indexers erfüllen.

    Azure Storage für Blobindexer und Dateiindexer ist eine Standardleistungsinstanz (allgemeine v2), die Hot-, Cool- und Cold Access-Ebenen unterstützt.

Parameter des Markdown-Analysemodus

Parameter für den Analysemodus werden in einer Indexerdefinition angegeben, wenn Sie einen Indexer erstellen oder aktualisieren.

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

Der Blobindexer enthält einen submode-Parameter, um die Ausgabe der Struktur der Suchdokumente zu bestimmen. Der Markdown-Analysemodus bietet die folgenden Untermodusoptionen:

parsingMode Untermodus Suchdokument Beschreibung
markdown oneToMany Mehrere Dokumente pro Blob (Standard) Unterteilt das Markdown in mehrere Suchdokumente, die jeweils einen Inhaltsabschnitt (Nichtheader) der Markdowndatei darstellen. Sie können den Untermodus weglassen, es sei denn, Sie möchten eine 1:1-Analyse ausführen.
markdown oneToOne Ein Dokument pro Blob Parst das Markdown in ein Suchdokument, wobei Abschnitte bestimmten Kopfzeilen in der Markdowndatei zugeordnet sind.

Für den Untermodus oneToMany finden Sie unter Indizieren von Blobs zum Generieren mehrerer Suchdokumente Informationen dazu, wie mit dem Blobindexer die Eindeutigkeit des Dokumentschlüssels für mehrere Suchdokumente gehandhabt wird, die aus dem gleichen Blob generiert wurden.

In späteren Abschnitten werden die einzelnen Untermodi ausführlicher beschrieben. Wenn Sie mit Indexerclients und -konzepten nicht vertraut sind, finden Sie entsprechende Informationen unter Erstellen eines Suchindexers. Sie sollten außerdem mit den Details der grundlegenden Konfiguration von Blobindexern vertraut sein, die hier nicht wiederholt wird.

Optionale Markdown-Analyseparameter

Bei den Parametern wird zwischen Groß- und Kleinschreibung unterschieden.

Parametername Zulässige Werte Beschreibung
markdownHeaderDepth h1, h2, h3, h4, h5, h6(default) Dieser Parameter bestimmt die tiefste Kopfzeilenebene, die beim Analysieren berücksichtigt wird, sodass eine flexible Behandlung der Dokumentstruktur möglich ist (z. B. wenn markdownHeaderDepth auf h1 festgelegt ist, erkennt der Parser nur Kopfzeilen der obersten Ebene, die mit "#" beginnen, und alle Kopfzeilen der unteren Ebene werden als Nur-Text behandelt). Wenn dieser Wert nicht angegeben ist, wird standardmäßig h6 verwendet.

Diese Einstellung kann nach der ersten Erstellung des Indexers geändert werden, die Struktur der resultierenden Suchdokumente kann sich jedoch je nach Markdowninhalt ändern.

Unterstützte Markdownelemente

Die Markdown-Analyse teilt Inhalte nur basierend auf Kopfzeilen auf. Alle anderen Elemente wie Listen, Codeblöcke, Tabellen usw. werden als Nur-Text behandelt und in ein Inhaltsfeld übergeben.

Beispielhafter Markdowninhalt

Der folgende Markdowninhalt wird für die Beispiele auf dieser Seite verwendet:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Verwenden des 1:n-Analysemodus

Der 1:n-Analysemodus parst Markdowndateien in mehrere Suchdokumente, wobei jedes Dokument einem bestimmten Inhaltsabschnitt der Markdowndatei entspricht, basierend auf den Headermetadaten an diesem Punkt im Dokument. Der Markdown wird basierend auf Kopfzeilen in Suchdokumente analysiert, die den folgenden Inhalt enthalten:

  • content: Eine Zeichenfolge, die den unformatierten Markdown enthält, der an einer bestimmten Stelle gefunden wurde, basierend auf den Headermetadaten an diesem Punkt im Dokument.

  • sections: Ein Objekt, das Unterfelder für die Headermetadaten bis zur gewünschten Headerebene enthält. Wenn z. B. markdownHeaderDepth auf h3 festgelegt ist, sind Zeichenfolgenfelder h1, h2 und h3 enthalten. Diese Felder werden durch Spiegelung dieser Struktur im Index oder durch Feldzuordnungen im Format /sections/h1, sections/h2 usw. indiziert. In den folgenden Beispielen finden Sie Index- und Indexerkonfigurationen für Kontextbeispiele. Die enthaltenen Unterfelder sind:

    • h1 – Eine Zeichenfolge, die den h1-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
    • (Optional) h2 – Eine Zeichenfolge, die den h2-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
    • (Optional) h3 – Eine Zeichenfolge, die den h3-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
    • (Optional) h4 – Eine Zeichenfolge, die den h4-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
    • (Optional) h5 – Eine Zeichenfolge, die den h5-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
    • (Optional) h6 – Eine Zeichenfolge, die den h6-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.

  • ordinal_position: Ein ganzzahliger Wert, der die Position des Abschnitts innerhalb der Dokumenthierarchie angibt. Dieses Feld wird verwendet, um die Abschnitte in der ursprünglichen, im Dokument angezeigten Reihenfolge zu sortieren, beginnend mit einer Ordnungsposition von 1 und einer sequenziellen Erhöhung für jeden Header.

Indexschema für die 1:n-Analyse

Eine Beispielindexkonfiguration könnte etwa wie folgt aussehen:

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

Indexerdefinition für die 1:n-Analyse

Wenn Feldnamen und Datentypen ausgerichtet sind, kann der BLOB-Indexer die Zuordnung ohne eine explizite Feldzuordnung in der Anforderung ableiten, sodass eine Indexerkonfiguration, die der bereitgestellten Indexkonfiguration entspricht, wie folgt aussehen kann:

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

Hinweis

Der submode muss hier nicht explizit festgelegt werden, da oneToMany die Standardeinstellung ist.

Indexerausgabe für die 1:n-Analyse

Diese Markdowndatei würde aufgrund der drei Inhaltsabschnitte drei Suchdokumente nach der Indizierung ergeben. Das Suchdokument, das sich aus dem ersten Inhaltsabschnitt des bereitgestellten Markdowndokuments ergibt, enthält die folgenden Werte für content, sections, h1 und 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
  }
}

Zuordnen von 1:n-Feldern in einem Suchindex

Mit Feldzuordnungen wird in den Fällen, in denen die Feldnamen und Feldtypen nicht identisch sind, ein Quellfeld einem Zielfeld zugeordnet. Feldzuordnungen können außerdem verwendet werden, um Teile eines Markdowndokuments abzugleichen und auf Felder der obersten Ebene des Suchdokuments „hochzustufen“.

Das folgende Beispiel illustriert dieses Szenario. Weitere allgemeine Informationen zu Feldzuordnungen finden Sie unter Feldzuordnungen.

Angenommen, Sie haben einen Suchindex mit den folgenden Feldern: raw_content vom Typ Edm.String, h1_header vom Typ Edm.String und h2_header vom Typ Edm.String. Um das Markdownobjekt in der gewünschten Form zuzuordnen, verwenden Sie die folgenden Feldzuordnungen:

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

Das resultierende Suchdokument im Index würde wie folgt aussehen:

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

Verwenden des 1:1-Analysemodus

Im 1:1-Analysemodus wird das gesamte Markdown-Dokument als einzelnes Suchdokument indiziert, wobei die Hierarchie und Struktur des ursprünglichen Inhalts beibehalten wird. Dieser Modus ist am nützlichsten, wenn die zu indizierten Dateien eine gemeinsame Struktur aufweisen, die Sie im Index verwenden können, um die relevanten Felder durchsuchbar zu machen.

Legen Sie in der Indexerdefinition den parsingMode auf "markdown" fest, und verwenden Sie den optionalen markdownHeaderDepth-Parameter, um die maximale Headertiefe für Blöcke zu definieren. Wenn nicht angegeben, wird standardmäßig h6 verwendet, wobei alle möglichen Headertiefen erfasst werden.

Der Markdown wird basierend auf Kopfzeilen in Suchdokumente analysiert, die den folgenden Inhalt enthalten:

  • document_content: Enthält den vollständigen Markdowntext als einzelne Zeichenfolge. Dieses Feld dient als unformatierte Darstellung des Eingabedokuments.

  • sections: Ein Array von Objekten, das die hierarchische Darstellung der Abschnitte im Markdown-Dokument enthält. Jeder Abschnitt wird in diesem Array als Objekt dargestellt und erfasst die Struktur des Dokuments auf geschachtelte Weise, die den Headern und dem jeweiligen Inhalt entspricht. Auf die Felder kann über Feldzuordnungen zugegriffen werden, indem auf den Pfad verwiesen wird, z. B. /sections/content. Die Objekte in diesem Array haben die folgenden Eigenschaften:

    • header_level: Eine Zeichenfolge, die die Ebene des Headers angibt (h1, h2, h3 usw.) in Markdownsyntax. Dieses Feld hilft beim Verständnis der Hierarchie und Strukturierung des Inhalts.

    • header_name: Eine Zeichenfolge, die den Text des Headers enthält, wie er im Markdowndokument angezeigt wird. Dieses Feld stellt eine Beschriftung oder einen Titel für den Abschnitt bereit.

    • content: Eine Zeichenfolge mit Textinhalt, die unmittelbar auf den Header folgt, bis zum nächsten Header. Dieses Feld erfasst die detaillierten Informationen oder Beschreibungen, die dem Header zugeordnet sind. Wenn kein Inhalt direkt unter einem Header vorhanden ist, handelt es sich um eine leere Zeichenfolge.

    • ordinal_position: Ein ganzzahliger Wert, der die Position des Abschnitts innerhalb der Dokumenthierarchie angibt. Dieses Feld wird verwendet, um die Abschnitte in der ursprünglichen, im Dokument angezeigten Reihenfolge zu sortieren, beginnend mit einer Ordnungsposition von 1 und einer sequenziellen Erhöhung für jeden Inhaltsblock.

    • sections: Ein Array, das Objekte enthält, die Unterabschnitte darstellen, die unter dem aktuellen Abschnitt geschachtelt sind. Dieses Array folgt der gleichen Struktur wie das sections-Array auf oberster Ebene, was die Darstellung mehrerer Ebenen geschachtelter Inhalte ermöglicht. Jedes Unterabschnittsobjekt enthält auch header_level-, header_name-, content- und ordinal_position-Eigenschaften, wodurch eine rekursive Struktur aktiviert wird, die die Hierarchie des Markdowninhalts darstellt.

Hier sehen Sie das Beispiel-Markdown, das wir verwenden, um ein Indexschema zu erläutern, das für jeden Analysemodus konzipiert ist.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Indexschema für die 1:1-Analyse

Wenn Sie keine Feldzuordnungen verwenden, sollte die Form des Indexes die Form des Markdowninhalts widerspiegeln. Angesichts der Struktur des Beispiel-Markdowns mit zwei Abschnitten und einem einzelnen Unterabschnitt sollte der Index ähnlich wie im folgenden Beispiel aussehen:

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

Indexerdefinition für die 1:1-Analyse

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

Indexerausgabe für die 1:1-Analyse

Da der Markdown, den wir indizieren möchten, nur bis zu einer Tiefe von h2 („##”) reicht, benötigen wir sections-Felder, die mit einer Tiefe von 2 geschachtelt sind, damit dies übereinstimmt. Diese Konfiguration würde zu den folgenden Daten im Index führen:

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

Wie Sie sehen können, erhöht sich die Ordnungsposition basierend auf der Position des Inhalts innerhalb des Dokuments.

Es sollte auch beachtet werden, dass, wenn Headerebenen im Inhalt übersprungen werden, die Struktur des resultierenden Dokuments die Header widerspiegelt, die im Markdowninhalt vorhanden sind, und nicht unbedingt verschachtelte Abschnitte für h1 bis h6 nacheinander enthält. Wenn das Dokument beispielsweise mit h2 beginnt, ist das erste Element im Bereichsarray der obersten Ebene h2.

Zuordnen von 1:1-Feldern in einem Suchindex

Wenn Sie Felder mit benutzerdefinierten Namen aus dem Dokument extrahieren möchten, können Sie dazu Feldzuordnungen verwenden. Betrachten Sie die folgende Indexkonfiguration, indem Sie das gleiche Markdownbeispiel wie zuvor verwenden:

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

Das Extrahieren bestimmter Felder aus dem analysierten Markdown wird ähnlich wie die Dokumentpfade in outputFieldMappings behandelt, außer der Pfad beginnt mit /sections anstelle von /document. Beispielsweise würde /sections/0/content dem Inhalt unter dem Element an Position 0 im Abschnittsarray zuordnen.

Ein Beispiel für einen starken Anwendungsfall könnte etwa wie folgt aussehen: Alle Markdown-Dateien haben einen Dokumenttitel im ersten h1, einen Unterabschnittstitel im ersten h2 und eine Zusammenfassung im Inhalt des endgültigen Absatzes unterhalb des endgültigen h1. Sie können die folgenden Feldzuordnungen verwenden, um nur diesen Inhalt zu indizieren:

"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 würden Sie nur die relevanten Teile aus diesem Dokument extrahieren. Um diese Funktionalität am effektivsten zu verwenden, sollten Dokumente, die Sie indizieren möchten, dieselbe hierarchische Headerstruktur aufweisen.

Das resultierende Suchdokument im Index würde wie folgt aussehen:

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

Hinweis

In diesen Beispielen wird angegeben, wie Sie diese Analysemodi vollständig mit oder ohne Feldzuordnungen verwenden, aber Sie können beides in einem Szenario nutzen, wenn dies Ihren Anforderungen entspricht.

Nächste Schritte