IBM ai-services v0.2からv0.3へのマイグレーション

Posted at 2026-07-01

はじめに

Open-Source AI Foundationに含まれるai-services の v0.2 から v0.3 へのアップデートは、単純なバイナリの入れ替えでは対応できず、既存アプリケーションのバックアップ・削除・再デプロイというマイグレーション手順が必要です。

本記事では、RAG アプリケーションを例に取り、実際の手順と実行ログ・スクリーンショットをもとにマイグレーションの流れを試しましたので、メモとして記載します。

公式マイグレーションガイドはこちらです。
https://www.ibm.com/docs/ja/aiservices/2026.06.0?topic=services-migration-guide-v020-v030

過去のSpyreに関する記事はこちら

前提環境

ランタイム: Podman
アップデート前: ai-services v0.2（rag テンプレート）
アップデート後: ai-services v0.3.0
アーキテクチャー: ppc64le（IBM Power）

マイグレーション前の稼働状況は以下のとおりです。

# ai-services application info rag-app --runtime podman
Application Name: rag-app
Application Template: rag
Version: 0.0.1
Info:
-------
Day N:

- Q&A Chatbot is available to use at http://xxx.xxx.xxx.xxx:4000.
- Add documents to your RAG application using the Digitize Documents UI: http://xxx.xxx.xxx.xxx:4001.
- Digitize Documents API is available to use at http://xxx.xxx.xxx.xxx:xxxxx.
- Summarize API is available to use at http://xxx.xxx.xxx.xxx:4002.

# ai-services application ps rag-app --runtime podman
 APPLICATION NAME    POD NAME                  STATUS
───────────────────────────────────────────────────────────────────
 rag-app             rag-app--vllm-server      Running (healthy)
                     rag-app--opensearch       Running (healthy)
                     rag-app--clean-docs       Created
                     rag-app--summarize-api    Running (healthy)
                     rag-app--chat-bot         Running (healthy)
                     rag-app--ingest-docs      Created
                     rag-app--digitize         Running (healthy)

バックアップ前の時点では、下の画像のようにいくつかのドキュメントが登録済みの状態でした。

マイグレーション手順の概要

大まかな流れは以下のとおりです。

OpenSearch データのバックアップ
Digitizeのバックアップ
既存アプリケーションの削除
ai-services バイナリを v0.3.0 に更新
bootstrap を実行して環境を再整備
catalog configure でカタログサービスをセットアップ
カタログ経由でアプリケーションを再デプロイ
OpenSearch / Digitize データのリストア

Step 1: OpenSearch のバックアップ

バックアップ用スクリプトを公式リポジトリから取得します。

wget https://raw.githubusercontent.com/IBM/project-ai-services/refs/heads/main/hack/backup-restore/backup-restore.sh
chmod +x backup-restore.sh

OpenSearch のエクスポートを実行します。

./backup-restore.sh export opensearch <app-name> <filename> --runtime <podman|openshift>

リストア時のバックアップファイルには .tar.gz 拡張子が必要です。

実行例:

# ./backup-restore.sh export opensearch rag-app rag-app-backup.tar.gz --runtime podman
============================================================
OpenSearch Export (Sidecar Container Approach)
============================================================
Container: rag-app--opensearch-opensearch
App name: rag-app
Output file: rag-app-backup.tar.gz

ℹ️  Starting sidecar container with Python and opensearch-py...
Trying to pull registry.access.redhat.com/ubi9/python-312-minimal:9.8...
...
ℹ️  Running backup from sidecar...
Connecting to OpenSearch...
✓ Connected to OpenSearch
Found 1 indices
  Exporting index: rag_db_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ✓ 458 documents
✓ Backup created: /tmp/rag-app-backup.tar.gz (1.09 MB)
ℹ️  Copying backup to host...

✅ OpenSearch export completed!
Backup file: rag-app-backup.tar.gz
-rw-r--r--. 1 root root 1.1M Jun 30 20:08 rag-app-backup

バックアップファイルの中身はこのような構成になっています。
バックアップファイルは、tar.gz 形式で圧縮されて保存されており、tarコマンドで展開しています。

backup
├── backup_info.json
└── opensearch
    ├── rag_db_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_data.json
    ├── rag_db_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_mapping.json
    └── rag_db_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_settings.json

Step 2: Digitize データのバックアップ

投入済みドキュメントのバックアップも取得します。

./backup-restore.sh export digitize <app-name> <filename> --runtime <podman|openshift>

実行例:

# ./backup-restore.sh export digitize rag-app rag-app-digitize-backup.tar.gz --runtime podman
============================================================
Digitize Data Export (podman)
============================================================
App name: rag-app
Output file: rag-app-digitize-backup.tar.gz

ℹ️  Backing up /var/cache...
  ✓ Backed up 19 files (3.6M)
ℹ️  Creating backup archive...

✅ Digitize data export completed!
Backup file: rag-app-digitize-backup.tar.gz
-rw-r--r--. 1 root root 368K Jun 30 20:10 rag-app-digitize-backup

Digitize バックアップのファイル構成は以下のとおりです。

backup
└── cache
    ├── digitized/
    ├── docs/
    ├── jobs/
    └── staging/

公式ドキュメントには、以下の注意書きがありますので、容量や中身を確認するのがよいと思います。

バックアップが正常に作成され、空でないことを確認してから次のステップに進んでください。有効なバックアップがない状態で既存のアプリケーションを削除すると、データが永久に失われる可能性があります。

Step 3: 既存アプリケーションの削除

バックアップが確認できたら既存のアプリを削除します。削除確認のプロンプトで Yes と応答すると処理が進みます。

# ai-services application delete rag-app --runtime podman
Found 7 pods for given applicationName: rag-app.
Below are the list of pods to be deleted
    -> rag-app--vllm-server
    -> rag-app--opensearch
    -> rag-app--clean-docs
    -> rag-app--summarize-api
    -> rag-app--chat-bot
    -> rag-app--ingest-docs
    -> rag-app--digitize
Are you sure you want to delete the above pods and application data?  true
Proceeding with deletion...
...
Application data cleaned up successfully

Step 4: ai-services バイナリの更新

v0.3.0 のバイナリ（ppc64le 向け）をダウンロードして配置します。

curl -Lo ./ai-services https://github.com/IBM/project-ai-services/releases/download/v0.3.0/ai-services-linux-ppc64le
chmod +x ai-services
mv ai-services /usr/local/bin/

上書き確認が出た場合は y で応答してください。

Step 5: bootstrap の実行

バイナリ更新後、bootstrap を実行して環境を整備します。

ai-services bootstrap --runtime podman

実行中に VFIO や SELinux の設定不備が検出されることがありますが、bootstrap が自動修正してくれます。

✓ Fixed: VFIO udev rules configuration
✓ Fixed: VFIO device permission
✓ Fixed: SELinux VFIO policy configuration
✓ Fixed: Podman service SupplementaryGroups configuration
✔ Spyre cards configuration validated successfully.
...
LPAR bootstrapped successfully

Step 6: catalog configure の実行

v0.3.0 では、アプリケーション管理にカタログ経由とCLIの両方を選択することができます。
今回は、新しく追加されたカタログ経由で実施してみます。

catalog configure でカタログサービスをセットアップします。

ai-services catalog configure --runtime podman

実行すると管理者パスワードの入力を求められます。このパスワードは後の catalog login やカタログ UI へのアクセスに使用するため、安全な場所に保管してください。

セットアップが完了すると、カタログ UI と API へのアクセス情報が表示されます。

✔ Catalog service deployed successfully
Next Steps:
- Access the Catalog UI at https://catalog-ui.xxx.xxx.xxx.xxx.nip.io
- Access the Catalog Backend at https://catalog-api.xxx.xxx.xxx.xxx.nip.io

カタログ UI にアクセスすると、デジタルアシスタントの管理ページが表示されます。

Services ページでは現在のデプロイ状況を確認できます。

カタログのページでは利用可能なサービスが一覧表示されます。

Step 7: アプリケーションの再デプロイ

カタログ UI からデジタルアシスタント（RAG アプリケーション）を再デプロイします。

デプロイ画面でアプリケーションの設定を行います。
デジタルアシスタントの管理ページにある、Deployボタンからデプロイ画面に移動できます。

各サービスの構成を変更・確認することができます。

各サービスのカスタマイズも可能です。vLLM サーバーのモデルや OpenSearch のインデックス設定などをここで調整できます。
現在は、IBM Spyreを使う構成の場合は表示されているモデルのみ選択できるようでした。
このバージョンからバックエンドに watsonx.ai を選択できるようにもなっています。

設定が完了したらデプロイを実行します。

デプロイが完了しました。

デプロイ完了後の詳細情報も確認できます。

デプロイ直後は Digitize にドキュメントが登録されていない初期状態です。次のステップでリストアを行います。

実際にDigitizeサービスのUIを開いてみると、何も登録されていない状態です。

Step 8: データのリストア

カタログへのログイン

リストア操作の前に、カタログへログインします。

ai-services catalog login --runtime podman --server <catalog-api-url> --username <user-name> --insecure

--insecure オプションは TLS 証明書の検証をスキップします。本番環境では使用せず、適切な証明書を設定してください。

# ai-services catalog login --runtime podman \
    --server https://catalog-api.xxx.xxx.xxx.xxx.nip.io \
    --username admin --insecure
Password:
WARNING: TLS certificate verification is disabled. This should NOT be used in production environments.
Login successful.

OpenSearch のリストア

リストアを実行します。アプリ名は v0.3.0 のカタログ上の名前を指定します（ここでは "Digital assistant"）。

ai-services application restore "Digital assistant" \
    --target opensearch \
    --filename rag-app-backup.tar.gz \
    --runtime podman

Starting restore for application: Digital assistant
Target: opensearch
...
Found 1 indices to restore
  Restoring index: rag_db_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ✓ Index restored successfully
✓ Restore completed successfully. Restored 1 indices
✓ Restore completed successfully for application Digital assistant

Digitize のリストア

同様に Digitize データをリストアします。

ai-services application restore "Digital assistant" \
    --target digitize \
    --filename rag-app-digitize-backup.tar.gz \
    --runtime podman

Starting restore for application: Digital assistant
Target: digitize
...
Import summary:
  Jobs - imported: 5, skipped: 0, failed: 0
  Documents - imported: 6, skipped: 0, failed: 0
Import completed with 1 warning(s)
✓ Digitize metadata restore completed successfully
✓ Restore completed successfully for application Digital assistant

リストアが完了すると、Digitize の UI でも登録済みドキュメントが確認できます。

v0.2 から v0.3 での変更点

マイグレーションを通じて気になった主な変更点をまとめておきます。

観点	v0.2	v0.3
アプリ管理	`ai-services application` コマンドのみ	カタログ UI / コマンド経由(カタログへのログインが必要)
エンドポイント形式	ポート番号（例: `:4000`）	URL ベース（例: `https://xxxxx.xxx.nip.io`）

特にエンドポイントの変更は、アプリケーションから ai-services の各サービスを呼び出している場合に影響します。

まとめ

v0.2 → v0.3 のマイグレーションは手順が多いですが、公式スクリプトのおかげでバックアップ・リストアはスムーズに進められました。

ポイントをまとめると:

バックアップは必ず backup-restore.sh で取得してから削除に進む
バイナリ更新後は bootstrap と catalog configure の両方を実行する
catalog configure 実行時に設定した管理者パスワードを保管しておく
リストア時のアプリ名は v0.3.0 のカタログ上の名前（今回は "Digital assistant"）を使用する
バックアップファイルは .tar.gz 拡張子をつける必要あり

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up