版本：稳定版 (v4.x)

通过 Markdown 索引提升回答质量

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

为大规模提供更精准、上下文丰富的回答，Ask AI 受益于结构清晰的内容。在 Algolia Crawler 配置中使用基于 Markdown 的索引助手是实现此目标的最有效方法之一。此设置确保 Ask AI 能访问格式规范、内容聚焦的记录——对于大型文档站点尤为重要，因为元数据、导航元素或布局干扰项可能降低生成式回答的质量。

信息

大多数情况下可通过 Crawler 界面自动设置 Markdown 索引。如需高级定制或了解底层配置，也可选择手动设置。

**注意：**更多集成示例（Docusaurus、VitePress、Astro/Starlight 及通用配置）请见页面底部章节。

概述

为最大化提升 Ask AI 回答质量，请配置爬虫为 Markdown 内容创建专用索引。这种方法使 Ask AI 能处理来自文档、支持内容或任何 Markdown 素材的结构化分块记录，从而生成更相关、更精准的回答。

可通过两种方式设置 Markdown 索引：

自动设置（推荐）：使用 Crawler 界面自动创建并配置 Markdown 索引
手动配置：为高级定制需求手动配置 Crawler

自动设置 Markdown 索引（推荐）

设置 Markdown 索引的最简方式是通过 Crawler 界面，它会自动创建并配置专为 Ask AI 优化的索引。

步骤 1：访问 Crawler 配置中的 Markdown 索引功能

进入 Crawler 控制面板
转到 Configuration → Markdown for LLMs 标签页
您将看到 Markdown 索引区域，可在此创建专用索引

Crawler 配置 - Markdown for LLMs

步骤 2：添加新 Markdown 索引

点击 "+ Add Index" 创建新 Markdown 索引
填写必填字段：
- Index Name：输入描述性名称（如 my-docs-markdown）
- Content Tag：指定 HTML 内容选择器（通常为 main）
- Template：选择匹配文档框架的模板：
  - Docusaurus - 适用于 Docusaurus 站点
  - VitePress - 适用于 VitePress 站点
  - Astro/Starlight - 适用于 Astro/Starlight 站点
  - Non-DocSearch (Generic) - 适用于自定义站点或其他框架

添加 Markdown 索引对话框

点击 "Add Index" 创建索引

Crawler 将自动为所选模板配置优化设置，包括：

正确的记录提取与分块
框架专属元数据提取（语言、版本、标签）
专为 Ask AI 优化的索引设置

步骤 3：运行 Crawler

完成 Markdown 索引配置后：

点击 "Start Crawling" 开始内容索引
在控制面板监控爬取进度
您的新 Markdown 索引将填充专为 Ask AI 优化的洁净结构化记录

Crawler 状态

步骤 4：与 Ask AI 集成

爬取完成后，配置 DocSearch 使用新 Markdown 索引处理 Ask AI 回答。详细设置说明请参阅下方的集成章节。

手动配置（高级）

对于需要深度定制或希望了解底层配置的用户，您可以直接修改爬虫配置来手动设置 Markdown 索引。

步骤 1：更新现有 DocSearch 爬虫配置

在爬虫配置的 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",
    });
  },
},
// ...],

然后在您的 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,
},
// ...},

步骤 2：运行 DocSearch 爬虫创建新的 Ask AI 优化索引

更新爬虫配置后：

在 Algolia 爬虫控制台发布配置，保存并激活更改
运行爬虫索引 Markdown 内容并创建新索引

爬虫将使用 Markdown 提取助手处理内容，并向新索引填充专为 Ask AI 优化的洁净结构化记录。

**提示：**在控制台监控爬取进度确保页面正确处理。可在 Algolia 索引中查看记录验证结构和内容

将新索引与 Ask AI 集成

创建优化索引后，可通过两种方式集成：使用 DocSearch（推荐多数用户）或通过 Ask AI API 构建自定义集成

DocSearch Integration
Custom API Integration

Using DocSearch

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

JavaScript
React

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
    },
  },
});

<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',
    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).

Custom API Integration

信息

We highly recommend using the DocSearch package for most use cases. Custom implementations using the Ask AI API directly are not fully supported to the same extent as the DocSearch package, and may require additional development effort for features like error handling, authentication, and UI components.

Build your own chat interface using the Ask AI API. This gives you full control over the user experience and allows for advanced customizations.

class CustomAskAI {
  constructor({ appId, apiKey, indexName, assistantId }) {
    this.appId = appId;
    this.apiKey = apiKey;
    this.indexName = indexName; // Your markdown index
    this.assistantId = assistantId;
    this.baseUrl = 'https://askai.algolia.com';
  }

  async getToken() {
    const response = await fetch(`${this.baseUrl}/chat/token`, {
      method: 'POST',
      headers: {
        'X-Algolia-Assistant-Id': this.assistantId,
      },
    });
    const data = await response.json();
    return data.token;
  }

  async sendMessage(conversationId, messages, searchParameters = {}) {
    const token = await this.getToken();
    
    const response = await fetch(`${this.baseUrl}/chat`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Algolia-Application-Id': this.appId,
        'X-Algolia-API-Key': this.apiKey,
        'X-Algolia-Index-Name': this.indexName, // Use your markdown index
        'X-Algolia-Assistant-Id': this.assistantId,
        'Authorization': token,
      },
      body: JSON.stringify({
        id: conversationId,
        messages,
        ...(Object.keys(searchParameters).length > 0 && { searchParameters }),
      }),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    // Handle streaming response
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    
    return {
      async *[Symbol.asyncIterator]() {
        try {
          while (true) {
            const { done, value } = await reader.read();
            if (done) break;
            
            const chunk = decoder.decode(value, { stream: true });
            if (chunk.trim()) {
              yield chunk;
            }
          }
        } finally {
          reader.releaseLock();
        }
      }
    };
  }
}

// Usage
const askAI = new CustomAskAI({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  indexName: 'YOUR_INDEX_NAME-markdown', // Your markdown index
  assistantId: 'YOUR_ASSISTANT_ID',
});

// Send a message with facet filters for your markdown index
const stream = await askAI.sendMessage('conversation-1', [
  {
    role: 'user',
    content: 'How do I configure my API?',
    id: 'msg-1',
  },
], {
  facetFilters: ['language:en', 'type:content'] // Filter to relevant content
});

// Handle streaming response
for await (const chunk of stream) {
  console.log(chunk); // Handle each chunk of the response
}

Benefits of custom integration:

Full control over UI/UX
Custom authentication and session management
Advanced filtering and search parameters for your markdown index
Integration with existing chat systems
Custom analytics and monitoring

📚 Learn More: For complete API documentation, authentication details, advanced examples, and more integration patterns, see the Ask AI API Reference.

Using Facet Filters with Your Markdown Index:

Since your markdown index includes attributes like lang, version, and docusaurus_tag, you can filter Ask AI's context precisely:

// Example: Filter to English documentation only
const searchParameters = {
  facetFilters: ['lang:en']
};

// Example: Filter to specific version and content type
const searchParameters = {
  facetFilters: ['lang:en', 'version:latest', 'type:content']
};

// Example: Use OR logic for multiple tags (from your integration examples)
const searchParameters = {
  facetFilters: [
    'lang:en',
    [
      'docusaurus_tag:default',
      'docusaurus_tag:docs-default-current'
    ]
  ]
};

**提示：**随文档演进保持双索引更新，确保最佳搜索和 AI 回答质量

最佳实践与技巧

Markdown 文件使用清晰一致的标题提升可搜索性
使用 Ask AI 测试索引确保返回相关回答
调整 maxRecordBytes 若发现回答过于宽泛或零碎
- **注意：**增大 maxRecordBytes 可能增加大语言模型的 token 消耗，影响上下文窗口大小及每次 Ask AI 回答的成本
保持 Markdown 结构良好（使用标题/列表等）实现最优分块
添加属性如 lang、version 或 tags 到记录中，若需在搜索界面或 Ask AI 中过滤或分面，请设置 attributesForFaceting

常见问题

问：为何使用独立 Markdown 索引？ 答：它让 Ask AI 能以大语言模型优化的格式访问内容，从而提升回答质量

问：是否支持其他内容类型？ 答：支持，但 Markdown 特别适合分块和上下文提取

问：如何处理超大 Markdown 文件？ 答：降低 maxRecordBytes 值将内容拆分为更聚焦的小记录

更多细节请参阅 Ask AI 文档，若需配置爬虫帮助请联系支持

按集成分类的爬虫配置示例

以下是不同文档平台的 Markdown 索引配置示例，展示如何提取分面（语言/版本/标签等）并为特定集成配置爬虫：

Non-DocSearch (Generic)
Docusaurus
VitePress
Astro / Starlight

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

Docusaurus Example:

// In your Crawler config:

// 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 [];

    // Extract meta tag values. These are required for Docusaurus
    const language =
      $('meta[name="docsearch:language"]').attr("content") || "en";
    const version =
      $('meta[name="docsearch:version"]').attr("content") || "latest";
    const docusaurus_tag =
      $('meta[name="docsearch:docusaurus_tag"]').attr("content") || "";

    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, // Required for Docusaurus
        language, // Required for Docusaurus
        version: version.split(","), // in case there are multiple versions. Required for Docusaurus
        docusaurus_tag: docusaurus_tag // Required for Docusaurus
          .split(",")
          .map((tag) => tag.trim())
          .filter(Boolean),
      },
      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", "language", "version", "docusaurus_tag"], // Required for Docusaurus
  ignorePlurals: true,
  minProximity: 1,
  removeStopWords: false,
  searchableAttributes: ["title", "heading", "unordered(text)"],
  removeWordsIfNoResults: "lastWords",
  attributesToHighlight: ["title", "text"],
  typoTolerance: false,
  advancedSyntax: false,
},
// ...},

VitePress Example:

// In your Crawler config:

// 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, // Required for VitePress
      },
      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"], // Required for VitePress
  ignorePlurals: true,
  minProximity: 1,
  removeStopWords: false,
  searchableAttributes: ["title", "heading", "unordered(text)"],
  removeWordsIfNoResults: "lastWords",
  attributesToHighlight: ["title", "text"],
  typoTolerance: false,
  advancedSyntax: false,
},
// ...},

Astro / Starlight Example:

// In your Crawler config:

// 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, // Required for Astro/StarLight
      },
      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"], // Required for Astro/StarLight
  ignorePlurals: true,
  minProximity: 1,
  removeStopWords: false,
  searchableAttributes: ["title", "heading", "unordered(text)"],
  removeWordsIfNoResults: "lastWords",
  attributesToHighlight: ["title", "text"],
  typoTolerance: false,
  advancedSyntax: false,
},
// ...},

每个示例展示如何提取常用分面并为 Ask AI 配置 Markdown 索引。请根据站点需求调整选择器和元标签名称

概述​

自动设置 Markdown 索引（推荐）​

步骤 1：访问 Crawler 配置中的 Markdown 索引功能​

步骤 2：添加新 Markdown 索引​

步骤 3：运行 Crawler​

步骤 4：与 Ask AI 集成​

手动配置（高级）​

步骤 1：更新现有 DocSearch 爬虫配置​

步骤 2：运行 DocSearch 爬虫创建新的 Ask AI 优化索引​

将新索引与 Ask AI 集成​

Using DocSearch​

Custom API Integration​

最佳实践与技巧​

常见问题​

按集成分类的爬虫配置示例​

概述