Aller au contenu principal
Version : Stable (v4.x)

Améliorer la qualité des réponses avec l'indexation Markdown

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Pour fournir des réponses plus précises et riches en contexte à grande échelle, Ask AI bénéficie d'un contenu proprement structuré. L'une des méthodes les plus efficaces pour y parvenir est d'utiliser un assistant d'indexation basé sur Markdown dans votre configuration du Crawler Algolia. Cette configuration garantit qu'Ask AI peut accéder à des enregistrements bien formés et centrés sur le contenu, ce qui est particulièrement important pour les sites de documentation volumineux où les métadonnées, les éléments de navigation ou les artefacts de mise en page pourraient autrement diluer la qualité des réponses génératives.

info

La configuration de l'indexation Markdown peut être automatisée via l'interface du Crawler pour la plupart des cas d'usage. Pour des personnalisations avancées ou pour comprendre la configuration sous-jacente, des options de configuration manuelle sont également disponibles.

Remarque : Pour plus d'exemples d'intégration (Docusaurus, VitePress, Astro/Starlight et configurations génériques), consultez la section en bas de cette page.

Vue d'ensemble​

Pour maximiser la qualité des réponses d'Ask AI, configurez votre Crawler pour créer un index dédié au contenu Markdown. Cette approche permet à Ask AI de travailler avec des enregistrements structurés et découpés provenant de votre documentation, de contenu d'assistance ou de tout matériel basé sur Markdown, ce qui aboutit à des réponses nettement plus pertinentes et précises.

Vous pouvez configurer l'indexation Markdown de deux manières :

  1. Configuration automatisée (recommandée) : Utilisez l'interface du Crawler pour créer et configurer automatiquement votre index Markdown

  2. Configuration manuelle : Configurez manuellement votre Crawler pour des besoins de personnalisation avancée

Configuration automatisée de l'indexation Markdown (recommandée)​

La manière la plus simple de configurer l'indexation Markdown est via l'interface du Crawler, qui crée et configure automatiquement un index Markdown optimisé pour Ask AI.

Étape 1 : Accéder à l'indexation Markdown dans la configuration du Crawler​

  1. Accédez à votre tableau de bord du Crawler

  2. Rendez-vous dans l'onglet Configuration → Markdown pour LLMs

  3. Vous verrez la section d'indexation Markdown où vous pouvez créer un index dédié

Configuration du Crawler - Markdown pour LLMs

Étape 2 : Ajouter un nouvel index Markdown​

  1. Cliquez sur "+ Ajouter un index" pour créer un nouvel index Markdown

  2. Remplissez les champs requis :

    • Nom de l'index : Saisissez un nom descriptif (ex. my-docs-markdown)
    • Balise de contenu : Spécifiez le sélecteur de contenu HTML (typiquement main)
    • Modèle : Choisissez le modèle correspondant à votre framework de documentation :
      • Docusaurus - Pour les sites Docusaurus
      • VitePress - Pour les sites VitePress
      • Astro/Starlight - Pour les sites Astro/Starlight
      • Non-DocSearch (Générique) - Pour les sites personnalisés ou autres frameworks

Boîte de dialogue Ajouter un index Markdown

  1. Cliquez sur "Ajouter l'index" pour le créer

Le Crawler configurera automatiquement les paramètres optimaux pour votre modèle choisi, notamment :

  • L'extraction et le découpage appropriés des enregistrements

  • L'extraction des métadonnées spécifiques au framework (langue, version, tags)

  • Paramètres d'index optimisés pour Ask AI

Étape 3 : Exécuter le Crawler​

Une fois votre index Markdown configuré :

  1. Cliquez sur "Démarrer l'exploration" pour commencer l'indexation de votre contenu

  2. Surveillez la progression dans le tableau de bord

  3. Votre nouvel index Markdown sera rempli d'enregistrements propres et structurés optimisés pour Ask AI

État du Crawler

Étape 4 : Intégrer avec Ask AI​

Une fois l'exploration terminée, configurez DocSearch pour utiliser votre nouvel index Markdown pour les réponses d'Ask AI. Consultez la section d'intégration ci-dessous pour des instructions détaillées de configuration.

Configuration manuelle (avancée)​

Pour les utilisateurs nécessitant une personnalisation avancée ou souhaitant comprendre la configuration sous-jacente, vous pouvez configurer manuellement l'indexation Markdown en modifiant directement votre configuration de Crawler.

Étape 1 : Mettre à jour votre configuration existante du Crawler DocSearch​

  • Dans votre configuration de Crawler, ajoutez les éléments suivants à votre tableau actions: [ ... ] :
// actions: [ ...,
{
  indexName: "my-markdown-index",
  pathsToMatch: ["https://example.com/docs/**"],
  recordExtractor: ({ $, url, helpers }) => {
    // Target only the main content, excluding navigation
    const text = helpers.markdown(
      "main > *:not(nav):not(header):not(.breadcrumb)",
    );

    if (text === "") return [];

    const language = $("html").attr("lang") || "en";

    const title = $("head > title").text();

    // Get the main heading for better searchability
    const h1 = $("main h1").first().text();

    return helpers.splitTextIntoRecords({
      text,
      baseRecord: {
        url,
        objectID: url,
        title: title || h1,
        heading: h1, // Add main heading as separate field
        lang: language,
      },
      maxRecordBytes: 100000, // Higher = fewer, larger records. Lower = more, smaller records.
      // Note: Increasing this value may increase the token count for LLMs, which can affect context size and cost.
      orderingAttributeName: "part",
    });
  },
},
// ...],
  • Puis ajoutez les éléments suivants à votre objet initialIndexSettings: { ... } :
// initialIndexSettings: { ...,
"my-markdown-index": {
  attributesForFaceting: ["lang"],
  ignorePlurals: true,
  minProximity: 1,
  removeStopWords: false,
  searchableAttributes: ["title", "heading", "unordered(text)"],
  removeWordsIfNoResults: "lastWords",
  attributesToHighlight: ["title", "text"],
  typoTolerance: false,
  advancedSyntax: false,
},
// ...},

Étape 2 : Exécuter le crawler DocSearch pour créer un nouvel index optimisé pour Ask AI​

Après avoir mis à jour votre configuration de Crawler :

  1. Publiez votre configuration dans le tableau de bord du Crawler Algolia pour l'enregistrer et l'activer.

  2. Exécutez le Crawler pour indexer votre contenu Markdown et créer le nouvel index.

Le Crawler traitera votre contenu à l'aide de l'assistant d'extraction Markdown et peuplera votre nouvel index avec des enregistrements propres et structurés optimisés pour Ask AI.

Conseil : Surveillez la progression du crawl dans votre tableau de bord pour vous assurer que toutes les pages sont traitées correctement. Vous pouvez consulter les enregistrements indexés dans votre index Algolia pour vérifier la structure et le contenu.

Intégrer votre nouvel index avec Ask AI​

Une fois que votre Crawler a créé votre index optimisé, vous pouvez l'intégrer à Ask AI de deux manières : en utilisant DocSearch (recommandé pour la plupart des utilisateurs) ou en créant une intégration personnalisée à l'aide de l'API Ask AI.

Using DocSearch​

Configure DocSearch to use both your main keyword index and your markdown index for Ask AI:

docsearch({
  indexName: 'YOUR_INDEX_NAME', // Main DocSearch keyword index
  apiKey: 'YOUR_SEARCH_API_KEY',
  appId: 'YOUR_APP_ID',
  askAi: {
    indexName: 'YOUR_INDEX_NAME-markdown', // Markdown index for Ask AI
    apiKey: 'YOUR_SEARCH_API_KEY', // (or a different key if needed)
    appId: 'YOUR_APP_ID',
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en'], // Optional: filter to specific language/version
    },
  },
});
  • indexName: Your main DocSearch index for keyword search.
  • askAi.indexName: The markdown index you created for Ask AI context.
  • assistantId: The ID of your configured Ask AI assistant.
  • searchParameters.facetFilters: Optional filters to limit Ask AI context (useful for multi-language sites).

Conseil : Maintenez les deux index à jour au fur et à mesure que votre documentation évolue pour garantir la meilleure qualité de recherche et de réponses de l'IA.

Bonnes pratiques et conseils​

  • Utilisez des titres clairs et cohérents dans vos fichiers Markdown pour une meilleure découvrabilité.

  • Testez votre index avec Ask AI pour vous assurer que des réponses pertinentes sont renvoyées.

  • Ajustez maxRecordBytes si vous remarquez que les réponses sont trop larges ou trop fragmentées.

    • Remarque : Augmenter maxRecordBytes peut augmenter le nombre de tokens pour les LLMs, ce qui peut affecter la taille de la fenêtre de contexte et le coût de chaque réponse d'Ask AI.

  • Maintenez votre Markdown bien structuré (utilisez des titres, listes, etc.) pour un découpage optimal.

  • Ajoutez des attributs comme lang, version ou tags à vos enregistrements et attributesForFaceting si vous souhaitez filtrer ou utiliser des facettes dans votre interface de recherche ou Ask AI.

FAQ​

Q : Pourquoi utiliser un index Markdown séparé ? R : Cela permet à Ask AI d'accéder au contenu dans un format optimisé pour les LLMs, améliorant ainsi la qualité des réponses.

Q : Puis-je utiliser cette solution avec d'autres types de contenu ? R : Oui, mais le Markdown est particulièrement adapté au découpage et à l'extraction de contexte.

Q : Que faire si j'ai des fichiers Markdown très volumineux ? R : Diminuez la valeur de maxRecordBytes pour diviser le contenu en enregistrements plus petits et plus ciblés.

Pour plus de détails, consultez la documentation d'Ask AI ou contactez le support si vous avez besoin d'aide pour configurer votre Crawler.

Exemples de configuration du Crawler par intégration​

Vous trouverez ci-dessous des exemples de configuration pour mettre en place votre index Markdown avec différentes plateformes de documentation. Chacun montre comment extraire des facettes (comme la langue, la version, les tags) et configurer le Crawler pour votre intégration spécifique :

Generic Example:

// In your Crawler config:

// actions: [ ...,
{
  indexName: "my-markdown-index",
  pathsToMatch: ["https://example.com/**"],
  recordExtractor: ({ $, url, helpers }) => {
    // Target only the main content, excluding navigation
    const text = helpers.markdown(
      "main > *:not(nav):not(header):not(.breadcrumb)",
    );

    if (text === "") return [];

    const language = $("html").attr("lang") || "en";

    const title = $("head > title").text();

    // Get the main heading for better searchability
    const h1 = $("main h1").first().text();

    return helpers.splitTextIntoRecords({
      text,
      baseRecord: {
        url,
        objectID: url,
        title: title || h1,
        heading: h1, // Add main heading as separate field
        lang: language,
      },
      maxRecordBytes: 100000, // Higher = fewer, larger records. Lower = more, smaller records.
      // Note: Increasing this value may increase the token count for LLMs, which can affect context size and cost.
      orderingAttributeName: "part",
    });
  },
},
// ...],

// initialIndexSettings: { ...,
"my-markdown-index": {
  attributesForFaceting: ["lang"], // Recommended if you add more attributes outside of objectID
  ignorePlurals: true,
  minProximity: 1,
  removeStopWords: false,
  searchableAttributes: ["title", "heading", "unordered(text)"],
  removeWordsIfNoResults: "lastWords",
  attributesToHighlight: ["title", "text"],
  typoTolerance: false,
  advancedSyntax: false,
},
// ...},

Chaque exemple montre comment extraire des facettes courantes et configurer votre index Markdown pour Ask AI. Ajustez les sélecteurs et les noms des balises meta selon les besoins de votre site.