跳至主内容
版本：稳定版 (v4.x)

v4 入门指南

非官方测试版翻译

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

简介​

DocSearch v4 相比之前版本有重大升级，提供了更强的可访问性、响应能力，并为您的文档带来更佳的搜索体验。它基于 Algolia Autocomplete 构建，确保无缝集成，已被全球领先的文档站点所信赖。

安装​

在寻找组合式 API 文档？您可以在此处找到。

DocSearch 包已发布在 npm registry 上。

Docusaurus 用户​

如果您的文档站点由 Docusaurus 驱动，请使用 @docsearch/docusaurus-adapter 以获取最新的 DocSearch 功能（包括侧边栏支持等新的 Ask AI 功能），同时保留 @docusaurus/preset-classic。

yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4

Without package manager​

Include CSS in your website's <head>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />

And the JavaScript at the end of your <body>:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>

优化首次查询性能​

通过使用 preconnect 来提升用户的首次搜索体验，请参阅下方的性能优化部分

实现​

DocSearch requires a dedicated container in your HTML

<div id="docsearch"></div>

Initialize DocSearch by passing your container:

import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});

DocSearch generates an accessible, fully-functional search input for you automatically.

快速测试（无需凭证）​

若您希望立即测试 DocSearch 而无需自己的凭证，请使用我们的演示配置：

docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
  askAi: 'askAIDemo',
});

或使用我们全新的专用 DocSearch Playground

搭配 Ask AI 使用 DocSearch​

DocSearch v4 引入了对 Ask AI 的支持，这是 Algolia 先进的 AI 驱动搜索能力。Ask AI 通过直接从您的文档中提供上下文相关且智能的响应，从而提升用户体验。您还可以使用相同的 askAi 配置对象，通过 Agent Studio 路由聊天请求。

要启用 Ask AI，您可以将 Algolia Assistant ID 作为字符串添加，或者使用对象进行更高级的配置（例如指定不同的索引、凭证、搜索参数，或启用 Agent Studio）：

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});

  • 使用字符串形式进行简单设置

  • 使用对象形式可自定义 Ask AI 使用的索引、凭证或过滤器

  • 建议问题功能在 控制台 的 Ask AI 部分进行管理

在 DocSearch 中使用 Agent Studio​

要将 Algolia Agent Studio 用作聊天后端，请在 askAi 对象内设置 agentStudio: true。

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    agentStudio: true,
    searchParameters: {
      YOUR_INDEX_NAME: {
        filters: 'type:content AND language:en',
        attributesToRetrieve: ['title', 'content', 'url'],
        restrictSearchableAttributes: ['title', 'content'],
        distinct: 'url',
      },
    },
  },
});

  • agentStudio 在 askAi 内部配置，而非作为顶层的 DocSearch 属性。

  • 当 agentStudio: true 时，searchParameters 必须按索引名称进行键控（keyed）。

  • Agent Studio 的搜索参数支持 filters、attributesToRetrieve、restrictSearchableAttributes 和 distinct。

过滤搜索结果​

关键词搜索​

如果您的网站使用了 DocSearch 元标签 或在配置中添加了自定义变量，您就能使用 facetFilters 选项将搜索结果限定在某个facet范围内

这有助于将搜索范围限定在单一语言或单一版本

docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});

Ask AI​

过滤功能同样适用于 Ask AI。这有助于将大型语言模型的搜索范围限定在相关结果内。

信息

当在多种语言或任何多面索引中使用 Ask AI 时，我们建议使用 facetFilters 选项

docsearch({
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  },
});
技巧

您可以使用 facetFilters: ['type:content'] 来确保 Ask AI 仅使用 type 属性为 content 的记录（即仅包含实际内容的记录）。这在您的索引包含导航、元数据或其他非内容类型的记录时非常有用

发送事件​

您可以在创建 DocSearch 实例时传入 insights 参数，从而将搜索事件发送到您的 DocSearch 索引

docsearch({
   // other options
+  insights: true,
});

性能优化​

预连接​

将此代码片段添加到您网站的 <head> 部分，以提高初始搜索请求的加载速度：

<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />

这有助于浏览器与 Algolia 建立快速连接，从而提升用户体验，尤其在移动设备上