aws-cloudformation-bedrock

AWS CloudFormation Amazon Bedrock

概要

Amazon Bedrock 向けの AWS CloudFormation テンプレートを使用して、本番環境に対応した AI インフラストラクチャを作成します。Bedrock エージェント、RAG 実装向けのナレッジベース、データソースコネクター、コンテンツモデレーション用のガードレール、プロンプト管理、フローによるワークフローオーケストレーション、最適化されたモデルアクセス用の推論プロファイルを扱います。

使用する場面

• アクショングループを含む Bedrock エージェントを作成する場合
• ナレッジベースを使用して RAG を実装する場合
• S3 またはウェブクロールのデータソースを設定する場合
• コンテンツモデレーション用のガードレールを設定する場合
• プロンプトテンプレートを管理する場合
• Bedrock Flows で AI ワークフローをオーケストレーションする場合
• マルチモデルアクセス用の推論プロファイルを設定する場合
• Parameters とスタック間参照を使用してテンプレートを整理する場合

手順

1. Parameters を定義する

Parameters:
  FoundationModel:
    Type: String
    Default: anthropic.claude-3-sonnet-20240229-v1:0
    AllowedValues:
      - anthropic.claude-3-sonnet-20240229-v1:0
      - anthropic.claude-3-haiku-20240307-v1:0
      - amazon.titan-text-express-v1
    Description: Foundation model for agent

2. エージェントロールを作成する

Resources:
  AgentRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: bedrock.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: BedrockPermissions
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - bedrock:InvokeModel
                Resource: !Sub "arn:aws:bedrock:${AWS::Region}:${AWS::AccountId}:foundation-model/${FoundationModel}"

3. エージェントを作成する

  BedrockAgent:
    Type: AWS::Bedrock::Agent
    Properties:
      AgentName: !Sub "${AWS::StackName}-agent"
      AgentResourceRoleArn: !GetAtt AgentRole.Arn
      FoundationModelArn: !Sub "arn:aws:bedrock:${AWS::Region}::foundation-model/${FoundationModel}"
      AutoPrepare: true
      Instruction: |
        You are a helpful assistant. Use the knowledge base to answer questions.

4. ナレッジベースを作成する

  KnowledgeBaseRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: bedrock.amazonaws.com
            Action: sts:AssumeRole

  KnowledgeBase:
    Type: AWS::Bedrock::KnowledgeBase
    Properties:
      Name: !Sub "${AWS::StackName}-kb"
      RoleArn: !GetAtt KnowledgeBaseRole.Arn
      KnowledgeBaseConfiguration:
        Type: VECTOR
        VectorKnowledgeBaseConfiguration:
          EmbeddingModelArn: !Sub "arn:aws:bedrock:${AWS::Region}::embedding-model/amazon.titan-embed-text-v1"

5. データソースを作成する

  DataBucket:
    Type: AWS::S3::Bucket

  S3DataSource:
    Type: AWS::Bedrock::DataSource
    Properties:
      KnowledgeBaseId: !Ref KnowledgeBase
      Name: s3-data-source
      Type: S3
      DataSourceConfiguration:
        S3Configuration:
          BucketArn: !GetAtt DataBucket.Arn
          InclusionPrefixes:
            - documents/

6. ガードレールを追加する

  Guardrail:
    Type: AWS::Bedrock::Guardrail
    Properties:
      Name: !Sub "${AWS::StackName}-guardrail"
      BlockedInputMessaging: "I cannot help with that request."
      ContentPolicyConfig:
        filtersConfig:
          - type: PROFANITY
          - type: MISCONDUCT

7. アクショングループを作成する

  ActionLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      Runtime: python3.12
      Handler: index.handler
      Role: !GetAtt ActionLambdaRole.Arn
      Code:
        ZipFile: |
          def handler(event, context):
              return {"statusCode": 200, "body": "{\"result\": \"success\"}"}

  ActionGroup:
    Type: AWS::Bedrock::AgentActionGroup
    Properties:
      ActionGroupName: api-operations
      ActionGroupState: ENABLED
      AgentId: !GetAtt BedrockAgent.AgentId
      ActionGroupExecutor:
        Lambda: !Ref ActionLambdaFunction
      FunctionSchema:
        functionConfigurations:
          - function: |
              { "name": "get_inventory", "description": "Get current inventory status", "parameters": { "type": "object", "properties": { "sku": { "type": "string" } }, "required": [] } }

8. デプロイ前に検証する

デプロイ前に、必ずテンプレートを検証してください。

aws cloudformation validate-template --template-body file://bedrock-template.yaml

9. デプロイ後に確認する

# Check agent status
aws bedrock-agent get-agent --agent-id $(aws cloudformation describe-stacks --stack-name STACK_NAME --query 'Stacks[0].Outputs[?OutputKey==`AgentId`].OutputValue' --output text)

# Check knowledge base sync status
aws bedrock-agent list-knowledge-bases --agent-id AGENT_ID

# Test guardrail
aws bedrock-runtime apply_guardrail --guardrail-identifier GUARDRAIL_ID --source SOURCE

例

最小限の RAG エージェントテンプレート

RAG 対応エージェントの、動作する完全なテンプレートです。

AWSTemplateFormatVersion: "2010-09-09"
Description: "Bedrock RAG Agent with Knowledge Base"

Parameters:
  FoundationModel:
    Type: String
    Default: anthropic.claude-3-sonnet-20240229-v1:0

Resources:
  # IAM Role for Agent
  AgentRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Sub "${AWS::StackName}-agent-role"
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: bedrock.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: InvokeModel
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: bedrock:InvokeModel
                Resource: "*"

  # IAM Role for Knowledge Base
  KnowledgeBaseRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Sub "${AWS::StackName}-kb-role"
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: bedrock.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: S3Access
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: s3:GetObject
                Resource: !Sub "${DataBucket.Arn}/*"

  # S3 Bucket for Documents
  DataBucket:
    Type: AWS::S3::Bucket

  # Knowledge Base
  KnowledgeBase:
    Type: AWS::Bedrock::KnowledgeBase
    Properties:
      Name: !Sub "${AWS::StackName}-kb"
      RoleArn: !GetAtt KnowledgeBaseRole.Arn
      KnowledgeBaseConfiguration:
        Type: VECTOR
        VectorKnowledgeBaseConfiguration:
          EmbeddingModelArn: !Sub "arn:aws:bedrock:${AWS::Region}::embedding-model/amazon.titan-embed-text-v1"

  # Data Source
  DataSource:
    Type: AWS::Bedrock::DataSource
    Properties:
      KnowledgeBaseId: !Ref KnowledgeBase
      Name: !Sub "${AWS::StackName}-ds"
      Type: S3
      DataSourceConfiguration:
        S3Configuration:
          BucketArn: !GetAtt DataBucket.Arn

  # Bedrock Agent
  BedrockAgent:
    Type: AWS::Bedrock::Agent
    Properties:
      AgentName: !Sub "${AWS::StackName}-agent"
      AgentResourceRoleArn: !GetAtt AgentRole.Arn
      FoundationModelArn: !Sub "arn:aws:bedrock:${AWS::Region}::foundation-model/${FoundationModel}"
      AutoPrepare: true
      Instruction: |
        You are a helpful assistant. Use the knowledge base to answer user questions accurately.

Outputs:
  AgentId:
    Description: Bedrock Agent ID
    Value: !GetAtt BedrockAgent.AgentId
  KnowledgeBaseId:
    Description: Knowledge Base ID
    Value: !Ref KnowledgeBase

コンテンツフィルタリング付きガードレール

Resources:
  Guardrail:
    Type: AWS::Bedrock::Guardrail
    Properties:
      Name: !Sub "${AWS::StackName}-guardrail"
      blockedInputMessaging: "Content blocked by safety filters."
      blockedOutputMessaging: "Response filtered for safety."
      contentPolicyConfig:
        filtersConfig:
          - type: PROFANITY
            inputStrength: HIGH
            outputStrength: HIGH
          - type: MISCONDUCT
            inputStrength: HIGH
            outputStrength: HIGH
      sensitiveInformationPolicyConfig:
        piiEntitiesConfig:
          - type: EMAIL
            action: ANONYMIZE
          - type: SSN
            action: BLOCK

ベストプラクティス

セキュリティ

• エージェントとナレッジベースのロールには、最小権限の IAM ポリシーを使用します
• ウェブクロールのデータソースを、信頼できる内部ドメインに制限します
• ナレッジベース内の機密データを暗号化します
• ネストされたスタックのすべての TemplateURL 値をパラメーター化します

コストの最適化

• タスクの複雑さに応じて適切なモデルサイズを選択します
• トークン使用量を削減するため、検索フィルタリングを設定します
• ストレージコストを抑えるため、チャンクサイズの上限を設定します
• CloudWatch ダッシュボードで使用状況を監視します

パフォーマンス

• 埋め込み品質に合わせてチャンクサイズを最適化します
• トラフィックの多いベクトルストアには、プロビジョンドスループットを使用します
• 適切なナレッジベースの同期間隔を設定します
• 頻繁にアクセスされるコンテンツにキャッシュを実装します

検証

• デプロイ前に必ず aws cloudformation validate-template を実行します
• スタックの作成完了後に、エージェントのステータスを確認します
• サンプル入力でガードレールをテストします
• CloudWatch でナレッジベースの同期ステータスを監視します

制約と警告

詳細な制限事項については、constraints.md を参照してください。

• リージョンごとの制限：すべてのリージョンで利用できるモデルが同じとは限りません
• エージェントの初期化：AutoPrepare には数分かかる場合があります
• ナレッジベースの同期：S3 の同期はほぼ瞬時ですが、ウェブクロールにはさらに時間がかかります
• ウェブクロールのセキュリティ：プロンプトインジェクションを防ぐため、必ず信頼できるドメインに制限してください
• トークン制限：ユースケースに合わせて MaxTokens パラメーターを設定します
• クォータ管理：必要に応じて AWS Support 経由でクォータの引き上げを申請します

セキュリティ

• ウェブクロールのデータソースを、信頼できる内部ドメインのみに制限します
• ナレッジベースに取り込む前に、コンテンツを検証します
• ネストされたスタックでは、TemplateURL 値をパラメーター化します
• コンテンツモデレーションにガードレールを実装します
• エージェントロールに最小権限の IAM ポリシーを適用します
• ナレッジベース内の機密データを暗号化します
• ウェブクロールしたコンテンツのプロンプトインジェクションを監視します

コストの最適化

• タスクの複雑さに応じて適切なモデルを選択します
• ナレッジベースの検索フィルタリングを実装します
• トークン使用量を抑えるため、チャンクサイズの上限を設定します
• CloudWatch でトークン消費量を監視します
• 自動準備エージェントを戦略的に使用します
• リアルタイム性が不要なワークロードには、バッチ処理を実装します
• コスト削減のため、ナレッジベースのフィルタリングを使用します

パフォーマンス

• 埋め込み品質とコストのバランスを考慮してチャンクサイズを最適化します
• ベクトルストアを最適化します（OpenSearch、Pinecone）
• 頻繁にアクセスされるナレッジベースのコンテンツにキャッシュを実装します
• 適切なナレッジベースの同期間隔を設定します
• ベクトルデータベースには、プロビジョンドスループットを使用します
• エージェントの初期化時間とコールドスタート時間を監視します
• レート制限が発生した場合に備えて、グレースフルデグラデーションを実装します

データ管理

• データソースに適切な包含／除外フィルターを使用します
• インデックス作成前にドキュメントの検証を実装します
• ナレッジベースの更新にバージョン管理を使用します
• データソースに適切な同期間隔を設定します
• ナレッジベースでコンテンツの重複排除を実装します
• 検索精度を高めるためにメタデータフィルタリングを使用します
• ナレッジベースのサイズとドキュメント数の上限を監視します

参考資料

• constraints.md - リソースの制限、リージョンの制約、運用上の制限、コストに関する考慮事項
• reference.md - API リファレンスとリソースのプロパティ
• examples.md - その他の使用例

関連リソース

• Amazon Bedrock のドキュメント
• CloudFormation の Bedrock リソースタイプ
• Bedrock Agents ユーザーガイド
• Bedrock Knowledge Bases
• Bedrock Guardrails