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

Craft RAG を利用する

Craft RAGは、Craft Sites上のファイルをコーパスにインポートし、Craft Functionsからベクトル検索や回答生成（Retrieval-Augmented Generation）に利用できる機能です。ベクトルDBの構築や埋め込み処理を自前で実装する必要はなく、ファイルの配置とAPI呼び出しで手軽に利用できます。インデックス設計や検索パイプラインを細かく制御したい場合は、Craft Vector Searchをご利用ください。

Craft RAGの概要

Craft RAGでは、検索対象のファイル群をコーパスと呼びます。Craft Sites上のファイルをコーパスにインポートすることで、Craft Functionsからベクトル検索が利用できるようになります。

インポート時にファイルの本文は検索しやすい長さに分割され、コーパスに保存されます。この分割単位をチャンクと呼びます。

Craft RAGを使うために必要な作業は次のとおりです。

対応ファイル形式

形式サイズ上限
HTML file10 MB
JSON file1 MB
Markdown file10 MB
Microsoft PowerPoint slides (PPTX file)10 MB
Microsoft Word documents (DOCX file)50 MB
PDF file50 MB
Text file10 MB

コーパスを作成する

RAG管理画面からコーパスを作成する手順は次のとおりです。

  1. KARTE管理画面で「すべてのメニュー」>「Craft」>「RAG」を選択し、RAGの管理画面を開きます。
  2. 「新規作成」を選択し、コーパスの作成画面を開きます。
    1. 「名前」 にコーパス名を入力します。
  3. 「作成」を選択します。
  4. 作成されたコーパスのId（corpusId）を控えます。
    1. Craft Functionsから参照するときに使用します。

ファイルをインポートする

Craft Sitesに保存したファイルをRAGコーパスにインポートする方法を説明します。

管理画面からインポートする

KARTE管理画面からCraft Sites上のファイルをRAGコーパスへインポートする手順は次のとおりです。

  1. KARTE管理画面で「すべてのメニュー」>「Craft」>「Sites」を選択し、対象サイトを開きます。
  2. インポート元のファイルまたはディレクトリを選択します。
  3. 取り込み先のRAGコーパスを指定してインポートを実行します。
  4. インポート処理が開始します。
  5. しばらく待機後にRAG管理画面を更新し、ファイルが取り込まれていることを確認します。

Sitesからインポートする場合、ダイアログでチャンクサイズと重複サイズ（トークン数）を指定できます。

ディレクトリ単位でのインポートにも対応しています。

APIからインポートする

Craft Sitesに保存済みのファイルを、Craft Functionsや外部サーバーからKARTE API v2経由でコーパスにインポートできます。Craft SitesへのアップロードもAPIで実行できるため、アップロードからインポートまで一連のAPI処理として自動化もできます（Sites側のアップロードAPIは Craft Sites Content Uploadをご確認ください）。

アプリを利用する の手順でAPI v2アプリを作成し、次のScopeを設定してください。

  • beta.craft.rag.importByFile
  • beta.craft.rag.importByDirectory

インポートは次のAPIを利用します。パラメータや呼び出し方の詳細は、各APIリファレンスをご確認ください。

Craft Functionsからの呼び出し例です。

// packages: { "api": "5.0.8" }
import api from 'api';


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


  const craft = api('@dev-karte/v1.0#xxxxxxxxxxxxxxxx');
  craft.auth('token_value'); // 実運用の際は、Secret Managerに設定したアクセストークンを利用します。


  // Import By File API でインポートを開始する
  const { data: result } = await craft.postV2betaCraftRagImportbyfile({
    siteName: 'my-site',
    path: '/product-guide.pdf',
    corpusId: '1234567890123456789',
  });


  logger.log(result);
}

インポートの例

KARTE Datahubのデータを定期的にCraft Sites経由で一括インポートする例です。

Craft Functionsから参照する

Craft Functionsからは、次の2系統が利用できます。

  • ベクトル検索でファイルの中身を取得（rag.retrieveContexts）— クエリに関連するチャンクを返します
  • ベクトル検索して回答文を生成する（aiModules.gcpGeminiGenerateContent と craftExtra.ragOptions）— コーパス内をベクトル検索し、LLMが回答文を生成します

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

rag.retrieveContexts で、指定したコーパス内からクエリに近いチャンクをベクトル検索で取得します。

サンプルコード

HTTPタイプのファンクションでクエリパラメータ text を受け取り、検索結果を返す例です。

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


  const corpusId = '1234567890123456789';
  const vectorDistanceThreshold = 0.8;


  const ret = await rag.retrieveContexts({
    corpusId,
    text,
    vectorDistanceThreshold,
  });


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

vectorDistanceThreshold（任意）は、ベクトル距離による絞り込みの閾値です。score が閾値より小さいチャンクのみが返ります。

レスポンス例

text に '返品方法は' を渡した場合の戻り値の例です。配列で返り、各要素はコーパス内のチャンク原文です。返却件数やチャンクの長さは、コーパス内容やインポート時のチャンク設定によります。filePath は取り込み元ファイル、score はクエリとチャンクのベクトル間の距離です。値が小さいほど、クエリの内容に近いチャンクです。

[
  {
    filePath: '/faq/return-policy.md',
    text: '商品到着から30日以内であれば返品を受け付けます。返品をご希望の場合は、マイページの「返品申請」から手続きをお願いします。一部の商品（食品など）は返品の対象外です。詳しくは商品ページの返品条件をご確認ください。',
    score: 0.222,
  },
  {
    filePath: '/faq/shipping.md',
    text: '返品時の送料は、原則としてお客様のご負担となります。不良品・誤配送の場合は当社が送料を負担します。返品商品の発送は、指定の返品センター宛に簡易包装のうえお送りください。',
    score: 0.222,
  },
  // クエリやコーパス内容により、さらに結果が続く場合があります
]

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

aiModules.gcpGeminiGenerateContent の craftExtra.ragOptions を指定します。チャンクの一覧ではなく、生成された回答文が返ります。

指定できるモデルについては、Craft RAG で利用できるモデル一覧をご確認ください。

サンプルコード

HTTPタイプのファンクションでクエリパラメータ text を受け取り、RAG連携付きで回答を生成して返す例です。

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


  const corpusId = '1234567890123456789';
  const vectorDistanceThreshold = 0.8;


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


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

レスポンス例

同じく text に '返品方法は' を渡した場合の戻り値の例です。返却されるのはチャンクの配列ではなく、LLMが生成した回答文です。成功時のレスポンスには、通常 usageMetadata が含まれます。

{
  candidates: [
    {
      content: {
        role: 'model',
        parts: [
          {
            text: '商品到着から30日以内であれば、マイページの「返品申請」より手続きが可能です。食品など一部の商品は返品対象外となる場合があります。\n\n返品時の送料は原則としてお客様負担となりますが、不良品や誤配送の場合は当社が負担します。返品商品は簡易包装のうえ、指定の返品センターへお送りください。\n\nなお、サイズ交換の場合は商品到着から14日以内にマイページの「交換申請」からお手続きください。交換は同一商品の別サイズ・別色のみで、在庫がない場合は返金となります。',
          },
        ],
      },
      finishReason: 'STOP',
    },
  ],
  usageMetadata: {
    promptTokenCount: 2,
    candidatesTokenCount: 112,
    totalTokenCount: 114,
  },
}

APIリファレンス