Skip to content

Latest commit

 

History

History
93 lines (61 loc) · 9.21 KB

V1_TO_V2_ja-JP.md

File metadata and controls

93 lines (61 loc) · 9.21 KB

マイグレーションガイド (v1 から v2)

要約

  • v1.2以前のユーザー向け: v1.4にアップグレードし、ナレッジベース（KB）を使用してボットを再作成してください。移行期間後、すべてがKBで正常に動作することを確認したら、v2にアップグレードしてください。
  • v1.3ユーザー向け: すでにKBを使用している場合でも、v1.4にアップグレードしてボットを再作成することを強く推奨します。pgvectorを使用している場合は、v1.4のKBを使用してボットを再作成することで移行してください。
  • pgvectorの使用を継続するユーザー向け: pgvectorの使用を続ける予定の場合、v2へのアップグレードは推奨されません。v2へのアップグレードにより、pgvectorに関連するすべてのリソースが削除され、今後のサポートは利用できなくなります。この場合は、v1を引き続き使用してください。
  • **v2へのアップグレードにより、Aurora関連のすべてのリソースが削除されることに注意してください。**今後の更新はv2に焦点を当て、v1は廃止されます。

はじめに

何が起こるか

v2アップデートでは、Aurora ServerlessとECSベースの埋め込みで使用されていたpgvectorを、Amazon Bedrock ナレッジベースに置き換えるという大きな変更が導入されます。この変更は後方互換性がありません。

なぜこのリポジトリがナレッジベースを採用し、pgvectorを廃止したのか

この変更には、いくつかの理由があります：

改善されたRAG精度

  • ナレッジベースはバックエンドにOpenSearch Serverlessを使用し、フルテキストとベクター検索の両方によるハイブリッド検索を可能にします。これにより、固有名詞を含む質問に対する応答の精度が向上し、pgvectorが苦手としていた部分を改善します。
  • また、高度なチャンキングやパースなど、RAG精度を向上させるさらなるオプションをサポートしています。
  • ナレッジベースは2024年10月時点で、ほぼ1年間一般提供されており、Webクローリングなどの機能がすでに追加されています。将来的な更新が期待され、長期的に高度な機能を採用しやすくなっています。例えば、このリポジトリではpgvectorで既存のS3バケットからのインポート（頻繁にリクエストされる機能）を実装していませんが、ナレッジベース（KB）ではすでにサポートされています。

メンテナンス

  • 現在のECS + Auroraセットアップは、PDFパース、Webクローリング、YouTubeトランスクリプト抽出などの多数のライブラリに依存しています。一方、ナレッジベースのようなマネージドソリューションは、ユーザーとリポジトリ開発チームの両方にとって、メンテナンスの負担を軽減します。

移行プロセス（要約）

v2に移行する前に、v1.4にアップグレードすることを強くお勧めします。v1.4では、pgvectorとナレッジベースボットの両方を使用でき、既存のpgvectorボットをナレッジベースに再作成し、期待通りに動作することを確認するための移行期間を設けることができます。RAGドキュメントが同一のままでも、OpenSearchのバックエンドの変更により、k-NNアルゴリズムなどの違いにより、結果が若干異なる可能性があることに注意してください。ただし、通常は非常に類似しています。

cdk.jsonでuseBedrockKnowledgeBasesForRagをtrueに設定することで、ナレッジベースを使用してボットを作成できます。ただし、pgvectorボットは読み取り専用になり、新しいpgvectorボットの作成や編集ができなくなります。

v1.4では、Amazon Bedrockのガードレールも導入されています。ナレッジベースの地域制限により、ドキュメントをアップロードするS3バケットはbedrockRegionと同じリージョンである必要があります。更新前に既存のドキュメントバケットをバックアップすることをお勧めします。これにより、後で大量のドキュメントを手動でアップロードする必要がなくなります（S3バケットのインポート機能が利用可能です）。

マイグレーションプロセス（詳細）

ステップは、v1.2以前のバージョンを使用しているか、v1.3を使用しているかによって異なります。

v1.2以前のユーザー向けステップ

  1. 既存のドキュメントバケットをバックアップ（オプションだが推奨）。 システムが既に稼働している場合、このステップを強くお勧めします。bedrockchatstack-documentbucketxxxx-yyyyという名前のバケットをバックアップします。例えば、AWS バックアップを使用できます。

  2. v1.4に更新: 最新のv1.4タグを取得し、cdk.jsonを変更して、デプロイします。以下の手順に従ってください：

    1. 最新のタグを取得： 
      git fetch --tags
git checkout tags/v1.4.0
    2. cdk.jsonを以下のように変更： 
      {
  ...,
  "useBedrockKnowledgeBasesForRag": true,
  ...
}
    3. 変更をデプロイ： 
      npx cdk deploy

  3. ボットの再作成: Knowledge Baseで、pgvectorボットと同じ定義（ドキュメント、チャンクサイズなど）でボットを再作成します。ドキュメントの量が多い場合、ステップ1のバックアップから復元すると、このプロセスが容易になります。復元には、クロスリージョンコピーの復元を使用できます。詳細はこちらを参照してください。復元されたバケットを指定するには、S3 データソースセクションを以下のように設定します。パス構造は s3://<bucket-name>/<user-id>/<bot-id>/documents/ です。ユーザーIDはCognitoユーザープールで、ボットIDはボット作成画面のアドレスバーで確認できます。

Knowledge BaseではウェブクローリングやYouTubeトランスクリプトのサポートなど、一部の機能が利用できないことに注意してください（ウェブクローラーのサポートを計画中 (issue))。 また、移行中はAuroraとKnowledge Baseの両方の料金が発生することに注意してください。

  1. 公開されたAPIの削除: VPCの削除により、以前に公開されたすべてのAPIをv2をデプロイする前に再公開する必要があります。そのためには、まず既存のAPIを削除する必要があります。管理者のAPI管理機能を使用すると、このプロセスを簡略化できます。すべてのAPIPublishmentStackXXXX CloudFormationスタックの削除が完了すると、環境の準備が整います。

  2. v2のデプロイ: v2のリリース後、タグ付けされたソースを取得し、以下のようにデプロイします（リリース後に可能になります）：

    git fetch --tags
git checkout tags/v2.0.0
npx cdk deploy

Warning

v2をデプロイした後、[サポート対象外、読み取り専用]の接頭辞が付いたすべてのボットは非表示になります。 アップグレード前に必要なボットを再作成し、アクセスの喪失を防いでください。

Tip

スタックの更新中、「リソースハンドラーがメッセージを返しました：『サブネット 'subnet-xxx' は依存関係があるため削除できません。』」のような繰り返しのメッセージが表示される場合があります。そのような場合は、管理コンソール > EC2 > ネットワークインターフェースに移動し、BedrockChatStackを検索します。表示されたインターフェースを削除して、デプロイプロセスをよりスムーズにします。

v1.3のユーザー向けステップ

前述のように、v1.4では、リージョンの制限により、Knowledge BaseはbedrockRegionで作成する必要があります。そのため、Knowledge Baseを再作成する必要があります。v1.3で既にKBをテストしている場合は、v1.4で同じ定義でボットを再作成してください。v1.2ユーザー向けに概説されている手順に従ってください。