Meter Reading AI Agent 導入手順

Meter Reading AI Agent のデプロイと設定手順をご紹介したします。

クイックスタート

前提条件

AWS アカウント
AWS CLI がインストール・設定済み
CloudFormation 実行権限
Bedrock AgentCore Runtime へのアクセス権限
S3 Tables へのアクセス権限

Meter Reading AI Agent と関連リソースのデプロイ

CloudFormationスタックのデプロイ（CLI）

bash

aws cloudformation create-stack \
  --stack-name meter-reading-agent-stack \
  --template-url https://cm-seller-resources.s3.us-east-1.amazonaws.com/meter-reading-ai-agent/cfn/reader-agent.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

デプロイ完了の確認

bash

aws cloudformation describe-stacks \
  --stack-name meter-reading-agent-stack \
  --region us-east-1 \
  --query 'Stacks[0].StackStatus'

出力値の取得

デプロイ完了後、以下の出力値を取得します：

bash

aws cloudformation describe-stacks \
  --stack-name meter-reading-agent-stack \
  --region us-east-1 \
  --query 'Stacks[0].Outputs'

重要な出力値：

RuntimeArn: AgentCore Runtime ARN
EndpointArn: AgentCore Runtime Endpoint ARN
ImageBucketName: 画像アップロード用 S3 バケット名
KnowledgeBaseId: Knowledge Base ID
KnowledgeBaseSourceBucketName: Knowledge Base ソースバケット名
MeterReadingsTableArn: S3 Tables テーブル ARN

ダッシュボードのサンプル実装のデプロイ

ダッシュボードスタックのデプロイ（CLI）

bash

aws cloudformation create-stack \
  --stack-name meter-dashboard-stack \
  --template-url https://cm-seller-resources.s3.us-east-1.amazonaws.com/meter-reading-ai-agent/cfn/dashboard-stack.yaml \
  --parameters \
    ParameterKey=ImageUri,ParameterValue=<ECR_IMAGE_URI> \
    ParameterKey=S3TablesArn,ParameterValue=<S3_TABLES_ARN> \
    ParameterKey=S3TablesNamespaceName,ParameterValue=meter_data \
    ParameterKey=S3TablesTableName,ParameterValue=meter_readings \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

CloudFront URLの取得

デプロイ完了後、 CloudFront の URL を取得します：

bash

aws cloudformation describe-stacks \
  --stack-name meter-dashboard-stack \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`CloudFrontDistributionURL`].OutputValue' \
  --output text

設定

メーター読取り指示書の登録

Knowledge Base のソースバケットに指示書ファイルを登録します。

指示書ファイルの準備
指示書は Markdown 形式で作成します。例：
markdown
```
# メーター読み取り指示書

## 読み取り手順
...
```
こちらからサンプルをダウンロードいただけます。
S3バケットへのアップロード

bash

# Knowledge Baseソースバケット名を取得
KB_BUCKET=$(aws cloudformation describe-stacks \
  --stack-name meter-reading-agent-stack \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`KnowledgeBaseSourceBucketName`].OutputValue' \
  --output text)

# 指示書ファイルをアップロード
aws s3 cp reading-instructions.md \
  s3://${KB_BUCKET}/instructions/reading-instructions.md \
  --region us-east-1

メーター仕様ファイルの登録

メーター仕様ファイルは JSON 形式で作成し、Knowledge Base のソースバケットに登録します。

メーター仕様ファイルの準備

meter-specs/meter-types.json形式で作成します：

json

{
  "meter_types": [
    {
      "id": "pressure-gauge-001",
      "name": "圧力計（アナログ単針式）",
      "type": "pressure",
      "description": "0-10MPa範囲の単針式圧力計",
      "unit": "MPa",
      "min_value": 0,
      "max_value": 10,
      "graduation": 0.5,
      "reading_method": "単針の指す位置を読み取る",
      "validation_rules": {
        "min": 0,
        "max": 10,
        "decimal_places": 2
      },
      "qr_code_prefix": "PRESS"
    }
  ],
  "common_instructions": {
    "image_quality": "画像は十分な明るさで撮影",
    "reading_angle": "メーターを正面から撮影",
    "qr_code": "QRコードをメーターと共に撮影"
  }
}

S3バケットへのアップロード

bash

# Knowledge Baseソースバケット名を取得
KB_BUCKET=$(aws cloudformation describe-stacks \
  --stack-name meter-reading-agent-stack \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`KnowledgeBaseSourceBucketName`].OutputValue' \
  --output text)

# メーター仕様ファイルをアップロード
aws s3 cp meter-types.json \
  s3://${KB_BUCKET}/meter-specs/meter-types.json \
  --region us-east-1

ナレッジベースの同期

ナレッジベースの同期は、Bedrock コンソールまたは CLI から実行できます。

CLIでの同期:

bash

# Knowledge Base IDとDataSource IDを取得
KB_ID=$(aws cloudformation describe-stacks \
  --stack-name meter-reading-agent-stack \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`KnowledgeBaseId`].OutputValue' \
  --output text)

DS_ID=$(aws cloudformation describe-stacks \
  --stack-name meter-reading-agent-stack \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`KnowledgeBaseDataSourceId`].OutputValue' \
  --output text)

# 同期ジョブを開始
aws bedrock start-ingestion-job \
  --knowledge-base-id ${KB_ID} \
  --data-source-id ${DS_ID} \
  --region us-east-1

# 同期ジョブの状態を確認
aws bedrock get-ingestion-job \
  --knowledge-base-id ${KB_ID} \
  --data-source-id ${DS_ID} \
  --ingestion-job-id <JOB_ID> \
  --region us-east-1

コンソールでの同期:

AWS Bedrock コンソールにアクセス
「Knowledge bases」を選択
対象の Knowledge Base を選択
「Data sources」タブを開く
対象のデータソースを選択し、「同期」をクリック

仕様

AIエージェントインターフェース仕様

エントリーポイント

AgentCore Runtime エンドポイントは以下の形式で呼び出します：

リクエスト形式:

json

{
  "s3_bucket": "camera-image-123456789012-us-east-1",
  "s3_key": "images/2025/01/15/image.jpg",
  "session_id": "uuid-string",
  "meter_info": {
    "meter_id": "001",
    "meter_type": "pressure",
    "unit": "MPa"
  }
}

レスポンス形式:

json

{
  "meter_id": "001",
  "meter_type": "pressure",
  "reading_value": 5.5,
  "status": "processed",
  "reading_unit": "MPa",
  "confidence_score": 0.95,
  "image_s3_key": "images/2025/01/15/image.jpg",
  "qr_code_data": "PRESS-001-A1F",
  "processing_duration_ms": 12000,
  "image_quality": 0.88,
  "validation_passed": true,
  "error_message": null,
  "notes": null
}

フィールド説明

フィールド名	型	必須	説明
`meter_id`	string	必須	メーターの一意な識別子
`meter_type`	string	必須	メータータイプ（pressure, temperature, flow, power, water）
`reading_value`	number	必須	読み取り値（数値）
`status`	string	必須	処理ステータス（processed, error, warning）
`reading_unit`	string	オプション	単位（MPa, ℃, L/min, kWh, m³）
`confidence_score`	number	オプション	信頼度スコア（0.0-1.0）
`image_s3_key`	string	オプション	画像ファイルのS3キー
`qr_code_data`	string	オプション	QRコードから読み取ったデータ
`processing_duration_ms`	integer	オプション	処理時間（ミリ秒）
`image_quality`	number	オプション	画像品質スコア（0.0-1.0）
`validation_passed`	boolean	オプション	バリデーション結果
`error_message`	string	オプション	エラーメッセージ（エラー時）
`notes`	string	オプション	特記事項

エラーレスポンス

エラーが発生した場合、以下の形式で返されます：

json

{
  "error": "エラーメッセージ",
  "status": "error",
  "meter_id": "001",
  "meter_type": "pressure"
}

メーター仕様ファイルフォーマット

メーター仕様ファイルは JSON 形式で、以下の構造を持ちます：

スキーマ定義

json

{
  "meter_types": [
    {
      "id": "string（必須）",
      "name": "string（必須）",
      "type": "string（必須）",
      "description": "string（必須）",
      "unit": "string（必須）",
      "min_value": "number（必須）",
      "max_value": "number（必須）",
      "graduation": "number（必須）",
      "reading_method": "string（必須）",
      "validation_rules": {
        "min": "number（必須）",
        "max": "number（必須）",
        "decimal_places": "integer（必須）"
      },
      "qr_code_prefix": "string（必須）"
    }
  ],
  "common_instructions": {
    "image_quality": "string（必須）",
    "reading_angle": "string（必須）",
    "qr_code": "string（必須）",
    "error_handling": "string（必須）",
    "confidence": "string（必須）"
  }
}

メーター仕様ファイルのフィールド説明

meter_types配列の各要素:

フィールド名	型	説明
`id`	string	メータータイプの一意なID
`name`	string	メータータイプの表示名
`type`	string	メーターカテゴリ（pressure, temperature, flow, power, water）
`description`	string	メーターの説明
`unit`	string	測定単位
`min_value`	number	最小測定値
`max_value`	number	最大測定値
`graduation`	number	目盛り間隔
`reading_method`	string	読み取り方法の説明
`validation_rules`	object	バリデーションルール
`qr_code_prefix`	string	QRコードのプレフィックス（PRESS, TEMP, FLOW, POWER, WATER）

サンプルファイル

json

{
  "meter_types": [
    {
      "id": "pressure-gauge-001",
      "name": "圧力計（アナログ単針式）",
      "type": "pressure",
      "description": "0-10MPa範囲の単針式圧力計。目盛りは0.5MPa刻み。",
      "unit": "MPa",
      "min_value": 0,
      "max_value": 10,
      "graduation": 0.5,
      "reading_method": "単針の指す位置を読み取る。目盛りの中間位置の場合は補間して読み取る。",
      "validation_rules": {
        "min": 0,
        "max": 10,
        "decimal_places": 2
      },
      "qr_code_prefix": "PRESS"
    }
  ]
}

ファイル配置

メーター仕様ファイルは、Knowledge Base ソースバケットのmeter-specs/プレフィックス配下に配置します：

text

s3://<knowledge-base-source-bucket>/
  └── meter-specs/
      └── meter-types.json

S3 Tablesスキーマ

メーター読み取りデータは以下のスキーマで S3 Tables に保存されます：

カラム名	型	必須	説明
`timestamp`	timestamp	必須	読み取り日時（UTC）
`meter_id`	string	必須	メーターID
`meter_type`	string	必須	メータータイプ
`reading_value`	double	必須	読み取り値
`reading_unit`	string	オプション	単位
`confidence_score`	double	オプション	信頼度スコア
`image_s3_key`	string	オプション	画像ファイルのS3キー
`qr_code_data`	string	オプション	QRコードデータ
`processing_duration_ms`	int	オプション	処理時間（ミリ秒）
`image_quality`	double	オプション	画像品質スコア
`validation_passed`	boolean	オプション	バリデーション結果
`error_message`	string	オプション	エラーメッセージ
`notes`	string	オプション	特記事項
`status`	string	必須	ステータス
`record_id`	string	必須	レコードID（UUID）

トラブルシュート

デプロイ関連

ダッシュボードスタックのデプロイエラー

エラー: "The maximum number of rules per security group has been reached."

原因: セキュリティグループのルール数が上限に達している

対処方法:

AWS Service Quotas コンソールにアクセス
「Inbound or outbound rules per security group」のクォータを確認
必要に応じて上限緩和申請を提出

エラー: CloudFormation スタックがCREATE_FAILED状態になる

原因: IAM 権限不足、リソース制限、テンプレートエラーなど

対処方法:

CloudFormation コンソールでスタックイベントを確認
エラーメッセージを確認して原因を特定
必要に応じて IAM 権限を追加、リソース制限を確認

Knowledge Baseが参照できない

原因: Knowledge Base ID の設定ミス、同期が完了していない

対処方法:

環境変数KNOWLEDGE_BASE_IDが正しく設定されているか確認
Knowledge Base の同期ジョブが完了しているか確認
データソースの設定を確認

その他

QRコードが読み取れない

原因: 画像品質不足、QR コードの形式が不正

対処方法:

画像が明瞭に撮影されているか確認
QR コードの形式が{PREFIX}-{METER_ID}-{LOCATION}になっているか確認
QR コードがメーターと共に撮影されているか確認

読み取り精度が低い

原因: 画像品質不足、メーター仕様の設定ミス

対処方法:

画像品質スコアを確認（0.7 以上推奨）
メーター仕様ファイルが正しく登録されているか確認
Knowledge Base の同期が完了しているか確認
より明瞭な画像で再撮影

Meter Reading AI Agent 導入手順 ​

クイックスタート ​

前提条件 ​

Meter Reading AI Agent と関連リソースのデプロイ ​

CloudFormationスタックのデプロイ（CLI） ​

デプロイ完了の確認 ​

出力値の取得 ​

ダッシュボードのサンプル実装のデプロイ ​

ダッシュボードスタックのデプロイ（CLI） ​

CloudFront URLの取得 ​

設定 ​

メーター読取り指示書の登録 ​

メーター仕様ファイルの登録 ​

ナレッジベースの同期 ​

仕様 ​

AIエージェント インターフェース仕様 ​

エントリーポイント ​

フィールド説明 ​

エラーレスポンス ​

メーター仕様ファイル フォーマット ​

スキーマ定義 ​

メーター仕様ファイルのフィールド説明 ​

サンプルファイル ​

ファイル配置 ​

S3 Tablesスキーマ ​

トラブルシュート ​

デプロイ関連 ​

ダッシュボードスタックのデプロイエラー ​

Knowledge Baseが参照できない ​

その他 ​

QRコードが読み取れない ​

読み取り精度が低い ​

Meter Reading AI Agent 導入手順

クイックスタート

前提条件

Meter Reading AI Agent と関連リソースのデプロイ

CloudFormationスタックのデプロイ（CLI）

デプロイ完了の確認

出力値の取得

ダッシュボードのサンプル実装のデプロイ

ダッシュボードスタックのデプロイ（CLI）

CloudFront URLの取得

設定

メーター読取り指示書の登録

メーター仕様ファイルの登録

ナレッジベースの同期

仕様

AIエージェントインターフェース仕様

エントリーポイント

フィールド説明

エラーレスポンス

メーター仕様ファイルフォーマット

スキーマ定義

メーター仕様ファイルのフィールド説明

サンプルファイル

ファイル配置

S3 Tablesスキーマ

トラブルシュート

デプロイ関連

ダッシュボードスタックのデプロイエラー

Knowledge Baseが参照できない

その他

QRコードが読み取れない

読み取り精度が低い