Zenn
🎼

Bedrock Converse API のJSON生成を理解したい

に公開
AWS
JSON
Bedrock
Anthropic
converse
tech

この記事は、AWS Communityの一連の記事の一部を翻訳したものです。
親記事は、こちらからご参照いただけます。

はじめに

この記事は、Amazon Bedrockのツール利用に関するシリーズの一部です。パート1ではAmazon Bedrock Converse APIのクイックチュートリアルを紹介し、パート2ではConverse APIでのツール利用方法を解説しました。本記事では、Amazon Bedrockの大規模言語モデルを使って、事前定義したJSON Schemaに準拠したJSONを生成する方法を紹介します。主要なJSON Schema要素の説明と、Pythonコード例もご紹介します。

Amazon Bedrock Converse APIは、Amazon Bedrockを利用した大規模言語モデル（LLM）への一貫したアクセス方法を提供します。ユーザーと生成AIモデル間のターン制メッセージをサポートし、ツール利用（いわゆる「関数呼び出し」）に対応したモデル向けに、ツール定義の一貫したフォーマットも提供します。

ツール利用とは、LLMが呼び出し元アプリケーションに対して、モデルが生成したパラメータで関数を呼び出すよう指示できる技術です。利用可能なツールと可能なパラメータをプロンプトと一緒にモデルに渡すと、ツール定義のJSON Schemaに従って、モデルはツールを選択し、パラメータを定義します。その後、アプリケーションが関数を呼び出し、モデルが生成したパラメータを渡します。

また、このツール利用機能を使い、関数呼び出しをスキップして、生成されたJSONを直接利用することもできます。この記事の例では、その方法を実演します。

なぜJSON生成が重要なのか？

これにより、非構造化コンテンツを構造化データへより確実に変換できます。従来は、膨大な非構造データがドキュメントや顧客フィードバック、メモ欄などに埋もれており、実質的に活用できませんでした。大規模言語モデルによるJSON生成を使えば、その生データを定量的に処理・理解できるデータに変換できます。

Amazon Bedrock Converse APIでJSONを生成する手順は以下の通りです：

  1. 呼び出し元アプリケーションが、（A）求められたJSON Schemaを含むツール定義と、（B）呼び出しメッセージをLLMに渡す。
  2. モデルが、ツール定義のJSON Schemaに準拠したJSONなどのツール利用リクエストを生成
  3. アプリケーションがモデルのツール利用リクエストからJSONを抽出し、処理する。

開発環境とAWSアカウントのセットアップ

免責事項

  • LLMは非決定的です。この記事の結果と異なる場合があります。
  • AWSアカウントでコードを実行すると、消費トークン分の料金が発生します。
  • 「最小限のプロンプト」を推奨していますが、用途によっては詳細なプロンプトが必要です。
  • すべてのモデルがConverse APIの全機能をサポートしているわけではありません。公式ドキュメントで確認してください。

シナリオ概要

投資運用会社で、毎日何千通もの顧客メールが共通の受信箱に届くとします。通常はカスタマーサービスチームが各メールを確認し、対応の要否や担当部署を判断します。その情報をデータベースに保存したり、他のアプリケーションに渡したりします。しかし、生成AIを使って顧客の要望を解釈し、情報を抽出し、対応部署を推薦できたらどうでしょう？

例えば、こんなリクエスト：

Acme Investments様
貴社のカスタマーサービス担当Shirley Scarryさんに感謝の意を伝えたくご連絡します。先日、口座入金についてShirleyさんとお話しし、とても親切かつ知識豊富で、すべての質問に丁寧に答えてくださいました。Robert Herbfordさんも通話に参加されましたが、正直あまり集中していない様子でした。妻のClaraも追加の質問がありましたが、Shirleyさんが解決してくれました。Shirleyさんのプロ意識と専門性に感謝しています。今後も他の方に貴社を推薦したいと思います。
Carson Bradford

これを、以下のようなJSONデータに抽出したい：

{
  "summary": "顧客がAcme InvestmentsのShirley Scarry氏の優れたカスタマーサービスを称賛し、Robert Herbford氏は通話中に集中していなかったと指摘。",
  "escalate_complaint": false,
  "overall_sentiment": "Positive",
  "supporting_business_unit": "Customer Service",
  "level_of_concern": 2,
  "customer_names": [
    "Carson Bradford",
    "Clara Bradford"
  ],
  "sentiment_towards_employees": [
    {
      "employee_name": "Shirley Scarry",
      "sentiment": "Positive"
    },
    {
      "employee_name": "Robert Herbford",
      "sentiment": "Negative"
    }
  ]
}

これを、以下の方法で行います

  • 求める出力に向けて、JSONスキーマを指定したツールを定義する
  • Converse API ツール使用リクエストによって生成されたJSONを直接使用する

JSON SchemaによるConverse APIツール定義の解説

まずは、Converse API のツール定義の様々なコンポーネントを一通り確認するところから始めていきましょう。この記事の終わりで、Pythonコードの完全なツール定義を共有しています。

ツール名と説明

まず、toolSpec要素でツール名と説明を定義します。これにより、モデルがツールをどのようなときに呼び出すべきなのか正しく決めることができます。

{
  "toolSpec": {
    "name": "summarize_email",
    "description": "Summarize email content.",

参考：
[Anthropicのツール定義ベストプラクティス集](Best practices for tool definitions)

  • Bedrockのツール定義は若干の違いもあるものの、ここのベストプラクティスは依然として有効です。

JSON生成用スキーマ定義

inputSchemaに、生成したいJSONのスキーマを記述します。

"inputSchema": {
  "json": {
    "type": "object",
    "properties": {

各プロパティの定義例

  • 文字列型プロパティ
  • 真偽値型プロパティ
  • 数値型プロパティ（範囲指定あり）
  • 列挙型プロパティ（enum）
  • 文字列配列
  • オブジェクト配列
  • 必須プロパティ（required）

文字列型プロパティ

"summary": {
    "type": "string",
    "description": "A brief one-line or two-line summary of the email."
},

これにより、以下のような生成が行えます。

"summary": "Customer compliments Acme Investments employee Shirley Scarry for her excellent customer service in resolving account deposit questions, but notes Robert Herbford seemed distracted on the call.",

文字列型タイプに関して、こちらで詳細に確認できます。

真偽値型プロパティ

"escalate_complaint": {
    "type": "boolean",
    "description": "Indicates if this email is serious enough to be immediately escalated for further review."
},

これにより、以下のような生成が行えます。

"escalate_complaint": false,

真偽値型タイプに関して、こちらで詳細に確認できます。

数値型プロパティ（範囲指定あり）

"level_of_concern": {
    "type": "integer",
    "description": "Rate the level of concern for the above content on a scale from 1-10",
    "minimum": 1,
    "maximum": 10
},

"level_of_concern": 2,

数値型タイプと範囲指定に関して、こちらで詳細に確認できます。

列挙型プロパティ（enum）

"overall_sentiment": {
    "type": "string",
    "description": "The sender's overall sentiment.",
    "enum": ["Positive", "Neutral", "Negative"]
},

"supporting_business_unit": {
    "type": "string",
    "description": "The internal business unit that this email should be routed to.",
    "enum": ["Sales", "Operations", "Customer Service", "Fund Management"]
},

これにより、以下のような生成が行えます。

"overall_sentiment": "Positive",
"supporting_business_unit": "Customer Service",

列挙型プロパティ（enum）に関して、こちらで詳細に確認できます。

文字列配列

"customer_names": {
    "type": "array",
    "description": "An array of customer names mentioned in the email.",
    "items": { "type": "string" }
},

これにより、以下のような生成が行えます。

"customer_names": [
    "Carson Bradford",
    "Clara Bradford"
],

文字列配列に関して、こちらで詳細に確認できます。

オブジェクト配列

"sentiment_towards_employees": {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "employee_name": {
                "type": "string",
                "description": "The employee's name."
            },
            "sentiment": {
                "type": "string",
                "description": "The sender's sentiment towards the employee.",
                "enum": ["Positive", "Neutral", "Negative"]
            }
        }
    }
}

これにより、以下のような生成が行えます。

"sentiment_towards_employees": [
    {
        "employee_name": "Shirley Scarry",
        "sentiment": "Positive"
    },
    {
        "employee_name": "Robert Herbford",
        "sentiment": "Negative"
    }
]

オブジェクト配列に関して、こちらで詳細に確認できます。

必須プロパティ

"required": [
    "summary",
    "escalate_complaint",
    "overall_sentiment",
    "supporting_business_unit",
    "level_of_concern",
    "customer_names",
    "sentiment_towards_employees"
]

必須プロパティに関して、こちらで詳細に確認できます。

Pythonコードによる実装例

依存関係の定義とクライアント生成

import boto3, json

session = boto3.Session()
bedrock = session.client(service_name='bedrock-runtime')

summarize_emailツール定義

tool_list = [
    {
        "toolSpec": {
            "name": "summarize_email",
            "description": "Summarize email content.",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "summary": {
                            "type": "string",
                            "description": "A brief one-line or two-line summary of the email."
                        },
                        "escalate_complaint": {
                            "type": "boolean",
                            "description": "Indicates if this email is serious enough to be immediately escalated for further review."
                        },
                        "level_of_concern": {
                            "type": "integer",
                            "description": "Rate the level of concern for the above content on a scale from 1-10",
                            "minimum": 1,
                            "maximum": 10
                        },
                        "overall_sentiment": {
                            "type": "string",
                            "description": "The sender's overall sentiment.",
                            "enum": ["Positive", "Neutral", "Negative"]
                        },
                        "supporting_business_unit": {
                            "type": "string",
                            "description": "The internal business unit that this email should be routed to.",
                            "enum": ["Sales", "Operations", "Customer Service", "Fund Management"]
                        },
                        "customer_names": {
                            "type": "array",
                            "description": "An array of customer names mentioned in the email.",
                            "items": { "type": "string" }
                        },
                        "sentiment_towards_employees": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "employee_name": {
                                        "type": "string",
                                        "description": "The employee's name."
                                    },
                                    "sentiment": {
                                        "type": "string",
                                        "description": "The sender's sentiment towards the employee.",
                                        "enum": ["Positive", "Neutral", "Negative"]
                                    }
                                }
                            }
                        }
                    },
                    "required": [
                        "summary",
                        "escalate_complaint",
                        "overall_sentiment",
                        "supporting_business_unit",
                        "level_of_concern",
                        "customer_names",
                        "sentiment_towards_employees"
                    ]
                }
            }
        }
    }
]

Amazon Bedrockに送信するメッセージの作成

content = """Dear Acme Investments,

I am writing to compliment one of your customer service representatives, Shirley Scarry. I recently had the pleasure of speaking with Shirley regarding my account deposit. Shirley was extremely helpful and knowledgeable, and went above and beyond to ensure that all of my questions were answered. Shirley also had Robert Herbford join the call, who wasn't quite as helpful. My wife, Clara Bradford, didn't like him at all.
Shirley's professionalism and expertise were greatly appreciated, and I would be happy to recommend Acme Investments to others based on my experience.
Sincerely,

Carson Bradford
"""

message = {
    "role": "user",
    "content": [
        { "text": f"<content>{content}</content>" },
        { "text": "Please use the summarize_email tool to generate the email summary JSON based on the content within the <content> tags." }
    ],
}

あくまで、これはEメールをプロンプトに組み込むための一つの方法に過ぎません。特定の利用例に沿って、XMLタグを使用しない方法や、異なるプロンプトを使用することもできます。

必須ツールがあるConverse APIの呼び出し

response = bedrock.converse(
  modelId="anthropic.claude-3-sonnet-20240229-v1:0",
  messages=[message],
  inferenceConfig={
    "maxTokens": 2000,
    "temperature": 0
  },
  toolConfig={
    "tools": tool_list,
    "toolChoice": {
      "tool": {
        "name": "summarize_email"
      }
    }
  }
)

レスポンスからJSONを抽出・表示

response_message = response['output']['message']

response_content_blocks = response_message['content']

content_block = next((block for block in response_content_blocks if 'toolUse' in block), None)

tool_use_block = content_block['toolUse']

tool_result_dict = tool_use_block['input']

print(json.dumps(tool_result_dict, indent=4))

実行結果例

{
  "summary": "顧客がAcme InvestmentsのShirley Scarry氏の優れたカスタマーサービスを称賛し、Robert Herbford氏は通話中に集中していなかったと指摘。",
  "escalate_complaint": false,
  "overall_sentiment": "Positive",
  "supporting_business_unit": "Customer Service",
  "level_of_concern": 2,
  "customer_names": [
    "Carson Bradford",
    "Clara Bradford"
  ],
  "sentiment_towards_employees": [
    {
      "employee_name": "Shirley Scarry",
      "sentiment": "Positive"
    },
    {
      "employee_name": "Robert Herbford",
      "sentiment": "Negative"
    }
  ]
}

まとめ

この記事では、JSON Schemaの定義方法と、非構造化コンテンツからJSONを生成する方法を紹介しました。ぜひ、ご自身のユースケースに合わせたスキーマ設計にもチャレンジしてみてください。

参考リンク

Continue reading articles in this series about tool use / function calling:

記事一覧

AWS Bedrock の converse API の使い方

AWS Bedrock の converse API の使い方

Bedrock Converse API の Tool Use とはなんぞや？

Bedrock Converse API の Tool Use とはなんぞや？

Bedrock Converse API のJSON生成を理解したい

Bedrock Converse API のJSON生成を理解したい

Bedrock で Tool-use を組み込んだエージェントループを作りたい

Bedrock で Tool-use を組み込んだエージェントループを作りたい

Discussion