Summary

AI Searchがカスタムメタデータの定義と検索フィルタリングをサポートしました。インスタンスごとに最大5つのカスタムフィールドを定義でき、text / number / boolean の型で文書をタグ付けして検索結果を絞り込めます。エンジニア向けに導入手順と実用的な使い方を簡潔に記載します。

Key Points

カスタムメタデータはインスタンスあたり最大5フィールド。各フィールドにfield_nameとdata_typeを指定（text、number、boolean）。
スキーマ定義はインスタンス作成/更新のAPIでcustom_metadata配列を送信（例: POST /accounts/{ACCOUNT_ID}/ai-search/instances）。
ドキュメントへのメタ付与方法:
- R2: オブジェクトアップロード時にS3互換ヘッダ x-amz-meta-* を使用。
- Website: HTMLの<meta>タグで指定。
検索での利用: 検索リクエストのai_search_options.retrieval.filtersにカスタムフィールドを含めてフィルタリング。例: "filters": { "category": "documentation", "version": { "$gte": 2.0 } }。
実装順序: 1) カスタムメタスキーマ定義 → 2) 既存/新規ドキュメントへメタ追加 → 3) 検索リクエストでフィルタ適用。

Practical tips

数値比較や真偽値フィルタを活用してバージョン管理や公開フラグで絞り込みを行う。
メタ名はクエリで使うため一貫した命名規則を採用する（例: category, version, is_public）。
既存データの一括反映はアップロードスクリプトやバッチ処理でx-amz-meta-*を付与して実行する。

openaijamodel: gpt-5-mini-2025-08-07

AI Search - AI Search のカスタムメタデータフィルタリング

AI Search のカスタムメタデータフィルタリング

AI Search はカスタムメタデータによるフィルタリングをサポートするようになりました。category（カテゴリ）、version（バージョン）、あるいは任意に定義したカスタムフィールドなどに基づいて検索結果を絞り込むことができます。

カスタムメタデータスキーマを定義する

AI Search インスタンスごとに最大 5 個のカスタムメタデータフィールドを定義できます。各フィールドは名前とデータ型（text、number、boolean）を持ちます。

以下はインスタンス作成時の例です（curl）:

Terminal window
curl -X POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances \ 
  -H "Content-Type: application/json" \ 
  -H "Authorization: Bearer {API_TOKEN}" \ 
  -d '{ "id": "my-instance", "type": "r2", "source": "my-bucket", "custom_metadata": [ { "field_name": "category", "data_type": "text" }, { "field_name": "version", "data_type": "number" }, { "field_name": "is_public", "data_type": "boolean" } ] }'

ドキュメントにメタデータを追加する

メタデータの付与方法はデータソースによって異なります。

R2 bucket: オブジェクトをアップロードする際に S3 互換のカスタムヘッダー（x-amz-meta-*）を使ってメタデータを設定します。詳しくは R2 custom metadata を参照してください。
Website: HTML ページに <meta> タグを追加してメタデータを設定します。詳しくは Website custom metadata を参照してください。

検索結果をフィルタリングする

定義したカスタムメタデータフィールドは、folder や timestamp のような組み込み属性と併せて検索クエリで指定できます。以下は検索リクエストの例です:

Terminal window
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances/{NAME}/search \ 
  -H "Content-Type: application/json" \ 
  -H "Authorization: Bearer {API_TOKEN}" \ 
  -d '{ "messages": [ { "content": "How do I configure authentication?", "role": "user" } ], "ai_search_options": { "retrieval": { "filters": { "category": "documentation", "version": { "$gte": 2.0 } } } } }'

詳細はメタデータフィルタリングのドキュメントを参照してください。

AI Search - Custom metadata filtering for AI Search

要約