これは「関連記事表示 by Vector Search 2.0」のデモサイトです。記事コンテンツはソリューションブログから引用しています。
Craft Cross CMSで公開したコンテンツをCraft RAGに同期する

Craft Cross CMSで公開したコンテンツをCraft RAGに同期する

こんにちは、Customer Engineerのgamiです！最近、Switch 2招待販売の案内が来て小躍りしました。

さて、先日リリースした記事でCraft RAGの機能紹介をしました。その中で、「Craft Cross CMSで入稿したテキストデータをCraft RAGにインポートして活用できる」という旨を記載しました。

Craft RAG と Craft Vector Search は、どう使い分ければいいのか？

たとえばCraft Cross CMSでFAQコンテンツを管理している場合、それをCraft RAGにも自動で同期できると、そのFAQナレッジを使って質問に回答をするAIボットを実装できるようになります。

そこで今回は、Craft Cross CMSで公開したコンテンツを自動でCraft RAGに同期するための仕組みについてご紹介します。

アウトプットイメージ

今回の記事では、Craft Cross CMSで入稿したFAQコンテンツをCraft RAGに自動連携したいというシーンを題材にします。

最終的なアウトプットイメージは次の通りです。

CMSでFAQコンテンツを作成・公開します。

すると、それがMarkdown形式でCraft Sitesに保存され、さらにCraft RAGにインポートされて検索可能になります。

ファイル名がわかりにくいですが、ここではCraft Cross CMSのコンテンツIDをファイル名に利用することでCMS側のコンテンツに対応するCraft SitesやCraft RAGのファイルとを紐付けています。

なおCraft RAGにインポートされたナレッジは、たとえば次のようなAIによるテキスト生成に利用できます。

構成図は次の通りです。

Craft Cross CMS側の対象モデルでコンテンツが公開されると、Hookの仕組みでCraft Functionsが実行されます。そのファンクション内で、次のような処理が実行されます。

  • CMSからコンテンツの中身を取得してMarkdown形式に変換
  • そのMarkdownテキストをファイルとしてCraft Sitesにアップロード
  • そのファイルをファイルパス指定でRAGコーパスにインポート

この一連の処理には、次のAPI群が使われています。

なお、今回紹介するテンプレートはコンテンツ非公開時のファイル削除にも対応しています。コンテンツ非公開時に利用しているAPIは次の通りです。

注意点

前提として、次の点に注意をしてください。

  • API v2、Craft Functions、Craft Cross CMS、Craft Sites、Craft RAGが利用できるKARTEプロジェクトが必要です

設定手順

設定の手順は次の通りです。

  1. API v2 アプリを作成する
  2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する
  3. Craft Cross CMSのモデルを作成する
  4. Craft Sitesのサイトを用意する
  5. Craft RAGのコーパスを作成する
  6. Craft Functionsを作成する
  7. CMS更新時のHookを設定する

1. API v2 アプリを作成する

Craft Functionsから各機能にアクセスするためのAPI v2アプリを作成します。

  • [ストア > API v2設定] からアプリを新規作成します

  • [アプリタイプ] を token に設定します

  • 必要なscopeを追加してください

    • beta.cms.content.get
    • beta.craft.sites.content.upload
    • beta.craft.sites.content.file.remove
    • beta.craft.rag.importByFile
    • beta.craft.rag.getFileByPath
    • beta.craft.rag.deleteFiles

  • アプリを保存し、一度だけ表示されるアクセストークンをメモしておきましょう

2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する

API v2 アプリのアクセストークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。

  • [Craft > シークレット] からシークレットを新規作成します

  • [名前] に、わかりやすい名前を入力します

  • メモしておいたAPI v2 アプリのアクセストークンを [シークレットの値] に入力し、作成してください

  • シークレット名は、Craft Functions作成時に必要なのでメモしておきましょう

3. Craft Cross CMSのモデルを作成する

RAGに同期するコンテンツの構造を定義するため、Craft Cross CMSでモデルを作成します。

  • [Craft > コンテンツ一覧 > コンテンツ設定] の [モデルを追加]から、モデル作成画面を開きます
  • faqなど適当なモデル名で、次の例のようなフィールドをもつモデルを作成してください
    • どのフィールドをCraft RAGに含めるかについては、後述する手順で指定できます
フィールド名タイプ表示名
titleテキストタイトル
contentリッチテキスト本文
category選択カテゴリ
tags選択（複数）タグ
  • JSONプレビューの中にあるmodelIdの値をコピーしておきます
    • 例: a1234567890b2345678901c3

4. Craft Sitesのサイトを用意する

Craft RAGにインポートするファイルをホスティングするためのサイトをCraft Sitesで作成します。

すでにサイトがある場合は、それを使っていただいても大丈夫です。

  • [Craft > サイト]の[新規作成]から、適当な設定でサイトを作成します
    • 検証目的であれば、ドメインは [自動でドメインを払い出す] を使っても問題ありません

5. Craft RAGのコーパスを作成する

Craft RAGでファイルを追加するためのコーパスを作成します。

  • [Craft > RAG] の [新規作成]から、適当な名前でコーパスを作成します
  • 作成したコーパスのIDをメモしておきます

6. Craft Functionsを作成する

CMS更新を検知してコンテンツをCraft RAGに同期するためのファンクションを作成します。

  • [Craft > ファンクション > 新規作成 > テンプレートから作成] を選択します

  • 「 Craft Cross CMSのコンテンツ変更をCraft RAGに同期する 」というテンプレートを検索し[取得]ボタンをクリックします

  • [反映] ボタンをクリックします

  • [設定 > ファンクションのタイプ] で「イベント駆動タイプ」を選択します

  • [変数] タブで次の変数の値を設定してください

変数名設定例説明
LOG_LEVELWARN出力するログのレベルです。ERROR/WARN/INFO/DEBUGから指定します
KARTE_APP_TOKEN_SECRETKARTE_APP_TOKENKARTE API v2アプリのtokenを登録したシークレット名です（手順2でメモした値）
TARGET_MODEL_IDa1234567890b2345678901c3Craft RAGに同期する対象のCraft Cross CMS モデルIDです（手順3でメモした値）
CMS_CONTENT_FIELDStitle,content,categoryRAGファイルに含めるCMS側フィールド名をカンマ区切りで指定します
SITE_NAMEmy-rag-siteCraft Sitesのサイト名です（手順4で作成したサイト名）
SITE_DIR_PATH/rag/Craft Sitesサイト側でファイルをアップロードしたい対象のディレクトリパスです
RAG_CORPUS_ID1234567890123456789Craft RAGのコーパスIDです（手順5でメモした値）
  • 適当なファンクション名をつけて [デプロイ] します

なお、テンプレートのソースコードはGitHubで公開しています。

craft-codes/craft-functions/xcms-hook-to-rag at main · plaidev/craft-codes

7. CMS更新時のHookを設定する

CMSのコンテンツが公開・非公開された際に自動でCraft Functionsを起動するため、作成したAPI v2アプリの設定でHook v2を設定します。

  • [ストア > API v2設定] から作成したアプリを選択します
  • [hook設定 > 編集] をクリックします
  • [トリガー設定] で次のトリガーを追加してください
    • KARTE CMS: コンテンツの公開時
    • KARTE CMS: コンテンツの非公開時
  • [チャネル設定 > Craft > hook status > 有効にする] にチェックを付け、作成したファンクションを選択します
  • アプリ設定を保存します

実際に動かしてみる

実際に動作を確認してみましょう。

「コンテンツ公開時」の動作確認

  • Craft Cross CMSの対象モデルで、コンテンツを新規作成し、公開します

  • 少し待って、Craft SitesとCraft RAGに対応するファイルが追加されることを確認します

「コンテンツ非公開時」の動作確認

  • Craft Cross CMS側で、先ほど作成・公開したコンテンツを下書き状態にします
  • 少し待って、Craft SitesとCraft RAG側の対応するファイルが削除されることを確認します

ちなみにファイル名に使われているCMS側の「コンテンツID」は、コンテンツを「ページとして開く」で開いたときの画面から確認できます

うまく動作しない場合は、ファンクションのログにエラーが出ていないか確認してみてください。

補足

Craft RAGにインポートするファイルのCraft Sites上での公開状態について

Craft Sites上にある個々のファイルは公開/非公開の状態を持っていますが、Craft RAGにインポートするファイルについては、特にCraft Sites上で公開状態になっている必要はありません。あくまでCraft内部の権限でCraft RAGにインポートされるので、対象ファイルが公開されていなくてもRAGへのインポートは可能です。

また、Craft Sites自体がpublicなサイトである必要もありません。「サイトの認証」機能が有効なサイトにアップロードしたファイルについても、Craft RAGにインポートすることが可能です。

まとめ

今回は、Craft Cross CMSで公開したコンテンツを自動でCraft RAGに同期する仕組みをご紹介しました。

Craft Cross CMSを使えば、管理しているコンテンツをAIが参照するナレッジとしてすぐに活用することができます。

ぜひ試してみてください！

Tags: