Saltar al contenido principal
Versión: Estable (v4.x)

Mejorar la calidad de respuestas con indexación Markdown

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Para ofrecer respuestas más precisas y con mayor contexto a escala, Ask AI se beneficia de contenido estructurado y limpio. Una de las formas más efectivas de lograrlo es usando un asistente de indexación basado en Markdown en tu configuración del Crawler de Algolia. Esta configuración garantiza que Ask AI acceda a registros bien formados y centrados en el contenido, algo especialmente importante en sitios de documentación grandes donde metadatos, elementos de navegación o artefactos de diseño podrían diluir la calidad de las respuestas generativas.

información

La configuración de indexación Markdown puede automatizarse mediante la interfaz de Crawler para la mayoría de casos. Para personalizaciones avanzadas o comprender la configuración subyacente, también existen opciones de configuración manual.

Nota: Para más ejemplos de integración (Docusaurus, VitePress, Astro/Starlight y configuraciones genéricas), consulta la sección al final de esta página.

Introducción​

Para maximizar la calidad de las respuestas de Ask AI, configura tu Crawler para crear un índice dedicado a contenido Markdown. Este enfoque permite a Ask AI trabajar con registros estructurados y fragmentados obtenidos de tu documentación, soporte o cualquier material basado en Markdown, lo que resulta en respuestas significativamente más relevantes y precisas.

Puedes configurar la indexación Markdown de dos formas:

  1. Configuración automatizada (recomendada): Usa la interfaz de Crawler para crear y configurar automáticamente tu índice Markdown

  2. Configuración manual: Configura manualmente tu Crawler para necesidades de personalización avanzada

Configuración automatizada de indexación Markdown (recomendada)​

La forma más sencilla de configurar la indexación Markdown es mediante la interfaz del Crawler, que crea y configura automáticamente un índice Markdown optimizado para Ask AI.

Paso 1: Acceder a la indexación Markdown en la configuración de Crawler​

  1. Navega al panel de control de tu Crawler

  2. Ve a Configuración → pestaña Markdown para LLMs

  3. Verás la sección de Indexación Markdown donde puedes crear un índice dedicado

Configuración de Crawler - Markdown para LLMs

Paso 2: Agregar un nuevo índice Markdown​

  1. Haz clic en "+ Agregar índice" para crear un nuevo índice Markdown

  2. Completa los campos requeridos:

    • Nombre del índice: Ingresa un nombre descriptivo (ej. my-docs-markdown)
    • Etiqueta de contenido: Especifica el selector de contenido HTML (típicamente main)
    • Plantilla: Elige la plantilla que coincida con tu framework de documentación:
      • Docusaurus - Para sitios Docusaurus
      • VitePress - Para sitios VitePress
      • Astro/Starlight - Para sitios Astro/Starlight
      • No-DocSearch (Genérico) - Para sitios personalizados u otros frameworks

Diálogo para agregar índice Markdown

  1. Haz clic en "Agregar índice" para crearlo

El Crawler configurará automáticamente los ajustes óptimos para tu plantilla seleccionada, incluyendo:

  • Extracción y fragmentación adecuada de registros

  • Extracción de metadatos específicos del framework (idioma, versión, etiquetas)

  • Ajustes de índice optimizados para Ask AI

Paso 3: Ejecutar el Crawler​

Una vez configurado tu índice Markdown:

  1. Haz clic en "Iniciar rastreo" para comenzar a indexar tu contenido

  2. Monitorea el progreso del rastreo en el panel

  3. Tu nuevo índice Markdown se poblará con registros limpios y estructurados optimizados para Ask AI

Estado del Crawler

Paso 4: Integrar con Ask AI​

Tras completar el rastreo, configura DocSearch para usar tu nuevo índice Markdown en las respuestas de Ask AI. Consulta la sección de Integración más abajo para instrucciones detalladas.

Configuración manual (avanzada)​

Para usuarios que necesitan personalización avanzada o quieren entender la configuración subyacente, puedes configurar manualmente la indexación de markdown modificando directamente la configuración de tu Crawler.

Paso 1: Actualiza tu configuración existente del Crawler de DocSearch​

  • En tu configuración del Crawler, añade lo siguiente a tu array 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",
    });
  },
},
// ...],
  • Luego, añade lo siguiente a tu objeto 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,
},
// ...},

Paso 2: Ejecuta el crawler de DocSearch para crear un nuevo índice optimizado para Ask AI​

Tras actualizar la configuración de tu Crawler:

  1. Publica tu configuración en el panel de control de Algolia Crawler para guardarla y activarla.

  2. Ejecuta el Crawler para indexar tu contenido de markdown y crear el nuevo índice.

El Crawler procesará tu contenido usando el asistente de extracción Markdown y poblará tu nuevo índice con registros limpios y estructurados optimizados para Ask AI.

Consejo: Supervisa el progreso del rastreo en tu panel para asegurarte de que todas las páginas se procesan correctamente. Puedes ver los registros indexados en tu índice de Algolia para verificar la estructura y el contenido.

Integra tu nuevo índice con Ask AI​

Una vez que tu Crawler haya creado tu índice optimizado, puedes integrarlo con Ask AI de dos formas: usando DocSearch (recomendado para la mayoría de usuarios) o creando una integración personalizada con la API de 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).

Consejo: Mantén ambos índices actualizados a medida que evoluciona tu documentación para garantizar la mejor calidad en búsquedas y respuestas de IA.

Mejores prácticas y consejos​

  • Usa títulos claros y consistentes en tus archivos markdown para mejorar la buscabilidad.

  • Prueba tu índice con Ask AI para garantizar que devuelve respuestas relevantes.

  • Ajusta maxRecordBytes si notas que las respuestas son demasiado amplias o fragmentadas.

    • Nota: Aumentar maxRecordBytes puede incrementar el recuento de tokens para LLMs, lo que podría afectar el tamaño de la ventana de contexto y el costo de cada respuesta de Ask AI.

  • Mantén tu markdown bien estructurado (usa encabezados, listas, etc.) para una fragmentación óptima.

  • Añade atributos como lang, version o tags a tus registros y attributesForFaceting si deseas filtrar o usar facetas en tu interfaz de búsqueda o Ask AI.

Preguntas frecuentes​

P: ¿Por qué usar un índice Markdown separado?
R: Permite a Ask AI acceder a contenido en un formato optimizado para LLMs, mejorando la calidad de las respuestas.

P: ¿Puedo usarlo con otros tipos de contenido?
R: Sí, pero markdown es especialmente adecuado para fragmentación y extracción de contexto.

P: ¿Qué pasa con archivos markdown muy grandes?
R: Reduce el valor de maxRecordBytes para dividir el contenido en registros más pequeños y enfocados.

Para más detalles, consulta la documentación de Ask AI o contacta a soporte si necesitas ayuda configurando tu Crawler.

Ejemplos de configuración del Crawler por integración​

A continuación se muestran configuraciones de ejemplo para configurar tu índice de markdown con diferentes plataformas de documentación. Cada una muestra cómo extraer facetas (como idioma, versión, etiquetas) y configurar el Crawler para tu integración específica:

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,
},
// ...},

Cada ejemplo muestra cómo extraer facetas comunes y configurar tu índice Markdown para Ask AI. Ajusta los selectores y nombres de metaetiquetas según necesites para tu sitio.