← Обзор / ai-search / how-to

Добавьте поиск на свой сайт

В этом руководстве вы создадите экземпляр AI Search, который индексирует ваш сайт, а затем добавите на фронтенд сайта рабочую строку поиска, чат-пузырь и модальное окно поиска. В нём используется UI-сниппеты, готовые веб-компоненты, которые подключаются к публичной конечной точке вашего экземпляра, поэтому добавить поиск можно всего несколькими строками кода на фронтенде.

Что вы создадите: Экземпляр AI Search, который индексирует ваш сайт, а также строка поиска, чат-пузырь и модальное окно поиска, добавленные во фронтенд вашего сайта и обращающиеся к этому контенту.

1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗.
2. Установка Node.js ↗.

Это руководство добавляет поиск в существующее приложение на React. Если вы начинаете новый проект, сначала разверните его с помощью Руководство по фреймворку React, затем выполните следующие шаги. Эти фрагменты кода представляют собой веб-компоненты, не привязанные к конкретному фреймворку, поэтому тот же подход работает и в других фреймворках, и в обычном HTML, как показано в UI-сниппеты.

Создайте экземпляр с помощью 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?'

UI-фрагменты подключаются к вашему экземпляру через его публичную конечную точку.

В проекте вашего сайта установите Библиотека сниппетов для интерфейса AI Search:

npm i @cloudflare/ai-search-snippet

Импортируйте библиотеку сниппетов в один из ваших компонентов и добавьте теги там, где должен появляться поиск. Однократный импорт пакета регистрирует компоненты в браузере. В следующем примере добавляются строка поиска, плавающий чат-пузырь и модальное окно поиска, которое открывается с помощью Cmd/Ctrl+K в корневой компонент приложения. Замените <PUBLIC_ENDPOINT_ID> с ID вашей публичной конечной точки из шага два.

import type { CSSProperties } from "react";
import "@cloudflare/ai-search-snippet";

export default function App() {
	return (
		<div>
			<search-bar-snippet
				api-url="https://<PUBLIC_ENDPOINT_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://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/"
				style={
					{
						"--search-snippet-primary-color": "#F6821F",
					} as CSSProperties
				}
			/>
			<search-modal-snippet
				api-url="https://<PUBLIC_ENDPOINT_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-демо ↗ в репозитории сниппетов.

Публичная конечная точка использует CORS, чтобы определять, какие сайты могут её вызывать. Добавьте origin, на котором работает ваш сайт во время локальной разработки, чтобы браузер мог обращаться к конечной точке. Приложение Vite работает на http://localhost:5173.

Запустите сервер разработки:

npm run dev

Откройте свой сайт в браузере (приложение Vite запускается на http://localhost:5173). Введите запрос в строку поиска, чтобы увидеть результаты в раскрывающемся списке, нажмите на значок чата в углу, чтобы задать вопрос, или нажмите Cmd/Ctrl+K и таким образом открыть модальное окно поиска. Полный список компонентов, атрибутов и параметров оформления см. в UI-сниппеты.

Сниппеты работают везде, где размещён ваш сайт. Когда вы развернёте сайт на продакшен-домене, вернитесь в Настройки > Публичная конечная точка и добавьте этот источник в Авторизованные хосты (как в пятом шаге), чтобы браузер мог обращаться к эндпойнту в продакшене.