Indexer des objets blob et des fichiers Markdown dans Recherche Azure AI

Dans Recherche Azure AI, les indexeurs pour Stockage Blob Azure, Azure Files et Microsoft OneLake prennent en charge un mode d’analyse markdown pour les fichiers Markdown. Les fichiers Markdown peuvent être indexés de deux façons :

• Mode d’analyse un-à-plusieurs, qui crée plusieurs documents de recherche par fichier Markdown.
• Mode d’analyse un-à-un, qui crée un document de recherche par fichier Markdown.

Conditions préalables

• Source de données prise en charge : Stockage Blob Azure, stockage de fichiers Azure, Microsoft OneLake.

  Pour OneLake, veillez à répondre à toutes les exigences de l’indexeur OneLake.

  stockage Azure pour les indexeurs d’objets blob et les indexeurs de fichiers (préversion) est une instance de type Usage général v2 offrant des performances standard et prenant en charge les niveaux d’accès froid et chaud.

Paramètres du mode d’analyse Markdown

Les paramètres du mode d’analyse sont spécifiés dans une définition d’indexeur lorsque vous créez ou mettez à jour un indexeur.

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

L’indexeur d’objets blob fournit un submode paramètre pour déterminer la structure de sortie des documents de recherche. Le mode d’analyse Markdown fournit les options de sous-modèle suivantes :

Pour le sous-mode oneToMany vous devriez consulter Indexer un blob pour produire plusieurs documents de recherche afin de comprendre comment l’indexeur Blob gère la désambiguïsation de la clé de document pour plusieurs documents de recherche produits à partir du même blob.

Les sections ultérieures décrivent chaque sous-modèle plus en détail. Si vous ne connaissez pas les clients et concepts de l’indexeur, consultez Créer un indexeur de recherche. Vous devez également être familiarisé avec les détails de la configuration de l’indexeur d’objets blob de base, ce qui n’est pas répété ici.

Paramètres d’analyse Markdown facultatifs

Les paramètres sont sensibles à la casse.

Ce paramètre peut être modifié une fois l’indexeur créé. Toutefois, la structure des documents de recherche résultants peut changer en fonction du contenu Markdown.

Éléments Markdown pris en charge

L’analyse Markdown fractionne uniquement le contenu en fonction des en-têtes. Tous les autres éléments, tels que les listes, les blocs de code et les tables, sont traités comme du texte brut et transmis dans un champ de contenu.

Exemple de contenu Markdown

Le contenu Markdown suivant est utilisé pour les exemples de cette page :

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Utiliser le mode d’analyse un-à-plusieurs

Le mode de parsing un-à-plusieurs analyse les fichiers Markdown en plusieurs documents de recherche, où chaque document correspond à une section de contenu spécifique du fichier Markdown en fonction des métadonnées d'en-tête à ce point du document. Markdown est analysé en fonction des en-têtes dans des documents de recherche, qui contiennent le contenu suivant :

• content: chaîne qui contient le Markdown brut trouvé dans un emplacement spécifique, en fonction des métadonnées d’en-tête à ce stade du document.

• sections: objet qui contient des sous-champs pour les métadonnées d’en-tête jusqu’au niveau d’en-tête souhaité. Par exemple, lorsqu’il markdownHeaderDepth est défini sur h3, il contient des champs de chaîne h1, h2 et h3. Ces champs sont indexés en mettant en miroir cette structure dans l’index, ou via des mappages de champs au format /sections/h1, /sections/h2et ainsi de suite. Consultez les configurations d’index et d’indexeur dans les exemples suivants pour obtenir des exemples dans le contexte. Les sous-champs contenus sont les suivants :

  • h1 - Chaîne contenant la valeur d’en-tête h1. Chaîne vide si elle n’est pas définie à ce stade dans le document.
  • (Facultatif) h2- Chaîne contenant la valeur d’en-tête h2. Chaîne vide si elle n’est pas définie à ce stade dans le document.
  • (Facultatif) h3- Chaîne contenant la valeur d’en-tête h3. Chaîne vide si elle n’est pas définie à ce stade dans le document.
  • (Facultatif) h4- Chaîne contenant la valeur d’en-tête h4. Chaîne vide si elle n’est pas définie à ce stade dans le document.
  • (Facultatif) h5- Chaîne contenant la valeur d’en-tête h5. Chaîne vide si elle n’est pas définie à ce stade dans le document.
  • (Facultatif) h6- Chaîne contenant la valeur d’en-tête h6. Chaîne vide si elle n’est pas définie à ce stade dans le document.

• ordinal_position: valeur entière indiquant la position de la section dans la hiérarchie de documents. Ce champ est utilisé pour classer les sections dans leur séquence d’origine à mesure qu’elles apparaissent dans le document, en commençant par une position ordinale de 1 et en incrémentant séquentiellement pour chaque en-tête.

Schéma d’index pour l’analyse un-à-plusieurs

Un exemple de configuration d’index peut ressembler à ceci :

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

Définition de l’indexeur pour l’analyse un-à-plusieurs

Si les noms de champs et les types de données s'alignent, l'indexeur de blob peut déduire le mappage sans qu’un mappage de champ explicite soit présent dans la requête. Par conséquent, une configuration d’indexeur correspondant à la configuration d’index fournie peut ressembler à ceci :

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

Sortie de l’indexeur pour l’analyse de type un-à-plusieurs

Ce fichier Markdown entraînerait trois documents de recherche après l’indexation, en raison des trois sections de contenu. Le document de recherche résultant de la première section de contenu du document Markdown fourni contient les valeurs suivantes pour content, , sectionsh1et 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
  }
}

Mappez des champs une-à-plusieurs dans un index de recherche

Les mappages de champs associent un champ source à un champ de destination dans les situations où les noms et types de champs ne sont pas identiques. Toutefois, les mappages de champs peuvent également être utilisés pour associer des parties d’un document Markdown et les élever dans des champs de niveau supérieur du document de recherche.

L’exemple suivant illustre ce scénario. Pour plus d’informations sur les mappages de champs en général, consultez mappages de champs.

Supposons qu’un index de recherche avec les champs suivants : raw_content de type Edm.String, h1_header de type Edm.String, et h2_header de type Edm.String. Pour mapper votre Markdown à la forme souhaitée, utilisez les mappages de champs suivants :

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

Le document de recherche obtenu dans l’index se présente comme suit :

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

Utiliser le mode d’analyse un-à-un

Dans le mode d’analyse un-à-un, l’intégralité du document Markdown est indexée en tant que document de recherche unique, conservant la hiérarchie et la structure du contenu d’origine. Ce mode est le plus utile lorsque les fichiers à indexer partagent une structure commune, afin que vous puissiez utiliser cette structure commune dans l’index pour rendre les champs pertinents pouvant faire l’objet d’une recherche.

Dans la définition de l’indexeur, définissez parsingMode et "markdown", et utilisez le paramètre facultatif markdownHeaderDepth pour définir la profondeur maximale des titres pour le fractionnement. S'il n'est pas spécifié, la valeur par défaut est h6, capturant toutes les profondeurs d'en-tête possibles.

Markdown est analysé en fonction des en-têtes dans des documents de recherche, qui contiennent le contenu suivant :

• document_content: contient le texte Markdown complet sous forme de chaîne unique. Ce champ sert de représentation brute du document d’entrée.

• sections: tableau d’objets qui contient la représentation hiérarchique des sections dans le document Markdown. Chaque section est représentée en tant qu’objet dans ce tableau et capture la structure du document de manière imbriquée correspondant aux en-têtes et à leur contenu respectif. Les champs sont accessibles via des mappages de champs en référençant le chemin, par exemple /sections/content. Les objets de ce tableau ont les propriétés suivantes :

  • header_level: chaîne qui indique le niveau de l’en-tête (h1, h2, h3et ainsi de suite) dans la syntaxe Markdown. Ce champ permet de comprendre la hiérarchie et la structure du contenu.

  • header_name: chaîne contenant le texte de l’en-tête tel qu’il apparaît dans le document Markdown. Ce champ fournit une étiquette ou un titre pour la section.

  • content: chaîne contenant du contenu texte qui suit immédiatement l’en-tête, jusqu’à l’en-tête suivant. Ce champ capture les informations détaillées ou la description associées à l’en-tête. S’il n’y a pas de contenu directement sous un en-tête, la valeur est une chaîne vide.

  • ordinal_position: valeur entière indiquant la position de la section dans la hiérarchie de documents. Ce champ est utilisé pour classer les sections dans leur séquence d’origine à mesure qu’ils apparaissent dans le document, en commençant par une position ordinale de 1 et en incrémentant séquentiellement pour chaque bloc de contenu.

  • sections: tableau qui contient des objets représentant des sous-sections imbriquées dans la section active. Ce tableau suit la même structure que le tableau de niveau sections supérieur, ce qui permet la représentation de plusieurs niveaux de contenu imbriqué. Chaque objet de sous-section inclut également les propriétés header_level, header_name, content, et ordinal_position, ce qui permet une structure récursive qui représente la hiérarchie du contenu Markdown.

Voici l’exemple Markdown que nous utilisons pour expliquer les schémas d’index conçus autour de chaque mode d’analyse.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Schéma d’index pour l’analyse un-à-un

Si vous n’utilisez pas de mappages de champs, la forme de l’index doit refléter la forme du contenu Markdown. Étant donné la structure de l’exemple Markdown avec ses deux sections et sa sous-section unique, l’index doit ressembler à l’exemple suivant :

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

Définition de l’indexeur pour l’analyse un-à-un

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

Sortie de l’indexeur pour l’analyse un-à-un

Étant donné que le Markdown que nous voulons indexer ne passe qu’à une profondeur de h2 (« ## »), nous avons besoin d'avoir des sections champs imbriqués à une profondeur de 2 pour correspondre à cela. Cette configuration entraînerait les données suivantes dans l’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": []
    }]
  }

Comme vous pouvez le voir, la position ordinale incrémente en fonction de l’emplacement du contenu dans le document.

Si les niveaux d’en-tête sont ignorés dans le contenu, la structure du document résultant reflète les en-têtes présents dans le contenu Markdown et ne contient pas nécessairement des sections imbriquées consécutives de h1 à h6. Par exemple, lorsque le document commence à h2, le premier élément du tableau de sections de niveau supérieur est h2.

Mapper des champs un-à-un dans un index de recherche

Pour extraire des champs avec des noms personnalisés du document, vous pouvez utiliser des mappages de champs. À l’aide du même exemple Markdown que précédemment, tenez compte de la configuration d’index suivante :

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

L’extraction de champs spécifiques de Markdown analysés est gérée de la même façon que les chemins de document dans outputFieldMappings, sauf que le chemin commence par /sections au lieu de /document. Ainsi, par exemple, /sections/0/content correspond au contenu sous l’élément à la position 0 dans le tableau des sections.

Un exemple de cas d’usage fort peut ressembler à ceci : tous les fichiers Markdown ont un titre de document dans le premier h1, un titre de sous-section dans le premier h2et un résumé dans le contenu du paragraphe final sous la finale h1. Vous pouvez utiliser les mappages de champs suivants pour indexer uniquement ce contenu :

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

Ici, vous n’extrayez que les éléments pertinents de ce document. Pour utiliser efficacement cette fonctionnalité, les documents que vous prévoyez d’indexer doivent partager la même structure d’en-tête hiérarchique.

Le document de recherche obtenu dans l’index se présente comme suit :

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

Gérer les documents obsolètes dans le contexte de la réindexation Markdown

Lorsque vous utilisez un mode d’analyse un-à-plusieurs, la réindexation d’un fichier Markdown modifié peut entraîner des documents obsolètes ou dupliqués si des sections sont supprimées. Ce comportement est spécifique au mode un-à-plusieurs et ne s’applique pas à l’analyse un-à-un.

Vue d’ensemble du comportement

Mode d’analyse un-à-plusieurs

En oneToMany mode, chaque section Markdown (basée sur les en-têtes) est indexée en tant que document de recherche distinct. Lorsque le fichier est réindexé :

• Aucune suppression automatique : l’indexeur remplace les documents existants avec de nouveaux documents, mais il ne supprime pas les documents qui ne correspondent plus à du contenu dans le fichier mis à jour.
• Risque de doublons : ce problème se produit spécifiquement lorsque plus de sections sont supprimées que celles insérées entre les exécutions d’indexation. Dans ce cas, les documents restants de la version précédente restent dans l’index, ce qui entraîne des entrées obsolètes qui ne reflètent plus l’état actuel du fichier source.

Mode d’analyse un-à-un

En oneToOne mode, l’intégralité du fichier Markdown est indexée en tant que document de recherche unique. Lorsque le fichier est réindexé :

• Comportement de remplacement : le document existant est entièrement remplacé par la nouvelle version.
• Aucune section obsolète : lorsque le fichier est réindexé, le document existant est remplacé par la version mise à jour et le contenu supprimé n’est plus inclus. La seule exception est si le chemin d’accès du fichier ou l’URI d’objet blob change, ce qui peut entraîner la création d’un nouveau document en même temps que l’ancien.

Options de solution de contournement

Pour vous assurer que l’index reflète l’état actuel de vos fichiers Markdown, envisagez l’une des approches suivantes :

Option numéro 1. Suppression réversible avec des métadonnées

Cette méthode utilise une suppression temporaire pour supprimer des documents associés à un blob spécifique. Pour plus d’informations, consultez Détection des changements et suppressions à l’aide d’indexeurs pour stockage Azure dans Recherche Azure AI.

Étapes:

1. Marquez l’objet blob comme supprimé en définissant un champ de métadonnées.
2. Laissez l’indexeur s’exécuter. Il supprime tous les documents de l’index associé à cet objet blob.
3. Supprimez le marqueur de suppression réversible et réindexez le fichier.

Option 2. Utiliser l’API delete

Avant de réindexer un fichier Markdown modifié, supprimez explicitement les documents existants associés à ce fichier à l’aide de l’API delete. Vous pouvez :

• Identifiez manuellement les documents obsolètes individuels en identifiant les doublons dans l’index à supprimer. Cela peut être possible pour les changements de petite taille et bien compris, mais peut prendre du temps.
• (Recommandé) Supprimez tous les documents générés à partir du même fichier parent avant la réindexation, ce qui garantit que les incohérences sont évitées.

Étapes:

1. Identifiez l’ID des documents associés au fichier. Utilisez une requête comme l’exemple suivant pour récupérer les ID de clé de document (par exemple, id ou chunk_id) pour tous les documents liés à un fichier spécifique. Remplacez metadata_storage_path par le champ approprié dans votre index qui correspond au chemin d’accès du fichier ou à l’URI d’objet blob. Ce champ doit être une clé.

   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. Émettez une demande de suppression pour les documents avec les clés identifiées.

   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. Réindexez le fichier mis à jour.

Étapes suivantes

• Configurer des indexeurs de blobs
• Définir des mappages de champs
• Vue d’ensemble des indexeurs
• Comment indexer des blobs CSV avec un indexeur de blobs
• Tutorial : Rechercher des données Markdown à partir de Stockage Blob Azure