本教程将创建可索引你网站的 AI Search 实例,然后在站点前端添加可用的搜索栏、聊天气泡和搜索模态框。教程使用 UI 片段——可连接到实例公共端点的预构建 Web 组件——因此只需少量前端代码即可添加搜索。
你将构建的内容: 一个可索引你网站的 AI Search 实例,以及添加到站点前端、用于查询该内容的搜索栏、聊天气泡和搜索模态框。
- 注册 Cloudflare 账户 ↗。
- 安装
Node.js↗。
Node.js 版本管理器
使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器,以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。
本教程为现有 React 应用添加搜索。如果你从新项目开始,请先按 React 框架指南 搭建项目,再执行后续步骤。这些片段是与框架无关的 Web 组件,因此同样适用于其他框架或纯 HTML,详见 UI 片段。
使用 Wrangler CLI 创建实例。若要索引你拥有的网站,请将其连接为数据源,以便 AI Search 自动爬取并建立索引:
npx wrangler ai-search create my-search --type web-crawler --source <YOUR_DOMAIN>yarn wrangler ai-search create my-search --type web-crawler --source <YOUR_DOMAIN>pnpm 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-searchyarn wrangler ai-search stats my-searchpnpm wrangler ai-search stats my-search索引完成后,可从命令行测试查询:
npx wrangler ai-search search my-search --query 'What is this site about?'yarn wrangler ai-search search my-search --query 'What is this site about?'pnpm wrangler ai-search search my-search --query 'What is this site about?'UI 片段通过实例的公共端点连接。
-
在 Cloudflare 仪表板中前往 AI Search。
Go to AI Search ↗ -
选择你的
my-search实例。 -
前往 Settings(设置) > Public Endpoint(公共端点)。
-
打开 Enable Public Endpoint(启用公共端点)。
-
从 URL
https://<INSTANCE_ID>.search.ai.cloudflare.com/复制公共端点 ID。后续步骤会用到。
在网站项目中安装 AI Search UI 片段库:
npm i @cloudflare/ai-search-snippetyarn add @cloudflare/ai-search-snippetpnpm add @cloudflare/ai-search-snippetbun add @cloudflare/ai-search-snippet在某个组件中导入片段库,并在需要展示搜索的位置添加对应标签。只需导入一次包,即可向浏览器注册这些组件。以下示例在应用的根组件中添加了搜索栏、浮动聊天气泡,以及可用 Cmd/Ctrl+K 打开的搜索模态框。将 <INSTANCE_ID> 替换为第二步中的公共端点 ID。
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 <search-bar-snippet> 及其他标签是合法的 JSX 元素。Vite 开发服务器不会做类型检查,因此不添加此步骤应用也能运行;但添加声明文件可避免 .tsx 类型检查和编辑器在自定义标签上报错。
创建类似 src/ai-search-snippet.d.ts 的声明文件:
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 声明 ↗。
公共端点使用 CORS 控制哪些站点可以调用它。请添加本地开发时站点所使用的 origin,以便浏览器能访问该端点。Vite 应用通常运行在 http://localhost:5173。
- 在 AI Search 实例中,前往 Settings(设置) > Public Endpoint(公共端点)。
- 在 Authorized hosts(授权主机) 下,添加本地 origin,例如
http://localhost:5173。 - 选择 Save(保存)。
启动开发服务器:
npm run devyarn run devpnpm run dev在浏览器中打开站点(Vite 应用通常为 http://localhost:5173)。在搜索栏中输入以在下拉列表中查看结果,点击角落的聊天气泡提问,或按 Cmd/Ctrl+K 打开搜索模态框。有关完整组件、属性和主题选项,请参阅 UI 片段。
片段可在站点被提供服务的任何位置工作。将站点部署到生产域名后,请返回 Settings(设置) > Public Endpoint(公共端点),并将该 origin 添加到 Authorized hosts(同第五步),以便生产环境中的浏览器能访问该端点。