跳转到内容
搜索文档

为网站添加搜索

最后更新 查看 MarkdownAgent 设置

本教程将创建可索引你网站的 AI Search 实例,然后在站点前端添加可用的搜索栏、聊天气泡和搜索模态框。教程使用 UI 片段——可连接到实例公共端点的预构建 Web 组件——因此只需少量前端代码即可添加搜索。

你将构建的内容: 一个可索引你网站的 AI Search 实例,以及添加到站点前端、用于查询该内容的搜索栏、聊天气泡和搜索模态框。

在站点上打开的 AI Search 模态框,显示搜索输入框、键盘导航提示,以及 Powered by Cloudflare AI Search 标签。

前提条件

  1. 注册 Cloudflare 账户
  2. 安装 Node.js

Node.js 版本管理器

使用 Voltanvm 等 Node 版本管理器,以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

本教程为现有 React 应用添加搜索。如果你从新项目开始,请先按 React 框架指南 搭建项目,再执行后续步骤。这些片段是与框架无关的 Web 组件,因此同样适用于其他框架或纯 HTML,详见 UI 片段

1. 创建 AI Search 实例

使用 Wrangler CLI 创建实例。若要索引你拥有的网站,请将其连接为数据源,以便 AI Search 自动爬取并建立索引:

npx wrangler ai-search create my-search --type web-crawler --source <YOUR_DOMAIN>

<YOUR_DOMAIN> 替换为已接入你 Cloudflare 账户的域名。若要创建不带数据源的实例并自行上传文件,请运行 npx wrangler ai-search create my-search --type builtin,然后从仪表板添加内容。

检查索引进度:

npx wrangler ai-search stats my-search

索引完成后,可从命令行测试查询:

npx wrangler ai-search search my-search --query 'What is this site about?'

2. 启用公共端点

UI 片段通过实例的公共端点连接。

  1. 在 Cloudflare 仪表板中前往 AI Search

    Go to AI Search ↗
  2. 选择你的 my-search 实例。

  3. 前往 Settings(设置) > Public Endpoint(公共端点)

  4. 打开 Enable Public Endpoint(启用公共端点)

  5. 从 URL https://<INSTANCE_ID>.search.ai.cloudflare.com/ 复制公共端点 ID。后续步骤会用到。

3. 安装片段库

在网站项目中安装 AI Search UI 片段库

npm i @cloudflare/ai-search-snippet

4. 添加搜索组件

在某个组件中导入片段库,并在需要展示搜索的位置添加对应标签。只需导入一次包,即可向浏览器注册这些组件。以下示例在应用的根组件中添加了搜索栏、浮动聊天气泡,以及可用 Cmd/Ctrl+K 打开的搜索模态框。将 <INSTANCE_ID> 替换为第二步中的公共端点 ID。

src/App.tsxtsx
import "@cloudflare/ai-search-snippet";

export default function App() {
	return (
		<div>
			<search-bar-snippet
				api-url="https://<INSTANCE_ID>.search.ai.cloudflare.com/"
				placeholder="Search..."
				max-results={50}
				max-render-results={10}
				show-url="true"
				show-date="true"
			/>
			<chat-bubble-snippet
				api-url="https://<INSTANCE_ID>.search.ai.cloudflare.com/"
				style={
					{
						"--search-snippet-primary-color": "#F6821F",
					} as React.CSSProperties
				}
			/>
			<search-modal-snippet
				api-url="https://<INSTANCE_ID>.search.ai.cloudflare.com/"
				placeholder="Search documentation..."
				shortcut="k"
				show-url="true"
				show-date="true"
			/>
		</div>
	);
}

为自定义元素添加 TypeScript 声明

片段包会附带其类的类型定义,但不会告诉 TypeScript <search-bar-snippet> 及其他标签是合法的 JSX 元素。Vite 开发服务器不会做类型检查,因此不添加此步骤应用也能运行;但添加声明文件可避免 .tsx 类型检查和编辑器在自定义标签上报错。

创建类似 src/ai-search-snippet.d.ts 的声明文件:

src/ai-search-snippet.d.tsts
import type { HTMLAttributes } from "react";

// Register the snippet web components as valid JSX elements. The index
// signature allows their custom attributes (such as api-url and placeholder).
type SnippetElement = HTMLAttributes<HTMLElement> & {
	[attribute: string]: unknown;
};

declare module "react" {
	namespace JSX {
		interface IntrinsicElements {
			"search-bar-snippet": SnippetElement;
			"chat-bubble-snippet": SnippetElement;
			"search-modal-snippet": SnippetElement;
		}
	}
}

这会宽松地为标签添加类型,允许任意属性。若需要更严格的按组件类型,请参阅片段仓库中的 React demo 声明

5. 允许本地 origin

公共端点使用 CORS 控制哪些站点可以调用它。请添加本地开发时站点所使用的 origin,以便浏览器能访问该端点。Vite 应用通常运行在 http://localhost:5173

  1. 在 AI Search 实例中,前往 Settings(设置) > Public Endpoint(公共端点)
  2. Authorized hosts(授权主机) 下,添加本地 origin,例如 http://localhost:5173
  3. 选择 Save(保存)

6. 测试

启动开发服务器:

npm run dev

在浏览器中打开站点(Vite 应用通常为 http://localhost:5173)。在搜索栏中输入以在下拉列表中查看结果,点击角落的聊天气泡提问,或按 Cmd/Ctrl+K 打开搜索模态框。有关完整组件、属性和主题选项,请参阅 UI 片段

7. 上线生产环境

片段可在站点被提供服务的任何位置工作。将站点部署到生产域名后,请返回 Settings(设置) > Public Endpoint(公共端点),并将该 origin 添加到 Authorized hosts(同第五步),以便生产环境中的浏览器能访问该端点。

后续步骤

UI snippets

全部片段组件、属性与 CSS 主题选项。

这篇文档对您有帮助吗?