翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

以下を使用 Converse API

を使用するには Converse APIでは、 Converse または ConverseStreamオペレーションを呼び出してモデルにメッセージを送信します。Converse を呼び出すには、bedrock:InvokeModel オペレーションを呼び出す許可も必要です。ConverseStream を呼び出すには、bedrock:InvokeModelWithResponseStream オペレーションを呼び出す許可も必要です。

リクエスト

使用するモデルを選択するには、modelId フィールドを設定します。Amazon Bedrock がサポートIDsするモデルのリストについては、「」を参照してくださいAmazon Bedrock でサポートされている基盤モデル。

会話は、ユーザーとモデル間でやり取りされる一連のメッセージです。ユーザー (ユーザーロール) は、メッセージをモデルに送信して会話を開始します。モデルはアシスタント (アシスタントロール) として機能し、メッセージとして返すレスポンスを生成します。必要に応じて、さらにユーザーロールメッセージをモデルに送信することで、会話を続行できます。会話コンテキストを維持するには、モデルから受信したアシスタントロールメッセージを後続のリクエストに必ず含めてください。

messages フィールドのモデルに渡すメッセージを指定します。これは、メッセージオブジェクトの配列にマッピングされます。各メッセージには、メッセージのコンテンツと、会話でメッセージが再生するロールが含まれます。

メッセージのコンテンツは、 ContentBlock オブジェクトの配列にマッピングされる contentフィールドに追加します。各 内でContentBlock、次のいずれかのフィールドを指定できます (どのモデルがどのモダリティをサポートしているかを確認するには、「」を参照してくださいサポートされているモデルとモデルの機能）。

text

text フィールドは、プロンプトを指定する文字列にマッピングされます。text フィールドは、同じ で指定されている他のフィールドと一緒に解釈されますContentBlock。

（オプション) 特定のモデルでは、cachePointフィールドを使用してキャッシュチェックポイントを追加してプロンプトキャッシュを利用できます。プロンプトキャッシュは、会話のコンテキストのキャッシュを開始して、コストとレイテンシーを節約できる機能です。詳細については、「モデル推論を高速化するためのプロンプトキャッシュ」を参照してください。

注記

Amazon Bedrock プロンプトキャッシュは、現在、一部のお客様にのみご利用いただけます。プレビューへの参加の詳細については、「Amazon Bedrock プロンプトキャッシュ」を参照してください。

以下は、テキスト のみを含むcontent配列を持つ Message オブジェクトを示していますContentBlock。

{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        }
    ]
}

以下は、テキストContentBlockとオプションのcachePointフィールドを含むcontent配列を含む Message オブジェクトを示しています。その結果、テキストの内容ContentBlockがキャッシュに追加されます。

{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

image

image フィールドは にマッピングされますImageBlock。base64 でエンコードされた raw バイトを、bytes フィールド内の画像に渡します。を使用する場合 AWS SDK、base64 でバイトをエンコードする必要はありません。

text フィールドを除外すると、モデルはイメージを記述します。

（オプション) 特定のモデルでは、cachePointフィールドを使用してキャッシュチェックポイントを追加してプロンプトキャッシュを利用できます。プロンプトキャッシュは、会話のコンテキストのキャッシュを開始して、コストとレイテンシーを節約できる機能です。詳細については、「モデル推論を高速化するためのプロンプトキャッシュ」を参照してください。

注記

Amazon Bedrock プロンプトキャッシュは、現在、一部のお客様にのみご利用いただけます。プレビューへの参加の詳細については、「Amazon Bedrock プロンプトキャッシュ」を参照してください。

以下は、イメージ のみを含むcontent配列を持つ Message オブジェクトを示していますContentBlock。

{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        }
    ]
}

以下は、イメージContentBlockとオプションのcachePointフィールドを含むcontent配列を含む Message オブジェクトを示しています。その結果、イメージコンテンツがキャッシュに追加されます。

{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

document

document フィールドは にマッピングされますDocumentBlock。DocumentBlock を含める場合は、リクエストが次の制限に準拠していることを確認します。

• メッセージオブジェクトの content フィールドに、ドキュメントに関連するプロンプトを含む text フィールドを含める必要があります。

• base64 でエンコードされた raw バイトを、bytes フィールド内のドキュメントに渡します。を使用する場合 AWS SDK、base64 でドキュメントのバイトをエンコードする必要はありません。

• name フィールドには以下の文字のみ含めることができます。

  • アルファベットの文字

  • 空白文字 (連続した空白文字は使用不可)

  • ハイフン

  • 括弧

  • 角括弧

  注記

  モデルが誤って指示として解釈する可能性があるため、name フィールドはプロンプトインジェクションに対して脆弱です。したがって、中立的な名前を指定することが推奨されます。

（オプション) 特定のモデルでは、cachePointフィールドを使用してキャッシュチェックポイントを追加してプロンプトキャッシュを利用できます。プロンプトキャッシュは、会話のコンテキストのキャッシュを開始して、コストとレイテンシーを節約できる機能です。詳細については、「モデル推論を高速化するためのプロンプトキャッシュ」を参照してください。

注記

Amazon Bedrock プロンプトキャッシュは、現在、一部のお客様にのみご利用いただけます。プレビューへの参加の詳細については、「Amazon Bedrock プロンプトキャッシュ」を参照してください。

以下は、ドキュメント ContentBlock と必須の付随テキスト のみを含むcontent配列を持つ Message オブジェクトを示していますContentBlock。

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        }
    ]
}

以下は、ドキュメントContentBlockと必要な付随するテキスト を含むcontent配列を持つ Message オブジェクトとContentBlock、ドキュメントとテキストの両方の内容をキャッシュcachePointに追加する を示しています。

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

video

video フィールドは にマッピングされますVideoBlock。base64 でエンコードされた bytesフィールドに raw バイトを渡します。を使用する場合 AWS SDK、base64 でバイトをエンコードする必要はありません。

text フィールドを含めない場合、モデルはビデオを記述します。

以下は、動画 のみを含むcontent配列を持つ Message オブジェクトを示していますContentBlock。

{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "bytes": "video in bytes"
                }
            }
        }
    ]
}

.3gp 拡張子が のファイルの場合、形式は として指定する必要がありますthree_gp。

リクエストボディでバイトを直接渡すURI代わりに、Amazon S3 に動画を渡すこともできます。以下は、Amazon S3 を介してビデオソースが渡されたビデオのみを含むコンテンツ配列ContentBlockを持つMessageオブジェクトを示していますURI。

{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "s3Location": {
                        "uri": "s3 uri",
                        "bucketOwner": "s3 uri bucket owner"
                    }
                }
            }
        }
    ]
}

s3Location パラメータは、米国東部 (バージニア北部) リージョンでのみサポートされています。

注記

引き受けたロールには、Amazon S3 に対する アクセスs3:GetObject許可が必要ですURI。bucketOwner フィールドはオプションですが、リクエストを行うアカウントが Amazon S3 が見つかったバケットを所有していない場合URIは指定する必要があります。

ContentBlock の他のフィールドは、ツール用です。

role フィールドで、ロールを指定します。ロールは、以下のいずれかにすることができます。

次の messages 例では、ユーザーはポップの曲を 3 曲含むリストを要求し、モデルは曲のリストを生成します。

[
    {
        "role": "user",
        "content": [
            {
                "text": "Create a list of 3 pop songs."
            }
        ]
    },
    {
        "role": "assistant",
        "content": [
            {
                "text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"As It Was\" by Harry Styles\n2. \"Easy On Me\" by Adele\n3. \"Unholy\" by Sam Smith and Kim Petras"
            }
        ]
    }
]

システムプロンプトは、会話中に実行するタスク、または採用するペルソナに関する指示やコンテキストをモデルに提供するプロンプトの一種です。次の例に示すように、 system (SystemContentBlock) フィールドでリクエストのシステムプロンプトのリストを指定できます。

[
    {
        "text": "You are an app that creates play lists for a radio station that plays rock and pop music. Only return song names and the artist. "
    }
]

オプションで、使用しているモデルに応じて、 systemまたは toolsフィールドにキャッシュチェックポイントを追加してプロンプトキャッシュを使用することもできます。詳細については、「モデル推論を高速化するためのプロンプトキャッシュ」を参照してください。

推論パラメータ

- Converse API は、 inferenceConfigフィールド () で設定した推論パラメータの基本セットをサポートしますInferenceConfiguration。推論パラメータの基本セットは次のとおりです。

詳細については、「推論パラメータでレスポンスの生成に影響を与える」を参照してください。

次の例では、temperature推論パラメータJSONを設定します。

{"temperature": 0.5}

使用しているモデルに追加の推論パラメータがある場合は、 additionalModelRequestFieldsフィールドJSONで として指定することで、それらのパラメータを設定できます。次の例はtop_k、 を設定する方法JSONを示しています。これは で利用できます。Anthropic Claude はモデルですが、メッセージ の基本推論パラメータではありませんAPI。

{"top_k": 200}

次の例に示すように、additionalModelResponseFieldPaths フィールドで追加のモデルパラメータのパスを指定できます。

[ "/stop_sequence" ]

は、 フィールドでリクエストした追加のadditionalModelResponseFieldsフィールドAPIを返します。

レスポンス

から取得したレスポンス Converse API は、呼び出すオペレーション、Converseまたは によって異なりますConverseStream。

会話レスポンス

からのレスポンスではConverse、 outputフィールド (ConverseOutput) に、モデルが生成するメッセージ (メッセージ) が含まれます。メッセージの内容は content (ContentBlock) フィールドにあり、メッセージが対応するロール (user または assistant) は roleフィールドにあります。

プロンプトキャッシュを使用した場合は、使用フィールドで、 cacheReadInputTokensCountと は、キャッシュから読み取られ、キャッシュに書き込まれたトークンの合計数をそれぞれcacheWriteInputTokensCount指定します。

metrics フィールド (ConverseMetrics) には、呼び出しのメトリクスが含まれます。モデルがコンテンツの生成を停止した理由を確認するには、stopReason フィールドを確認します。usage フィールド () を確認することで、リクエストでモデルに渡されたトークンと、レスポンスで生成されたトークンに関する情報を取得できますTokenUsage。リクエストで追加のレスポンスフィールドを指定した場合、 はそれらを additionalModelResponseFieldsフィールドJSONで としてAPI返します。

次の例は、リクエスト で説明されているプロンプトを渡す際の Converse からのレスポンスを示しています。

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"Wannabe\" by Spice Girls\n2. \"Bitter Sweet Symphony\" by The Verve \n3. \"Don't Look Back in Anger\" by Oasis"
                }
            ]
        }
    },
    "stopReason": "end_turn",
    "usage": {
        "inputTokens": 125,
        "outputTokens": 60,
        "totalTokens": 185
    },
    "metrics": {
        "latencyMs": 1175
    }
}

ConverseStream レスポンス

モデルからレスポンスをストリーミングするために ConverseStream を呼び出すと、stream レスポンスフィールドにストリームが返されます。ストリームは、以下の順序で次のイベントを出力します。

ConverseStream は、完全なコンテンツブロックをContentBlockStartEventイベント、1 つ以上のContentBlockDeltaEventイベント、およびContentBlockStopEventイベントとしてストリーミングします。contentBlockIndex フィールドをインデックスとして使用して、コンテンツブロックを構成するイベントを関連付けます。

次の例は、ConverseStream からのレスポンスの一部です。

{'messageStart': {'role': 'assistant'}}
{'contentBlockDelta': {'delta': {'text': ''}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ' Title'}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ':'}, 'contentBlockIndex': 0}}
.
.
.
{'contentBlockDelta': {'delta': {'text': ' The'}, 'contentBlockIndex': 0}}
{'messageStop': {'stopReason': 'max_tokens'}}
{'metadata': {'usage': {'inputTokens': 47, 'outputTokens': 20, 'totalTokens': 67}, 'metrics': {'latencyMs': 100.0}}}