GenAIIDP Deployment Guide

This guide covers how to deploy, build, publish, and test the GenAI Intelligent Document Processing solution.

Deployment Options

The GenAI IDP Accelerator can be deployed using either the AWS CloudFormation console (recommended for first-time users) or the IDP CLI (recommended for automation and programmatic deployments).

Administrator Access Requirements

Important: Deploying the GenAI IDP Accelerator requires administrator access to your AWS account. However, for organizations that want to enable non-administrator users to deploy and manage IDP stacks, we provide an optional CloudFormation service role approach:

For Administrators: Use the deployment options below with your existing administrator privileges
For Delegated Access: See iam-roles/cloudformation-management/README.md for instructions on provisioning a CloudFormation service role that allows non-administrator users to deploy and maintain IDP stacks without requiring administrator permissions

Option 1: One-Click CloudFormation Console Deployment (Recommended for First-Time Users)

Choose your region and click the Launch Stack button:

Region name	Region code	Launch
US West (Oregon)	us-west-2
US East (N.Virginia)	us-east-1
EU Central (Frankfurt)	eu-central-1

Review the template parameters and provide values as needed
Check the acknowledgment box and click Create stack
Wait for the stack to reach the CREATE_COMPLETE state (10-15 minutes)

Note: When the stack is deploying for the first time, it will send an email with a temporary password to the address specified in the AdminEmail parameter. You will need to use this temporary password to log into the UI and set a permanent password.

Option 2: CLI-Based Deployment (Recommended for Automation)

For programmatic deployment, updates, and batch processing, use the IDP CLI.

Install the CLI

cd lib/idp_cli_pkg
pip install -e .

Deploy a New Stack

idp-cli deploy \
    --stack-name my-idp-stack \
    --pattern pattern-2 \
    --admin-email your.email@example.com \
    --max-concurrent 100 \
    --wait

What this does:

Creates all CloudFormation resources (~120 resources)
Waits for deployment to complete (10-15 minutes)
Sends email with temporary admin password
Returns stack outputs including Web UI URL and bucket names

Deploy with Custom Configuration

# Deploy with local config file (automatically uploaded to S3)
idp-cli deploy \
    --stack-name my-idp-stack \
    --pattern pattern-2 \
    --admin-email your.email@example.com \
    --custom-config ./config_library/pattern-2/bank-statement-sample/config.yaml \
    --wait

Update an Existing Stack

# Update configuration
idp-cli deploy \
    --stack-name my-idp-stack \
    --custom-config ./updated-config.yaml \
    --wait

# Update parameters
idp-cli deploy \
    --stack-name my-idp-stack \
    --max-concurrent 200 \
    --log-level DEBUG \
    --wait

Benefits of CLI deployment:

Scriptable and automatable
Version-controlled deployments
Rapid iteration for configuration testing
Integration with CI/CD pipelines
No manual console clicking required

For complete CLI documentation, see IDP CLI Documentation.

Option 3: Build Deployment Assets from Source Code

Demo Video (5 minutes)

Dependencies

You need to have the following packages installed on your computer:

bash shell (Linux, MacOS, Windows-WSL)
aws (AWS CLI)
sam (AWS SAM)
python 3.11 or later
A local Docker daemon
Python packages for publish.py: pip install boto3 rich typer PyYAML botocore setuptools ruff build cfn-lint
Node.js 22.12+ and npm (required for UI validation in publish script)

For guidance on setting up a development environment, see:

Copy the repo to your computer. Either:

Use the git command to clone the repo, if you have access
OR, download and expand the ZIP file for the repo, or use the ZIP file that has been shared with you

Build and Publish the Solution

To build and publish your own template to your own S3 bucket:

cfn_bucket_basename: A prefix added to the beginning of the bucket name (e.g. idp-1234567890 to ensure global uniqueness)
cfn_prefix: A prefix added to CloudFormation resources (e.g. idp or idp-dev)

Navigate into the project root directory and run:

Using publish.py (Recommended)

python3 publish.py <cfn_bucket_basename> <cfn_prefix> <region> [--verbose] [--no-validate] [--clean-build] [--max-workers N]

Parameters:

cfn_bucket_basename: A prefix for the S3 bucket name (e.g., idp-1234567890)
cfn_prefix: S3 prefix for artifacts (e.g., idp)
region: AWS region for deployment (e.g., us-east-1)
--verbose or -v: (Optional) Enable detailed error output for debugging build failures
Pattern-2 functions are built and deployed as container images automatically. Pattern-1 and Pattern-3 use ZIP-based Lambdas.

Standard ZIP Deployment:

python3 publish.py idp-1234567890 idp us-east-1

Note: Pattern-2 container images are built and pushed automatically when Pattern-2 changes are detected. Ensure Docker is running and you have ECR permissions.

Note: Container-based deployment is recommended when Lambda functions exceed the 250MB unzipped size limit. This allows deployment packages up to 10GB.

Troubleshooting Build Issues: If the build fails, use the --verbose flag to see detailed error messages:

python3 publish.py idp-1234567890 idp us-east-1 --verbose

This will show:

Exact SAM build commands being executed
Complete error output from failed builds
Python version compatibility issues
Missing dependencies or configuration problems

Using publish.sh (Legacy)

./publish.sh <cfn_bucket_basename> <cfn_prefix> <region>

Example:

./publish.sh idp-1234567890 idp us-east-1

Both scripts:

Check your system dependencies for required packages
Create CloudFormation templates and asset zip files
Publish the templates and required assets to an S3 bucket in your account
The bucket will be named <cfn_bucket_basename>-<region> (created if it doesn't exist)

When completed, the script displays:

The CloudFormation template's S3 URL
A 1-click URL for launching the stack creation in the CloudFormation console

Deployment Options

Recommended: Deploy using AWS CloudFormation console

For your first deployment, use the 1-Click Launch URL provided by the publish script. This lets you inspect the available parameter options in the console.

CLI Deployment

For scripted/automated deployments, use the AWS CLI:

aws cloudformation deploy \
  --region <region> \
  --template-file <template-file> \
  --s3-bucket <bucket-name> \
  --s3-prefix <s3-prefix> \
  --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
  --parameter-overrides IDPPattern="<pattern-name>" AdminEmail=<your-email> \
  --stack-name <your-stack-name>

Or to update an already-deployed stack:

aws cloudformation update-stack \
  --stack-name <your-stack-name> \
  --template-url <template URL output by publish script, e.g. https://s3.us-east-1.amazonaws.com/blahblah.yaml> \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
  --region <region> \
  --parameters ParameterKey=AdminEmail,ParameterValue="<your-email>" ParameterKey=IDPPattern,ParameterValue="<pattern-name>"

Pattern Parameter Options:

Pattern1 - Packet or Media processing with Bedrock Data Automation (BDA)
- Can use an existing BDA project or create a new demo project
Pattern2 - Packet processing with Textract and Bedrock
- Supports both page-level and holistic classification
- Recommended for first-time users
Pattern3 - Packet processing with Textract, SageMaker(UDOP), and Bedrock
- Requires a UDOP model in S3 that will be deployed on SageMaker

After deployment, check the Outputs tab in the CloudFormation console to find links to dashboards, buckets, workflows, and other solution resources.

Container-Based Lambda Deployment

When Lambda functions exceed the 250MB unzipped size limit, use the container-based deployment option. This allows deployment packages up to 10GB.

When to Use Container Deployment

Use container-based deployment when:

Lambda package size exceeds 250MB unzipped
You need additional system dependencies not available in the Lambda runtime
You want to use custom runtime environments
Your deployment includes large ML models or data files

Container Deployment Process

Pattern-2 Uses Containers Automatically:
- When Pattern-2 changes are detected, the script builds Docker images for Pattern-2 functions and pushes them to ECR.
- Ensure Docker is running and your AWS credentials have ECR permissions.
What Happens Behind the Scenes:
- Creates/verifies ECR repository for Lambda images
- Builds Docker images for each Lambda function
- Pushes images to ECR with appropriate tags
- Updates CloudFormation templates to use container images
- Uploads templates to S3 for deployment
Architecture Support:

Default: ARM64 (Graviton2) for better price/performance
Optional: x86_64 for broader compatibility (adjust Docker build if needed)

Container Image Structure

The solution uses optimized multi-stage Docker builds:

Base stage: Python runtime and system dependencies
Dependencies stage: Python packages from requirements.txt
Function stage: Lambda function code and handler

Monitoring Container Deployments

Check deployment status:

# View ECR images
aws ecr list-images --repository-name idp-<stack-name>-lambda

# Check Lambda function configuration
aws lambda get-function --function-name <function-name>

# View container logs
aws logs tail /aws/lambda/<function-name> --follow

For detailed container deployment documentation, see Container Lambda Deployment Guide.

Updating an Existing Stack

To update an existing GenAIIDP deployment to a new version:

Log into the AWS console
Navigate to CloudFormation in the AWS Management Console
Select your existing GenAIIDP stack
Click on the "Update" button
Select "Replace current template"
Provide the new template URL:
- us-west-2: https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/genai-idp/idp-main.yaml
- us-east-1: https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/genai-idp/idp-main.yaml
- eu-central-1: https://s3.eu-central-1.amazonaws.com/aws-ml-blog-eu-central-1/artifacts/genai-idp/idp-main.yaml
Click "Next"
Review the parameters and make any necessary changes
- The update will preserve your existing parameter values
- Consider checking for new parameters that may be available in the updated template
Click "Next", then "Next" again on the Configure stack options page
Review the changes that will be made to your stack
Check the acknowledgment box for IAM capabilities
Click "Update stack"
Monitor the update process in the CloudFormation console

Note: Updating the stack may cause some resources to be replaced, which could lead to brief service interruptions. Consider updating during a maintenance window if the solution is being used in production.

Testing the Solution

Method 1: CLI-Based Batch Testing (Recommended for Automation)

For batch processing, evaluation workflows, or automated testing:

Quick Batch Test

# Install CLI
cd lib/idp_cli_pkg && pip install -e .

# Process sample documents
idp-cli run-inference \
    --stack-name IDP \
    --dir ./samples/ \
    --batch-id sample-test \
    --monitor

What you'll see:

✓ Uploaded 3 documents to InputBucket
✓ Sent 3 messages to processing queue

Monitoring Batch: sample-test
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Status Summary
 ─────────────────────────────────────
 ✓ Completed      3     100%
 ⏸ Queued         0       0%

Download Results

# Download all results
idp-cli download-results \
    --stack-name IDP \
    --batch-id sample-test \
    --output-dir ./test-results/

# View extraction data
cat ./test-results/sample-test/lending_package.pdf/sections/1/result.json | jq .

Evaluation Workflow Testing

Test accuracy with validated baselines:

# 1. Process documents initially
idp-cli run-inference \
    --stack-name IDP \
    --dir ./test-docs/ \
    --batch-id baseline-run \
    --monitor

# 2. Download and validate results
idp-cli download-results \
    --stack-name IDP \
    --batch-id baseline-run \
    --output-dir ./baselines/ \
    --file-types sections

# 3. Manually review and correct baselines
# (Edit ./baselines/baseline-run/*/sections/*/result.json as needed)

# 4. Create manifest with baselines
cat > eval-manifest.csv << EOF
document_path,baseline_source
./test-docs/invoice.pdf,./baselines/baseline-run/invoice.pdf/
./test-docs/w2.pdf,./baselines/baseline-run/w2.pdf/
EOF

# 5. Reprocess with evaluation
idp-cli run-inference \
    --stack-name IDP \
    --manifest eval-manifest.csv \
    --batch-id eval-test \
    --monitor

# 6. Download evaluation results
idp-cli download-results \
    --stack-name IDP \
    --batch-id eval-test \
    --output-dir ./eval-results/ \
    --file-types evaluation

# 7. Review accuracy metrics
cat ./eval-results/eval-test/invoice.pdf/evaluation/report.md

For complete evaluation workflow documentation, see IDP CLI - Complete Evaluation Workflow.

Method 2: Web UI Testing (Interactive)

Method 3: Direct S3 Upload Testing (Simple)

Open the S3InputBucketConsoleURL and S3OutputBucketConsoleURL from the stack Outputs tab
Open the StateMachineConsoleURL from the stack Outputs tab
Upload a PDF form to the Input bucket (sample files are in the ./samples folder):
- For Patterns 1 (BDA) and Pattern 2: Use samples/lending_package.pdf
- For Pattern 3 (UDOP): Use samples/rvl_cdip_package.pdf
Monitor the Step Functions execution to observe the workflow
When complete, check the Output bucket for the structured JSON file with extracted fields

Upload Multiple Files for Volume Testing

To copy a sample file multiple times:

n=10
for i in `seq 1 $n`; do 
  aws s3 cp ./samples/lending_package.pdf \
    s3://idp-inputbucket-kmsxxxxxxxxx/lending_package-$i.pdf
done

Method 4: Web UI Testing (Interactive)

Open the Web UI URL from the CloudFormation stack's Outputs tab
Log in using your credentials (the temporary password from the email if this is your first login)
Navigate to the main dashboard
Click the "Upload Document" button
Select a sample PDF file appropriate for your pattern (see above for recommendations)
Follow the upload process and observe the document processing in the UI
View the extraction results once processing is complete

Testing Individual Lambda Functions Locally

To test any lambda function locally:

Change directory to the folder containing the function's template.yaml
Create an input event file (some templates are in the ./testing folder)
Verify ./testing/env.json and change the region if necessary
Run sam build to package the function(s)

Use sam local to run the function:

sam local invoke OCRFunction -e testing/OCRFunction-event.json --env-vars testing/env.json

Steady-State Volume Testing

Use the load simulator script to test high document volumes:

python ./scripts/simulate_load.py -s source_bucket -k prefix/exampledoc.pdf -d idp-kmsxxxxxxxxx -r 500 -t 10

This simulates an incoming document rate of 500 docs per minute for 10 minutes.

Variable Volume Testing

Use the dynamic load simulator script for variable document rates over time:

python ./scripts/simulate_dynamic_load.py -s source_bucket -k prefix/exampledoc.pdf -d idp-kmsxxxxxxxxx -f schedule.csv

This simulates incoming documents based on minute-by-minute rates in the schedule CSV file.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GenAIIDP Deployment Guide

Deployment Options

Administrator Access Requirements

Option 1: One-Click CloudFormation Console Deployment (Recommended for First-Time Users)

Option 2: CLI-Based Deployment (Recommended for Automation)

Install the CLI

Deploy a New Stack

Deploy with Custom Configuration

Update an Existing Stack

Option 3: Build Deployment Assets from Source Code

Dependencies

Build and Publish the Solution

Using publish.py (Recommended)

Using publish.sh (Legacy)

Deployment Options

Recommended: Deploy using AWS CloudFormation console

CLI Deployment

Container-Based Lambda Deployment

When to Use Container Deployment

Container Deployment Process

Container Image Structure

Monitoring Container Deployments

Updating an Existing Stack

Testing the Solution

Method 1: CLI-Based Batch Testing (Recommended for Automation)

Quick Batch Test

Download Results

Evaluation Workflow Testing

Method 2: Web UI Testing (Interactive)

Method 3: Direct S3 Upload Testing (Simple)

Upload Multiple Files for Volume Testing

Method 4: Web UI Testing (Interactive)

Testing Individual Lambda Functions Locally

Steady-State Volume Testing

Variable Volume Testing

FilesExpand file tree

deployment.md

Latest commit

History

deployment.md

File metadata and controls

GenAIIDP Deployment Guide

Deployment Options

Administrator Access Requirements

Option 1: One-Click CloudFormation Console Deployment (Recommended for First-Time Users)

Option 2: CLI-Based Deployment (Recommended for Automation)

Install the CLI

Deploy a New Stack

Deploy with Custom Configuration

Update an Existing Stack

Option 3: Build Deployment Assets from Source Code

Dependencies

Build and Publish the Solution

Using publish.py (Recommended)

Using publish.sh (Legacy)

Deployment Options

Recommended: Deploy using AWS CloudFormation console

CLI Deployment

Container-Based Lambda Deployment

When to Use Container Deployment

Container Deployment Process

Container Image Structure

Monitoring Container Deployments

Updating an Existing Stack

Testing the Solution

Method 1: CLI-Based Batch Testing (Recommended for Automation)

Quick Batch Test

Download Results

Evaluation Workflow Testing

Method 2: Web UI Testing (Interactive)

Method 3: Direct S3 Upload Testing (Simple)

Upload Multiple Files for Volume Testing

Method 4: Web UI Testing (Interactive)

Testing Individual Lambda Functions Locally

Steady-State Volume Testing

Variable Volume Testing