` にオブジェクトが作成されると、[Amazon S3 の通知](https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventNotifications.html)により Lambda 関数 `data-ingestion-processor` が呼び出されます。
1. Lambda 関数 `data-ingestion-processor` は、Amazon Elastic Container Registry (Amazon ECR) リポジトリ `bedrock-rag-template` に保存されている Docker イメージに基づいています。
関数は [LangChain S3FileLoader](https://python.langchain.com/v0.1/docs/integrations/document_loaders/aws_s3_file/) を使用して、ファイルを [LangChain ドキュメント](https://api.python.langchain.com/en/v0.0.339/schema/langchain.schema.document.Document.html)として読み取ります。次に、[LangChain RecursiveCharacterTextSplitter](https://python.langchain.com/v0.1/docs/modules/data_connection/document_transformers/recursive_text_splitter/) は、Amazon Titan Text Embedding V2 埋め込みモデルの最大トークンサイズに依存する `CHUNK_SIZE` と `CHUNK_OVERLAP` を指定して、各ドキュメントをチャンク化します。次に、Lambda 関数は Amazon Bedrock の埋め込みモデルを呼び出して、チャンクを数値ベクトル表現に埋め込みます。最後に、これらのベクトルが Aurora PostgreSQL データベースに保存されます。データベースにアクセスするには、Lambda 関数がまずユーザー名とパスワードを取得します AWS Secrets Manager。
1. Amazon SageMaker AI [ノートブックインスタンス](https://docs.aws.amazon.com/sagemaker/latest/dg/nbi.html) `aws-sample-bedrock-rag-template` では、ユーザーは質問プロンプトを記述できます。このコードは Amazon Bedrock で Claude 3 を呼び出し、ナレッジベース情報をプロンプトのコンテキストに追加します。その結果、Claude 3 はドキュメント内の情報を使用してレスポンスを提供します。
ネットワークとセキュリティに対するこのパターンのアプローチは次のとおりです。
+ Lambda 関数 `data-ingestion-processor` は、仮想プライベートクラウド (VPC) 内のプライベートサブネットにあります。Lambda 関数は、セキュリティグループのため、パブリックインターネットにトラフィックを送信することはできません。そのため、Amazon S3 と Amazon Bedrock へのトラフィックは VPC エンドポイントを介してのみルーティングされます。したがって、トラフィックはパブリックインターネットを経由しないため、レイテンシーが短縮され、ネットワークレベルでセキュリティレイヤーが追加されます。
+ すべてのリソースとデータは、該当する場合、エイリアス で AWS Key Management Service (AWS KMS) キーを使用して暗号化されます`aws-sample/bedrock-rag-template`。
**自動化とスケール**
このパターンでは、Terraform を使用してコードリポジトリから AWS アカウントにインフラストラクチャをデプロイします。
## ツール
**AWS のサービス**
+ 「[Amazon Aurora PostgreSQL 互換エディション](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.AuroraPostgreSQL.html)」は、PostgreSQL デプロイのセットアップ、運用、スケーリングに役立つ、フルマネージド型の ACID 準拠のリレーショナルデータベースエンジンです。このパターンでは、Aurora PostgreSQL 互換は pgvector プラグインをベクトルデータベースとして使用します。
+ [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) は、主要な AI スタートアップや Amazon が提供する高パフォーマンスな基盤モデル (FM) を、統合 API を通じて利用できるようにするフルマネージド型サービスです。
+ [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) は、コマンドラインシェルのコマンド AWS のサービス を使用して を操作するのに役立つオープンソースツールです。
+ [Amazon Elastic Container Registry (Amazon ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) は、セキュリティ、スケーラビリティ、信頼性を備えたマネージドコンテナイメージレジストリサービスです。このパターンでは、Amazon ECR は `data-ingestion-processor` Lambda 関数用に Docker イメージをホストします。
+ [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) は、リソースの使用を認証および認可されたユーザーを制御することで、 AWS リソースへのアクセスを安全に管理できます。
+ [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) は、データの保護に効果的な暗号キーを作成および管理する上で役立ちます。
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。このパターンでは、Lambda はデータをベクトルストアに取り込みます。
+ [Amazon SageMaker AI](https://docs.aws.amazon.com/sagemaker/?id=docs_gateway) はマネージド型の機械学習 (ML) サービスで、ML モデルの構築とトレーニングを行い、それらを本番稼働環境に対応したホスティング環境にデプロイします。
+ [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) を使用すると、コード内のハードコードされた認証情報 (パスワードを含む) を Secrets Manager への API コールで置き換えて、プログラムでシークレットを取得することができます。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) は、あらゆる量のデータを保存、保護、取得できるクラウドベースのオブジェクトストレージサービスです。
+ [Amazon Virtual Private Cloud (Amazon VPC)](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) は、定義した仮想ネットワークに AWS リソースを起動するのに役立ちます。この仮想ネットワークは、ユーザー自身のデータセンターで運用されていた従来のネットワークと似ていますが、 AWSのスケーラブルなインフラストラクチャを使用できるという利点があります。VPC には、トラフィックフローを制御するためのサブネットとルーティングテーブルが含まれています。
**その他のツール**
+ [Docker](https://docs.docker.com/manuals/) は、オペレーティングシステムレベルの仮想化を使用してソフトウェアをコンテナで配信するサービスとしての Platform as a Service (PaaS) 製品のセットです。
+ [HashiCorp Terraform](https://www.terraform.io/docs) は、コードを使用してクラウドインフラストラクチャとリソースをプロビジョニングして管理するのに役立つ infrastructure as code (IaC) ツールです。
+ [Poetry](https://pypi.org/project/poetry/) は、Python での依存関係の管理とパッケージングのためのツールです。
+ 「[Python](https://www.python.org/)」は汎用のコンピュータプログラミング言語です。
**コードリポジトリ**
このパターンのコードは、GitHub の [terraform-rag-template-using-amazon-bedrock](https://github.com/aws-samples/terraform-rag-template-using-amazon-bedrock) リポジトリで利用できます。
## ベストプラクティス
+ このコードサンプルは任意の にデプロイできますが AWS リージョン、米国東部 (バージニア北部) – `us-east-1`または米国西部 (北カリフォルニア) – を使用することをお勧めします`us-west-1`。この推奨事項は、このパターンの公開時点での Amazon Bedrock での基盤モデルと埋め込みモデルの可用性に基づくものです。での Amazon Bedrock 基盤モデルサポートup-to-dateリストについては AWS リージョン、Amazon Bedrock ドキュメントの「 [によるモデルサポート AWS リージョン](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html)」を参照してください。このコードサンプルを他のリージョンにデプロイする方法については、「[追加情報](#deploy-rag-use-case-on-aws-additional)」を参照してください。
+ このパターンは、概念実証 (PoC) またはパイロットデモのみを提供します。コードを本番環境に移行する場合は、次のベストプラクティスに従ってください。
+ Amazon S3 のサーバーアクセスログを有効にします。
+ Lambda 関数の[モニタリングとアラート](https://docs.aws.amazon.com/lambda/latest/dg/lambda-monitoring.html)を設定します。
+ ユースケースで API が必要な場合は、取得タスクと質疑応答タスクを実行する Lambda 関数を使用して Amazon API Gateway を追加することを検討してください。
+ 最小特権の原則に従い、タスクの実行に必要最小限の権限を付与します。詳細については、IAM ドキュメントの「[最小限の特権を認める。](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#grant-least-priv)」と「[IAM でのセキュリティのベストプラクティス](https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPracticesAndUseCases.html)」を参照してください。
## エピック
### ソリューションを にデプロイする AWS アカウント
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| リポジトリのクローン作成 | このパターンの GitHub リポジトリをクローン作成するには、以下のコマンドを実行します。git clone https://github.com/aws-samples/terraform-rag-template-using-amazon-bedrock
| AWS DevOps |
| 変数を設定します。 | このパターンのパラメータを設定するには、以下を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-rag-use-case-on-aws.html) | AWS DevOps |
| ソリューションのデプロイ | ソリューションを展開するには、次を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-rag-use-case-on-aws.html)インフラストラクチャのデプロイでは、VPC 内に SageMaker AI インスタンスをプロビジョニングし、Aurora PostgreSQL データベースにアクセスするアクセス許可を付与します。 | AWS DevOps |
### ソリューションをテストする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| デモを実行する。 | 以前のインフラストラクチャのデプロイが成功したら、次のステップに従って Jupyter Notebook でデモを実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-rag-use-case-on-aws.html)Jupyter Notebook では、以下のプロセスがガイドされます。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-rag-use-case-on-aws.html) | AWS 全般 |
### インフラストラクチャをクリーンアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| インフラストラクチャをクリーンアップします。 | 不要になったときに、作成したすべてのリソースを削除するには、次のコマンドを実行します。terraform destroy -var-file=commons.tfvars
| AWS DevOps |
## 関連リソース
**AWS リソース**
+ [Python で Lambda 関数を構築する](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html)
+ [基盤モデルの推論パラメータ](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html)
+ [Amazon Bedrock 基盤モデルへのアクセス](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)
+ [生成 AI アプリケーションにおけるベクトルデータベースの役割](https://aws.amazon.com/blogs/database/the-role-of-vector-datastores-in-generative-ai-applications/) (AWS データベースブログ)
+ [Amazon Aurora PostgreSQL の操作](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.AuroraPostgreSQL.html)
**その他のリソース**
+ [pgvector ドキュメント](https://github.com/pgvector/pgvector)
## 追加情報
**ベクトルデータベースの実装**
このパターンでは、Aurora PostgreSQL 互換を使用して RAG のベクトルデータベースを実装します。Aurora PostgreSQL の代わりに、 は Amazon Bedrock ナレッジベースや Amazon OpenSearch Service など、RAG の他の機能やサービス AWS を提供します。特定の要件に最適なソリューションを選択できます。
+ [Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/what-is.html) は、大量のデータを格納およびクエリするために使用できる分散型の検索および分析エンジンを備えています。
+ [Amazon Bedrock ナレッジベース](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)は、RAG の取り込みおよび取得プロセスを簡素化するための追加の抽象化としてナレッジベースを構築およびデプロイするように設計されています。Amazon Bedrock ナレッジベースは、Aurora PostgreSQL と Amazon OpenSearch Service の両方と一緒に使用できます。
**他の へのデプロイ AWS リージョン**
[アーキテクチャ](#deploy-rag-use-case-on-aws-architecture)で説明されているように、このコードサンプルをデプロイするには、米国東部 (バージニア北部) リージョン – `us-east-1` または米国西部 (北カリフォルニア) リージョン – `us-west-1` を使用することをお勧めします。ただし、このコードサンプルを `us-east-1`および `us-west-1` 以外のリージョンにデプロイするには、2 つの方法があります。`commons.tfvars` ファイルでデプロイリージョンを設定できます。クロスリージョン基盤モデルにアクセスするには、次のオプションを検討してください。
+ **パブリックインターネットを経由する** – トラフィックがパブリックインターネットを経由できる場合は、VPC にインターネットゲートウェイを追加します。次に、Lambda 関数 `data-ingestion-processor` と SageMaker AI ノートブックインスタンスに割り当てられたセキュリティグループを調整して、パブリックインターネットへのアウトバウンドトラフィックを許可します。
+ **パブリックインターネットを経由しない** – このサンプルを `us-east-1` または `us-west-1` 以外のリージョンにデプロイするには、次の手順を実行します。
1. `us-east-1` または `us-west-1` リージョンのいずれかで、`bedrock-runtime` の VPC エンドポイントを含む追加の VPC を作成します。
1. アプリケーション VPC への [VPC ピアリング](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html)または[トランジットゲートウェイ](https://docs.aws.amazon.com/vpc/latest/tgw/tgw-peering.html)を使用して、ピアリング接続を作成します。
1. `us-east-1` または `us-west-1` の外部で Lambda 関数で `bedrock-runtime` boto3 クライアントを設定する場合は、`us-east-1` または us-west-1 用の `bedrock-runtime` の VPC エンドポイントのプライベート DNS 名を `endpoint_url` として boto3 クライアントに渡します。
# Amazon SageMaker の推論パイプラインを使用して、前処理ロジックを単一エンドポイントの ML モデルにデプロイする
*Mohan Gowda Purushothama、Gabriel Rodriguez Garcia、Mateusz Zaremba、Amazon Web Services*
## 概要
このパターンでは、Amazon SageMaker の[推論パイプライン](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipelines.html)を使用して 1 つのエンドポイントに複数のパイプラインモデルオブジェクトをデプロイする方法を説明します。パイプラインモデルオブジェクトは、前処理、モデル推論、後処理など、さまざまな機械学習 (ML) ワークフローステージを表します。このパターンでは、シリアル接続されたパイプラインモデルオブジェクトのデプロイを説明するために、SageMaker に組み込まれている[線形学習アルゴリズム](https://docs.aws.amazon.com/sagemaker/latest/dg/linear-learner.html)に基づく前処理の [Scikit-learn](https://docs.aws.amazon.com/sagemaker/latest/dg/sklearn.html) コンテナとリグレッションモデルをデプロイする方法を示します。デプロイメントは SageMaker の単一のエンドポイントの背後でホストされます。
**注記**
このパターンのデプロイメントは ml.m4.2xlarge インスタンスタイプを使用します。データサイズの要件とワークフローの複雑さに合ったインスタンスタイプを使用することをお勧めします。詳細については、「[Amazon SageMaker の料金](https://aws.amazon.com/sagemaker/pricing/)」を参照してください。このパターンでは [Scikit-Learn 用にビルド済みの Docker イメージ](https://docs.aws.amazon.com/sagemaker/latest/dg/pre-built-docker-containers-scikit-learn-spark.html)を使用しますが、独自の Docker コンテナを使用してワークフローに統合することもできます。
## 前提条件と制限事項
**前提条件**
+ アクティブな AWS アカウント
+ [Python 3.9](https://www.python.org/downloads/release/python-390/)
+ [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable/) と [Boto3 ライブラリ](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
+ 基本的な SageMaker [権限](https://docs.aws.amazon.com/sagemaker/latest/dg/api-permissions-reference.html)と Amazon Simple Storage Service (Amazon S3) [権限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html)を持つ AWS Identity and Access Management (AWS IAM) [ロール](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)
**製品バージョン**
+ [Amazon SageMaker Python SDK 2.49.2](https://sagemaker.readthedocs.io/en/v2.49.2/)
## アーキテクチャ
**ターゲットテクノロジースタック**
+ Amazon Elastic Container Registry (Amazon ECR)
+ Amazon SageMaker
+ Amazon SageMaker Studio
+ Amazon Simple Storage Service (Amazon S3)
+ Amazon SageMaker 用の[リアルタイム推論](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html)エンドポイント
**ターゲットアーキテクチャ**
次の図表は、Amazon SageMaker Pipelines モデルオブジェクトをデプロイするためのアーキテクチャを示します。
![\[SageMaker パイプラインモデルオブジェクトをデプロイするためのアーキテクチャ\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/1105d51b-752f-46d7-962c-acef1fb3399f/images/12f06715-b1c2-4de0-b277-99ce87308152.png)
この図表は、次のワークフローを示しています:
1. SageMaker ノートブックはパイプラインモデルをデプロイします。
1. S3 バケットにはモデルアーティファクトが格納されます。
1. Amazon ECR は S3 バケットからソースコンテナイメージを取得します。
## ツール
**AWS ツール**
+ [Amazon Elastic Container Registry (Amazon ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) は、セキュリティ、スケーラビリティ、信頼性を備えたマネージドコンテナイメージレジストリサービスです。
+ 「[Amazon SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/whatis.html)」 は、ML モデルの構築とトレーニングを行うことができ、それらを稼働準備が整ったホストされている環境にデプロイするのに役立つマネージド型 ML サービスです。
+ [Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio.html) は、ML モデルの構築、トレーニング、デバッグ、デプロイ、モニタリングを可能にする、ウェブベースの ML 用統合開発環境 (IDE) です。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) は、あらゆる量のデータを保存、保護、取得できるクラウドベースのオブジェクトストレージサービスです。
**コード**
このパターンのコードは、GitHub 内の「[Inference Pipeline with Scikit-learn and Linear Learner](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-python-sdk/scikit_learn_inference_pipeline/Inference%20Pipeline%20with%20Scikit-learn%20and%20Linear%20Learner.ipynb)」リポジトリで利用できます。
## エピック
### データセットの準備
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| リグレッションタスク用のデータセットを準備します。 | Amazon SageMaker Studio で[ノートブックを開きます](https://docs.aws.amazon.com/sagemaker/latest/dg/notebooks-create-open.html#notebooks-open)。必要なライブラリをすべてインポートして作業環境を初期化するには、ノートブックで以下のサンプルコードを使用してください。import sagemaker
from sagemaker import get_execution_role
sagemaker_session = sagemaker.Session()
# Get a SageMaker-compatible role used by this Notebook Instance.
role = get_execution_role()
# S3 prefix
bucket = sagemaker_session.default_bucket()
prefix = "Scikit-LinearLearner-pipeline-abalone-example"
サンプルデータセットをダウンロードするには、以下のコードをノートブックに追加します。! mkdir abalone_data
! aws s3 cp s3://sagemaker-sample-files/datasets/tabular/uci_abalone/abalone.csv ./abalone_data
** **このパターンの例では、UCI 機械学習のリポジトリの [Abalone データセット](https://archive.ics.uci.edu/ml/datasets/abalone)を使用しています。 | データサイエンティスト |
| データセットを S3 バケットにアップロードします。 | 先にデータセットを準備したノートブックに、以下のコードを追加してサンプルデータを S3 バケットにアップロードします。WORK_DIRECTORY = "abalone_data"
train_input = sagemaker_session.upload_data(
path="{}/{}".format(WORK_DIRECTORY, "abalone.csv"),
bucket=bucket,
key_prefix="{}/{}".format(prefix, "train"),
)
| データサイエンティスト |
### SKLearn を使用してデータプリプロセッサを作成します。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| preprocessor.py スクリプトを準備します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-preprocessing-logic-into-an-ml-model-in-a-single-endpoint-using-an-inference-pipeline-in-amazon-sagemaker.html) | データサイエンティスト |
| SKLearn プリプロセッサオブジェクトを作成します。 | 最終的な推論パイプラインに組み込むことができる SKLearn プリプロセッサオブジェクト (SKLearn Estimator と呼ばれる) を作成するには、SageMaker ノートブックで次のコードを実行します。from sagemaker.sklearn.estimator import SKLearn
FRAMEWORK_VERSION = "0.23-1"
script_path = "sklearn_abalone_featurizer.py"
sklearn_preprocessor = SKLearn(
entry_point=script_path,
role=role,
framework_version=FRAMEWORK_VERSION,
instance_type="ml.c4.xlarge",
sagemaker_session=sagemaker_session,
)
sklearn_preprocessor.fit({"train": train_input})
| データサイエンティスト |
| プリプロセッサの推論をテストします。 | プリプロセッサが正しく定義されていることを確認するには、SageMaker ノートブックに次のコードを入力して[バッチ変換ジョブ](https://docs.aws.amazon.com/sagemaker/latest/dg/batch-transform.html)を起動します。# Define a SKLearn Transformer from the trained SKLearn Estimator
transformer = sklearn_preprocessor.transformer(
instance_count=1, instance_type="ml.m5.xlarge", assemble_with="Line", accept="text/csv"
)
# Preprocess training input
transformer.transform(train_input, content_type="text/csv")
print("Waiting for transform job: " + transformer.latest_transform_job.job_name)
transformer.wait()
preprocessed_train = transformer.output_path
| |
### 機械学習モデルを作成する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| モデルオブジェクトを作成します。 | 線形学習器アルゴリズムに基づいてモデルオブジェクトを作成するには、SageMaker ノートブックに次のコードを入力します。import boto3
from sagemaker.image_uris import retrieve
ll_image = retrieve("linear-learner", boto3.Session().region_name)
s3_ll_output_key_prefix = "ll_training_output"
s3_ll_output_location = "s3://{}/{}/{}/{}".format(
bucket, prefix, s3_ll_output_key_prefix, "ll_model"
)
ll_estimator = sagemaker.estimator.Estimator(
ll_image,
role,
instance_count=1,
instance_type="ml.m4.2xlarge",
volume_size=20,
max_run=3600,
input_mode="File",
output_path=s3_ll_output_location,
sagemaker_session=sagemaker_session,
)
ll_estimator.set_hyperparameters(feature_dim=10, predictor_type="regressor", mini_batch_size=32)
ll_train_data = sagemaker.inputs.TrainingInput(
preprocessed_train,
distribution="FullyReplicated",
content_type="text/csv",
s3_data_type="S3Prefix",
)
data_channels = {"train": ll_train_data}
ll_estimator.fit(inputs=data_channels, logs=True)
上記のコードでは、パブリック Amazon ECR レジストリからモデルの関連する Amazon ECR Docker イメージを取得し、推定オブジェクトを作成し、そのオブジェクトを使用してリグレッションモデルをトレーニングします。 | データサイエンティスト |
### 最後のパイプラインをデプロイする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| パイプラインモデルをデプロイします。 | パイプラインモデルオブジェクト (つまり、プリプロセッサオブジェクト) を作成してオブジェクトをデプロイするには、SageMaker ノートブックに次のコードを入力します。from sagemaker.model import Model
from sagemaker.pipeline import PipelineModel
import boto3
from time import gmtime, strftime
timestamp_prefix = strftime("%Y-%m-%d-%H-%M-%S", gmtime())
scikit_learn_inferencee_model = sklearn_preprocessor.create_model()
linear_learner_model = ll_estimator.create_model()
model_name = "inference-pipeline-" + timestamp_prefix
endpoint_name = "inference-pipeline-ep-" + timestamp_prefix
sm_model = PipelineModel(
name=model_name, role=role, models= [scikit_learn_inferencee_model, linear_learner_model]
)
sm_model.deploy(initial_instance_count=1, instance_type="ml.c4.xlarge", endpoint_name=endpoint_name)
モデルオブジェクトで使用されるインスタンスタイプは、必要に応じて調整できます。 | データサイエンティスト |
| 推論をテストします。 | エンドポイントが正しく動作していることを確認するには、SageMaker ノートブックで以下のサンプル推論コードを実行します。from sagemaker.predictor import Predictor
from sagemaker.serializers import CSVSerializer
payload = "M, 0.44, 0.365, 0.125, 0.516, 0.2155, 0.114, 0.155"
actual_rings = 10
predictor = Predictor(
endpoint_name=endpoint_name, sagemaker_session=sagemaker_session, serializer=CSVSerializer()
)
print(predictor.predict(payload))
| データサイエンティスト |
## 関連リソース
+ [Preprocess input data before making predictions using Amazon SageMaker inference pipelines and Scikit-learn](https://aws.amazon.com/blogs/machine-learning/preprocess-input-data-before-making-predictions-using-amazon-sagemaker-inference-pipelines-and-scikit-learn/) (AWS 機械学習のブログ)
+ [End to end Machine Learning with Amazon SageMaker](https://github.com/aws-samples/amazon-sagemaker-build-train-deploy) (GitHub)
# Kiro やその他のコーディングアシスタントで MCP サーバーを使用してリアルタイムのコーディングセキュリティ検証をデプロイする
*Ivan Girardi と Iker Reina Fuente、Amazon Web Services*
## 概要
このパターンでは、3 つの業界標準のセキュリティスキャンツールを統合して包括的なコードセキュリティ分析を提供するモデルコンテキストプロトコル (MCP) サーバーを実装する方法について説明します。サーバーは、AI コーディングアシスタント (Kiro、Amazon Q Developer、Cline など) がコードスニペットとInfrastructure as Code (IaC) 設定を自動的にスキャンできるようにします。これらのスキャンにより、コーディングアシスタントはセキュリティの脆弱性、設定ミス、コンプライアンス違反を特定するのに役立ちます。
何百万ものコードスニペットでトレーニングされた AI コードジェネレーターは、セキュリティの死角を生みます。そのトレーニングデータはどの程度安全ですか? このパターンは、コード生成中のリアルタイムのセキュリティ検証を提供し、デベロッパーがコード化する潜在的なセキュリティ問題を特定して理解するのに役立ちます。このアプローチは、開発者が直接的な脆弱性と依存関係から継承されたリスクの両方に対処するのに役立ちます。AI 効率とセキュリティコンプライアンスのギャップを埋めることで、このパターンは AI を活用した開発ツールを安全に導入するのに役立ちます。
このパターンは、組織が AI 支援のコーディングツールを使用して開発セキュリティプラクティスを強化し、複数のプログラミング言語とインフラストラクチャ定義にわたって継続的なセキュリティスキャン機能を提供するのに役立ちます。このソリューションは、次のツールの機能を組み合わせています。
+ Terraform、、Kubernetes マニフェストなどの IaC AWS CloudFormationファイルをスキャンするための Checkov
+ Python、JavaScript、Java などの複数のプログラミング言語を分析するための Semgrep
+ 特殊な Python セキュリティスキャン用の Bandit
このソリューションの主な機能は次のとおりです。
+ 新しいコードセグメントのデルタスキャンによる計算オーバーヘッドの削減
+ 分離されたセキュリティツール環境、クロスツールの汚染の防止
+ AI コーディングアシスタント (Kiro、Amazon Q Developer、Cline など) とのシームレスな統合
+ コード生成中のリアルタイムのセキュリティフィードバック
+ 組織コンプライアンスのためのカスタマイズ可能なスキャンルール
このパターンは、標準化されたレスポンス形式でセキュリティスキャン用の統合インターフェイスを提供するため、セキュリティチェックを開発ワークフローに簡単に統合できます。このパターンでは、Python と MCP フレームワークを使用して、自動化されたセキュリティフィードバックを提供します。このアプローチは、開発者が開発プロセスの早い段階でセキュリティ問題を特定して対処し、詳細な検出結果を通じてセキュリティのベストプラクティスを学ぶのに役立ちます。
## 前提条件と制限
**前提条件**
+ これらのコーディングアシスタントのいずれかを使用する場合、Kiro または Amazon Q Developer を使用するためのアクセス権 AWS アカウント を持つアクティブな 。
+ Python バージョン 3.10 以降[がインストールされている](https://www.python.org/downloads/)
+ `uv` パッケージマネージャー[のインストール](https://docs.astral.sh/uv/getting-started/installation/)
+ セキュリティスキャンのツールと概念に精通している
+ IaC とアプリケーションセキュリティの基本的な理解
**制限事項**
+ バンディットスキャンは Python ファイルのみに制限されます。
+ リアルタイムスキャンは、大規模なコードベースのパフォーマンスに影響を与える可能性があります。
+ ツール固有の制限は、サポートされているファイル形式と言語に基づいています。
+ セキュリティの検出結果を検証するには、手動によるレビューが必要です。
+ セキュリティスキャンの結果には、適切な解釈のためのセキュリティの専門知識が必要です。
+ 一部の AWS のサービス は では使用できません AWS リージョン。利用可能なリージョンについては、「[AWS サービス (リージョン別)](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)」を参照してください。特定のエンドポイントについては、「[サービスエンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)」を参照して、サービスのリンクを選択してください。
**製品バージョン**
+ Python バージョン 3.10 以降
+ Checkov バージョン 3.0.0 以降
+ Semgrep バージョン 1.45.0 以降
+ Bandit バージョン 1.7.5 以降
+ MCP[cli] バージョン 1.11.0 以降
+ Pydantic バージョン 1.10.0 以降
+ Loguru バージョン 0.6.0 以降
## アーキテクチャ
このソリューション用のアーキテクチャを次の図に示します。
![\[AI アシスタントはコードを MCP セキュリティスキャナーサーバーに送信して、特殊なスキャナーにルーティングします。スキャン結果は開発者に送信されます。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/fa623544-4d54-48af-a4e4-9b6a0624e776/images/9c881f95-76d0-40f6-983e-d987fd2097b8.png)
この図表は、次のワークフローを示しています:
1. 開発者は AI アシスタント (Kiro、Cline、Amazon Q Developer、Roo Code など) を使用してコードを生成または分析します。AI アシスタントは、セキュリティスキャンのためにコードを送信します。
1. MCP セキュリティスキャナーサーバーは、IaC ファイルの場合は Checkov、複数のプログラミング言語分析の場合は Semgrep、Python 固有のセキュリティスキャンの場合は Bandit などの適切な専用スキャナーにルーティングしてリクエストを処理します。
1. セキュリティ検出結果、重要度レベル、詳細な説明、推奨される修正を含むスキャナーの結果は、AI アシスタントを通じて開発者に返送されます。
1. 開発者がリアルタイムのセキュリティ検証を受ける継続的なフィードバックループが確立され、AI アシスタントによる自動修正が可能になり、開発中のセキュリティのベストプラクティスが促進されます。
このアーキテクチャは、以下の一般的なセキュリティリスクを軽減します。
+ コマンドインジェクション
+ プロンプトインジェクション
+ パストラバーサル
+ 依存関係攻撃
+ リソースの枯渇
このアーキテクチャは、以下のベストプラクティスを実装することで、これらの一般的なセキュリティリスクを軽減します。
+ ユーザーと AI モデルの入力はすべて一時ファイルに書き込まれます。
+ コマンドラインインターフェイス (CLI) コマンドへの直接入力は提供されません。
+ ファイルシステムへのアクセスは、一時ディレクトリとファイルのみに制限されます。
+ 一時ファイルは自動的にクリーンアップされます。
+ スキャンレスポンスはサニタイズされます。
+ プロセス機能を制限するプロセス分離が適用されます。
+ すべてのスキャンアクティビティがログに記録されます。
**自動化とスケール**
このパターンでは、次の機能による自動化がサポートされています。
+ 自動コードスキャンのための AI コーディングアシスタントとの統合
+ 自動処理のための標準化された API レスポンス
+ MCP 設定ファイルによる設定
+ 複数のファイルのバッチ処理のサポート
+ 複数のプログラミング言語と IaC 形式でのスケーラブルなスキャン
スキャンプロセスは、提供された API エンドポイントを使用して自動化できます。
+ `scan_with_checkov` IaC スキャン用
+ `scan_with_semgrep` 多言語コードスキャン用
+ `scan_with_bandit` Python 固有のスキャン用
+ `get_supported_formats` 形式検証用
スキャンツールを拡張する場合は、このセクションで前述した設計原則とベストプラクティスに従ってください。[ベストプラクティス](#deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants-best-practices)も参照してください。
## ツール
**AWS のサービス**
+ [Kiro](https://aws.amazon.com/documentation-overview/kiro/) は、デベロッパーと協力してプロンプトを詳細な仕様に変換し、作業コード、ドキュメント、テストに変換するエージェントコーディングサービスです。Kiro エージェントは、開発者が困難な問題を解決し、ドキュメントの生成や単体テストなどのタスクを自動化するのに役立ちます。
+ [Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/what-is.html) は、生成 AI を活用した会話アシスタントであり、 AWS アプリケーションの理解、構築、拡張、運用に役立ちます。
**その他のツール**
+ [Bandit](https://bandit.readthedocs.io/en/latest/) は特殊な Python セキュリティスキャナーツールです。安全でない関数、ハードコードされたシークレット、インジェクションの脆弱性などの一般的な Python セキュリティの問題を検出します。Bandit は、詳細な信頼度と重要度の評価を提供します。
+ [Checkov](https://github.com/bridgecrewio/checkov) は、IaC のセキュリティとコンプライアンスの設定ミスをチェックする静的コード分析ツールです。さらに、Checkov はコンプライアンス違反とセキュリティのベストプラクティスを検出します。
+ [Cline](https://cline.bot/) は、VS Code で実行される AI を活用したコーディングアシスタントです。
+ [Loguru](https://loguru.readthedocs.io/en/stable/) は Python 用のデータ検証ライブラリです。
+ [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) は、AI 支援開発ツールを構築するためのオープンソースフレームワークです。
+ [Pydantic](https://docs.pydantic.dev/latest/) は Python 用のデータ検証ライブラリです。
+ [Semgrep](https://semgrep.dev/docs/introduction) は、ソースコードでセキュリティの脆弱性とバグを分析します。複数のプログラミング言語をサポートしています。Semgrep は、セキュリティに焦点を当てたルールセットを使用して包括的な分析を行います。詳細な信頼度と重要度の評価を提供します。
**コードリポジトリ**
このパターンのコードは、GitHub [MCP Security Scanner: Real-Time Protection for AI Code Assistants](https://github.com/aws-samples/sample-mcp-security-scanner) リポジトリで入手できます。リポジトリには、MCP サーバーの実装、Kiro、Amazon Q Developer、Cline などの MCP 設定の詳細、設定例、テストユーティリティが含まれます。
リポジトリ構造には以下が含まれます。
+ `security_scanner_mcp_server/` - メインサーバーの実装
+ `docs/` - ドキュメントとデモ資料
+ `tests/` - テストファイル
+ `mcp-config-example.json` - MCP 設定の例
+ `requirements.txt` - プロジェクトの依存関係
## ベストプラクティス
**セキュリティスキャンの実装**
+ セキュリティの検出結果を確認して、問題を検証し、優先順位を付けます。
+ スキャンツール (Checkov、Semgrep、Bandit) を最新バージョンに更新し続けます。
+ このパターンの MCP セキュリティツールは、他のセキュリティ対策やツールと組み合わせて使用します。
+ セキュリティルールセットとポリシーを定期的に更新します。
**設定管理**
+ 公式バージョン管理ソースの MCP 設定ファイルを使用します。
+ カスタムルールと設定を文書化します。
**Integration**
+ 開発サイクルの早い段階でセキュリティスキャンを統合します。
+ コミット前フックまたは継続的インテグレーションと継続的デプロイ (CI/CD) パイプラインで自動スキャンを設定します。
+ 環境に適した重要度のしきい値を設定します。
+ セキュリティ検出結果を処理するための明確な手順を確立します。
**運用上の考慮事項**
+ スキャンパフォーマンスとリソース使用量をモニタリングします。
+ 適切なエラー処理とログ記録を実装します。
+ カスタム設定のドキュメントを維持します。
+ セキュリティルールを確認および更新するプロセスを確立します。
また、次のベストプラクティスにも注意してください。
+ 常に特定のコンテキストでセキュリティ検出結果を検証します。
+ セキュリティツールと依存関係を最新の状態に保つ。
+ 包括的なカバレッジを実現するには、複数のセキュリティツールを使用します。
+ 開発プロセスでセキュリティのベストプラクティスに従ってください。
## エピック
### (Kiro ユーザー) MCP セキュリティスキャナーサーバーをセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| MCP 設定を構成します。 | Kiro の設定ファイルは、 (オプション 1) で設定ファイルを手動で検索するか、（オプション 2) で Kiro IDE を使用して編集できます。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html){
"mcpServers": {
"security-scanner": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main",
"security_scanner_mcp_server"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
}
}
} | アプリ開発者 |
### (Amazon Q Developer ユーザー) MCP セキュリティスキャナーサーバーをセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| MCP 設定を構成します。 | MCP 設定を手動で設定するには、次の手順を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html){
"mcpServers": {
"security-scanner": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main",
"security_scanner_mcp_server"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
}
}
}
} | アプリ開発者 |
### (Cline ユーザー) MCP セキュリティスキャナーサーバーをセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| MCP 設定を構成します。 | MCP 設定を手動で設定するには、次の手順を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html){
"mcpServers": {
"security-scanner": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main",
"security_scanner_mcp_server"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
}
}
} | アプリ開発者 |
### Python と Bandit を使用したコード分析の例
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| コード分析を実行します。 | Python と Bandit を使用してコード分析を実行するには、次の手順を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) | アプリ開発者 |
### Terraform と Checkov を使用したコード分析の例
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| コード分析を実行します。 | Terraform と Checkov を使用してコード分析を実行するには、次の手順を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) | アプリ開発者 |
### 高度なスキャン機能の例
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| ターゲットスキャンを実行します。 | ターゲットスキャンの実行に使用できるリクエストの例を次に示します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) | アプリ開発者 |
| コード生成でセキュリティスキャンを使用します。 | コード生成ループを使用してセキュリティ検出結果を解決するには、次のステップを使用します (この例では、コーディングアシスタントとして Kiro を使用します）。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) | アプリデベロッパー |
## トラブルシューティング
| 問題 | ソリューション |
| --- | --- |
| 環境設定の問題 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) |
| スキャナーの問題 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) |
| 統合の問題 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) |
| 追加のサポート | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html) |
## 関連リソース
**AWS ドキュメント**
+ [Infrastructure as Code](https://docs.aws.amazon.com/whitepapers/latest/introduction-devops-aws/infrastructure-as-code.html) (AWS ホワイトペーパー*「DevOps の概要 DevOps AWS*」)
**その他の AWS リソース**
+ [セキュリティ、アイデンティティ、コンプライアンスのベストプラクティス](https://aws.amazon.com/architecture/security-identity-compliance/)
**その他のリソース**
+ [Bandit ドキュメント](https://aws.amazon.com/architecture/security-identity-compliance/)
+ [Checkov ドキュメント](https://aws.amazon.com/architecture/security-identity-compliance/)
+ [Model Context Protocol (MCP) ドキュメント](https://aws.amazon.com/architecture/security-identity-compliance/)
+ [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/) (OWASP Foundation ウェブサイト)
+ [Semgrep ドキュメント](https://aws.amazon.com/architecture/security-identity-compliance/)
## 追加情報
**自動承認が有効になっている MCP 設定の例**
`autoApprove` 設定されていない場合、ユーザーはスキャンのために MCP セキュリティサーバーにコードを送信する承認を付与する必要があります。`autoApprove` を設定すると、コードアシスタントはユーザーの承認なしにツールを呼び出すことができます。これらのツールはマシン上でローカルに実行され、データは送信されず、コードスキャンのみが実行されます。
次の設定では、すべてのセキュリティスキャン関数の自動実行を有効にします。
```
{
"mcpServers": {
"security-scanner": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main",
"security_scanner_mcp_server"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": [
"scan_with_checkov",
"scan_with_semgrep",
"scan_with_bandit",
"get_supported_formats"
]
}
}
}
```
デバッグログ記録を有効にするには、 `"FASTMCP_LOG_LEVEL"`を に設定します`"DEBUG"`。
**セキュリティスキャンツールでサポートされるファイル形式**
このソリューションの各セキュリティスキャンツールは、次のファイル形式をサポートしています。
*Checkov (IaC)*
+ Terraform – .tf、.tfvars、.tfstate
+ CloudFormation – .yaml、.yml、.json、.template
+ Kubernetes – .yaml、.yml
+ Dockerfile – Dockerfile
+ ARM – .json (Azure リソースマネージャー)
+ Bicep – .bicep
+ サーバーレス – .yml、.yaml
+ Helm – .yaml、.yml、.tpl
+ GitHub アクション – .yml、.yaml
+ GitLab\$1ci – .yml、.yaml
+ Ansible – .yml、.yaml
*Semgrep (ソースコード)*
+ Python – .py
+ JavaScript – .js
+ TypeScript – .ts
+ Java – .java
+ Go – .go
+ C – .c
+ C\$1\$1 – .cpp
+ C\$1 – .cs
+ Ruby – .rb
+ PHP – .php
+ Scala – .scala
+ Kotlin – .kt
+ Rust – .rs
*Bandit (Python のみ)*
+ Python – .py
**デモ**
コードスキャンでは、AI アシスタントで次のサンプルプロンプトを試してください。
+ 「現在のスクリプトをスキャンして結果を教えてください。」
+ 「20～60 行をスキャンして結果を教えてください」
+ 「この Amazon DynamoDB テーブルリソースをスキャンして結果を教えてください。」
詳細については、このパターンの GitHub リポジトリにあるこの[コードスキャンデモ](https://github.com/aws-samples/sample-mcp-security-scanner/blob/main/docs/demo_code_scan.gif)を参照してください。
安全なコードを生成するには、次のサンプルプロンプトを試してください。
+ 「Terraform 設定を生成して、暗号化を有効にした DynamoDB テーブルを作成し、セキュリティ上の問題がないかスキャンします。」
+ DynamoDB に書き込み、脆弱性がないかスキャンする Python Lambda 関数を作成します。」
+ 「適切なセキュリティ設定で S3 バケットの CloudFormation テンプレートを生成し、セキュリティチェックに合格することを確認します。」
+ 「ページ分割を使用して DynamoDB をクエリし、セキュリティのベストプラクティスをスキャンする Python スクリプトを作成します。」
+ 「セキュリティを強化したマイクロサービスの Kubernetes デプロイマニフェストを作成し、検証します」
詳細については、このパターンの GitHub リポジトリの[「セキュリティスキャンデモを使用したこのコード生成](https://github.com/aws-samples/sample-mcp-security-scanner/blob/main/docs/demo_code_generation.gif)」を参照してください。
# RAG と ReAct プロンプトを使用して高度な生成 AI チャットベースのアシスタントを開発する
*Amazon Web Services、Praveen Kumar Jeyarajan、Shuai Cao、Noah Hamilton、Kioua Jackson、Jundong Qiao、Kara Yang*
## 概要
一般的な企業では、データの 70% がサイロ化されたシステムにトラップされています。生成 AI を活用したチャットベースのアシスタントを使用して、自然言語のやり取りを通じて、これらのデータサイロ間のインサイトと関係性を引き出すことができます。生成 AI を最大限に活用するには、出力の信頼性の高さと正確さ、出力に利用可能な企業データが含まれていることが必要となります。チャットベースのアシスタントの成否は、以下によって決まります。
+ 生成 AI モデル (Anthropic Claude 2 など)
+ データソースのベクトル化
+ モデルをプロンプトするための [ReAct フレームワーク](https://www.promptingguide.ai/techniques/react)などの高度な推論手法
このパターンでは、Amazon Simple Storage Service (Amazon S3) バケット、AWS Glue、Amazon Relational Database Service (Amazon RDS) などのデータソースからのデータ取得アプローチを提供します。データからの値の取得は、[検索拡張生成 (RAG)](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) を思考連鎖メソッドでインターリーブすることによって行われます。結果は、企業の保存されたデータ全体を利用する複雑なチャットベースのアシスタントの会話をサポートします。
このパターンでは、Amazon SageMaker のマニュアルと料金データテーブルを例として使用して、生成 AI チャットベースのアシスタントの機能について説明します。料金とサービスの機能に関する質問に回答することにより、顧客が SageMaker サービスを評価できるようにするチャットベースのアシスタントを構築します。このソリューションでは、フロントエンドアプリケーションを構築するための Streamlit ライブラリと、大規模言語モデル (LLM) を搭載したアプリケーションバックエンドを開発するための LangChain フレームワークを使用します。
チャットベースのアシスタントへの質問には、3 つの可能なワークフローのいずれかにルーティングするための初期インテント分類で対応します。最も洗練されたワークフローは、一般的なアドバイザリガイダンスと複雑な料金分析を組み合わせたものです。このパターンは、企業、会社、業界のユースケースに合わせて調整できます。
## 前提条件と制限
**前提条件**
+ [AWS コマンドラインインターフェイス (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) がインストールされ、設定されていること
+ [AWS Cloud Development Kit (AWS CDK) ツールキット 2.114.1 以降](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)がインストールされ、設定されていること
+ Python および AWS CDK の基本的な知識
+ インストール済み[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+ [Docker](https://docs.docker.com/get-docker/) がインストールされていること
+ [Python 3.11 以降](https://www.python.org/downloads/)がインストールされ、設定されていること (詳細は、「[ツール](#develop-advanced-generative-ai-chat-based-assistants-by-using-rag-and-react-prompting-tools)」セクションを参照してください)
+ [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) を使用して[有効な AWS アカウント](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html)がブートストラップされていること
+ Amazon Titan および Anthropic Claude [モデルアクセス](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html#add-model-access)が Amazon Bedrock サービスで有効になっていること
+ ターミナル環境における [AWS セキュリティ認証情報](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) (`AWS_ACCESS_KEY_ID` を含む) の適切な設定
**制限事項**
+ LangChain は、すべての LLM のストリーミングをサポートしているわけではありません。Anthropic Claude モデルはサポートされていますが、AI21 Labs のモデルはサポートされていません。
+ このソリューションは単一 AWS アカウントにデプロイされます。
+ このソリューションは、Amazon Bedrock と Amazon Kendra が利用可能な AWS リージョンでのみデプロイできます。詳細は、[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html#bedrock-regions) と [Amazon Kendra](https://docs.aws.amazon.com/general/latest/gr/kendra.html) のドキュメントを参照してください。
**製品バージョン**
+ Python バージョン 3.11 以降
+ Streamlit バージョン 1.30.0 以降
+ Streamlit-chat バージョン 0.1.1 以降
+ LangChain バージョン 0.1.12 以降
+ AWS CDK バージョン 2.132.1 以降
## アーキテクチャ
**ターゲットテクノロジースタック**
+ Amazon Athena
+ Amazon Bedrock
+ Amazon Elastic Container Service (Amazon ECS)
+ AWS Glue
+ AWS Lambda
+ Amazon S3
+ Amazon Kendra
+ エラスティックロードバランシング
**ターゲットアーキテクチャ**
AWS CDK コードは、AWS アカウントでチャットベースのアシスタントアプリケーションを設定するのに必要なすべてのリソースをデプロイします。次の図に示すチャットベースのアシスタントアプリケーションは、ユーザーからの SageMaker 関連のクエリに応答するように設計されています。ユーザーは Application Load Balancer を介して、Streamlit アプリケーションをホストする Amazon ECS クラスターを含む VPC に接続します。オーケストレーション Lambda 関数はアプリケーションに接続します。S3 バケットデータソースは、Amazon Kendra と AWS Glue を介して Lambda 関数にデータを提供します。Lambda 関数は Amazon Bedrock に接続して、チャットベースのアシスタントユーザーからのクエリ (質問) に応答します。
![\[アーキテクチャ図。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/b4df6405-76ab-4493-a722-15ceca067254/images/4e5856cf-9489-41f8-a411-e3b8d8a50748.png)
1. オーケストレーション Lambda 関数が、LLM プロンプトリクエストを Amazon Bedrock モデル (Claude 2) に送信します。
1. Amazon Bedrock が、LLM レスポンスをオーケストレーション Lambda 関数に返送します。
**オーケストレーション Lambda 関数内のロジックフロー**
ユーザーが Streamlit アプリケーションを通じて質問すると、アプリケーションによってオーケストレーション Lambda 関数が直接呼び出されます。次の図に、Lambda 関数が呼び出されたときのロジックフローを示します。
![\[アーキテクチャ図。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/b4df6405-76ab-4493-a722-15ceca067254/images/70ae4736-06a6-4d3a-903a-edc5c10d78a0.png)
+ ステップ 1 – 入力 `query` (質問) が 3 つのインテントのいずれかに分類されます。
+ 一般的な SageMaker ガイダンスに関する質問
+ 一般的な SageMaker 料金 (トレーニング/推論) に関する質問
+ SageMaker と料金に関する複雑な質問
+ ステップ 2 – 入力 `query` が 3 つのサービスのいずれかを開始します。
+ `RAG Retrieval service`: [Amazon Kendra ](https://aws.amazon.com/kendra/)ベクトルデータベースから関連するコンテキストを取得し、[Amazon Bedrock](https://aws.amazon.com/bedrock/) を介して LLM を呼び出して、取得したコンテキストをレスポンスとして要約します。
+ `Database Query service`: LLM、データベースメタデータ、および関連するテーブルのサンプル行を使用して、入力 `query` を SQL クエリに変換します。Database Query サービスは、[Amazon Athena](https://aws.amazon.com/athena/) を介して SageMaker 料金データベースに対して SQL クエリを実行し、クエリ結果をレスポンスとして要約します。
+ `In-context ReACT Agent service`: レスポンスを提供する前に、入力 `query` を複数のステップに分割します。エージェントは、推論プロセス中に関連情報を取得するためのツールとして `RAG Retrieval service` と `Database Query service` を使用します。推論プロセスとアクションプロセスが完了すると、エージェントはレスポンスとして最終的な回答を生成します。
+ ステップ 3 – オーケストレーション Lambda 関数からのレスポンスが、出力として Streamlit アプリケーションに送信されます。
## ツール
**AWS サービス**
+ 「[Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/what-is.html)」は、標準 SQL を使用して Amazon Simple Storage Service (Amazon S3) 内のデータを直接分析できるようにするインタラクティブなクエリサービスです。
+ [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) は、主要な AI スタートアップ企業や Amazon が提供する高パフォーマンスな基盤モデル (FM) を、統合 API を通じて利用できるようにするフルマネージド型サービスです。
+ [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html) は、AWS クラウドインフラストラクチャをコードで定義してプロビジョニングするのに役立つソフトウェア開発フレームワークです。
+ 「[AWS コマンドラインインターフェイス (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」は、オープンソースのツールであり、コマンドラインシェルのコマンドを使用して AWS サービスとやり取りすることができます。
+ 「[Amazon Elastic Container Service (Amazon ECS)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html)」 は、クラスターでのコンテナの実行、停止、管理を支援する、高速でスケーラブルなコンテナ管理サービスです。
+ [AWS Glue](https://docs.aws.amazon.com/glue/) は、フルマネージド型の抽出、変換、ロード (ETL) サービスです。これにより、データストアとデータストリーム間でのデータの確実な分類、整理、強化、移動をサポートできます。このパターンでは、AWS Glue クローラーと AWS Glue データカタログテーブルを使用します。
+ [Amazon Kendra](https://docs.aws.amazon.com/kendra/latest/dg/what-is-kendra.html) は、自然言語処理と高度な機械学習アルゴリズムを使用して、データから検索に関する質問に対する特定の回答を返すインテリジェント検索サービスです。
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) は、任意の量のデータを保存、保護、取得する上で役立つクラウドベースのオブジェクトストレージサービスです。
+ 「[Elastic Load Balancing (ELB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/what-is-load-balancing.html)」は、受信するアプリケーションまたはネットワークのトラフィックを複数のターゲットに分散します。例えば、1 つ以上のアベイラビリティゾーンにある Amazon Elastic Compute Cloud (Amazon EC2) インスタンス、コンテナ、および IP アドレス間でトラフィックを分散できます。
**コードリポジトリ**
このパターンのコードは GitHub の [genai-bedrock-chatbot](https://github.com/awslabs/genai-bedrock-chatbot) リポジトリで入手できます。
コードリポジトリには以下のファイルとフォルダが含まれています。
+ `assets` フォルダ - アーキテクチャ図とパブリックデータセットの静的アセット
+ `code/lambda-container` フォルダ - Lambda 関数で実行される Python コード
+ `code/streamlit-app` フォルダ - Amazon ECS のコンテナイメージとして実行される Python コード
+ `tests` フォルダ - AWS CDK コンストラクトをユニットテストするために実行される Python ファイル
+ `code/code_stack.py` - AWS リソースの作成に使用される AWS CDK コンストラクト Python ファイル
+ `app.py` - ターゲット AWS アカウントで AWS リソースをデプロイするために使用される AWS CDK スタック Python ファイル
+ `requirements.txt` - AWS CDK のためにインストールする必要があるすべての Python 依存関係のリスト
+ `requirements-dev.txt` - AWS CDK でユニットテストスイートを実行するためにインストールする必要があるすべての Python 依存関係のリスト
+ `cdk.json` — リソースの起動に必要な値を提供する入力ファイル
|
|
| 注記: AWS CDK コードは、ソリューションをデプロイするために、[L3 (レイヤー 3) コンストラクト](https://docs.aws.amazon.com/cdk/latest/guide/getting_started.html)と [AWS によって管理される AWS Identity and Access Management (IAM) ポリシー](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)を使用します。 |
| --- |
## ベストプラクティス
+ ここに示すコード例は、PoC (概念実証) またはパイロットデモ専用です。コードを本番環境に移行する場合は、次のベストプラクティスに従ってください。
+ [Amazon S3 アクセスログ記録が有効になっていること](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html)。
+ [VPC フローログが有効になっていること](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html)。
+ [Amazon Kendra Enterprise Edition インデックス](https://docs.aws.amazon.com/whitepapers/latest/how-aws-pricing-works/amazon-kendra.html)が有効になっていること。
+ Lambda 関数のモニタリングとアラートを設定します。詳細については、[Lambda 関数をモニタリングおよびトラブルシューティングする](https://docs.aws.amazon.com/lambda/latest/dg/lambda-monitoring.html)を参照してください。Lambda 関数を使用する際の一般的なベストプラクティスについては、[AWS ドキュメント](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)を参照してください。
## エピック
### ローカルマシンで AWS 認証情報をセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| スタックをデプロイするアカウントと AWS リージョンの変数をエクスポートします。 | 環境変数を使用して AWS CDK の AWS 認証情報を提供には、次のコマンドを実行します。export CDK_DEFAULT_ACCOUNT=<12 Digit AWS Account Number>
export CDK_DEFAULT_REGION=
| DevOps エンジニア、AWS DevOps |
| AWS CLI プロファイルをセットアップします。 | アカウントの AWS CLI プロファイルを設定するには、[AWS ドキュメント](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/keys-profiles-credentials.html)の指示に従います。 | DevOps エンジニア、AWS DevOps |
### 環境をセットアップします。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| ローカルマシンにリポジトリを複製します。 | リポジトリのクローンを作成するには、ターミナルで次のコマンドを実行します。git clone https://github.com/awslabs/genai-bedrock-chatbot.git
| DevOps エンジニア、AWS DevOps |
| Python 仮想環境を設定し、必要な依存関係をインストールします。 | Python 仮想環境をセットアップするには、次のコマンドを実行します。cd genai-bedrock-chatbot
python3 -m venv .venv
source .venv/bin/activate
必要な依存関係をセットアップするには、次のコマンドを実行します。pip3 install -r requirements.txt
| DevOps エンジニア、AWS DevOps |
| AWS CDK 環境をセットアップし、AWS CDK コードを合成します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/develop-advanced-generative-ai-chat-based-assistants-by-using-rag-and-react-prompting.html) | DevOps エンジニア、AWS DevOps |
### チャットベースのアシスタントアプリケーションを設定してデプロイする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| Claude モデルアクセスをプロビジョニングする。 | AWS アカウントの Anthropic Claude モデルアクセスを有効にするには、[Amazon Bedrock ドキュメント](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html#add-model-access)の手順に従います。 | AWS DevOps |
| アカウントにリソースをデプロイします。 | AWS CDK を使用して AWS アカウントでリソースをデプロイするには、以下を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/develop-advanced-generative-ai-chat-based-assistants-by-using-rag-and-react-prompting.html)デプロイが正常に完了したら、CloudFormation の**出力**セクションにある URL を使用して、チャットベースのアシスタントアプリケーションにアクセスすることができます。 | AWS DevOps、DevOps エンジニア |
| AWS Glue クローラーを実行し、データカタログテーブルを作成します。 | [AWS Glue クローラー](https://docs.aws.amazon.com/glue/latest/dg/add-crawler.html)は、データスキーマを動的に保つために使用されます。このソリューションでは、オンデマンドでクローラーを実行することにより、[AWS Glue データカタログテーブル](https://docs.aws.amazon.com/athena/latest/ug/querying-glue-catalog.html)のパーティションを作成および更新します。CSV データセットファイルが S3 バケットにコピーされたら、AWS Glue クローラーを実行し、テスト用の Data Catalog テーブルスキーマを作成します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/develop-advanced-generative-ai-chat-based-assistants-by-using-rag-and-react-prompting.html)AWS CDK コードは、AWS Glue クローラーをオンデマンドで実行するように設定しますが、定期的に実行するように[スケジュール](https://docs.aws.amazon.com/glue/latest/dg/schedule-crawler.html)することもできます。 | DevOps エンジニア、AWS DevOps |
| ドキュメントのインデックス作成を開始する。 | ファイルが S3 バケットにコピーされたら、Amazon Kendra を使用してクロールとインデックス付けを行います。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/develop-advanced-generative-ai-chat-based-assistants-by-using-rag-and-react-prompting.html)AWS CDK コードは、Amazon Kendra インデックス同期をオンデマンドで実行するように設定しますが、[スケジュールパラメータ](https://docs.aws.amazon.com/kendra/latest/dg/data-source.html#cron)を使用して定期的に実行することもできます。 | AWS DevOps、DevOps エンジニア |
### ソリューション内のすべての AWS リソースをクリーンアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| AWS リソースを削除します。 | ソリューションをテストしたら、リソースをクリーンアップします。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/develop-advanced-generative-ai-chat-based-assistants-by-using-rag-and-react-prompting.html) | DevOps エンジニア、AWS DevOps |
## トラブルシューティング
| 問題 | ソリューション |
| --- | --- |
| AWS CDK はエラーを返します。 | AWS CDK の問題に関するヘルプは、[一般的な AWS CDK 問題をトラブルシューティングする](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html)を参照してください。 |
## 関連リソース
+ Amazon Bedrock:
+ [モデルアクセス](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)
+ [基盤モデルの推論パラメータ](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html)
+ [Python で Lambda 関数を構築する](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html)
+ [Get started with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
+ [Working with the AWS CDK in Python](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-python.html)
+ [AWS での生成 AI Application Builder](https://docs.aws.amazon.com/solutions/latest/generative-ai-application-builder-on-aws/solution-overview.html)
+ [LangChain ドキュメント](https://python.langchain.com/docs/get_started/introduction)
+ [Streamlit ドキュメント](https://docs.streamlit.io/)
## 追加情報
**AWS CDK コマンド**
AWS CDK を使用する際は、以下の便利なコマンドに注意してください。
+ アプリ内のすべてのスタックを一覧表示
```
cdk ls
```
+ 合成された AWS CloudFormation テンプレートを発行
```
cdk synth
```
+ スタックをデフォルトの AWS アカウントとリージョンにデプロイ
```
cdk deploy
```
+ デプロイされたスタックを現在の状態と比較
```
cdk diff
```
+ AWS CDK ドキュメントを開く
```
cdk docs
```
+ CloudFormation スタックを削除し、AWS にデプロイされたリソースを削除
```
cdk destroy
```
# Amazon Bedrock エージェントとナレッジベースを使用して、完全に自動化したチャットベースのアシスタントを開発する
*Amazon Web Services、Jundong Qiao、Shuai Cao、Noah Hamilton、Kioua Jackson、Praveen Kumar Jeyarajan、Kara Yang*
## 概要
多くの組織が、包括的な回答を提供するために多様なデータソースをオーケストレーションできるチャットベースのアシスタントを作成する際に課題に直面します。このパターンでは、簡単なデプロイによりドキュメントとデータベースの両方からクエリに回答できるチャットベースのアシスタントを開発するためのソリューションを示します。
このフルマネージド生成 AI サービスは、[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) をはじめとして、さまざまな高度な基盤モデル (FM) を提供しています。これにより、プライバシーとセキュリティに重点を置いた生成 AI アプリケーションを簡単に効率よく作成できます。ドキュメントの取得において、[検索拡張生成 (RAG)](https://docs.aws.amazon.com/sagemaker/latest/dg/jumpstart-foundation-models-customize-rag.html) は重要な機能です。[ナレッジベース](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)を使用して、外部ソースからのコンテキストに関連する情報で FM プロンプトを補強します。[Amazon OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-overview.html) インデックスは、Amazon Bedrock ナレッジベースの背後にあるベクトルデータベースとして機能します。この統合は、不正確さを最小限に抑え、応答が事実関係のドキュメントに確実に基づくようにするための慎重なプロンプトエンジニアリングによって強化されます。データベースクエリの場合、Amazon Bedrock の FM により、テキストクエリが構造化された SQL クエリに変換され、特定のパラメータが組み込まれます。これにより、データベースによって管理される[AWS Glue データベース](https://docs.aws.amazon.com/glue/latest/dg/define-database.html)からデータを正確に取得できます。これらのクエリには [Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/what-is.html) が使用されます。
より複雑なクエリを処理し、包括的な回答を得るには、ドキュメントとデータベースの両方から取得された情報が必要です。[Amazon Bedrock エージェント](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) は、複雑なタスクを理解し、オーケストレーションのためによりシンプルなタスクに分割できる自律型エージェントを構築するのに役立つ生成 AI 機能です。簡素化されたタスクから取得されるインサイトが Amazon Bedrock の自律型エージェントによって結び付けられることにより、情報の合成が強化され、より詳細で包括的な回答が得られます。このパターンでは、Amazon Bedrock および関連する生成 AI サービスと自動ソリューション内の機能を使用してチャットベースのアシスタントを構築する方法を説明します。
## 前提条件と制限
**前提条件**
+ アクティブな AWS アカウント
+ Docker が[インストールされていること](https://docs.docker.com/engine/install/)
+ AWS Cloud Development Kit (AWS CDK)、 `us-east-1` または に[インストール](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_tools)および[ブートストラップ](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_bootstrap) `us-west-2` AWS リージョン
+ AWS CDK Toolkit バージョン 2.114.1 以降、[インストール](https://docs.aws.amazon.com/cdk/v2/guide/cli.html)済み
+ AWS Command Line Interface (AWS CLI)、[インストール](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)および[設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)済み
+ Python バージョン 3.11 以降が[インストールされていること](https://www.python.org/downloads/)
+ Amazon Bedrock で、Claude 2、Claude 2.1、Claude Instant、Titan Embeddings G1 – Text への[アクセスを有効にすること](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)
**制限事項**
+ このソリューションは 1 つの にデプロイされます AWS アカウント。
+ このソリューションは、Amazon Bedrock と Amazon OpenSearch Serverless がサポートされている AWS リージョン でのみデプロイできます。詳細は、[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) ドキュメントおよび [Amazon OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-overview.html#serverless-regions) ドキュメントを参照してください。
**製品バージョン**
+ Llama-index バージョン 0.10.6 以降
+ Sqlalchemy バージョン 2.0.23 以降
+ Opensearch-py バージョン 2.4.2 以降
+ Requests\$1aws4auth バージョン 1.2.3 以降
+ AWS SDK for Python (Boto3) バージョン 1.34.57 以降
## アーキテクチャ
**ターゲットテクノロジースタック**
[AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) は、コードでクラウドインフラストラクチャを定義し、それをプロビジョニングするためのオープンソースのソフトウェア開発フレームワークです AWS CloudFormation。このパターンで使用される AWS CDK スタックは、次の AWS リソースをデプロイします。
+ AWS Key Management Service (AWS KMS)
+ Amazon Simple Storage Service (Amazon S3)
+ AWS Glue Data Catalog AWS Glue データベースコンポーネントの 。
+ AWS Lambda
+ AWS Identity and Access Management (IAM)
+ Amazon OpenSearch Serverless
+ Amazon Elastic Container Registry (Amazon ECR)
+ Amazon Elastic Container Service (Amazon ECS)
+ AWS Fargate
+ Amazon Virtual Private Cloud (Amazon VPC)
+ [Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html)
**ターゲット アーキテクチャ**
![\[Amazon Bedrock ナレッジベースとエージェントを使用したアーキテクチャ図\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/15372718-3a5d-4918-9cfa-422c455f288d/images/ff19152e-0bb6-4758-a6dd-4f6140e55113.png)
この図は、複数の を使用した AWS リージョン、単一の 内の包括的な AWS クラウドネイティブセットアップを示しています AWS のサービス。チャットベースのアシスタントの主なインターフェイスは、Amazon ECS クラスターでホストされている [Streamlit](https://docs.streamlit.io/) アプリケーションです。[Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/) はアクセシビリティを管理します。このインターフェイスを介して行われたクエリは `Invocation` Lambda 関数をアクティブ化し、それによって Amazon Bedrock エージェントとのインターフェイスが行われます。このエージェントは、Amazon Bedrock ナレッジベースを参照するか、`Agent executor` Lambda 関数を呼び出して、ユーザーの問い合わせに応答します。この関数は、事前定義された API スキーマに従って、エージェントに関連付けられた一連のアクションをトリガーします。Amazon Bedrock ナレッジベースは、OpenSearch Serverless インデックスをベクトルデータベース基盤として使用します。さらに、`Agent executor`関数は Amazon Athena を介して AWS Glue データベースに対して実行される SQL クエリを生成します。
## ツール
**AWS のサービス**
+ [Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/what-is.html)は、標準 SQL を使用して Amazon Simple Storage Service (Amazon S3) 内のデータを直接分析できるようにするインタラクティブなクエリサービスです。
+ [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) は、主要な AI スタートアップ企業や Amazon が提供する高パフォーマンスな基盤モデル (FM) を、統合 API を通じて利用できるようにするフルマネージド型サービスです。
+ [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html) は、 AWS クラウドインフラストラクチャをコードで定義してプロビジョニングするのに役立つソフトウェア開発フレームワークです。
+ [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) は、コマンドラインシェルのコマンド AWS のサービス を使用して を操作するのに役立つオープンソースツールです。
+ 「[Amazon Elastic Container Service (Amazon ECS)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html)」 は、クラスターでのコンテナの実行、停止、管理を支援する、高速でスケーラブルなコンテナ管理サービスです。
+ 受信したアプリケーションまたはネットワークトラフィックを複数のターゲットに分散するには、[Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/what-is-load-balancing.html) を使用します。例えば、1 つまたは複数のアベイラビリティーゾーンの Amazon Elastic Compute Cloud (Amazon EC2) インスタンス、コンテナ、および IP アドレスにトラフィックを分散できます。
+ [AWS Glue](https://docs.aws.amazon.com/glue/) は、フルマネージド型の抽出、変換、ロード (ETL) サービスです。これにより、データストアとデータストリーム間でのデータの分類、整理、強化、移動を確実に行うことができます。このパターンでは、 クローラと AWS Glue AWS Glue Data Catalog テーブルを使用します。
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。
+ [Amazon OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-overview.html) は、Amazon OpenSearch Service 用のオンデマンドサーバーレス設定です。このパターンでは、OpenSearch Serverless インデックスは Amazon Bedrock ナレッジベースのベクトルデータベースとして機能します。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) は、あらゆる量のデータを保存、保護、取得できるクラウドベースのオブジェクトストレージサービスです。
**その他のツール**
+ [Streamlit](https://docs.streamlit.io/) は、データアプリケーションを作成するためのオープンソースの Python フレームワークです。
**コードリポジトリ**
このパターンのコードは、GitHub の [genai-bedrock-agent-chatbot](https://github.com/awslabs/genai-bedrock-agent-chatbot/) リポジトリで入手できます。コードリポジトリには以下のファイルとフォルダが含まれています。
+ `assets` フォルダ – アーキテクチャ図やパブリックデータセットなどの静的アセット。
+ `code/lambdas/action-lambda` フォルダ – Amazon Bedrock エージェントのアクションとして機能する Lambda 関数の Python コード。
+ `code/lambdas/create-index-lambda` フォルダ – OpenSearch Serverless インデックスを作成する Lambda 関数の Python コード。
+ `code/lambdas/invoke-lambda` フォルダ – Amazon Bedrock エージェントを呼び出す Lambda 関数の Python コード。Streamlit アプリケーションから直接呼び出されます。
+ `code/lambdas/update-lambda` フォルダ – を介してリソースがデプロイされた後に AWS リソースを更新または削除する Lambda 関数の Python コード AWS CDK。
+ `code/layers/boto3_layer` フォルダ – すべての Lambda 関数間で共有される Boto3 レイヤーを作成する AWS CDK スタック。
+ `code/layers/opensearch_layer` フォルダ – インデックスを作成するためのすべての依存関係をインストールする OpenSearch Serverless レイヤーを作成する AWS CDK スタック。
+ `code/streamlit-app` フォルダ – Amazon ECS のコンテナイメージとして実行される Python コード。
+ `code/code_stack.py` – AWS リソースを作成する AWS CDK コンストラクト Python ファイル。
+ `app.py` – ターゲット AWS アカウントに AWS リソースをデプロイする AWS CDK スタック Python ファイル。
+ `requirements.txt` – にインストールする必要があるすべての Python 依存関係のリスト AWS CDK。
+ `cdk.json` — リソースの作成に必要な値を提供する入力ファイル。また、`context/config` フィールドでは、状況に応じてソリューションをカスタマイズできます。カスタマイズの詳細は、「[追加情報](#develop-a-fully-automated-chat-based-assistant-by-using-amazon-bedrock-agents-and-knowledge-bases-additional)」セクションを参照してください。
## ベストプラクティス
+ ここに示すコード例は、PoC (概念実証) またはパイロットのみを目的としています。コードを本番環境に移行する場合は、次のベストプラクティスに従ってください。
+ [Amazon S3 アクセスログ](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html)を有効にする
+ [VPC フローログ](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html)を有効にする
+ Lambda 関数のモニタリングとアラートを設定します。詳細については、「[Lambda 関数をモニタリングおよびトラブルシューティングする](https://docs.aws.amazon.com/lambda/latest/dg/lambda-monitoring.html)」を参照してください。ベストプラクティスについては、「 [AWS Lambda 関数を使用するためのベストプラクティス](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)」を参照してください。
## エピック
### ローカルワークステーションで AWS 認証情報を設定する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| アカウントとリージョンの変数をエクスポートする。 | 環境変数 AWS CDK を使用して の AWS 認証情報を提供するには、次のコマンドを実行します。export CDK_DEFAULT_ACCOUNT=<12-digit AWS account number>
export CDK_DEFAULT_REGION=
| AWS DevOps、DevOps エンジニア |
| AWS CLI 名前付きプロファイルを設定します。 | アカウント AWS CLI の名前付きプロファイルを設定するには、[「設定と認証情報ファイルの設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)」の手順に従います。 | AWS DevOps、DevOps エンジニア |
### 環境をセットアップします。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| ローカルワークステーションにリポジトリのクローンを作成する。 | リポジトリのクローンを作成するには、ターミナルで次のコマンドを実行します。git clone https://github.com/awslabs/genai-bedrock-agent-chatbot.git
| DevOps エンジニア、AWS DevOps |
| Python 仮想環境をセットアップする。 | Python 仮想環境をセットアップするには、次のコマンドを実行します。cd genai-bedrock-agent-chatbot
python3 -m venv .venv
source .venv/bin/activate
必要な依存関係をセットアップするには、次のコマンドを実行します。pip3 install -r requirements.txt
| DevOps エンジニア、AWS DevOps |
| AWS CDK 環境をセットアップします。 | コードを AWS CloudFormation テンプレートに変換するには、 コマンドを実行します`cdk synth`。 | AWS DevOps、DevOps エンジニア |
### アプリケーションを設定してデプロイする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| アカウントにリソースをデプロイします。 | AWS アカウント を使用して にリソースをデプロイするには AWS CDK、以下を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/develop-a-fully-automated-chat-based-assistant-by-using-amazon-bedrock-agents-and-knowledge-bases.html)デプロイが正常に完了したら、CloudFormation コンソールの**出力**タブにある URL を使用して、チャットベースのアシスタントアプリケーションにアクセスできます。 | DevOps エンジニア、AWS DevOps |
### ソリューション内のすべての AWS リソースをクリーンアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| AWS リソースを削除します。 | ソリューションをテストした後、リソースをクリーンアップするには、`cdk destroy` コマンドを実行します。 | AWS DevOps、DevOps エンジニア |
## 関連リソース
**AWS ドキュメント**
+ Tag Amazon Bedrock リソース:
+ [モデルアクセス](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)
+ [基盤モデルの推論パラメータ](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html)
+ [Amazon Bedrock のエージェント](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html)
+ [Amazon Bedrock ナレッジベース](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)
+ [Python で Lambda 関数を構築する](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html)
+ AWS CDK リソース:
+ [の使用を開始する AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
+ [一般的な AWS CDK 問題のトラブルシューティング](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html)
+ [Python AWS CDK での の使用](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-python.html)
+ [での生成 AI Application Builder AWS](https://docs.aws.amazon.com/solutions/latest/generative-ai-application-builder-on-aws/solution-overview.html)
**その他の AWS リソース**
+ [Amazon OpenSearch Serverless 用ベクトルエンジン](https://aws.amazon.com/opensearch-service/serverless-vector-engine/)
**その他のリソース**
+ [LlamaIndex ドキュメント](https://docs.llamaindex.ai/en/stable/)
+ [Streamlit ドキュメント](https://docs.streamlit.io/)
## 追加情報
**チャットベースのアシスタントを独自のデータでカスタマイズする**
カスタムデータを統合してソリューションをデプロイするには、以下の構造化されたガイドラインに従ってください。これらのステップは、シームレスで効率的な統合プロセスを実現するように設計されており、カスタムデータを使用して効果的にソリューションをデプロイできます。
*ナレッジベースのデータ統合の場合*
**データ準備**
1. `assets/knowledgebase_data_source/` ディレクトリの場所を確認します。
1. データセットをこのフォルダに配置します。
**設定の調整**
1. `cdk.json` ファイルを開きます。
1. `context/configure/paths/knowledgebase_file_name` フィールドに移動し、それに応じて更新します。
1. `bedrock_instructions/knowledgebase_instruction` フィールドに移動し、新しいデータセットの意味合いとコンテキストを正確に反映するように更新します。
*構造化データ統合の場合*
**データの整理**
1. `assets/data_query_data_source/` ディレクトリに `tabular_data` などのサブディレクトリを作成します。
1. 構造化データセット (CSV、JSON、ORC、Parquet などの許容される形式) をこの新しく作成されたサブフォルダに配置します。
1. 既存のデータベースに接続する場合は、`code/lambda/action-lambda/build_query_engine.py` の `create_sql_engine()` 関数を更新してデータベースに接続します。
**設定とコードの更新**
1. `cdk.json` ファイルで、新しいデータパスに合わせて `context/configure/paths/athena_table_data_prefix` フィールドを更新します。
1. データセットに対応する新しい text-to-SQL の例を組み込んで `code/lambda/action-lambda/dynamic_examples.csv` を修正します。
1. 構造化データセットの属性をミラーリングするように `code/lambda/action-lambda/prompt_templates.py` を修正します。
1. `cdk.json` ファイルで、`Action group` Lambda 関数の目的と機能の説明を記述するように `context/configure/bedrock_instructions/action_group_description` フィールドを更新します。
1. `assets/agent_api_schema/artifacts_schema.json` ファイルに、`Action group` Lambda 関数の新しい機能の説明を記述します。
*一般的な更新*
`cdk.json` ファイルの `context/configure/bedrock_instructions/agent_instruction` セクションに、新しく統合されたデータを考慮して、Amazon Bedrock エージェントの意図した機能と設計目的の包括的な説明を記述します。
# Amazon Bedrock と Amazon Transcribe を使用して音声入力から組織の知識を文書化する
*Amazon Web Services、Praveen Kumar Jeyarajan、Jundong Qiao、Rajiv Upadhyay、Megan Wu*
## 概要
組織の成功とレジリエンスを確保するためには、組織の知識を記録することが最優先事項です。組織の知識とは、従業員が長期にわたって蓄積した集合的な知恵、インサイト、経験のことで、多くの場合は本質的に暗黙的で、非公式に受け継がれます。この豊富な情報には、他では文書化されていないような複雑な問題に対する独自のアプローチ、ベストプラクティス、解決策が含まれています。この知識を形式化して文書化することにより、企業は組織の記憶を保持し、イノベーションを促進し、意思決定プロセスを強化し、新入社員の学習曲線を加速させることができます。さらに、連携を促進し、個人に権限を与え、継続的な改善の文化を育みます。組織の知識を活用すると、最終的に、企業は最も重要なアセットである従業員の集合的インテリジェンスに基づいて、課題を乗り越え、成長を促進し、動的なビジネス環境で競争上の優位性を維持することができます。
このパターンでは、上級従業員からの音声記録を通じて組織の知識を記録する方法について説明します。[Amazon Transcribe](https://docs.aws.amazon.com/transcribe/latest/dg/what-is.html) と [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) を使用して、体系的な文書化と検証を行います。この非公式な知識を文書化することにより、知識を保存し、後続の従業員の仲間と共有することができます。この取り組みは、運用上の優秀性をサポートするものであり、直接的な経験を通じて獲得した実践的な知識を組み込むことにより、トレーニングプログラムの有効性を向上させます。
## 前提条件と制限
**前提条件**
+ アクティブなAWS アカウント
+ Docker が[インストールされていること](https://docs.docker.com/engine/install/)
+ AWS Cloud Development Kit (AWS CDK) バージョン 2.114.1 以降が `us-east-1` または `us-west-2` AWS リージョンに[インストール](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_tools)および[ブートストラップされていること](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_bootstrap)
+ AWS CDK ツールキットバージョン 2.114.1 以降が[インストールされていること](https://docs.aws.amazon.com/cdk/v2/guide/cli.html)
+ [インストール](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)および[設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)済みの AWS コマンドラインインターフェイス (AWS CLI)
+ Python バージョン 3.12 以降が[インストールされていること](https://www.python.org/downloads/)
+ Amazon Transcribe、Amazon Bedrock、Amazon Simple Storage Service (Amazon S3)、および AWS Lambda リソースを作成するためのアクセス権限
**制限**
+ このソリューションは単一 AWS アカウントにデプロイされます。
+ このソリューションは、Amazon Bedrock と Amazon Transcribe が利用可能な AWS リージョンでのみデプロイできます。詳細は、[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) と [Amazon Transcribe](https://docs.aws.amazon.com/transcribe/latest/dg/what-is.html#tsc-regions) のドキュメントを参照してください。
+ オーディオファイルは、Amazon Transcribe がサポートする形式である必要があります。サポートされている形式のリストについては、Transcribe ドキュメントの「[Media formats](https://docs.aws.amazon.com/transcribe/latest/dg/how-input.html#how-input-audio)」を参照してください。
**製品バージョン**
+ AWS SDK for Python (Boto3) バージョン 1.34.57 以降
+ LangChain バージョン 0.1.12 以降
## アーキテクチャ
アーキテクチャは、AWS でのサーバーレスワークフローを表します。[AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html) は、オーディオ処理、テキスト分析、ドキュメント生成のために Lambda 関数を調整します。次の図に、*ステートマシン*とも呼ばれる Step Functions ワークフローを示します。
![\[ドキュメントを生成する Step Functions ステートマシンのアーキテクチャ図\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/f1e0106d-b046-4adc-9718-c299efb7b436/images/e90298ca-1b7f-4c3e-97bd-311a9d5a4997.png)
ステートマシンの各ステップは、個別の Lambda 関数によって処理されます。ドキュメント生成プロセスの手順は次のとおりです。
1. `preprocess` Lambda 関数が、Step Functions に渡された入力を検証し、提供された Amazon S3 URI フォルダパスに存在するすべてのオーディオファイルを一覧表示します。ワークフローのダウンストリーム Lambda 関数は、ファイルリストを使用してドキュメントを検証、要約、生成します。
1. `transcribe` Lambda 関数が Amazon Transcribe を使用してオーディオファイルをテキストトランスクリプトに変換します。この Lambda 関数は、文字起こしプロセスを開始し、スピーチをテキストに正確に変換し、後続の処理のために保存します。
1. `validate` Lambda 関数がテキストトランスクリプトを分析し、最初の質問に対する応答の関連性を判断します。Amazon Bedrock で大規模言語モデル (LLM) を使用することにより、トピック関連の回答を特定してトピック外の回答から分離します。
1. `summarize` Lambda 関数が Amazon Bedrock を使用して、トピック関連の回答の一貫した簡潔な概要を生成します。
1. `generate` Lambda 関数が、概要を構造化されたドキュメントにアセンブルします。事前定義されたテンプレートに従ってドキュメントをフォーマットし、追加の必要なコンテンツやデータを含めることができます。
1. いずれかの Lambda 関数が失敗すると、Amazon Simple Notification Service (Amazon SNS) から E メール通知が送信されます。
このプロセス全体をとおして、AWS Step Functions は各 Lambda 関数が正しい順序で開始されることを確認します。このステートマシンでは、効率を向上させるための並列処理が可能です。Amazon S3 バケットは中央ストレージリポジトリとして機能し、関連するさまざまなメディアおよびドキュメント形式を管理することでワークフローをサポートします。
## ツール
**AWS サービス**
+ [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) は、主要な AI スタートアップ企業や Amazon が提供する高パフォーマンスな基盤モデル (FM) を、統合 API を通じて利用できるようにするフルマネージド型サービスです。
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。
+ 「[Amazon Simple Notification Service (Amazon SNS)](https://docs.aws.amazon.com/sns/latest/dg/welcome.html)」は、ウェブサーバーやメールアドレスなど、パブリッシャーとクライアント間のメッセージの交換を調整および管理するのに役立ちます。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) は、量にかかわらず、データを保存、保護、取得する上で役立つクラウドベースのオブジェクトストレージサービスです。
+ [AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)は、AWS Lambda関数と他のAWS サービスを組み合わせてビジネスクリティカルなアプリケーションを構築できるサーバーレスオーケストレーションサービスです。
+ [Amazon Transcribe](https://docs.aws.amazon.com/transcribe/latest/dg/what-is.html) は、機械学習モデルを使用して音声をテキストに変換する自動音声認識サービスです。
**その他のツール**
+ [LangChain](https://python.langchain.com/docs/get_started/introduction/) は、言語モデル (LLM) を利用するアプリケーションを開発するためのフレームワークです。
**コードリポジトリ**
このパターンのコードは、GitHub の [genai-knowledge-capture](https://github.com/aws-samples/genai-knowledge-capture) リポジトリで入手できます。
コードリポジトリには以下のファイルとフォルダが含まれています。
+ `assets` フォルダ - アーキテクチャ図やパブリックデータセットなど、ソリューションの静的アセット
+ `code/lambdas` フォルダ - すべての Lambda 関数のための Python コード
+ `code/lambdas/generate` フォルダ - S3 バケット内の要約データからドキュメントを生成する Python コード
+ `code/lambdas/preprocess` フォルダ - Step Functions ステートマシンの入力を処理する Python コード
+ `code/lambdas/summarize` フォルダ - Amazon Bedrock サービスを使用して文字起こしデータを要約する Python コード
+ `code/lambdas/transcribe` フォルダ - Amazon Transcribe を使用してスピーチデータ (オーディオファイル) をテキストに変換する Python コード
+ `code/lambdas/validate` フォルダ - すべての回答が同じトピックに関連しているかどうかを検証する Python コード
+ `code/code_stack.py` - AWS リソースの作成に使用される AWS CDK コンストラクト Python ファイル
+ `app.py` - ターゲット AWS アカウントで AWS リソースをデプロイするために使用される AWS CDK アプリケーション Python ファイル
+ `requirements.txt` - AWS CDK のためにインストールする必要があるすべての Python 依存関係のリスト
+ `cdk.json` - リソースの作成に必要な値を提供する入力ファイル
## ベストプラクティス
ここに示すコード例は、PoC (概念実証) またはパイロットのみを目的としています。ソリューションを本番環境に移行する場合は、次のベストプラクティスに従ってください。
+ [Amazon S3 アクセスログ](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html)を有効にする
+ [VPC フローログ](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html)を有効にする
## エピック
### ローカルワークステーションで AWS 認証情報をセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| アカウントと AWS リージョンの変数をエクスポートする。 | 環境変数を使用して AWS CDK の AWS 認証情報を提供するには、次のコマンドを実行します。export CDK_DEFAULT_ACCOUNT=<12-digit AWS account number>
export CDK_DEFAULT_REGION=
| AWS DevOps、DevOps エンジニア |
| AWS CLI 名前付きプロファイルをセットアップする。 | アカウントに AWS CLI 名前付きプロファイルをセットアップするには、「[Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)」の手順に従います。 | AWS DevOps、DevOps エンジニア |
### 環境をセットアップします。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| ローカルワークステーションにリポジトリのクローンを作成する。 | [genai-knowledge-capture](https://github.com/aws-samples/genai-knowledge-capture) リポジトリのクローンを作成するには、ターミナルで次のコマンドを実行します。git clone https://github.com/aws-samples/genai-knowledge-capture
| AWS DevOps、DevOps エンジニア |
| (オプション) オーディオファイルを置き換える。 | サンプルアプリケーションをカスタマイズして独自のデータを組み込むには、以下を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/document-institutional-knowledge-from-voice-inputs-by-using-amazon-bedrock-and-amazon-transcribe.html) | AWS DevOps、DevOps エンジニア |
| Python 仮想環境をセットアップする。 | Python 仮想環境をセットアップするには、次のコマンドを実行します。cd genai-knowledge-capture
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
| AWS DevOps、DevOps エンジニア |
| AWS CDK コードを合成する。 | コードを AWS CloudFormation スタック設定に変換するには、次のコマンドを実行します。cdk synth
| AWS DevOps、DevOps エンジニア |
### ソリューションを設定してデプロイする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 基盤モデルアクセスをプロビジョニングする。 | AWS アカウントの Anthropic Claude 3 Sonnet モデルへのアクセスを有効にします。手順については、Bedrock ドキュメントの「[Add model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html#model-access-add)」を参照してください。 | AWS DevOps |
| アカウントにリソースをデプロイします。 | AWS CDK を使用して AWS アカウントでリソースをデプロイするには、以下を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/document-institutional-knowledge-from-voice-inputs-by-using-amazon-bedrock-and-amazon-transcribe.html) | AWS DevOps、DevOps エンジニア |
| Amazon SNS トピックを購読します。 | 通知用に Amazon SNS トピックを登録するには、次の手順を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/document-institutional-knowledge-from-voice-inputs-by-using-amazon-bedrock-and-amazon-transcribe.html) | AWS 全般 |
### ソリューションをテストする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| ステートマシンを実行します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/document-institutional-knowledge-from-voice-inputs-by-using-amazon-bedrock-and-amazon-transcribe.html) | アプリ開発者、AWS 全般 |
### ソリューション内のすべての AWS リソースをクリーンアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| AWS リソースを削除します。 | ソリューションをテストしたら、リソースをクリーンアップします。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/document-institutional-knowledge-from-voice-inputs-by-using-amazon-bedrock-and-amazon-transcribe.html) | AWS DevOps、DevOps エンジニア |
## 関連リソース
**AWS ドキュメント**
+ Tag Amazon Bedrock リソース:
+ [モデルアクセス](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)
+ [基盤モデルの推論パラメータ](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html)
+ AWS CDK リソース:
+ [Get started with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
+ [Working with the AWS CDK in Python](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-python.html)
+ [Troubleshooting common AWS CDK issues](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html)
+ [Toolkit commands](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-commands)
+ AWS Step Functions リソース:
+ [Getting started with AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html)
+ [トラブルシューティング](https://docs.aws.amazon.com/step-functions/latest/dg/troubleshooting.html)
+ [Python で Lambda 関数を構築する](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html)
+ [AWS での生成 AI Application Builder](https://docs.aws.amazon.com/solutions/latest/generative-ai-application-builder-on-aws/solution-overview.html)
**その他のリソース**
+ [LangChain ドキュメント](https://python.langchain.com/docs/get_started/introduction)
# Amazon Personalize を使用して、パーソナライズされ再ランク付けされたレコメンデーションを生成します
*Mason Cahill、Matthew Chasse、Tayo Olajide、Amazon Web Services*
## 概要
このパターンは、Amazon Personalize を使用して、ユーザーからのリアルタイムのユーザーインタラクションデータの取り込みに基づいて、ユーザー向けにパーソナライズされたレコメンデーション (再ランク付けされたレコメンデーションを含む) を生成する方法を示しています。このパターンで使用されるシナリオの例は、ペット養子縁組ウェブサイトに基づいています。このウェブサイトでは、ユーザーとのやり取り (たとえば、ユーザーが訪問したペットなど) に基づいてユーザー向けのレコメンデーションが生成されます。シナリオ例に従うことで、Amazon Kinesis Data Streams を使用してインタラクションデータを取り込み、AWS Lambda を使用してレコメンデーションを生成してレコメンデーションを再ランク付けする方法と、Amazon Data Firehose を使用してデータを Amazon Simple Storage Service (Amazon S3) バケットに保存する方法を学習します。また、AWS Step Functions を使用して、レコメンデーションを生成するソリューションバージョン (つまり、トレーニング済みモデル) を管理するステートマシンを構築する方法も学びます。
## 前提条件と制限
**前提条件**
+ 「[ブートストラップ](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)」された AWS Cloud Development Kit (AWS CDK) を使用したアクティブな「[AWS アカウント](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/)」
+ 認証情報が設定された「[AWS コマンドラインインターフェイス(AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」
+ 「[Python 3.9](https://www.python.org/downloads/release/python-390/)」
**製品バージョン**
+ Python 3.9
+ AWS CDK 2.23.0 以降
+ AWS CLI 2.7.27 以降
## アーキテクチャ
**テクノロジースタック**
+ Amazon Data Firehose
+ Amazon Kinesis Data Streams
+ Amazon Personalize
+ Amazon Simple Storage Service (Amazon S3)
+ AWS Cloud Development Kit (AWS CDK)
+ AWS コマンドラインインターフェイス (AWS CLI)
+ AWS Lambda
+ AWS Step Functions
**ターゲットアーキテクチャ**
次の図は、Amazon Personalize にリアルタイムデータを取り込むためのパイプラインを示しています。次に、パイプラインはそのデータを使用して、ユーザー向けにパーソナライズされ、ランクが変更されたレコメンデーションを生成します。
![\[Amazon Personalize データインジェストアーキテクチャ\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/42eb193b-2347-408a-8b25-46beeb3b29ca/images/786dbd56-7d7f-41bb-90f6-d4485d73fe15.png)
この図表は、次のワークフローを示しています:
1. Kinesis Data Streams は、リアルタイムのユーザーデータ (例: 訪問したペットなどのイベント) を取り込み、Lambda と Firehose で処理します。
1. Lambda 関数は Kinesis データストリームからのレコードを処理し、レコード内のユーザーインタラクションを Amazon Personalize のイベントトラッカーに追加するための API コールを行います。
1. 時間ベースのルールは Step Functions ステートマシンを呼び出し、Amazon Personalize のイベントトラッカーからのイベントを使用して、レコメンデーションモデルと再ランク付けモデルの新しいソリューションバージョンを生成します。
1. Amazon Personalize「[キャンペーン](https://docs.aws.amazon.com/personalize/latest/dg/campaigns.html)」は、ステートマシンによって新しいソ「[リューションバージョン](https://docs.aws.amazon.com/personalize/latest/dg/creating-a-solution-version.html)」を使用するように更新されます。
1. Lambda は Amazon Personalize 再ランキングキャンペーンを呼び出して、おすすめ商品のリストを再ランク付けします。
1. Lambda は Amazon Personalize レコメンデーションキャンペーンを呼び出して、おすすめ商品のリストを取得します。
1. Firehose はイベントを S3 バケットに保存し、そこで履歴データとしてアクセスできます。
## ツール
AWS ツール
+ [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html) は、AWS クラウドインフラストラクチャをコードで定義してプロビジョニングするのに役立つソフトウェア開発フレームワークです。
+ 「[AWS コマンドラインインターフェイス (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」は、オープンソースのツールであり、コマンドラインシェルのコマンドを使用して AWS サービスとやり取りすることができます。
+ 「[Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html)」を使用すると、リアルタイムの「[ストリーミングデータ](https://aws.amazon.com/streaming-data/)」を他の AWS サービス、カスタム HTTP エンドポイント、サードパーティーのサービスプロバイダーが所有する HTTP エンドポイントに提供できます。
+ 「[Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html)」は、データレコードの大量のストリームをリアルタイムで収集し、処理するのに役立ちます。
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。
+ 「[Amazon Personalize](https://docs.aws.amazon.com/personalize/latest/dg/what-is-personalize.html)」はフルマネージド型の機械学習 (ML) サービスで、データに基づいてユーザー向けの商品レコメンデーションを作成できます。
+ 「[AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)」は、Lambda 関数と他の AWS サービスを組み合わせてビジネスクリティカルなアプリケーションを構築できるサーバーレスオーケストレーションサービスです。
その他のツール
+ 「[pytest](https://docs.pytest.org/en/7.2.x/index.html)」は、小さくて読みやすいテストを書くための Python フレームワークです。
+ 「[Python](https://www.python.org/)」は汎用のコンピュータープログラミング言語です。
**Code**
このパターンのコードは、GitHub 内の「[Animal Recommender](https://github.com/aws-samples/personalize-pet-recommendations)」リポジトリで利用できます。このリポジトリの AWS CloudFormation テンプレートを使用して、サンプルソリューションのリソースをデプロイできます。
**注記**
Amazon Personalize ソリューションのバージョン、イベントトラッカー、キャンペーンは、ネイティブの CloudFormation リソースを拡張する (インフラストラクチャ内の)「[カスタムリソース](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html)」によって支えられています。
## エピック
### インフラストラクチャを作成する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 隔離された Python 環境を作成します。 | Mac/Linux セットアップ[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/generate-personalized-and-re-ranked-recommendations-using-amazon-personalize.html)Windows セットアップ仮想環境を手動で作成するには、ターミナルから `% .venv\Scripts\activate.bat` コマンドを実行します。 | DevOps エンジニア |
| CloudFormation のテンプレートを合成します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/generate-personalized-and-re-ranked-recommendations-using-amazon-personalize.html)ステップ 2 では、`CDK_ENVIRONMENT` は `config/{env}.yml` ファイルを参照します。 | DevOps エンジニア |
| リソースをデプロイし、インフラストラクチャーを構築します。 | ソリューションリソースをデプロイするには、ターミナルから `./deploy.sh` コマンドを実行します。このコマンドは、必要な Python 依存関係をインストールします。Python スクリプトは、S3 バケットと AWS Key Management Service (AWS KMS) キーを作成し、最初にモデルを作成するためのシードデータを追加します。最後に、スクリプトは `cdk deploy` を実行し、残りのインフラストラクチャを作成します。最初のモデルトレーニングはスタックの作成中に行われます。スタックの作成が完了するまでに、最大 2 時間かかることがあります。 | DevOps エンジニア |
## 関連リソース
+ 「[アニマルレコメンダー](https://github.com/aws-samples/personalize-pet-recommendations)」(GitHub)
+ 「[AWS CDK リファレンスドキュメント](https://docs.aws.amazon.com/cdk/api/v2/)」
+ 「[Boto3 ドキュメント](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)」
+ 「[Amazon Personalize で選択したビジネス指標に最適化されたパーソナライズされたレコメンデーションを最適化](https://aws.amazon.com/blogs/machine-learning/optimize-personalized-recommendations-for-a-business-metric-of-your-choice-with-amazon-personalize/)」(AWS 機械学習 ブログ)。
## 追加情報
ペイロードとレスポンスの例
Lambda 関数の推奨事項
レコメンデーションを取得するには、以下の形式のペイロードを含むレコメンデーション Lambda 関数にリクエストを送信します。
```
{
"userId": "3578196281679609099",
"limit": 6
}
```
次のレスポンス例には、アニマルグループのリストが含まれています。
```
[{"id": "1-domestic short hair-1-1"},
{"id": "1-domestic short hair-3-3"},
{"id": "1-domestic short hair-3-2"},
{"id": "1-domestic short hair-1-2"},
{"id": "1-domestic short hair-3-1"},
{"id": "2-beagle-3-3"},
```
`userId` フィールドを省略すると、関数は一般的な推奨事項を返します。
Lambda 関数の再ランク付け
再ランク付けを使用するには、再ランク付けの Lambda 関数にリクエストを送信します。ペイロードには、再ランク付けの対象となるすべてのアイテム ID の `userId` とそのメタデータが含まれます。以下のデータ例では、`animal_species_id` (1=猫、2=犬) には Oxford Pets クラスを使用し、`animal_age_id` および `animal_size_id` には 1 ～ 5 の整数を使用しています。
```
{
"userId":"12345",
"itemMetadataList":[
{
"itemId":"1",
"animalMetadata":{
"animal_species_id":"2",
"animal_primary_breed_id":"Saint_Bernard",
"animal_size_id":"3",
"animal_age_id":"2"
}
},
{
"itemId":"2",
"animalMetadata":{
"animal_species_id":"1",
"animal_primary_breed_id":"Egyptian_Mau",
"animal_size_id":"1",
"animal_age_id":"1"
}
},
{
"itemId":"3",
"animalMetadata":{
"animal_species_id":"2",
"animal_primary_breed_id":"Saint_Bernard",
"animal_size_id":"3",
"animal_age_id":"2"
}
}
]
}
```
Lambda 関数はこれらの項目を再ランク付けし、項目 ID と Amazon Personalize からのダイレクトレスポンスを含む順序付きリストを返します。これは、商品が属するアニマルグループとそのスコアをランク付けしたリストです。Amazon Personalize は、「[ユーザーパーソナライズ](https://docs.aws.amazon.com/personalize/latest/dg/native-recipe-new-item-USER_PERSONALIZATION.html)」と「[パーソナライズランキング](https://docs.aws.amazon.com/personalize/latest/dg/native-recipe-search.html)」のレシピを使用して、各項目のスコアをレコメンデーションに含めます。これらのスコアは、ユーザーが次にどのアイテムを選ぶかについて、Amazon Personalize の相対的な確実性を表します。スコアが高いほど、確実性が高くなります。
```
{
"ranking":[
"1",
"3",
"2"
],
"personalizeResponse":{
"ResponseMetadata":{
"RequestId":"a2ec0417-9dcd-4986-8341-a3b3d26cd694",
"HTTPStatusCode":200,
"HTTPHeaders":{
"date":"Thu, 16 Jun 2022 22:23:33 GMT",
"content-type":"application/json",
"content-length":"243",
"connection":"keep-alive",
"x-amzn-requestid":"a2ec0417-9dcd-4986-8341-a3b3d26cd694"
},
"RetryAttempts":0
},
"personalizedRanking":[
{
"itemId":"2-Saint_Bernard-3-2",
"score":0.8947961
},
{
"itemId":"1-Siamese-1-1",
"score":0.105204
}
],
"recommendationId":"RID-d97c7a87-bd4e-47b5-a89b-ac1d19386aec"
}
}
```
Amazon Kinesis スペイロード
Amazon Kinesis に送信するペイロードの形式は次のとおりです。
```
{
"Partitionkey": "randomstring",
"Data": {
"userId": "12345",
"sessionId": "sessionId4545454",
"eventType": "DetailView",
"animalMetadata": {
"animal_species_id": "1",
"animal_primary_breed_id": "Russian_Blue",
"animal_size_id": "1",
"animal_age_id": "2"
},
"animal_id": "98765"
}
}
```
**注記**
認証されていないユーザーの場合、`userId` フィールドは削除されます。
# SageMaker AI と Hybrid を使用して、ローカルでの開発からスケーラブルな実験に至るまでの機械学習ワークフローを合理化する
*Amazon Web Services、David Sauerwein、Marco Geiger、Julian Ferdinand Grueber*
## 概要
このパターンでは、Amazon SageMaker AI でのローカルテストから本番稼働に至るまで、機械学習 (ML) アルゴリズムを設定および実行する統一されたアプローチを提供します。ML アルゴリズムがこのパターンの焦点となりますが、そのアプローチは特徴量エンジニアリング、推論、ML パイプライン全体に及びます。このパターンでは、サンプルユースケースを通じて、ローカルスクリプト開発から SageMaker AI トレーニングジョブへの移行について説明します。
一般的な ML ワークフローでは、ローカルマシンでソリューションを開発およびテストし、クラウドで大規模な実験 (異なるパラメータを使用した実験など) を実行して、承認されたソリューションをクラウドにデプロイします。その後、デプロイされたソリューションをモニタリングして保守する必要があります。通常、このワークフローに対する統一されたワークフローがない場合、開発者は各段階でコードのリファクタリングを実行する必要が生じます。ソリューションが多数のパラメータに依存しており、そのパラメータがこのワークフローのいずれかの段階で変更される可能性があると、整合性と一貫性の維持がさらに困難になりかねません。
このパターンでは、このような課題に対処します。まず、実行環境 (ローカルマシン、コンテナ、SageMaker AI) にかかわらず一貫性を保つ統一ワークフローを提供することで、環境間でのコードのリファクタリングを不要にします。次に、Hydra の設定システムを通じてパラメータ管理を簡素化します。このシステムでは、パラメータが個別の設定ファイルに定義されているため、変更や組み合わせが容易です。また、各実行の設定が自動的にログに記録されます。このパターンがこれらの課題にどのように対処するかについては、「[追加情報](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-additional)」を参照してください。
## 前提条件と制限
**前提条件**
+ アクティブな AWS アカウント
+ SageMaker AI トレーニングジョブをデプロイおよび開始するための AWS Identity and Access Management (IAM) [ユーザーロール](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)
+ AWS Command Line Interface (AWS CLI) バージョン 2.0 以降[がインストールされ](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)、[設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)されている
+ [Poetry](https://python-poetry.org/) バージョン 1.8 以降かつ 2.0 以前をインストール済み
+ [Docker](https://www.docker.com/) をインストール済み
+ Python [バージョン 3.10.x](https://www.python.org/downloads/release/python-31011/)
**制限事項**
+ 現在、コードは SageMaker AI トレーニングジョブのみを対象としています。処理ジョブや SageMaker AI パイプライン全体に容易に拡張できます。
+ 完全に本番稼働化された SageMaker AI のセットアップでは、追加の詳細設定を行う必要があります。例としては、コンピューティングとストレージの custom AWS Key Management Service (AWS KMS) キーや、ネットワーク設定などがあります。これらの追加オプションは、`config` フォルダの専用サブフォルダにある Hydra を使用して設定することもできます。
+ 一部の AWS のサービス は では使用できません AWS リージョン。利用可能なリージョンについては、「[AWS サービス (リージョン別)](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)」を参照してください。特定のエンドポイントについては、「[サービスエンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)」を参照して、サービスのリンクを選択してください。
## アーキテクチャ
ソリューションアーキテクチャを次の図に示します。
![\[SageMaker AI トレーニングまたは HPO ジョブを作成して実行するワークフロー。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/1db57484-f85c-49a6-b870-471dade02b26/images/d80e7474-a975-4d92-8f66-2d34e33053fd.png)
この図表は、次のワークフローを示しています:
1. データサイエンティストは、Docker や SageMaker AI を必要とせずに、ローカル環境でのアルゴリズムの小規模な反復処理、パラメータの調整、トレーニングスクリプトの迅速なテストを実行できます (詳細については、[エピック](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-epics)の「クイックテストのためにローカルで実行します」タスクを参照してください)。
1. アルゴリズムが適切であることを確認したら、データサイエンティストは Docker イメージを構築し、`hydra-sm-artifact` という名前の Amazon Elastic Container Registry (Amazon ECR) リポジトリにプッシュします (詳細については、エピックの「[SageMaker AI でワークフローを実行する](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-epics)」を参照してください)。
1. データサイエンティストは、Python スクリプトを使用して SageMaker AI トレーニングジョブまたはハイパーパラメータの最適化 (HPO) ジョブを開始します。通常のトレーニングジョブの場合、調整された設定は `hydra-sample-config` という名前の Amazon Simple Storage Service (Amazon S3) バケットに書き込まれます。HPO ジョブの場合、`config` フォルダにあるデフォルト設定セットが適用されます。
1. SageMaker AI トレーニングジョブが、Docker イメージをプルし、Amazon S3 バケット `hydra-sample-data` から入力データを読み取り、Amazon S3 バケット `hydra-sample-config` から設定を取得するか、デフォルト設定を使用します。トレーニング後、ジョブが出力データを Amazon S3 バケット `hydra-sample-data` に保存します。
**自動化とスケール**
+ 自動トレーニング、再トレーニング、推論では、 AWS CLI コードを [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)、、[AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html)[Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) などのサービスと統合できます。
+ スケーリングは、インスタンスサイズの設定を変更するか、分散トレーニングの設定を追加することで実現できます。
## ツール
**AWS のサービス**
+ [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) は、 AWS リソースをセットアップし、迅速かつ一貫してプロビジョニングし、 AWS アカウント および 全体のライフサイクルを通じてリソースを管理するのに役立ちます AWS リージョン。
+ [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) は、コマンドラインシェルのコマンド AWS のサービス を使用して を操作するのに役立つオープンソースツールです。このパターンでは、 AWS CLI は初期リソース設定とテストの両方に役立ちます。
+ [Amazon Elastic Container Registry (Amazon ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) は、セキュリティ、スケーラビリティ、信頼性を備えたマネージドコンテナイメージレジストリサービスです。
+ [Amazon SageMaker AI](https://docs.aws.amazon.com/sagemaker/?id=docs_gateway) はマネージド型の機械学習 (ML) サービスで、ML モデルの構築とトレーニングを行い、それらを本番稼働環境に対応したホスティング環境にデプロイします。SageMaker AI Training は、大規模な ML モデルのトレーニングを可能にする SageMaker AI 内の完全マネージド型 ML サービスです。このツールは、組み込みのスケーラビリティと他の との統合を利用して、トレーニングモデルの計算上の需要を効率的に処理できます AWS のサービス。SageMaker AI Training はカスタムアルゴリズムとコンテナもサポートしているため、幅広い ML ワークフローに柔軟に対応できます。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) は、あらゆる量のデータを保存、保護、取得できるクラウドベースのオブジェクトストレージサービスです。
**その他のツール**
+ [Docker](https://www.docker.com/) は、オペレーティングシステムレベルの仮想化を使用してソフトウェアをコンテナで配信するサービスとしての Platform as a Service (PaaS) 製品のセットです。このパターンでは、開発からデプロイまでのさまざまな段階で一貫した環境を確保し、依存関係とコードを確実にパッケージ化するために使用されています。Docker のコンテナ化により、ワークフロー全体でのスケーリングとバージョン管理が容易になりました。
+ [Hydra](https://hydra.cc/) は、複数の設定と動的リソース管理を柔軟に処理できる設定管理ツールです。環境設定の管理に役立ち、さまざまな環境でのシームレスなデプロイを可能にします。Hydra の詳細については、「[追加情報](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-additional)」を参照してください。
+ 「[Python](https://www.python.org/)」は汎用のコンピュータプログラミング言語です。Python は、ML コードとデプロイワークフローの記述に使用されています。
+ [Poetry](https://python-poetry.org/) は、Python での依存関係管理とパッケージングのためのツールです。
**コードリポジトリ**
このパターンのコードは、GitHub の [configuring-sagemaker-training-jobs-with-hydra](https://github.com/aws-samples/configuring-sagemaker-training-jobs-with-hydra) リポジトリで入手できます。
## ベストプラクティス
+ SageMaker AI トレーニングジョブをデプロイおよび開始するための IAM ロールを選択します。最小特権の原則に従い、タスクの実行に必要な最小限の権限を付与してください。詳細については、IAM ドキュメントの「[最小限の特権を認める。](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#grant-least-priv)」と「[IAM でのセキュリティのベストプラクティス](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)」を参照してください。
+ 一時的な認証情報を使用して、ターミナルの IAM ロールにアクセスします。
## エピック
### 環境をセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 仮想環境を作成してアクティブ化します。 | 仮想環境を作成してアクティブ化するには、リポジトリのルートで次のコマンドを実行します。poetry install
poetry shell
| AWS 全般 |
| インフラストラクチャを準備します。 | CloudFormation を使用してインフラストラクチャをデプロイするには、次のコマンドを実行します。aws cloudformation deploy --template-file infra/hydra-sagemaker-setup.yaml --stack-name hydra-sagemaker-setup --capabilities CAPABILITY_NAMED_IAM
| AWS 全般、DevOps エンジニア |
| サンプルデータをダウンロードします。 | [openml](https://www.openml.org/) からローカルマシンに入力データをダウンロードするには、次のコマンドを実行します。python scripts/download_data.py
| AWS 全般 |
| クイックテストのためにローカルで実行します。 | テストのためにトレーニングコードをローカルで実行するには、次のコマンドを実行します。python mypackage/train.py data.train_data_path=data/train.csv evaluation.base_dir_path=data
すべての実行のログは、実行時間ごとに `outputs` というフォルダに保存されます。詳細については、[GitHub リポジトリ](https://github.com/aws-samples/configuring-sagemaker-training-jobs-with-hydra)の「出力」セクションを参照してください。`--multirun` 機能を使用することで、異なるパラメータで複数のトレーニングを並行して実行することもできます。詳細については、[Hydra のドキュメント](https://hydra.cc/docs/tutorials/basic/running_your_app/multi-run/)を参照してください。 | データサイエンティスト |
### SageMaker AI でワークフローを実行する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 環境変数を設定します。 | SageMaker AI でジョブを実行するには、 AWS リージョン と AWS アカウント ID を指定して、次の環境変数を設定します。export ECR_REPO_NAME=hydra-sm-artifact
export image_tag=latest
export AWS_REGION="" # for instance, us-east-1
export ACCOUNT_ID=""
export BUCKET_NAME_DATA=hydra-sample-data-$ACCOUNT_ID
export BUCKET_NAME_CONFIG=hydra-sample-config-$ACCOUNT_ID
export AWS_DEFAULT_REGION=$AWS_REGION
export ROLE_ARN=arn:aws:iam::${ACCOUNT_ID}:role/hydra-sample-sagemaker
export INPUT_DATA_S3_PATH=s3://$BUCKET_NAME_DATA/hydra-on-sm/input/
export OUTPUT_DATA_S3_PATH=s3://$BUCKET_NAME_DATA/hydra-on-sm/output/
| AWS 全般 |
| Docker イメージを作成してプッシュします。 | Docker イメージを作成して Amazon ECR リポジトリにプッシュするには、次のコマンドを実行します。chmod +x scripts/create_and_push_image.sh
scripts/create_and_push_image.sh $ECR_REPO_NAME $image_tag $AWS_REGION $ACCOUNT_ID
このタスクは、環境に有効な認証情報があることを前提としています。Docker イメージは、前のタスクの環境変数で指定された Amazon ECR リポジトリにプッシュされ、トレーニングジョブが実行される SageMaker AI コンテナをアクティブ化するために使用されます。 | ML エンジニア、AWS 全般 |
| 入力データを Amazon S3 にコピーします。 | SageMaker AI トレーニングジョブでは、入力データを取得する必要があります。入力データをデータ用の Amazon S3 バケットにコピーするには、次のコマンドを実行します。aws s3 cp data/train.csv "${INPUT_DATA_S3_PATH}train.csv" | データエンジニア、AWS 全般 |
| SageMaker AI トレーニングジョブを送信します。 | スクリプトの実行を簡素化するには、`default.yaml` ファイルでデフォルトの設定パラメータを指定します。このアプローチでは、実行間の一貫性の維持に加えて、必要に応じてデフォルト設定を柔軟に上書きできます。次の例を参照してください。python scripts/start_sagemaker_training_job.py sagemaker.role_arn=$ROLE_ARN sagemaker.config_s3_bucket=$BUCKET_NAME_CONFIG sagemaker.input_data_s3_path=$INPUT_DATA_S3_PATH sagemaker.output_data_s3_path=$OUTPUT_DATA_S3_PATH
| AWS 全般、ML エンジニア、データサイエンティスト |
| SageMaker AI ハイパーパラメータチューニングを実行します。 | SageMaker AI ハイパーパラメータチューニングの実行は、SageMaker AII トレーニングジョブの送信に似ています。ただし、[start\$1sagemaker\$1hpo\$1job.py](https://github.com/aws-samples/configuring-sagemaker-training-jobs-with-hydra/blob/main/scripts/start_sagemaker_hpo_job.py) ファイルで確認できるように、実行スクリプトにはいくつかの重要な点で相違があります。チューニングするハイパーパラメータは、トレーニングジョブへのチャネルではなく、boto3 ペイロードを通過する必要があります。ハイパーパラメータの最適化 (HPO) ジョブを開始するには、次のコマンドを実行します。python scripts/start_sagemaker_hpo_job.py sagemaker.role_arn=$ROLE_ARN sagemaker.config_s3_bucket=$BUCKET_NAME_CONFIG sagemaker.input_data_s3_path=$INPUT_DATA_S3_PATH sagemaker.output_data_s3_path=$OUTPUT_DATA_S3_PATH
| データサイエンティスト |
## トラブルシューティング
| 問題 | ソリューション |
| --- | --- |
| 期限切れのトークン | 新しい AWS 認証情報をエクスポートします。 |
| IAM アクセス許可の欠如 | CloudFormation テンプレートをデプロイし、SageMaker AI トレーニングジョブを開始するために必要なすべての IAM アクセス許可を持つ IAM ロールの認証情報をエクスポートしてください。 |
## 関連リソース
+ [Amazon SageMaker AI を使用してモデルをトレーニング](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html)する (AWS ドキュメント)
+ [ハイパーパラメータチューニングとは何ですか?](https://aws.amazon.com/what-is/hyperparameter-tuning/#:~:text=Hyperparameter%20tuning%20allows%20data%20scientists,the%20model%20as%20a%20hyperparameter.)
## 追加情報
このパターンでは、以下の課題に対処します。
**ローカル開発から大規模なデプロイまでの一貫性** – このパターンでは、ローカル Python スクリプトを使用しているか、ローカル Docker コンテナを実行しているか、SageMaker AI で大規模実験を実行しているか、SageMaker AI で本番環境にデプロイしているかに関係なく、開発者が同じワークフローを使用できます。この一貫性は、次の理由により重要です。
+ **イテレーションの高速化** – スケールアップする際に大幅な調整を必要とせずに、ローカルで迅速に実験できます。
+ **リファクタリング不要** – SageMaker AI での大規模実験への移行はシームレスで、既存のセットアップの見直しは必要ありません。
+ **継続的な改善** – 環境間で同じコードを使用するため、新機能の開発やアルゴリズムの継続的な改善が容易です。
**設定管理** – このパターンでは、設定管理ツールである [Hydra](https://hydra.cc/) を活用することで次のような利点があります。
+ パラメータは、コードとは別に設定ファイルで定義されます。
+ さまざまなパラメータセットの入れ替えや組み合わせを簡単に実行できます。
+ 各実行の設定は自動的にログに記録されるため、実験の追跡が簡素化されます。
+ クラウド実験では、ローカル実行と同じ設定構造を使用して一貫性を確保できます。
Hydra を使用すると、設定を効果的に管理し、次の機能を有効にできます。
+ **設定の分割** – プロジェクト設定を管理しやすい小単位に分割できます (それぞれ個別に変更可能)。このアプローチにより、複雑なプロジェクトを簡単に処理できます。
+ **デフォルト調整が容易** – ベースライン設定をすばやく変更できるため、新しいアイデアをより簡単にテストできます。
+ **CLI 入力と設定ファイルの連携** – コマンドライン入力を設定ファイルとスムーズに組み合わせることができます。このアプローチにより、煩雑さや混乱が軽減され、時間経過に合わせたプロジェクトの管理がより簡単になります。
# 自然言語を OpenSearch と Elasticsearch のクエリ向けにクエリ DSL に変換する
*Amazon Web Services、Tabby Ward、Nicholas Switzer、Breanne Warner*
## 概要
このパターンでは、大規模言語モデル (LLM) を使用して自然言語クエリをクエリドメイン固有言語 (クエリ DSL) に変換する方法を説明します。この方法を使用することで、ユーザーはクエリ言語に関する広範な知識がなくても OpenSearch や Elasticsearch などの検索サービスと容易にやり取りできるようになります。このリソースは、自然言語クエリ機能で検索ベースのアプリケーションを強化し、最終的にユーザーエクスペリエンスと検索機能を向上させたい開発者やデータサイエンティストにとって特に有益です。
このパターンでは、プロンプトエンジニアリング、反復的な改良、専門知識の組み込みといった手法を示します。これらはすべて合成データ生成に不可欠です。このアプローチは主にクエリ変換に焦点を当てていますが、データ拡張とスケーラブルな合成データ生成の可能性を暗黙的に示しています。この基盤は、より包括的な合成データ生成タスクに拡張可能であり、構造化されていない自然言語入力と構造化されたアプリケーション固有の出力をブリッジする LLM の能力を明確に示すことができます。
このソリューションには、従来の意味での移行ツールやデプロイツールは含まれていません。代わりに、LLM を使用して自然言語クエリをクエリ DSL に変換する概念実証 (PoC) の説明に焦点を当てています。
+ このパターンでは、環境を設定し、テキストからクエリへの変換を実装するためのステップバイステップガイドとして Jupyter Notebook を使用します。
+ Amazon Bedrock を使用して LLM にアクセスします。これは自然言語を解釈し、適切なクエリを生成するために不可欠です。
+ このソリューションは、Amazon OpenSearch Service と連携するように設計されています。Elasticsearch でも同様のプロセスに従うことが可能で、生成されたクエリを同様の検索エンジンに適用できる可能性があります。
[クエリ DSL](https://opensearch.org/docs/latest/query-dsl/) は、Elasticsearch と OpenSearch の両方で複雑なクエリを構築するために使用される柔軟な JSON ベースの検索言語です。これは、検索オペレーションのクエリパラメータでクエリを指定できるようにするもので、さまざまなクエリタイプをサポートしています。DSL クエリには、リーフクエリや複合クエリがあります。リーフクエリは、特定のフィールドの特定の値を検索します。全文クエリ、用語レベルクエリ、地理的クエリ、結合クエリ、スパンクエリ、および特殊なクエリを含みます。複合クエリは、複数のリーフ句または複合句のラッパーとして機能し、結果を結合したり、動作を変更したりします。クエリ DSL は、単純な完全一致クエリから非常に具体的な結果を生成する複雑な複数句のクエリまで、高度な検索の作成をサポートします。クエリ DSL は、高度な検索機能、柔軟なクエリ構築、JSON ベースのクエリ構造を必要とするプロジェクトに特に役立ちます。
このパターンでは、テキストからクエリへの DSL 変換に、フューショットプロンプト、システムプロンプト、構造化出力、プロンプトチェイニング、コンテキストのプロビジョニング、タスク固有のプロンプトなどの手法を使用します。これらの手法の定義と例については、「[追加情報](#translate-natural-language-query-dsl-opensearch-elasticsearch-additional)」セクションを参照してください。
## 前提条件と制限
**前提条件**
Jupyter Notebook を効果的に使用して自然言語クエリをクエリ DSL のクエリに変換するには、以下が必要です。
+ **Jupyter Notebook への精通**。Jupyter Notebook 環境でコードを移動および実行する方法の基本的な理解。
+ **Python 環境**。必要なライブラリがインストールされた、動作中の Python 環境 (Python 3.x を推奨)。
+ **Elasticsearch または OpenSearch の知識**。アーキテクチャやクエリの実行方法など、Elasticsearch または OpenSearch の基本的な知識。
+ **AWS アカウント**。 Amazon Bedrock およびその他の関連サービスにアクセス AWS アカウント するためのアクティブな 。
+ **ライブラリと依存関係**。 AWS インタラクション`boto3`や LLM 統合に必要なその他の依存関係など、ノートブックに記載されている特定のライブラリのインストール。
+ **Amazon Bedrock のモデルアクセス**。このパターンでは、Anthropic の Claude LLM を 3 つ使用します。[Amazon Bedrock コンソール](https://console.aws.amazon.com/bedrock/)を開き、**[モデルアクセス]**を選択します。次の画面で、**[特定のモデルを有効にする]**を選択し、次の 3 つのモデルを選択します。
+ Claude 3 Sonnet
+ Claude 3.5 Sonnet
+ Claude 3 Haiku
+ **適切な IAM ポリシーと IAM ロール**。でノートブックを実行するには AWS アカウント、 AWS Identity and Access Management (IAM) ロールに `SagemakerFullAccess`ポリシーと、[「追加情報](#translate-natural-language-query-dsl-opensearch-elasticsearch-additional)」セクションで提供されているポリシーが必要です。このポリシーには、 という名前を付けることができます`APGtext2querydslpolicy`。このポリシーには、リストされている 3 つの Claude モデルへのサブスクライブが含まれています。
これらの前提条件を設定することで、ノートブックの操作やテキストからクエリへの変換機能の実装をスムーズに行うことができます。
**制限事項**
+ **概念実証のステータス**。このプロジェクトは主に概念実証 (PoC) を目的としています。これは、LLM を使用して自然言語クエリをクエリ DSL に変換する潜在能力を示すものですが、完全に最適化されておらず、本番環境には対応していない可能性があります。
+ **モデルの制限**:
**コンテキストウィンドウの制約***。*Amazon Bedrock で利用可能な LLM を使用する場合は、コンテキストウィンドウの制限に注意してください。
Claude モデル (2024 年 9 月現在):
+ Claude 3 Opus: 200,000 トークン
+ Claude 3 Sonnet: 200,000 トークン
+ Claude 3 Haiku: 200,000 トークン
Amazon Bedrock のその他のモデルでは、コンテキストウィンドウのサイズが異なる場合があります。最新情報については、最新のドキュメントを参照してください。
**モデルの可用性***。*Amazon Bedrock における特定のモデルの可用性は異なる場合があります。このソリューションを実装する前に、必要なモデルにアクセスできることを確認してください。
+ **その他の制限事項**
+ **クエリの複雑さ**。自然言語からクエリ DSL への変換の有効性は、入力クエリの複雑さによって異なる場合があります。
+ **バージョン互換性**。生成されたクエリ DSL は、使用する Elasticsearch または OpenSearch の特定のバージョンに応じて調整が必要になる場合があります。
+ **パフォーマンス**。このパターンで提供するのは PoC 実装であるため、大規模な本番環境で使用する場合はクエリ生成の速度と精度が最適でない可能性があります。
+ **料金**。Amazon Bedrock で LLM を使用すると、コストが発生します。選択したモデルの料金体系に注意してください。詳細については、「[Amazon Bedrock の料金](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-pricing.html)」を参照してください。
+ **メンテナンス**。LLM テクノロジーの進歩やクエリ DSL 構文の変更に対応するために、プロンプトとモデルの選択を定期的に更新する必要が生じる場合があります。
**製品バージョン**
このソリューションは Amazon OpenSearch Service でテストされています。Elasticsearch を使用する場合、このパターンの機能を正確にレプリケートするためにいくつかの変更が必要になる場合があります。
+ **OpenSearch バージョンの互換性**。****OpenSearch は、メジャーバージョン内で下位互換性を維持します。例えば、次のようになります。
+ OpenSearch 1.x クライアントは、通常、OpenSearch 1.x クラスターと互換性があります。
+ OpenSearch 2.x クライアントは、通常、OpenSearch 2.x クラスターと互換性があります。
ただし、可能な限り、クライアントとクラスターの両方で同じマイナーバージョンを使用することをお勧めします。
+ **OpenSearch API の互換性**。****OpenSearch は、ほとんどのオペレーションで Elasticsearch OSS 7.10.2 との API 互換性を維持しています。ただし、特に新しいバージョンでは、いくつかの相違点が存在します。
+ **OpenSearch のアップグレードに関する考慮事項**:
+ 直接ダウングレードはサポートされていません。必要に応じて、スナップショットを使用してロールバックします。
+ アップグレードする際は、重大な変更がないか[互換性マトリックスとリリースノート](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-operations.html)を確認してください。
**Elasticsearch に関する考慮事項**
+ **Elasticsearch のバージョン**。クエリ構文や機能はメジャーバージョン間で変更される可能性があるため、使用している Elasticsearch のメジャーバージョンが重要です。現在、最新の安定バージョンは Elasticsearch 8.x です。クエリが特定の Elasticsearch バージョンと互換性があることを確認してください。
+ **Elasticsearch クエリ DSL ライブラリのバージョン**。Elasticsearch の Python 用クエリ DSL ライブラリを使用している場合は、そのバージョンが Elasticsearch のバージョンと一致していることを確認してください。例えば、次のようになります。
+ Elasticsearch 8.x の場合は、8.0.0 以降 9.0.0 より前の `elasticsearch-dsl` バージョンを使用します。
+ Elasticsearch 7.x の場合は、7.0.0 以降 8.0.0 より前の `elasticsearch-dsl` バージョンを使用します。
+ **クライアントライブラリのバージョン**。公式の Elasticsearch クライアントを使用する場合も言語固有のクライアントを使用する場合も、Elasticsearch バージョンと互換性があることを確認してください。
+ **クエリ DSL のバージョン**。クエリ DSL は Elasticsearch バージョンとともに進化します。一部のクエリタイプまたはパラメータは、バージョンによって廃止されたり、導入されたりする可能性があります。
+ **マッピングのバージョン**。インデックスのマッピングを定義する方法やバージョン間で変更する方法です。特定の Elasticsearch バージョンのマッピングに関するドキュメントを必ず確認してください。
+ **分析ツールのバージョン**。アナライザー、トークナイザ、またはその他のテキスト分析ツールを使用している場合、バージョンによって動作や可用性が変わる可能性があります。
## アーキテクチャ
**ターゲットアーキテクチャ**
このパターンのアーキテクチャを以下に図で示します。
![\[Amazon Bedrock で自然言語からクエリ DSL に変換する場合のアーキテクチャ。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/75296405-2893-4328-9551-9bcc6ec7fd3e/images/ffb1b893-d23c-4e1c-b679-8063b4f85a8a.png)
各パラメータの意味は次のとおりです。
1. フューショットプロンプトの例を含むユーザー入力とシステムプロンプト。このプロセスは、自然言語クエリまたはスキーマ生成のリクエストを提供するユーザーから始まります。
1. Amazon Bedrock 入力は Amazon Bedrock に送信されます。Amazon Bedrock は Claude LLM にアクセスするためのインターフェイスとして機能します。
1. Claude 3 Sonnet LLM。Amazon Bedrock は、Claude 3 ファミリーの Claude 3 Sonnet LLM を使用して入力を処理します。入力を解釈して、適切な Elasticsearch または OpenSearch クエリ DSL を生成します。スキーマリクエストの場合、Elasticsearch または OpenSearch の合成マッピングを生成します。
1. クエリ DSL の生成。自然言語クエリの場合、アプリケーションは LLM の出力を受け取り、有効な Elasticsearch または OpenSearch Service のクエリ DSL にフォーマットします。
1. 合成データ生成。また、アプリケーションはスキーマを受け取り、Elasticsearch または OpenSearch の合成データを作成して、テスト用に OpenSearch Serverless コレクションにロードします。
1. OpenSearch または Elasticsearch。生成されたクエリ DSL は、すべてのインデックスの OpenSearch Serverless コレクションに対してクエリされます。JSON 出力には、OpenSearch Serverless コレクションに存在するデータからの関連データと*ヒット*数が含まれます。
**自動化とスケール**
このパターンで提供されるコードは、PoC のみを目的として構築されています。次のリストに、ソリューションの自動化とスケーリングをさらに進め、コードを本番環境に移行するための提案を示します。これらの機能拡張は、このパターンの範囲には含まれません。
+ コンテナ化:
+ アプリケーションを Docker 化して、さまざまな環境での一貫性を確保します。
+ Amazon Elastic Container Service (Amazon ECS) や Kubernetes などのコンテナオーケストレーションプラットフォームを使用して、スケーラブルなデプロイを実現します。
+ サーバーレスアーキテクチャ:
+ コア機能を AWS Lambda 関数に変換します。
+ Amazon API Gateway を使用して、自然言語クエリ入力用の RESTful エンドポイントを作成します。
+ 非同期処理:
+ Amazon Simple Queue Service (Amazon SQS) を実装して、受信クエリをキューに入れます。
+ を使用して AWS Step Functions 、クエリを処理し、クエリ DSL を生成するワークフローを調整します。
+ キャッシュ:
+ プロンプトをキャッシュするメカニズムを実装します。
+ モニタリングとログ記録:
+ モニタリングとアラートに Amazon CloudWatch を使用します。
+ ログ分析に Amazon CloudWatch Logs または Amazon OpenSearch Service を使用して一元的なログ記録を実装します。
+ セキュリティ強化:
+ IAM ロールを実装してきめ細かなアクセスコントロールを実現します。
+ を使用して AWS Secrets Manager 、API キーと認証情報を安全に保存および管理します。
+ マルチリージョンデプロイ:
+ レイテンシーとディザスタリカバリを改善する AWS リージョン ために、ソリューションを複数の にデプロイすることを検討してください。
+ インテリジェントなリクエストルーティングに Amazon Route 53 を使用します。
これらの提案を実装することで、この PoC を堅牢かつスケーラブルで本番環境に対応したソリューションに変換できます。完全なデプロイの前に、各コンポーネントとシステム全体を徹底的にテストすることをお勧めします。
## ツール
**ツール**
+ [Amazon SageMaker AI ノートブック](https://aws.amazon.com/sagemaker/notebooks/)は、機械学習開発用のフルマネージド型 Jupyter Notebook です。このパターンでは、Amazon SageMaker AI のデータ探索、モデル開発、実験のためのインタラクティブな環境としてノートブックを使用します。ノートブックは、他の SageMaker AI 機能や とシームレスに統合できます AWS のサービス。
+ 「[Python](https://www.python.org/)」は汎用のコンピュータプログラミング言語です。このパターンでは、Python をコア言語として使用してソリューションを実装します。
+ [Amazon Bedrock](https://aws.amazon.com/bedrock/) は、主要な AI スタートアップや Amazon が提供する高パフォーマンスな基盤モデル (FM) を、統合 API を通じて利用できるようにするフルマネージド型サービスです。Amazon Bedrock は、自然言語処理用の LLM へのアクセスを提供します。このパターンでは、Anthropic Claude 3 モデルを使用します。
+ [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) は、Amazon Bedrock AWS のサービスを含む Python アプリケーション、ライブラリ、またはスクリプトを と統合するのに役立つソフトウェア開発キットです。
+ 「[Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/what-is.html)」は、AWS クラウドにおける OpenSearch クラスターのデプロイ、オペレーション、スケーリングを支援するマネージドサービスです。このパターンでは、クエリ DSL を生成するためのターゲットシステムとして OpenSearch Service を使用します。
**コードリポジトリ**
このパターンのコードは、GitHub の「[Prompt Engineering Text-to-QueryDSL Using Claude 3 Models](https://github.com/aws-samples/text-to-queryDSL/blob/main/text2ES_prompting_guide.ipynb)」リポジトリで入手できます。この例では、ヘルスソーシャルメディアアプリを使用して、ユーザーに対する投稿とヘルスアプリケーションに関連付けられたユーザープロファイルを作成します。
## ベストプラクティス
このソリューションを使用する場合は、次の点を考慮してください。
+ Amazon Bedrock にアクセスするための適切な AWS 認証情報とアクセス許可の必要性
+ AWS のサービス および LLMs の使用に関連する潜在的なコスト
+ クエリ DSL を理解して、生成されたクエリを検証し、必要に応じて変更することが重要です。
## エピック
### 環境を設定し、データを準備する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 開発環境を設定します。 | この詳細な手順とコード、およびこのパターンのその他の手順については、[GitHub リポジトリ](https://github.com/aws-samples/text-to-queryDSL/blob/main/text2ES_prompting_guide.ipynb)の包括的なチュートリアルを参照してください。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/translate-natural-language-query-dsl-opensearch-elasticsearch.html) | Python、pip、AWS SDK |
| AWS アクセスを設定します。 | Amazon Bedrock クライアントと SageMaker AI セッションを設定します。後で OpenSearch Serverless コレクションの作成時に使用するために、SageMaker AI 実行ロールの Amazon リソースネーム (ARN) を取得します。 | IAM、AWS CLI、Amazon Bedrock、Amazon SageMaker |
| ヘルスアプリのスキーマをロードします。 | 事前定義されたファイルからヘルス投稿とユーザープロファイル用の JSON スキーマを読み取り、解析します。後でプロンプトで使用するためにスキーマを文字列に変換します。 | DevOps エンジニア、AWS 全般、Python、JSON |
### 合成データを生成する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| LLM ベースのデータジェネレーターを作成します。 | **generate\$1data()** 関数を実装して、Claude 3 モデルで Amazon Bedrock Converse API を呼び出します。Sonnet、Sonnet 3.5、および Haiku のモデル ID を設定します。model_id_sonnet3_5 = "anthropic.claude-3-5-sonnet-20240620-v1:0"
model_id_sonnet = "anthropic.claude-3-sonnet-20240229-v1:0"
model_id_haiku = "anthropic.claude-3-haiku-20240307-v1:0"
| Python、Amazon Bedrock API、LLM プロンプト |
| 合成ヘルス投稿を作成します。 | 特定のメッセージプロンプトとともに **generate\$1data()** 関数を使用し、指定されたスキーマに基づいて合成ヘルス投稿エントリを作成します。関数呼び出しは次のようになります。health_post_data = generate_data(bedrock_rt, model_id_sonnet, system_prompt, message_healthpost, inference_config)
| Python、JSON |
| 合成ユーザープロファイルを作成します。 | 特定のメッセージプロンプトとともに **generate\$1data()** 関数を使用し、指定されたスキーマに基づいて合成ユーザープロファイルエントリを作成します。これはヘルス投稿の生成に似ていますが、別のプロンプトを使用します。 | Python、JSON |
### OpenSearch を設定してデータを取り込む
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| OpenSearch Serverless コレクションを設定します。 | Boto3 を使用し、適切な暗号化、ネットワーク、アクセスポリシーを指定して OpenSearch Serverless コレクションを作成します。コレクションの作成は次のようになります。collection = aoss_client.create_collection(name=es_name, type='SEARCH')
OpenSearch Serverless の詳細については、[AWS ドキュメント](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless.html)を参照してください。 | OpenSearch Serverless、IAM |
| OpenSearch インデックスを定義します。 | 事前定義されたスキーママッピングに基づいて OpenSearch クライアントを使用して、ヘルス投稿とユーザープロファイルのインデックスを作成します。インデックスの作成は次のようになります。response_health = oss_client.indices.create(healthpost_index, body=healthpost_body)
| OpenSearch、JSON |
| OpenSearch にデータをロードします。 | **ingest\$1data()** 関数を実行して、合成ヘルス投稿とユーザープロファイルをそれぞれの OpenSearch インデックスに一括挿入します。関数は、`opensearch-py` の bulk ヘルパーを使用します。success, failed = bulk(oss_client, actions)
| Python、OpenSearch API、データ一括操作 |
### クエリを作成して実行する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| フューショットプロンプトの例を設計します。 | Claude 3 モデルを使用してクエリ生成のフューショットの例を提供し、クエリの例と対応する自然言語の質問を生成します。システムプロンプトには、次の例が含まれます。system_prompt_query_generation = [{"text": f"""You are an expert query dsl generator. ... Examples: {example_prompt} ..."""}] | LLM プロンプト、クエリ DSL |
| テキストからクエリ DSL へのコンバーターを作成します。 | クエリ生成用のスキーマ、データ、フューショットの例を含むシステムプロンプトを実装します。システムプロンプトを使用して、自然言語クエリをクエリ DSL に変換します。関数呼び出しは次のようになります。query_response = generate_data(bedrock_rt, model_id, system_prompt_query_generation, query, inference_config)
| Python、Amazon Bedrock API、LLM プロンプト |
| OpenSearch でクエリ DSL をテストします。 | **query\$1oss()** 関数を実行し、生成されたクエリ DSL を OpenSearch Serverless コレクションに対して実行し、結果を返します。関数は OpenSearch クライアントの検索方法を使用します。response = oss_client.search(index="_all", body=temp)
| Python、OpenSearch API、クエリ DSL |
### テストと評価
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| テストクエリセットを作成します。 | Claude 3 を使用し、合成データとスキーマに基づいてさまざまなテスト用の質問を生成します。test_queries = generate_data(bedrock_rt, model_id_sonnet, query_system_prompt, query_prompt, inference_config)
| LLM プロンプト |
| クエリ DSL 変換の精度を評価します。 | OpenSearch に対してクエリを実行し、返された結果の関連性と精度を分析して、生成されたクエリ DSL をテストします。これには、クエリの実行とヒットの検査が含まれます。output = query_oss(response1) print("Response after running query against Opensearch") print(output) | Python、データ分析、クエリ DSL |
| Claude 3 モデルをベンチマークします。 | 精度とレイテンシーの観点から、クエリ生成についてさまざまな Claude 3 モデル (Haiku、Sonnet、Sonnet 3.5) のパフォーマンスを比較します。比較するには、**generate\$1data()** を呼び出す際に `model_id` を変更し、実行時間を測定します。 | Python、パフォーマンスベンチマーク |
### クリーンアップとドキュメント化
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| クリーンアッププロセスを開発します。 | 使用後に OpenSearch Serverless コレクションからすべてのインデックスを削除します。 | Python、AWS SDK、OpenSearch API |
## 関連リソース
+ [Query DSL](https://opensearch.org/docs/latest/query-dsl/) (OpenSearch ドキュメント)
+ 「[Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/what-is.html)」
+ [OpenSearch Serverless コレクション](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html)
+ [Amazon Bedrock ドキュメント](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)
+ [Amazon SageMaker AI ドキュメント](https://docs.aws.amazon.com/sagemaker/latest/dg/whatis.html)
+ [AWS SDK for Python (Boto3) ドキュメント](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
## 追加情報
**IAM ポリシー**
このパターンで使用される IAM ロールの `APGtext2querydslpolicy` ポリシーは次のとおりです。
```
{
"Version": "2012-10-17",
"Statement": [
{ "Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": "*"
},
{ "Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::sagemaker-*",
"arn:aws:s3:::sagemaker-*/*"
]
},
{ "Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:*:*:log-group:/aws/sagemaker/*"
},
{ "Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
},
{ "Effect": "Allow",
"Action": [
"aoss:*"
],
"Resource": "*"
},
{ "Effect": "Allow",
"Action": [
"iam:PassRole",
"sagemaker:*"
],
"Resource": [
"arn:aws:iam::*:role/*", "*"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "sagemaker.amazonaws.com"
}
}
},
{ "Effect": "Allow",
"Action": [
"codecommit:GetBranch",
"codecommit:GetCommit",
"codecommit:GetRepository",
"codecommit:ListBranches",
"codecommit:ListRepositories"
],
"Resource": "*"
},
{ "Effect": "Allow",
"Action": [
"aws-marketplace:Subscribe"
],
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"aws-marketplace:ProductId": [
"prod-6dw3qvchef7zy",
"prod-m5ilt4siql27k",
"prod-ozonys2hmmpeu"
]
}
}
},
{ "Effect": "Allow",
"Action": [
"aws-marketplace:Unsubscribe",
"aws-marketplace:ViewSubscriptions"
],
"Resource": "*"
},
{ "Effect": "Allow",
"Action": "iam:*",
"Resource": "*"
}
]
}
```
**Anthropic Claude 3 モデルを使用したプロンプト手法**
このパターンでは、Claude 3 モデルを使用したテキストからクエリ DSL への変換に関する次のプロンプト手法を説明します。
+ **フューショットプロンプト**: フューショットプロンプトは、Amazon Bedrock での Claude 3 モデルのパフォーマンスを向上させる強力な手法です。このアプローチでは、モデルに同様のタスクの実行を求める前に、小数の例を提供して望ましい入出力動作を示します。Amazon Bedrock で Claude 3 モデルを使用すると、特定のフォーマット、推論パターン、またはドメイン知識を必要とするタスクにおいて、フューショットプロンプトが特に効果的になります。この手法を実装するには、通常、サンプルセクションと実際のクエリの 2 つの主要コンポーネントでプロンプトを構成します。セクションの例にはタスクを説明する 1 つ以上の入出力ペアが含まれており、クエリセクションにはレスポンスが必要な新しい入力が表示されます。この方法は、Claude 3 がコンテキストと期待される出力形式を理解するのに役立ちます。多くの場合、より正確で一貫性のあるレスポンスが得られるようになります。
例:
```
"query": {
"bool": {
"must": [
{"match": {"post_type": "recipe"}},
{"range": {"likes_count": {"gte": 100}}},
{"exists": {"field": "media_urls"}}
]
}
}
Question: Find all recipe posts that have at least 100 likes and include media URLs.
```
+ **システムプロンプト**: Amazon Bedrock の Claude 3 モデルは、フューショットプロンプトに加えてシステムプロンプトの使用もサポートしています。システムプロンプトでは、特定のユーザー入力を提示する前に、モデルに対して全体的なコンテキスト、指示、またはガイドラインを示すことができます。トーンの設定、モデルのロールの定義、会話全体における制約事項を確立する場合に特に役立ちます。Amazon Bedrock で Claude 3 とともにシステムプロンプトを使用するには、API リクエストの `system` パラメータに含めます。これはユーザーメッセージとは別のものであり、インタラクション全体に適用されます。詳細なシステムプロンプトは、コンテキストの設定やモデルのガイドラインの提供に使用されます。
例:
```
You are an expert query dsl generator. Your task is to take an input question and generate a query dsl to answer the question. Use the schemas and data below to generate the query.
Schemas: [schema details]
Data: [sample data]
Guidelines:
- Ensure the generated query adheres to DSL query syntax
- Do not create new mappings or other items that aren't included in the provided schemas.
```
+ **構造化された出力**: JSON や XML タグ内など、特定の形式で出力を提供するようモデルに指示できます。
例:
```
Put the query in json tags
```
+ **プロンプトチェイニング**: ノートブックは、生成された合成データを使用して質問の例を作成するなど、ある LLM 呼び出しの出力を別の LLM 呼び出しの入力として使用します。
+ **コンテキストプロビジョニング**: スキーマやサンプルデータなどの関連コンテキストがプロンプトに表示されます。
例:
```
Schemas: [schema details]
Data: [sample data]
```
+ **タスク固有のプロンプト**: 合成データの生成、質問の例の作成、自然言語クエリからクエリ DSL への変換など、特定のタスクに対して異なるプロンプトが作成されます。
テスト問題生成の例:
```
Your task is to generate 5 example questions users can ask the health app based on provided schemas and data. Only include the questions generated in the response.
```
# Amazon Q Developer をコーディングアシスタントとして使用して生産性を高める
*Amazon Web Services、Ram Kandaswamy*
## 概要
このパターンでは、マルバツゲームを例として使用し、さまざまな開発タスクに Amazon Q Developer を使用する方法を示します。Amazon Q Developer は、マルバツゲームのコードを単一ページアプリケーション (SPA) として生成し、UI を改善して、アプリケーションを AWSにデプロイするためのスクリプトを作成します。
Amazon Q Developer はコーディングアシスタントとして機能して、ソフトウェア開発ワークフローを高速化し、開発者と非開発者の両方の生産性を向上させます。お客様の技術的な専門知識に関係なく、アーキテクチャの作成とビジネス課題に対するソリューションの設計に役立ち、作業環境をブートストラップし、新機能の実装を支援し、検証用のテストケースを生成します。自然言語での指示と AI 機能により、コードの一貫性と高い品質を確保し、プログラミングスキルに関係なくコーディングの課題を軽減します。
Amazon Q Developer の主な利点は、反復的なコーディングタスクから解放されることです。`@workspace` 注釈を使用すると、Amazon Q Developer は統合開発環境 (IDE) 内のすべてのコードファイル、設定、プロジェクト構造を取り込んでインデックス化し、お客様がクリエイティブな問題解決に集中できるようにカスタマイズされた応答を返します。これにより、革新的なソリューションを設計し、ユーザーエクスペリエンスを向上させるためにより多くの時間を費やすことができます。技術的な専門知識をお持ちでない場合は、Amazon Q Developer を使用してワークフローを合理化し、開発チームとより効果的にコラボレーションできます。Amazon Q Developer の**コードの説明**機能では詳細な手順と概要を利用できるため、複雑なコードベースに対処できます。
さらに、Amazon Q Developer は、特定の言語に依存しないアプローチを提供し、初心者レベルや中級者レベルの開発者がスキルセットを拡張するのに役立ちます。特定の言語だけで使用される構文ではなく、主要な概念とビジネスロジックに集中できます。これにより、使用言語を切り替える際の学習曲線が短縮されます。
## 前提条件と制限
**前提条件**
+ Amazon Q Developer プラグインがインストールされた IDE (WebStorm や Visual Studio Code など)。手順については、Amazon Q Developer ドキュメントの「[IDE に Amazon Q Developer 拡張機能またはプラグインをインストールする](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/q-in-IDE-setup.html)」を参照してください。
+ Amazon Q Developer でのアクティブな AWS アカウント セットアップ。手順については、Amazon Q Developer ドキュメントの「[開始方法](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/getting-started-q-dev.html)」を参照してください。
+ インストール済みの **npm**。手順については、[npm ドキュメント](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)を参照してください。このパターンは npm バージョン 10.8 でテストされています。
+ AWS Command Line Interface (AWS CLI) がインストールされています。手順については、[AWS CLI ドキュメント](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)を参照してください。
**制限事項**
+ Amazon Q Developer は、一度に 1 つの開発タスクのみ実行できます。
+ 一部の AWS のサービス は では使用できません AWS リージョン。利用可能なリージョンについては、「[AWS のサービス (リージョン別)](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)」を参照してください。特定のエンドポイントについては、「[サービスエンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)」を参照して、サービスのリンクを選択してください。
## ツール
+ このパターンには、Visual Studio Code や WebStorm などの IDE が必要です。サポートされている IDE のリストについては、[Amazon Q Developer ドキュメント](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/q-in-IDE.html#supported-ides-features)を参照してください。
+ [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) は、コマンドラインシェルのコマンド AWS のサービス を使用して を操作するのに役立つオープンソースツールです。
## ベストプラクティス
AWS 規範ガイダンスの[「Amazon Q Developer でのコーディングのベストプラクティス](https://docs.aws.amazon.com/prescriptive-guidance/latest/best-practices-code-generation/best-practices-coding.html)」を参照してください。加えて:
+ Amazon Q Developer にプロンプトを入力するときは、指示が明確であいまいでないことを確認してください。プロンプトについてより多くのコンテキストを提供するために、プロンプトに `@workspace` などのコードスニペットと注釈を追加してください。
+ システムによる競合や誤った推測を回避するため、関連するライブラリを含めてインポートしてください。
+ 生成されたコードが正確でない、または期待どおりのものでない場合は、**[フィードバックを提供して再生成する]** オプションを使用してください。プロンプトを複数の小さな手順に分割してみてください。
## エピック
### 作業環境をセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 新しいプロジェクトを作成します。 | 作業環境で新しいプロジェクトを作成するには、次のコマンドを実行して、すべての質問のデフォルト設定を受け入れます。npx create-next-app@latest
| アプリ開発者、プログラマー、ソフトウェア開発者 |
| ベースアプリケーションをテストします。 | 次のコマンドを実行し、ベースアプリケーションがブラウザで正常にロードされることを確認します。npm run dev
| アプリ開発者、プログラマー、ソフトウェア開発者 |
| ベースコードをクリーンアップします。 | `src/app` フォルダ内の `page.tsx` ファイルに移動して、デフォルトのコンテンツを削除して空白のページを取得します。削除した後、ファイルは次のようになります。export default function Home() {
return (
);
} | アプリ開発者、プログラマー、ソフトウェア開発者 |
### Amazon Q Developer を使用してマルバツゲームプロジェクトを設計する
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| ステップの概要を取得します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/use-q-developer-as-coding-assistant-to-increase-productivity.html) | アプリ開発者、プログラマー、ソフトウェア開発者 |
| マルバツゲームのコードを生成します。 | チャットパネルで、`/dev` コマンドを使用してタスクの説明を入力し、開発タスクを開始します。例えば、次のようになります。/dev Create a React-based single-page application written in TypeScript for a tic-tac-toe game with the following specifications:
1. Design an aesthetically pleasing interface with the game grid centered vertically and
horizontally on the page.
2. Include a heading and clear instructions on how to play the game.
3. Implement color-coding for X and O marks to distinguish them easily.
Amazon Q Developer は指示に基づいてコードを生成します。 | アプリ開発者、プログラマー、ソフトウェア開発者 |
| 生成されたコードを確認して承認します。 | コードを目視で確認し、**[コードを承認する]** を選択して `page.tsx` ファイルを自動的に置き換えます。問題が発生した場合は、**[フィードバックを提供して再生成する]** を選択し、発生した問題についての説明を入力します。 | アプリ開発者、プログラマー、ソフトウェア開発者 |
| lint エラーを修正します。 | サンプルのマルバツゲームにはグリッドが含まれています。Amazon Q Developer が生成するコードは、デフォルトのタイプ `any` を使用する場合があります。Amazon Q Developer に次のようにプロンプトを入力することで、型安全性を高められます。/dev Ensure proper TypeScript typing for the onSquare Click event handler
to resolve any 'any' type issues.
| アプリ開発者、プログラマー、ソフトウェア開発者 |
| 見た目の魅力を向上させます。 | 元の要件は、複数の小さなフラグメントに分割できます。例えば、開発タスクで次のプロンプトを使用して、ゲーム UI を改善できます。このプロンプトは、カスケードスタイルシート (CSS) のスタイルを改善し、デプロイ用にアプリケーションをエクスポートします。/dev Debug and fix any CSS issues to correctly display the game grid and overall layout.
Simplify the code by removing game history functionality and related components.
Implement static file export to an 'out' directory for easy deployment. The solution
should be fully functional, visually appealing, and free of typing errors or layout issues.
| アプリ開発者、プログラマー、ソフトウェア開発者 |
| テストをもう一度実行します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/use-q-developer-as-coding-assistant-to-increase-productivity.html) | アプリ開発者、プログラマー、ソフトウェア開発者 |
### アプリケーションを にデプロイする AWS クラウド
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| デプロイ用のフォルダとファイルを作成します。 | 作業環境のプロジェクトで、デプロイフォルダを作成し、その中に `pushtos3.sh` と `cloudformation.yml` の 2 つのファイルを作成します。mkdir deployment && cd deployment
touch pushtos3.sh && chmod +x pushtos3.sh
touch cloudformation.yml
| アプリ開発者、プログラマー、ソフトウェア開発者 |
| 自動化コードを生成します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/use-q-developer-as-coding-assistant-to-increase-productivity.html) | AWS 管理者、AWS DevOps、アプリ開発者 |
| スクリプトコンテンツを生成します。 | デプロイスクリプトを作成するには、次のプロンプトを使用します。/dev Modify the pushtos3 shell script so that it can use AWS CLI commands to create a
CloudFormation stack named tictactoe-stack if it does not exist already, and use
cloudformation.yml as the source template. Wait for the stack to complete and sync the
contents from the out folder to the S3 bucket. Perform invalidation of the CloudFront
origin.
| アプリ開発者、プログラマー、ソフトウェア開発者 |
| アプリケーションを AWS クラウドにデプロイします。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/use-q-developer-as-coding-assistant-to-increase-productivity.html) | AWS 管理者、AWS DevOps、クラウドアーキテクト、アプリ開発者 |
## トラブルシューティング
| 問題 | ソリューション |
| --- | --- |
| ビルドは、単一ページのアプリケーションを作成したり、出力フォルダにエクスポートしたりしません。 | `next.config.mjs` ファイルのコンテンツを確認します。コードに次のデフォルト設定が使用されている場合:const nextConfig = {};次のように変更します。const nextConfig = {
output: 'export',
distDir: 'out',
}; |
## 関連リソース
+ [新しい React プロジェクトの作成](https://react.dev/learn/start-a-new-react-project) (React ドキュメント)
+ [Amazon Q Developer の概要](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/what-is.html) (AWS ドキュメント)
+ [Amazon Q Developer のベストプラクティス ](https://docs.aws.amazon.com/prescriptive-guidance/latest/best-practices-code-generation/introduction.html)(AWS 規範ガイダンス)
+ [Installing, Configuring, and Using Amazon Q Developer with JetBrains IDEs](https://www.youtube.com/watch?v=-iQfIhTA4J0&pp=ygUSYW1hem9uIHEgZGV2ZWxvcGVy) (YouTube 動画)
+ [コマンドライン用の Amazon Q のインストール](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-getting-started-installing.html) (AWS ドキュメント)
# SageMaker Processing を使用して、テラバイト規模の ML データセットの分散型特徴量エンジニアリングを実現
*Amazon Web Services、Chris Boomhower*
## 概要
テラバイト規模またはそれ以上のデータセットの多くは階層的なフォルダ構造で構成されており、データセット内のファイルは相互に依存している場合があります。このため、機械学習 (ML) エンジニアとデータサイエンティストは、モデルトレーニングや推論のためにデータを準備するために、慎重に設計上の決定を下さなければなりません。このパターンは、手動のマクロシャーディングとマイクロシャーディングの手法を Amazon SageMaker Processing と仮想 CPU (vCPU) 並列化と組み合わせて使用して、複雑なビッグデータ ML データセットの特徴量エンジニアリングプロセスを効率的にスケーリングする方法を示しています。
このパターンでは、データディレクトリを複数のマシンに分割して処理することを「*マクロシャーディング*」と定義し、「*マイクロシャーディング*」は各マシンのデータを複数の処理スレッドに分割することと定義されています。このパターンでは、Amazon SageMaker と「[PhysioNet MIMIC-III](https://physionet.org/content/mimic3wdb/1.0/)」データセットのサンプル時系列波形レコードを使用して、これらの手法を実証しています。このパターンの手法を実装することで、リソース利用率とスループット効率を最大化しながら、特徴量エンジニアリングの処理時間とコストを最小限に抑えることができます。これらの最適化では、データタイプに関係なく、類似の大規模データセットで、Amazon Elastic Compute Cloud (Amazon EC2) インスタンスと vCPUs で、分散された SageMaker 処理を使用します。
## 前提条件と制限
**前提条件**
+ 独自のデータセットにこのパターンを実装する場合は、SageMaker ノートブックインスタンスまたは SageMaker Studio にアクセスできます。Amazon SageMaker を初めて使用する場合は、AWS ドキュメントの「[Amazon SageMaker の入門](https://docs.aws.amazon.com/sagemaker/latest/dg/gs.html)」を参照してください。
+ SageMaker Studio、「[PhysioNet MIMIC-III](https://physionet.org/content/mimic3wdb/1.0/)」のサンプルデータを使用してこのパターンを実装したい場合。
+ このパターンは SageMaker 処理を使用しますが、SageMaker 処理ジョブを実行した経験は必要ありません。
**制限事項**
+ このパターンは、相互に依存するファイルを含む ML データセットに非常に適しています。このような相互依存関係は、手動によるマクロシャーディングと、複数の単一インスタンスの SageMaker Processing ジョブをparallel 実行することから最もメリットがあります。そのような相互依存関係が存在しないデータセットの場合、SageMaker Processing の`ShardedByS3Key`機能は、同じ処理ジョブによって管理される複数のインスタンスにシャーディングされたデータを送信するため、マクロシャーディングのより良い代替となる可能性があります。ただし、このパターンのマイクロシャーディング戦略をどちらのシナリオでも実装して、インスタンス vCPUs を最大限に活用できます。
**製品バージョン**
+ Amazon SageMaker Python SDK バージョン 2
## アーキテクチャ
**ターゲットテクノロジースタック**
+ Amazon Simple Storage Service (Amazon S3)
+ Amazon SageMaker
**ターゲットアーキテクチャ**
*マクロシャーディングと分散型 EC2 インスタンス*
このアーキテクチャで表される 10 個のparallel プロセスは、MIMIC-III データセットの構造を反映しています。(図を簡略化するため、プロセスは楕円で示されています)。手動マクロシャーディングを使用する場合も、同様のアーキテクチャがどのデータセットにも適用されます。MIMIC-III の場合、各患者グループフォルダを最小の労力で個別に処理することで、データセットの未加工の構造を活用できます。以下の図では、レコードグループブロックが左側に表示されています (1)。データが分散されていることを考えると、患者グループごとにシャードするのは理にかなっています。
![\[マイクロシャーディングと分散 EC2 インスタンスのアーキテクチャ\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/e7a90b31-de8f-41fd-bb3f-c7c6100fc306/images/c19a8f87-ac59-458e-89cb-50be17ca4a0c.png)
ただし、患者グループごとに手動でシャーディングを行うと、図 (2) の中央のセクションでわかるように、複数の EC2 インスタンスによる単一の処理ジョブではなく、患者グループフォルダごとに個別の処理ジョブが必要になります。MIMIC-III のデータには、バイナリ波形ファイルと対応するテキストベースのヘッダーファイルの両方が含まれており、バイナリデータ抽出には「[wfdb ライブラリ](https://wfdb.readthedocs.io/en/latest/)」に依存する必要があるため、特定の患者のすべてのレコードを同じインスタンスで利用できるようにする必要があります。各バイナリ波形ファイルの関連ヘッダーファイルも確実に存在させる唯一の方法は、各シャードを独自の処理ジョブ内で実行する手動シャーディングを実装し、処理ジョブの入力を定義するときに`s3_data_distribution_type='FullyReplicated'`を指定することです。あるいは、すべてのデータが単一のディレクトリにあり、ファイル間に依存関係がない場合、より適切なオプションは、複数の EC2 インスタンスと`s3_data_distribution_type='ShardedByS3Key'`を指定して単一の処理ジョブを起動することかもしれません。Amazon S3 データ分散タイプとして`ShardedByS3Key `を指定すると、SageMaker はインスタンス間のデータシャーディングを自動的に管理するようになります。
複数のインスタンスを同時に実行すると時間を節約できるため、データを前処理するにはフォルダごとに処理ジョブを起動するのがコスト効率の高い方法です。コストと時間をさらに節約するために、各処理ジョブ内でマイクロシャーディングを使用することもできます。
*マイクロシャーディングとparallel vCPUs*
各処理ジョブ内で、グループ化されたデータはさらに分割され、SageMaker のフルマネージド EC2 インスタンスで使用可能なすべての vCPUs を最大限に活用します。図の中央のセクション (2) のブロックは、各主要処理ジョブ内で何が起こるかを表しています。患者記録フォルダの内容は、インスタンスで使用可能なvCPUs の数に基づいてフラット化され、均等に分割されます。フォルダの内容が分割されると、同じサイズのファイルセットがすべての vCPUs に分散されて処理されます。処理が完了すると、各 vCPU の結果は、処理ジョブごとに 1 つのデータファイルにまとめられます。
添付のコードでは、これらの概念が`src/feature-engineering-pass1/preprocessing.py`ファイルの次のセクションに示されています。
```
def chunks(lst, n):
"""
Yield successive n-sized chunks from lst.
:param lst: list of elements to be divided
:param n: number of elements per chunk
:type lst: list
:type n: int
:return: generator comprising evenly sized chunks
:rtype: class 'generator'
"""
for i in range(0, len(lst), n):
yield lst[i:i + n]
# Generate list of data files on machine
data_dir = input_dir
d_subs = next(os.walk(os.path.join(data_dir, '.')))[1]
file_list = []
for ds in d_subs:
file_list.extend(os.listdir(os.path.join(data_dir, ds, '.')))
dat_list = [os.path.join(re.split('_|\.', f)[0].replace('n', ''), f[:-4]) for f in file_list if f[-4:] == '.dat']
# Split list of files into sub-lists
cpu_count = multiprocessing.cpu_count()
splits = int(len(dat_list) / cpu_count)
if splits == 0: splits = 1
dat_chunks = list(chunks(dat_list, splits))
# Parallelize processing of sub-lists across CPUs
ws_df_list = Parallel(n_jobs=-1, verbose=0)(delayed(run_process)(dc) for dc in dat_chunks)
# Compile and pickle patient group dataframe
ws_df_group = pd.concat(ws_df_list)
ws_df_group = ws_df_group.reset_index().rename(columns={'index': 'signal'})
ws_df_group.to_json(os.path.join(output_dir, group_data_out))
```
最初に関数`chunks`を定義し、与えられたリストを`n `の長さの均一な大きさのブロックに分割し、その結果をジェネレータとして返すことにより、与えられたリストを使用します。次に、存在するすべてのバイナリ波形ファイルのリストをコンパイルして、データを患者フォルダ全体でフラット化します。これが完了すると、EC2 インスタンスで使用可能な vCPUs の数が取得されます。バイナリ波形ファイルのリストは、`chunks`を呼び出すことによってこれらのvCPUに均等に分割され、その後、「[joblibのParallelクラス](https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html)」を使用することによって、各波形サブリストがそれぞれのvCPUで処理されます。処理ジョブによって結果は自動的に 1 つのデータフレームリストにまとめられ、SageMaker はさらに処理してからジョブ完了時に Amazon S3 に書き込まれます。この例では、処理ジョブによって Amazon S3 に書き込まれるファイルが 10 個あります (ジョブごとに 1 つ)。
最初の処理ジョブがすべて完了すると、図 (3) の右側のブロックに示されているセカンダリ処理ジョブが、各プライマリ処理ジョブによって生成された出力ファイルを結合し、結合された出力を Amazon S3 (4) に書き込みます。
## ツール
**ツール**
+ [Python](https://www.python.org/) — このパターンに使用されるサンプルコードは Python (バージョン 3) です。
+ [SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio.html) – Amazon SageMaker Studio は、ウェブベースの機械学習用の統合開発環境 (IDE) です。この IDE を使うと、機械学習モデルを構築、トレーニング、デバッグ、デプロイ、モニタリングできます。SageMaker Processing ジョブは、SageMaker Studio 内の Jupyter Notebookを使用して実行します。
+ [SageMaker Processing](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html) — Amazon SageMaker Processingを使用すると、データ処理ワークロードを簡単に実行できます。このパターンでは、特徴量エンジニアリングコードは SageMaker Processing ジョブを使用して大規模に実装されます。
**Code**
添付の.zip ファイルには、このパターンの完全なコードが記載されています。次のセクションでは、このパターンのアーキテクチャを構築する手順について説明します。各ステップは、添付ファイルのサンプルコードで説明されています。
## エピック
### SageMaker Studio 環境をセットアップする
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| Amazon SageMaker Studio へアクセスします。 | 「[Amazon SageMaker ドキュメント](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html)」に記載されている指示に従って、AWS アカウントの SageMaker Studio にオンボーディングします。 | データサイエンティスト、ML エンジニア |
| wget ユーティリティをインストールします。 | 新しい SageMaker Studio 構成をオンボーディングした場合や、SageMaker Studio でこれらのユーティリティをこれまで使用したことがない場合は、「*wget*」をインストールしてください。 インストールするには、SageMaker Studio コンソールでターミナルウィンドウを開き、以下のコマンドを実行します。sudo yum install wget
| データサイエンティスト、ML エンジニア |
| サンプルコードをダウンロードして解凍します。 | 「*添付ファイル*」セクションから`attachments.zip`ファイルをダウンロードします。ターミナルウィンドウで、ファイルをダウンロードしたフォルダに移動し、その内容を抽出します。unzip attachment.zip
`Scaled-Processing.zip`ファイルを抽出したフォルダに移動し、ファイルの内容を抽出します。unzip Scaled-Processing.zip
| データサイエンティスト、ML エンジニア |
| physionet.org からサンプルデータセットをダウンロードし、Amazon S3 にアップロードします。 | `Scaled-Processing`ファイルが含まれているフォルダ内で `get_data.ipynb` Jupyter Notebookを実行します。このノートブックは「[physionet.org](https://physionet.org)」からサンプル MIMIC-III データセットをダウンロードし、Amazon S3 の SageMaker Studio セッションバケットにアップロードします。 | データサイエンティスト、ML エンジニア |
### 1 つ目の前処理スクリプトを設定します。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| すべてのサブディレクトリにわたってファイル階層をフラット化する。 | MIMIC-III のような大規模なデータセットでは、論理的な親グループ内であってもファイルが複数のサブディレクトリに分散されることがよくあります。次のコードが示すように、スクリプトはすべてのサブディレクトリにあるすべてのグループファイルをフラット化するように設定する必要があります。# Generate list of .dat files on machine
data_dir = input_dir
d_subs = next(os.walk(os.path.join(data_dir, '.')))[1]
file_list = []
for ds in d_subs:
file_list.extend(os.listdir(os.path.join(data_dir, ds, '.')))
dat_list = [os.path.join(re.split('_|\.', f)[0].replace('n', ''), f[:-4]) for f in file_list if f[-4:] == '.dat']
このエピックのサンプルコードスニペットは、添付ファイルにある `src/feature-engineering-pass1/preprocessing.py` ファイルからのものです。 | データサイエンティスト、ML エンジニア |
| vCPU 数に基づいてファイルをサブグループに分割します。 | ファイルは、スクリプトを実行するインスタンスに存在するvCPUs の数に応じて、同じサイズのサブグループまたはチャンクに分割する必要があります。このステップでは、次のようなコードを実装できます。# Split list of files into sub-lists
cpu_count = multiprocessing.cpu_count()
splits = int(len(dat_list) / cpu_count)
if splits == 0: splits = 1
dat_chunks = list(chunks(dat_list, splits))
| データサイエンティスト、ML エンジニア |
| vCPUs 間のサブグループの処理を並列化します。 | スクリプトロジックは、すべてのサブグループを並行して処理するように設定する必要があります。そのためには、Joblib ライブラリの`Parallel `クラスと`delayed `メソッドを次のように使用します。 # Parallelize processing of sub-lists across CPUs
ws_df_list = Parallel(n_jobs=-1, verbose=0)(delayed(run_process)(dc) for dc in dat_chunks)
| データサイエンティスト、ML エンジニア |
| Amazon S3 に単一ファイルグループの出力を保存します。 | 並列 vCPU 処理が完了したら、各 vCPU の結果を組み合わせて、ファイルグループの S3 バケットパスにアップロードする必要があります。このステップでは、次のようなコードを実行できます。# Compile and pickle patient group dataframe
ws_df_group = pd.concat(ws_df_list)
ws_df_group = ws_df_group.reset_index().rename(columns={'index': 'signal'})
ws_df_group.to_json(os.path.join(output_dir, group_data_out))
| データサイエンティスト、ML エンジニア |
### 2 つ目の前処理スクリプトを設定します。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 最初のスクリプトを実行したすべての処理ジョブで生成されたデータファイルを結合します。 | 前述のスクリプトは、データセットのファイルグループを処理する SageMaker Processing ジョブごとに 1 つのファイルを出力します。 次に、これらの出力ファイルを 1 つのオブジェクトに結合し、1 つの出力データセットを Amazon S3 に書き込む必要があります。これは、添付ファイルにある`src/feature-engineering-pass1p5/preprocessing.py`ファイルに次のように示されています。def write_parquet(wavs_df, path):
"""
Write waveform summary dataframe to S3 in parquet format.
:param wavs_df: waveform summary dataframe
:param path: S3 directory prefix
:type wavs_df: pandas dataframe
:type path: str
:return: None
"""
extra_args = {"ServerSideEncryption": "aws:kms"}
wr.s3.to_parquet(
df=wavs_df,
path=path,
compression='snappy',
s3_additional_kwargs=extra_args)
def combine_data():
"""
Get combined data and write to parquet.
:return: waveform summary dataframe
:rtype: pandas dataframe
"""
wavs_df = get_data()
wavs_df = normalize_signal_names(wavs_df)
write_parquet(wavs_df, "s3://{}/{}/{}".format(bucket_xform, dataset_prefix, pass1p5out_data))
return wavs_df
wavs_df = combine_data()
| データサイエンティスト、ML エンジニア |
### 処理ジョブの実行
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| 最初の処理ジョブを実行します。 | マクロシャーディングを実行するには、ファイルグループごとに個別の処理ジョブを実行します。マイクロシャーディングは各処理ジョブ内で実行されます。これは、各ジョブで最初のスクリプトが実行されるためです。次のコードは、次のスニペット (`notebooks/FeatExtract_Pass1.ipynb`に含まれている) 内の各ファイルグループディレクトリの処理ジョブを起動する方法を示しています。pat_groups = list(range(30,40))
ts = str(int(time.time()))
for group in pat_groups:
sklearn_processor = SKLearnProcessor(framework_version='0.20.0',
role=role,
instance_type='ml.m5.4xlarge',
instance_count=1,
volume_size_in_gb=5)
sklearn_processor.run(
code='../src/feature-engineering-pass1/preprocessing.py',
job_name='-'.join(['scaled-processing-p1', str(group), ts]),
arguments=[
"input_path", "/opt/ml/processing/input",
"output_path", "/opt/ml/processing/output",
"group_data_out", "ws_df_group.json"
],
inputs=
[
ProcessingInput(
source=f's3://{sess.default_bucket()}/data_inputs/{group}',
destination='/opt/ml/processing/input',
s3_data_distribution_type='FullyReplicated'
)
],
outputs=
[
ProcessingOutput(
source='/opt/ml/processing/output',
destination=f's3://{sess.default_bucket()}/data_outputs/{group}'
)
],
wait=False
)
| データサイエンティスト、ML エンジニア |
| 2 つ目の処理ジョブを実行します。 | 最初の処理ジョブセットで生成された出力を結合し、前処理のために追加の計算を実行するには、1 つの SageMaker 処理ジョブを使用して 2 番目のスクリプトを実行します。次のコードはこれを示しています (`notebooks/FeatExtract_Pass1p5.ipynb`に含まれている)。ts = str(int(time.time()))
bucket = sess.default_bucket()
sklearn_processor = SKLearnProcessor(framework_version='0.20.0',
role=role,
instance_type='ml.t3.2xlarge',
instance_count=1,
volume_size_in_gb=5)
sklearn_processor.run(
code='../src/feature-engineering-pass1p5/preprocessing.py',
job_name='-'.join(['scaled-processing', 'p1p5', ts]),
arguments=['bucket', bucket,
'pass1out_prefix', 'data_outputs',
'pass1out_data', 'ws_df_group.json',
'pass1p5out_data', 'waveform_summary.parquet',
'statsdata_name', 'signal_stats.csv'],
wait=True
)
| データサイエンティスト、ML エンジニア |
## 関連リソース
+ [クイックスタートを使用して Amazon SageMaker Studio にオンボーディングする](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html) (SageMaker ドキュメント)
+ [プロセスデータ](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html) (SageMaker ドキュメンテーション)
+ [scikit-learn を使ってデータを処理する](https://docs.aws.amazon.com/sagemaker/latest/dg/use-scikit-learn-processing-container.html) (SageMaker ドキュメンテーション)
+ [JobLib. パラレルドキュメンテーション](https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html)
+ ムーディ、B.、ムーディ、G.、ビジャロエル、M.、クリフォード、G.D.、シルバ、I. (2020)。[MIMIC-III](https://doi.org/10.13026/c2607m) 波形データベース (バージョン 1.0)。*フィジオネット*。
+ ジョンソン、A. E. W.、ポラード、T.J.、シェン、L.、リーマン、L.H.、フェン、M.、ガセミ、M.、ムーディ、B.、ゾロビッツ、P.、セリ、L.A.、マーク、R.G.（2016）。「[MIMIC-III](https://dx.doi.org/10.1038/sdata.2016.35)」は、無料でアクセスできる救命救急データベースです。科学データ、3、160035。
+ [MIMIC-III 波形データベースライセンス](https://physionet.org/content/mimic3wdb/1.0/LICENSE.txt)
## アタッチメント
このドキュメントに関連する追加コンテンツにアクセスするには、次のファイルを解凍してください。「[attachment.zip](samples/p-attach/e7a90b31-de8f-41fd-bb3f-c7c6100fc306/attachments/attachment.zip)」
# フラスコと AWS Elastic Beanstalk を使用して AI/ML モデルの結果を視覚化
*Amazon Web Services、Chris Caudill、Durga Sury*
## 概要
人工知能と機械学習 (AI/ML) サービスからの出力を視覚化するには、開発者やエンジニアがカスタマイズする必要な複雑な API 呼び出しが必要になることがよくあります。アナリストが新しいデータセットを迅速に探索する場合、これは欠点になる可能性があります。
ウェブベースのユーザーインターフェイス (UI) を使用することで、サービスのアクセシビリティを高め、よりインタラクティブなデータ分析を実現できます。これにより、ユーザーが独自のデータをアップロードし、ダッシュボードでモデルの結果を視覚化できます。
このパターンでは、[Flask](https://flask.palletsprojects.com/en/2.0.x/) と [Plotly](https://plotly.com/) を使用して、 Amazon Comprehend をカスタムウェブアプリケーションと統合し、ユーザーが提供したデータからセンチメントとエンティティを視覚化します。このパターンでは、AWS Elastic Beanstalk を使用してアプリケーションをデプロイするステップも記載されています。[Amazon Web Services (AWS) の AI サービス](https://aws.amazon.com/machine-learning/ai-services/)を使用するか、エンドポイント ([Amazon SageMaker エンドポイントなど](https://docs.aws.amazon.com/sagemaker/latest/dg/deploy-model.html)) でホストされるカスタムトレーニング済みモデルを使用してアプリケーションを適応させることができます。
## 前提条件と制限事項
**前提条件**
+ アクティブな AWS アカウント。
+ ローカルマシンにインストールされ、設定されたAWS コマンドラインインターフェイス (AWS CLI) 詳細については、JupyterHub ドキュメントの[Configuration Basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) を参照してください。AWS Cloud9 統合開発環境 (IDE) を使用することもできます。詳細については、AWS Cloud9 ドキュメントの[AWS Cloud9 の Python チュートリアル](https://docs.aws.amazon.com/cloud9/latest/user-guide/sample-python.html)」と[AWS Cloud9 IDE で実行中のアプリケーションのプレビュー](https://docs.aws.amazon.com/cloud9/latest/user-guide/app-preview.html) を参照してください。
**注意**: AWS Cloud9 は新規顧客には利用できなくなりました。の既存のお客様は、通常どおりサービスを AWS Cloud9 引き続き使用できます。[詳細はこちら](https://aws.amazon.com/blogs/devops/how-to-migrate-from-aws-cloud9-to-aws-ide-toolkits-or-aws-cloudshell/)
+ Flask のウェブアプリケーションフレームワークについての理解。 へのサインアップの詳細については、 ドキュメント内の[クイックスタート](https://flask.palletsprojects.com/en/1.1.x/quickstart) を参照してください。
+ インストールされ、設定されたPython バージョン 3.6 以降。Python をインストールするには、AWS Elastic Beanstalk ドキュメントの[Python 開発環境のセットアップ](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/python-development-environment.html) の指示に従います。
+ Elastic Beanstalk コマンドラインインターフェイス (EB CLI) これに関する詳細については、AWS Elastic Beanstalk ドキュメントから[EB CLI をインストール](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-install.html) と[EB CLI を設定](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-configuration.html) を参照してください。
**制限事項**
+ このパターンの Flask アプリケーションは、単一のテキスト列を使用し、200 行に制限されている.csv ファイルで動作するように設計されています。アプリケーションコードは他のファイルタイプやデータ量を処理するように調整できます。
+ アプリケーションはデータの保持を考慮せず、アップロードされたユーザーファイルは手動で削除されるまで集計を続けます。アプリケーションを Amazon Simple Storage Service (Amazon S3) と統合して永続的なオブジェクトストレージを作成したり、Amazon DynamoDB などのデータベースを使用してサーバーレスのキーバリューストレージを作成したりできます。
+ このアプリケーションは英語のドキュメントのみを考慮します。ただし、Amazon Comprehend を使用してドキュメントの主要言語を検出することはできます。各アクションに適用される言語の詳細については、Amazon Comprehend ドキュメントの[API リファレンス](https://docs.aws.amazon.com/comprehend/latest/dg/API_Reference.html) を参照してください。
+ 一般的なエラーとその解決策を含むトラブルシューティングリストは、*追加情報*セクションにあります。
## アーキテクチャ
**アプリケーションのアーキテクチャ**
Flaskは、Pythonでウェブアプリケーションを開発するための軽量フレームワークです。Python の強力なデータ処理と豊富な ウェブ UI を組み合わせるように設計されています。パターンの Flask アプリケーションでは、ユーザーがデータをアップロードし、そのデータを Amazon Comprehend に送信して推論し、結果を視覚化するウェブアプリケーションの構築方法を示しています。 マッピングドキュメントの構造は次のとおりです。
+ `static` — ウェブ UI が適用されるすべての静的ファイル (JavaScript、CSS、画像など) が含まれています。
+ `templates` — アプリケーションのすべての HTML ページが含まれます。
+ `userData` — アップロードされたユーザーデータを格納します。
+ `application.py` — Flask アプリケーションファイル
+ `comprehend_helper.py` — Amazon Comprehend に API 呼び出しを行う関数
+ アプリケーション設定ファイル。
+ `requirements.txt` — アプリケーションに必要な Python の依存関係
`application.py` このスクリプトには、4 つの Flask ルートで構成されるウェブアプリケーションのコア機能が含まれています。以下の図に、これらの Flask ルートを示します。
![\[ウェブアプリケーションのコア機能を構成する 4 つの Flask ルート。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/03d80cf1-ec97-43f7-adb5-2746a9ec70e6/images/9ca6bad1-26e2-4262-98d0-d54c172336bf.png)
+ `/` はアプリケーションのルートで、ユーザーを `upload.html` ページ ( `templates` ディレクトリに格納) にガイドします。
+ `/saveFile` は、ユーザーがファイルをアップロードした後に呼び出されるルートです。このルートは、ユーザーがアップロードしたファイルを含む HTML フォームを介して `POST` リクエストを受け取ります。`userData` ファイルがディレクトリに保存され、ルートはユーザーを `/dashboard` ルートにガイドします。
+ `/dashboard` がユーザーを `dashboard.html` ページにがガイドします。このページの HTML、`/data` ルートからデータを読み取る `static/js/core.js` に JavaScript コードを実行して、ページの視覚化を構築します。
+ `/data` は、ダッシュボードに視覚化されるデータを表示する JSON API です。このルートでは、ユーザーが提供したデータを読み取り、`comprehend_helper.py` の関数を使用してユーザーデータを Amazon Comprehend にガイドして、センチメント分析と名前付けのエンティティ認識 (NER) を行います。Amazon Comprehend のレスポンスがフォーマットされ、JSON オブジェクトとして返されます。
デプロイアーキテクチャ
![\[フラスコと Elastic Beanstalk を使用して AI/ML モデルの結果を視覚化するためのアーキテクチャ図。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/03d80cf1-ec97-43f7-adb5-2746a9ec70e6/images/d691bfd2-e2ec-4830-8bff-ffa1e3a95c4a.png)
[設計上の考慮事項](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/concepts.concepts.design.html)
AWS クラウドで Elastic Beanstalk を使用してデプロイされるアプリケーションの設計の考慮事項の詳細については、AWS Elastic Beanstalk ドキュメントを参照してください。
**テクノロジースタック**
+ Amazon Comprehend
+ (Elastic Beanstalk)
+ Flask
**自動化とスケール**
Elastic Beanstalk のデプロイは、ロードバランサーとauto スケーリンググループを使用して自動的にセットアップされます。その他の設定オプションについては、AWS Elastic Beanstalk ドキュメントの[Elastic Beanstalk 環境設定](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/customize-containers.html) を参照してください。
## ツール
+ [AWS コマンドラインインターフェイス (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) は、AWS のすべての部分を操作するための一貫したインターフェイスを提供する統合ツールです。
+ [Amazon Comprehend](https://docs.aws.amazon.com/comprehend/latest/dg/comprehend-general.html) では、ドキュメントの内容に関するインサイトの抽出用に自然言語処理 (NLP) を使用しています。
+ [AWS Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/Welcome.html) を使用すると、アプリケーションを実行しているインフラストラクチャについて知識を得なくても、AWS クラウドでアプリケーションのデプロイと管理を簡単に行うことができます。
+ [Elastic Beanstalk CLI (EB CLI)](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3.html) は AWS Elastic Beanstalk のコマンドラインインターフェイスで、ローカルリポジトリの環境の作成、更新、モニタリングを簡素化するインタラクティブコマンドを提供します。
+ [Flask](https://flask.palletsprojects.com/en/2.0.x/) フレームワークは Python を使用してデータ処理と API コールを実行し、Plotly を使用してインタラクティブなウェブビジュアライゼーションを提供します。
**コード**
このパターンのコードは、GitHub 内の「[Flask と AWS Elastic Beanstalk を使用して AI/ML モデルの結果を視覚化](https://github.com/aws-samples/aws-comprehend-elasticbeanstalk-for-flask)」リポジトリで利用できます。
## エピック
### Flask アプリケーションをセットアップします。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| GitHub リポジトリのクローンを作成します。 | 次のコマンドを実行して、GitHub の [Flask と AWS Elastic Beanstalk を使用して、AI/ML モデル結果を可視化](https://github.com/aws-samples/aws-comprehend-elasticbeanstalk-for-flask) を取得します。`git clone git@github.com:aws-samples/aws-comprehend-elasticbeanstalk-for-flask.git`必ず GitHub に SSH キーを設定します。 | 開発者 |
| Python モジュールをインストールします。 | リポジトリをクローンすると、新しいローカル `aws-comprehend-elasticbeanstalk-for-flask` ディレクトリが作成されます。そのディレクトリでは、`requirements.txt` ファイルには、アプリケーションを実行する Python モジュールとバージョンが含まれています。 と をインストールするには、次のコマンドを使用します。`cd aws-comprehend-elasticbeanstalk-for-flask``pip install -r requirements.txt` | Python 開発 |
| アプリケーションのローカルテスト | 次のコマンドを実行して、Weka サーバーを作成します。`python application.py`これにより、実行中のサーバーに関する情報が返されます。ブラウザを開いて http://localhost:5000 にアクセスすると、アプリケーションにアクセスできます。アプリケーションを AWS Cloud9 IDE で実行している場合、`application.py` ファイル内の `application.run()` コマンドを次の行に置き換える必要があります。`application.run(host=os.getenv('IP', '0.0.0.0'),port=int(os.getenv('PORT', 8080)))`デプロイする前にこの変更を元に戻す必要があります。 | Python 開発 |
### アプリケーションを Elastic Beanstalk にデプロイします。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| AWS Elastic Beanstalk アプリケーション | Elastic Beanstalk アプリケーションとしてプロジェクトを起動するには、アプリケーションのルートディレクトリから以下のコマンドを実行します。`eb init -p python-3.6 comprehend_flask --region us-east-1`[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/visualize-ai-ml-model-results-using-flask-and-aws-elastic-beanstalk.html)`eb init -i` コマンドを実行する場合、より多くのデプロイ設定オプションが表示されます。 | アーキテクト、開発者 |
| Elastic Beanstalk 環境をデプロイします。 | プロジェクトルートディレクトリから以下のコマンドを実行すると、アプリケーションが構築されます。`eb create comprehend-flask-env``comprehend-flask-env` は Elastic Beanstalk 環境の名前で、必要に応じて変更できます。含むことができるのは、英文字、数字、およびダッシュのみです。 | アーキテクト、開発者 |
| Amazon Comprehend を使用するようにデプロイを承認します。 | アプリケーションが正常にデプロイされるかもしれませんが、デプロイに Amazon Comprehend へのアクセス権も提供する必要があります。`ComprehendFullAccess` は、デプロイされたアプリケーションに Amazon Comprehend への API 呼び出しを行うためのアクセス権限を提供する AWS 管理ポリシーです。次のコマンドを実行して、`aws-elasticbeanstalk-ec2-role` に `ComprehendFullAccess` ポリシーを添付します(このロールがデプロイの Amazon Elastic Compute Cloud (Amazon EC2 インスタンスに自動的に作成)。`aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/ComprehendFullAccess --role-name aws-elasticbeanstalk-ec2-role``aws-elasticbeanstalk-ec2-role` は、アプリケーションのデプロイ時に作成されます。AWS Identity and Access Management (IAM) ポリシーをアタッチする前に、デプロイプロセスを完了する必要があります。 | 開発者、セキュリティアーキテクト |
| デプロイしたアプリケーションにアクセスします。 | アプリケーションが正常にデプロイされた後、 `eb open` コマンドを実行して、そのアプリケーションにアクセスできます。`eb status` コマンドを実行して、デプロイに関する詳細を取得することもできます。デプロイ URL は `CNAME` に記載されています。 | アーキテクト、開発者 |
### (オプション) ML モデルに合わせてアプリケーションをカスタマイズ
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| Elastic Beanstalk が新しいモデルにアクセスすることを許可します。 | Elastic Beanstalk に新しいモデルエンドポイントに必要なアクセス権限があることを保証します。たとえば、Amazon SageMaker エンドポイントを使用する場合、デプロイにはエンドポイントを呼び出すアクセス権限が必要です。 これに関する詳細については、Amazon SageMaker ドキュメントの[InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) を参照してください。 | 開発者、セキュリティアーキテクト |
| ユーザーデータを新しいモデルに送信します。 | このアプリケーションの基になる ML モデルを変更するには、以下のファイルを変更する必要があります。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/visualize-ai-ml-model-results-using-flask-and-aws-elastic-beanstalk.html) | データサイエンティスト |
| ダッシュボードのビジュアライゼーションを更新します。 | 通常、新しい ML モデルを組み込むと、新しい結果を反映するようにビジュアライゼーションを更新する必要があります。これらのフラグは、次のファイルで定義されています。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/visualize-ai-ml-model-results-using-flask-and-aws-elastic-beanstalk.html) | ウェブ開発者 |
### 更新したアプリケーションをデプロイします。
| タスク | 説明 | 必要なスキル |
| --- | --- | --- |
| アプリケーションの要件ファイルを更新します。 | Elastic Beanstalk に変更を送信する前に、アプリケーションのルートディレクトリで以下のコマンドを実行して、新しい Pythonモジュールを反映するように `requirements.txt` ファイルを更新します。`pip freeze > requirements.txt` | Python 開発 |
| Elastic Beanstalk 環境をセットアップします。 | アプリケーションの変更が Elastic Beanstalk デプロイに確実に反映されるようにするには、アプリケーションのルートディレクトリに移動し、以下のコマンドを実行します。`eb deploy`これにより、アプリケーションのコードの最新バージョンが既存の Elastic Beanstalk デプロイに送信されます。 | システム管理者、アーキテクト |
## 関連リソース
+ [Amazon API Gatewayと AWS Lambda を使用して Amazon SageMaker モデルエンドポイントを呼び出す](https://aws.amazon.com/blogs/machine-learning/call-an-amazon-sagemaker-model-endpoint-using-amazon-api-gateway-and-aws-lambda/)
+ [Elastic Beanstalk への Flask アプリケーションのデプロイ](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create-deploy-python-flask.html)
+ [EB CLI コマンドリファレンス](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb3-cmd-commands.html)
+ [Python 開発環境をセットアップします](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/python-development-environment.html)
## 追加情報
**トラブルシューティングのリスト**
一般的な原因とその解決策を以下に示します。
***エラー 1* **
```
Unable to assume role "arn:aws:iam::xxxxxxxxxx:role/aws-elasticbeanstalk-ec2-role". Verify that the role exists and is configured correctly.
```
**解決策**： `eb create` を実行する時、このエラーが発生した場合、Elastic Beanstalk コンソールでサンプルアプリケーションを作成して、デフォルトのインスタンスプロファイルを作成します。詳細については、AWS Elastic Beanstalk ドキュメントの[Elastic Beanstalk 環境を作成](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.environments.html) を参照してください。
***エラー 2***
```
Your WSGIPath refers to a file that does not exist.
```
**解決策：**このエラーがデプロイログで発生されます。Elastic Beanstalk が `application.py` という名前のFlask コードを想定しているためです。別の名前を選択した場合は、次のコードサンプルに示すように WSGIPath `eb config` を実行して編集します。
```
aws:elasticbeanstalk:container:python:
NumProcesses: '1'
NumThreads: '15'
StaticFiles: /static/=static/
WSGIPath: application.py
```
自分のファイル名で `application.py` を置き換えます。
Gunicorn と Procfile を利用することもできます。このアプローチの詳細については、AWS Elastic Beanstalk ドキュメントの[プロファイルファイルによる WSGI サーバーの設定](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/python-configuration-procfile.html) を参照してください。
***エラー 3***
```
Target WSGI script '/opt/python/current/app/application.py' does not contain WSGI application 'application'.
```
**解決策：**Elastic Beanstalk では、Flask アプリケーションを表す変数に `application` という名前が付けられていることを想定しています。`application.py` ファイルが変数名として `application` を使用していることを確認します。
```
application = Flask(__name__)
```
***エラー 4***
```
The EB CLI cannot find your SSH key file for keyname
```
**解決策：**EB CLI を使用して、使用するキーペアを指定するか、デプロイの EC2 インスタンス用のキーペアを作成します。エラーを解決するには、`eb init -i` を実行します。一つのオプションでは、下記のように提示されます。
```
Do you want to set up SSH for your instances?
```
`Y` と回答して、キーペアを作成するか、既存のキーペアを指定します。
***エラー 5***
*コードを更新して再デプロイしましたが、デプロイに変更が反映されていません。*
**解決策：**デプロイに Git リポジトリを使用している場合、再デプロイする前に変更を追加してコミットする必要があります。
***エラー 6***
*AWS Cloud9 IDE から Flask アプリケーションをプレビューしていて、エラーが発生しました。*
**解決策：**詳細については、AWS Cloud9 ドキュメントの「[AWS Cloud9 IDE での実行中のアプリケーションのプレビュー](https://docs.aws.amazon.com/cloud9/latest/user-guide/app-preview.html)」 を参照してください。
**自然言語処理に Amazon Comprehend を使用**
Amazon Comprehend を使用することを選択すると、リアルタイム分析または非同期バッチジョブを実行して、個々のテキストドキュメント内のカスタムエンティティを検出できます。Amazon Comprehend では、エンドポイントを作成することでリアルタイムで使用できるカスタムエンティティ認識モデルとテキスト分類モデルをトレーニングすることもできます。
このパターンでは、非同期バッチジョブを使用して、複数のドキュメントを含む入力ファイルからセンチメントとエンティティを検出します。このパターンで提供されるサンプルアプリケーションは、ユーザーが 1 つの列と 1 行に 1 つのテキストドキュメントを含む.csv ファイルをアップロードできるように設計されています。GitHub の[Flask と AWS Elastic Beanstalk を使用して、Visualize AI/ML モデルの結果を視覚化](https://github.com/aws-samples/aws-comprehend-elasticbeanstalk-for-flask) リポジトリの `comprehend_helper.py` ファイルが、入力ファイルを読み取り、その入力を Amazon Comprehend に送信して処理します。
*BatchDetectEntities*
Amazon Comprehend は、一連のドキュメントのテキストに指定されたエンティティがないか検査し、検出されたエンティティ、場所、[エンティティのタイプ](https://docs.aws.amazon.com/comprehend/latest/dg/how-entities.html)、および Amazon Comprehend の信頼度を示すスコアを返します。1 つの API 呼び出しで送信できるドキュメントは最大 25 個で、各ドキュメントのサイズは 5,000 バイト未満です。結果をフィルタリングして、ユースケースに基づいて特定のエンティティのみを表示できます。たとえば、`‘quantity’` エンティティタイプをスキップして、検出されたエンティティのしきい値スコア (0.75 など) を設定できます。しきい値を選択する前に、特定のユースケースの結果を調べることを推薦します。これに関する詳細については、Amazon Comprehend ドキュメントの[BatchDetectEntities](https://docs.aws.amazon.com/comprehend/latest/dg/API_BatchDetectEntities.html) を参照してください。
*BatchDetectSentiment*
Amazon Comprehend は、受信した複数のドキュメントを検査し、各ドキュメントの一般的なセンチメント(`POSITIVE`、`NEUTRAL`、`MIXED`、または `NEGATIVE`)を返します。1 つの API 呼び出しで送信できるドキュメントは最大 25 個で、各ドキュメントのサイズは 5,000 バイト未満です。センチメントの分析は簡単で、スコアが最も高いセンチメントを選択して最終結果に表示します。これに関する詳細については、Amazon Comprehend ドキュメントの[BatchDetectSentiment](https://docs.aws.amazon.com/comprehend/latest/dg/API_BatchDetectSentiment.html) を参照してください。
**フラスコの設定処理**
Flask サーバーは一連の[設定変数](https://flask.palletsprojects.com/en/1.1.x/config/) を使用して、サーバーの実行方法を制御します。これらの変数には、デバッグ出力、セッショントークン、その他のアプリケーション設定を含めることができます。アプリケーションの実行中にアクセスできるカスタム変数を定義することもできます。設定変数を設定する方法は複数あります。
このパターンでは、設定が `config.py` で定義され、`application.py` の内部で継承されます。
+
**注記**
`config.py` には、アプリケーションの起動時に設定される設定変数が含まれます。このアプリケーションでは、サーバーを[デバッグモード](https://flask.palletsprojects.com/en/1.1.x/config/#DEBUG) で実行するようにアプリケーションに指示する `DEBUG` 変数が定義されています。実稼働環境でアプリケーションを実行する場合、デバッグモードを使用しません。`UPLOAD_FOLDER` は、アプリケーションで後から参照できるように定義されるカスタム変数で、アップロードされたユーザーデータの保存場所を通知します。
+ `application.py` はFlask アプリケーションを初期化し、`config.py` で定義されている設定を継承します。これは以下のコードによって実行されます。
```
application = Flask(__name__)
application.config.from_pyfile('config.py')
```
# その他のパターン
**Topics**
+ [Backstage とセルフサービスの Amazon SageMaker AI テンプレートを使用して MLOps を高速化](accelerate-mlops-with-backstage-and-sagemaker-templates.md)
+ [Amazon Bedrock を使用して AWS インフラストラクチャオペレーションを自動化する](automate-aws-infrastructure-operations-by-using-amazon-bedrock.md)
+ [Terraform を使用して CrewAI フレームワークで Amazon Bedrock にエージェンティックシステムを展開する](deploy-agentic-systems-on-amazon-bedrock-with-the-crewai-framework.md)
+ [ChatOps ソリューションをデプロイして、チャットアプリケーションのカスタムアクションと で Amazon Q Developer を使用して SAST スキャン結果を管理する CloudFormation](deploy-chatops-solution-to-manage-sast-scan-results.md)
+ [Quick Sight で AWS Mainframe Modernization と Amazon Q を使用してデータインサイトを生成する](generate-data-insights-by-using-aws-mainframe-modernization-and-amazon-q-in-quicksight.md)
+ [Quick Sight で AWS Mainframe Modernization と Amazon Q を使用して Db2 z/OS データインサイトを生成する](generate-db2-zos-data-insights-aws-mainframe-modernization-amazon-q-in-quicksight.md)
+ [SageMaker ノートブックインスタンスに、別の AWS アカウントの CodeCommit リポジトリへの一時的なアクセスを許可する](give-sagemaker-notebook-instances-temporary-access-to-a-codecommit-repository-in-another-aws-account.md)
+ [AWS CodePipeline と Amazon Bedrock を使用して AWS Organizations ポリシーをコードとして管理する](manage-organizations-policies-as-code.md)
+ [を使用して CardDemo メインフレームアプリケーションをモダナイズする AWS Transform](modernize-carddemo-mainframe-app.md)
+ [と Terraform を使用してメインフレームアプリケーションをモダナイズ AWS Transform およびデプロイする](modernize-mainframe-app-transform-terraform.md)
+ [Amazon Redshift ML機械学習を使用して高度な分析を実行する](perform-advanced-analytics-using-amazon-redshift-ml.md)
+ [Amazon Bedrock エージェントと を使用して Amazon EC2 コンプライアンス管理を合理化する AWS Config](streamline-amazon-ec2-compliance-management-with-amazon-bedrock-agents-and-aws-config.md)
+ [自動ワークフローを使用して Amazon Lex ボットの開発とデプロイを合理化する](streamline-amazon-lex-bot-development-and-deployment-using-an-automated-workflow.md)
+ [Amazon Bedrock AWS Step Functions を使用して の状態をトラブルシューティングする](troubleshooting-states-in-aws-step-functions.md)