Web サイトへ検索を追加する

このチュートリアルでは、Web サイトをインデックスする AI Search インスタンスを作成し、サイトのフロントエンドへ検索バー、チャットバブル、検索モーダルを追加します。UI スニペット を使います。これはインスタンスの公開エンドポイントに接続する、用意済みの Web コンポーネントです。フロントエンドに数行足すだけで検索を追加できます。

作成するもの: Web サイトをインデックスする AI Search インスタンスと、そのコンテンツを検索する検索バー、チャットバブル、検索モーダルです。サイトのフロントエンドへ追加します。

1. Cloudflare アカウント ↗ に登録します。
2. Node.js ↗ をインストールします。

このチュートリアルは、既存の React アプリへ検索を追加します。新規プロジェクトから始める場合は、先に React フレームワークガイド で土台を作り、続けて次の手順に進みます。スニペットはフレームワークに依存しない Web コンポーネントです。ほかのフレームワークやプレーン HTML でも同じ手順が使えます。詳細は UI スニペット を参照してください。

Wrangler CLI でインスタンスを作成します。所有する Web サイトをインデックスするには、データソースとして接続します。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-search

yarn wrangler ai-search stats my-search

pnpm 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 スニペットは、インスタンスの公開エンドポイント経由で接続します。

Web サイトのプロジェクトで、AI Search UI スニペットライブラリ をインストールします。

npm i @cloudflare/ai-search-snippet

yarn add @cloudflare/ai-search-snippet

pnpm add @cloudflare/ai-search-snippet

bun add @cloudflare/ai-search-snippet

いずれかのコンポーネントでスニペットライブラリをインポートし、検索を出したい場所にタグを置きます。パッケージを 1 回インポートすると、コンポーネントがブラウザに登録されます。次の例では、アプリのルートコンポーネントへ検索バー、フローティングのチャットバブル、Cmd/Ctrl+K で開く検索モーダルを追加します。<PUBLIC_ENDPOINT_ID> は、手順 2 の公開エンドポイント 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

yarn run dev

pnpm run dev

ブラウザでサイトを開きます（Vite アプリは http://localhost:5173 で動きます）。検索バーに入力するとドロップダウンに結果が出ます。隅のチャットバブルを選ぶと質問できます。Cmd/Ctrl+K で検索モーダルが開きます。コンポーネント、属性、テーマの全オプションは UI スニペット を参照してください。

スニペットは、サイトを配信している場所ならどこでも動きます。サイトを本番ドメインへデプロイしたら、Settings > Public Endpoint に戻り、その origin を Authorized hosts へ追加します（手順 5 と同じです）。本番でもブラウザからエンドポイントへ届くようにします。