# Converse API の使用
<a name="using-converse-api"></a>

Converse API は、Amazon Nova モデルとやり取りするための統合インターフェイスを提供します。モデル固有の詳細を抽象化し、すべての Amazon Nova モデルでマルチターン会話、システムプロンプト、ストリーミングレスポンスを一貫した方法で処理できます。

**Topics**
+ [リクエスト構造](#converse-api-request-structure)
+ [システムプロンプトの使用](#converse-api-system-prompt)
+ [推論パラメータ](#converse-api-inference-params)
+ [推論の使用](#converse-api-reasoning)

## リクエスト構造
<a name="converse-api-request-structure"></a>
+ **マルチターン会話:** 複数の交換のコンテキストを維持します
+ **システムプロンプト:** ペルソナやレスポンスガイドラインなどのシステム指示
+ **ドキュメントチャット:** ドキュメントまたはドキュメントのコレクションを操作してクエリします
+ **ビジョン:** 画像と動画を処理および分析します
+ **ツールの使用:** モデルが外部ツールと API を使用できるようにします
+ **ガードレール:** コンテンツフィルタリングと安全コントロールを適用します
+ **推論:** 複雑な問題解決のための拡張思考

基本的な Converse API リクエストには、モデル ID とメッセージのリストが含まれます。

```
import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'What is machine learning?'}]
        }
    ]
)

content_list = response["output"]["message"]["content"]
# Extract the first text block
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)
```

## システムプロンプトの使用
<a name="converse-api-system-prompt"></a>

システムプロンプトは、モデルに指示またはコンテキストを提供します。

```
import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    system=[
        {'text': 'You are a helpful AI assistant specializing in cloud computing.'}
    ],
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'Explain serverless computing.'}]
        }
    ]
)

# Print the response text
content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)
```

## 推論パラメータ
<a name="converse-api-inference-params"></a>

推論パラメータを使用してモデルの出力を制御します。以下は利用できる推論パラメータです。
+  maxTokens (整数): 生成するトークンの最大数 (最大 65,000)。指定しない場合、モデルはリクエストコンテキストに基づいて動的デフォルトを使用します。
+  温度 (浮動): ランダム性 (0.0～1.0、デフォルト 0.7) を制御します。値を小さくすると、出力がより決定的になります 
+  topP (浮動): Nucleus サンプリングしきい値 (0～1、デフォルト 0.9)。値が低いほど、出力の焦点が絞られます 
+  stopSequences (配列): 発生時に生成を停止する文字のシーケンス 

 例: 

```
import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'Write a short story.'}]
        }
    ],
    inferenceConfig={
        'maxTokens': 512,
        'temperature': 0.7,
        'topP': 0.9,
        'stopSequences': ['END']
    }
)

content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)
```

## 推論の使用
<a name="converse-api-reasoning"></a>

Nova 2 Lite は、複雑な問題解決のための拡張思考をサポートしています。`reasoningConfig` で推論を有効にします。

デフォルトでは、推論は単純なクエリの速度とコストを最適化するために無効になっています。これらの単純なタスクを超える必要がある場合は、推論を有効にできます。Nova 2 では、次の 3 つの労力レベルを通じて推論深度を柔軟に制御できます。

低労力 (`maxReasoningEffort: "low"`)  
最適な用途: 構造化された思考を必要とする複雑なタスク。例えば、モデルが既存のコード品質を慎重に検討する必要があるコードレビューや改善の提案、複数の要因を慎重に検討する必要がある分析タスク、または体系的なアプローチから恩恵を受ける問題解決シナリオに使用できます。低労力は、基本的な推論が詳細なマルチステップ計画を必要とせずに精度を向上させる複合タスクに最適です。

中程度の労力 (`maxReasoningEffort: "medium"`)  
最適な用途: マルチステップタスクとコーディングワークフロー。例えば、変更を実装する前にモデルが既存のコード構造を理解する必要があるソフトウェア開発とデバッグ、複数のファイルまたはコンポーネント間の調整を必要とするコード生成、相互依存関係による複数ステップの計算、または複数の制約を伴うタスクの計画に使用できます。中程度の労力は、複数のツールを調整し、モデルが複数のシーケンシャルオペレーションにわたってコンテキストを維持する必要があるエージェントワークフローに最適です。

高労力 (`maxReasoningEffort: "high"`)  
最適な用途: STEM の推論と高度な問題解決。例えば、これを厳格な段階的検証を必要とする高度な数学的な問題や証明、科学分析、詳細な調査を必要とする研究タスク、複数のディメンションにわたるアーキテクチャ上の考慮事項を含む複雑なシステム設計、重大な影響を伴う重要な意思決定シナリオに使用できます。高労力は、高度な推論、代替案の慎重な評価、結論の徹底的な検証を必要とするタスクに最大限の精度をもたらします。

次の例は、さまざまな推論の労力レベルを示しています。

------
#### [ Low effort ]

```
import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    system=[{"text": "You are a highly capable personal assistant"}],
    messages=[{
        "role": "user",
        "content": [{"text": "Provide a meal plan for a gluten free family of 4."}]
    }],
    inferenceConfig={
        "temperature": 0.7,
        "topP": 0.9,
        "maxTokens": 10000
    },
    additionalModelRequestFields={
        "reasoningConfig": {
            "type": "enabled",
            "maxReasoningEffort": "low"
        }
    }
)
```

------

 **推論パラメータ:** 

 以下は推論パラメータです 
+ `type`: `enabled` または `disabled` (デフォルト: `disabled`)
+ `maxReasoningEffort`: `low`、`medium` または `high`。推論が有効な場合は必須です。

**注記**  
温度、topP、topK は、`maxReasoningEffort` を `high` に設定して使用することはできません。エラーが発生します。

レスポンスには推論コンテンツが含まれます。

```
{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "reasoningContent": {
                        "reasoningText": {
                            "text": "[REDACTED]"
                        }
                    }
                },
                {
                    "text": "Based on the premises, we can conclude..."
                }
            ]
        }
    },
    "stopReason": "end_turn"
}
```

**注記**  
Amazon Nova 2 では、推論コンテンツは `[REDACTED]` として表示されます。推論トークンは出力品質の向上に寄与するため、引き続き課金されます。今後推論コンテンツを公開するオプションを保持するために、このフィールドをレスポンス構造に含めるようになりました。当社は、お客様と積極的に連携して、モデルの推論プロセスを表面化するための最善のアプローチを決定しています。