コンテンツにスキップ
KARTE Craft Developer Portal

Craft RAG のメタデータフィルタ

Craft RAGでは、コーパス内のファイルにメタデータを付与し、検索時に検索対象を絞り込めます。

メタデータのキー（例: category）は、コーパスごとにスキーマとして定義する任意の項目です。あらかじめ定義したスキーマに沿ってファイルへ値を付与し、metadataFilter で検索対象を絞り込みます。

たとえば、商品ページとFAQが混在するコーパスを category で分けると、次のように絞り込めます。

  1. コーパスに category スキーマ（型: STRING）を定義する
  2. 商品ページ由来のファイルには category: item、FAQ由来のファイルには category: faq を付与する
  3. 検索時に metadataFilter: 'category == "faq"' を指定すると、FAQファイル群だけを対象にベクトル検索できる

filePath（Sites上の保存場所）と category は連動しないため、フォルダを分けなくてもメタデータで絞り込めます。

利用の流れ

  1. メタデータスキーマを定義する — コーパスにメタデータキーと値の型を登録する
  2. ファイルにメタデータを付与する — インポート時または管理画面から付与する
  3. 検索時に条件を指定する — ベクトル検索でファイルの中身を取得する処理、または回答生成のいずれかの metadataFilter に式を渡す

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

管理画面でメタデータスキーマを追加する

次の手順でメタデータスキーマを追加します。

  1. KARTE管理画面で「すべてのメニュー」>「Craft」>「RAG」を選択し、対象コーパスを開きます。
  2. 「スキーマ」を選択し、スキーマ管理画面を開きます。
  3. メタデータキーと型を入力して追加します。

同じ操作はCraft Functionsからも実行できます。

Craft Functionsでメタデータスキーマを追加する

Craft Functionsでは rag.createDataSchemas でメタデータスキーマを追加します。

const { rag } = MODULES;


await rag.createDataSchemas({
  corpusId: '1234567890123456789',
  schemas: [
    { key: 'category', type: 'STRING' },
    { key: 'priority', type: 'INTEGER' },
    { key: 'active', type: 'BOOLEAN' },
  ],
});

type には値（value）の型として INTEGER / FLOAT / STRING / DATETIME / BOOLEAN / LIST を指定できます。

メタデータを付与する

管理画面でメタデータを付与する

次の手順でメタデータを付与します。

  1. KARTE管理画面で「すべてのメニュー」>「Craft」>「RAG」を選択し、対象コーパスを開きます。
  2. ファイル一覧でチェックボックスを使い、メタデータを付与するファイルを選択します。
  3. 「メタデータ付与」を選択し、キーと値を入力して付与します。
  4. 各ファイルのサブメニュー「メタデータ」から、付与済みの内容を確認できます。

Craft Functionsでメタデータを付与する

SitesからRAGへインポート済みのファイルに対して、Craft Functions内でメタデータを付与する流れは次のとおりです。

  1. 対象コーパスの corpusId を確認する（RAG管理画面のコーパス一覧 Id 列で確認できます。Craft RAG を利用する — コーパスを作成するもご確認ください）
  2. メタデータを付与したいRAGファイルの fileId を確認する（管理画面のファイル一覧で確認可能。APIで取得する場合は Craft RAG Get RAG File By Path を利用）
  3. rag.attachMetadata でメタデータを付与する
const { rag } = MODULES;


await rag.attachMetadata({
  corpusId: '1234567890123456789',
  fileId: '9876543210987654321', // メタデータを付与したいRAGファイルのID
  metadata: [
    { key: 'category', value: 'item' },
    { key: 'priority', value: 1 },
    { key: 'active', value: true },
  ],
});

メタデータフィルタで検索する

スキーマ定義とメタデータ付与が済んだら、metadataFilter にCEL式を指定して検索対象を絞り込めます。たとえば category == "faq" のように書きます。

metadataFilter は、ベクトル検索でファイルの中身を取得する処理、または回答生成のいずれかに、任意パラメータとして追加します。基本的な呼び出し方と返却形式はCraft RAG を利用する — Craft Functionsから参照するをご確認ください。

ベクトル検索でファイルの中身を取得する場合

rag.retrieveContexts の引数に metadataFilter を追加します。

export default async function (data, { MODULES }) {
  const { res, req } = data;
  const { rag, logger } = MODULES;


  const corpusId = '1234567890123456789';
  const text = req.query.text || '返品方法は';


  const ret = await rag.retrieveContexts({
    corpusId,
    text,
    vectorDistanceThreshold: 0.8,
    metadataFilter: 'category == "faq"',
    topK: 5,
  });


  logger.log(ret);
  res.json(ret);
}

ベクトル検索して回答文を生成する場合

craftExtra.ragOptions に metadataFilter を追加します。

export default async function (data, { MODULES }) {
  const { res, req } = data;
  const { aiModules, logger } = MODULES;


  const text = req.query.text || '返品方法は';
  const corpusId = '1234567890123456789';


  const ret = await aiModules.gcpGeminiGenerateContent({
    model: 'gemini-2.5-flash',
    contents: [{ role: 'user', parts: [{ text }] }],
    craftExtra: {
      ragOptions: {
        corpusId,
        vectorDistanceThreshold: 0.8,
        metadataFilter: 'category == "faq"',
        topK: 5,
      },
    },
  });


  logger.log(ret);
  res.json(ret);
}

APIリファレンス