本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 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>
+ **多轉對話：**維護多個交換的內容
+ **系統提示：**系統指示，例如角色或回應準則
+ **文件聊天：**與 互動並查詢文件或文件集合
+ **願景：**處理和分析影像和影片
+ **工具使用：**啟用模型以使用外部工具和 APIs
+ **護欄：**套用內容篩選和安全控制
+ **原因：**擴展思考以解決複雜的問題

基本的 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 透過三個工作層級，提供對推理深度的彈性控制：

低工作量 (`maxReasoningEffort: "low"`)  
最適合：具有額外複雜性且需要結構化思考的任務。例如，您可以將此用於程式碼檢閱和改進建議，其中模型需要仔細考慮現有的程式碼品質、需要考慮多個因素的分析任務，或受益於系統化方法的問題解決案例。低工作量適用於複合任務，其中基本推理可提高準確性，而不需要深入的多步驟規劃。

中等努力 (`maxReasoningEffort: "medium"`)  
最適合：多步驟任務和編碼工作流程。例如，您可以將此用於軟體開發和偵錯，其中模型需要在實作變更之前了解現有的程式碼結構、需要跨多個檔案或元件進行協調的程式碼產生、具有相互依存性的多步驟計算，或規劃具有多個限制的任務。對於協調多個工具的代理程式工作流程而言，中等程度的工作量是最佳的，並且需要模型來維持數個循序操作的內容。

大量努力 (`maxReasoningEffort: "high"`)  
最適合：幹推理和進階問題解決。例如，您可以將此用於需要嚴格step-by-step驗證的進階數學問題和證據、需要深入調查的科學分析和研究任務、具有跨多個維度架構考量的複雜系統設計，或具有重大影響的關鍵決策案例。對於需要複雜推理的任務、仔細評估替代方案，以及徹底驗證結論，高度努力可提供最大的準確性。

下列範例顯示不同的推理工作水準：

------
#### [ 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`：`medium`、 `low`或 `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]`。您仍需支付推理權杖的費用，因為它們有助於改善輸出品質。我們現在在回應結構中包含此欄位，以保留未來公開推理內容的選項。我們積極與客戶合作，以判斷浮現模型推理程序的最佳方法。