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

# 疑難排解
<a name="troubleshooting"></a>

本節提供使用 Amazon Nova 模型時常見問題的解決方案。

## 身分驗證和設定
<a name="authentication-setup"></a>

缺少許可  
**徵狀：**無法存取 Nova 模型或功能  
**解決方案**：  
+ 確保您的 IAM 角色具有 AmazonBedrockFullAccess 或適當的許可
+ 透過 Amazon Bedrock 主控台請求特定模型存取
+ 驗證模型存取和工具使用的許可

## 拒絕模型存取
<a name="model-access-denied"></a>

**徵狀：**模型存取請求失敗  
**解決方案**：  
+ 透過 Amazon Bedrock 主控台請求特定模型存取
+ 確認您的帳戶已獲授權存取請求的模型
+ 檢查模型的區域可用性

## 區域可用性問題
<a name="regional-availability-issues"></a>

**徵狀：**所選區域不提供此功能  
**解決方案**：  
+ Web Grounding 僅適用於具有美國 CRIS 設定檔的美國區域
+ 確認模型和功能在您選取的區域中可用
+ 視需要切換到支援的區域

## 逾時組態
<a name="timeout-configuration"></a>

**症狀：**請求在完成之前逾時  
**原因：**對於複雜操作，預設逾時太短  
**解決方案：**設定延長逾時設定  

```
from botocore.config import Config

bedrock = boto3.client(
    'bedrock-runtime',
    region_name='us-east-1',
    config=Config(
        read_timeout=3600      # 60 minutes
    )
)
```
Amazon Nova 推論請求最多可能需要 60 分鐘才能執行複雜的操作。

## API 回應問題
<a name="api-response-issues"></a>

了解停止原因：

end\_turn  
正常完成。不需採取任何動作。

max\_tokens  
已達到字符限制。  
**解決方案**：增加 中的`maxTokens`參數`inferenceConfig`。

content\_filtered  
內容違反了 AWS 負責任的 AI 政策。  
解決方案：檢閱和修改您的輸入，以符合內容政策。

格式錯誤\_model\_output  
無效的輸出格式。  
解決方案：檢查您的輸出結構描述和限制條件；確認 JSON 結構描述格式正確。

格式錯誤\_tool\_use  
無效的工具呼叫格式。  
解決方案：確認工具定義符合預期的結構描述；檢查工具輸入參數的格式是否正確。

service\_unavailable  
無法使用內建工具服務。  
解決方案：短暫延遲後重試請求；檢查 AWS 服務運作狀態儀表板。

invalid\_query  
對內建工具的查詢無效。  
解決方案：檢閱查詢格式和參數；確保查詢符合工具需求。

max\_tool\_invocations  
工具重試已用盡。  
解決方案：簡化任務或將其分成較小的步驟；檢閱工具錯誤訊息是否有特定問題。

## 原因模式錯誤
<a name="reasoning-mode-errors"></a>

以高推理力截斷的回應  
**解決方案：**對於高推理工作，請取消設定這些參數：`temperature`、`topP`、`maxToken`。這可讓模型針對複雜的推理任務使用最佳設定。

權杖不足以推理  
**錯誤：**「maxTokens 不足」  
**解決方案：**以更高的限制自動重試  

```
token_limits = {
    "low": 15000,
    "medium": 30000,
    "high": 50000
}

try:
    response = client.converse(
        modelId="us.amazon.nova-2-lite-v1:0",
        messages=messages,
        inferenceConfig={
            "maxTokens": token_limits[max_effort]
        },
        additionalModelRequestFields={
            "reasoningConfig": {
                "type": "enabled",
                "maxReasoningEffort": max_effort
            }
        }
    )
except Exception as e:
    if "maxTokens is insufficient" in str(e):
        higher_limit = int(token_limits[max_effort] * 1.5)
        # Retry with higher limit
```

## 工具使用問題
<a name="tool-use-issues"></a>

### 結構描述驗證失敗
<a name="schema-validation-failures"></a>

工具結構描述驗證錯誤  
**解決方案**：  
+ 將 JSON 結構描述限制為兩層巢狀，以獲得最佳效能
+ 確定所有必要欄位都已正確定義
+ 根據 JSON 結構描述規格驗證結構描述

模型未正確使用工具  
**解決方案**：  
+ 確保工具名稱清楚描述其用途
+ 提供工具功能的詳細說明
+ 使用明確的參數描述明確定義輸入結構描述
+ 當有幫助時，在描述中包含範例

不一致的工具呼叫行為  
**解決方案：**將工具呼叫的溫度設定為 0：  

```
inferenceConfig={
    "temperature": 0,
    "maxTokens": 10000
}
```
這可啟用貪婪解碼，以更可靠地使用工具。

工具選擇衝突  
**問題：**搭配 Web 搜尋或程式碼解譯器使用自訂工具時發生錯誤  
**解決方案：**請勿包含名稱為 的自訂 toolSpec `nova_grounding` - 這與系統工具衝突。請改用系統工具組態：  

```
# Correct - use system tool
tool_config = {
    "tools": [{
        "systemTool": {"name": "nova_grounding"}
    }]
}

# Incorrect - don't create custom tool with this name
# tool_config = {
#     "tools": [{
#         "toolSpec": {"name": "nova_grounding", ...}
#     }]
# }
```

### Web Grounding 問題
<a name="web-grounding-issues"></a>

存取控制問題  
**問題：**Web Grounding 和 Code Interpreter 無法運作  
**解決方案：**確保您的 IAM 政策包含：  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeTool"],
      "Resource": ["arn:aws:bedrock::{YOUR_ACCOUNT_ID}:system-tool/amazon.nova_grounding"]
    }
  ]
}
```

服務控制政策問題  
**問題：**SCP 封鎖 Web Grounding  
**解決方案：**如果您有具有 `aws:requestedRegion`條件的服務控制政策，請更新它們以允許 Web Grounding 功能的「未指定」區域。

### 媒體處理限制
<a name="media-processing-limitations"></a>

對影像/影片中多語言內容的理解不佳  
**限制：**Nova 模型對視覺化媒體中的多語言內容的理解有限  
**解決方法：**  
+ 提供文字翻譯與影像
+ 盡可能使用多語言內容的文字型輸入

人員識別  
**問題：**模型拒絕識別影像中的人物  
**預期行為：**基於隱私權和安全考量，模型會拒絕在影像、文件或影片中識別或命名個人  
**解決方法：**詢問一般特性或內容，而非特定身分

空間推理限制  
**問題：**當地語系化或配置分析不準確  
**限制：**精確空間推理的有限功能  
**解決方法：**  
+ 使用週框方塊偵測進行物件當地語系化
+ 在提示中提供明確的參考點
+ 將複雜的空間查詢分解為更簡單的元件

影像/影片中的小型文字  
**問題：**無法讀取媒體中的小文字  
**解決方案**：  
+ 裁剪影像以專注於相關文字區段
+ 提高來源媒體的解析度
+ 如果可用，請分別提供文字

### 文件和檔案處理
<a name="document-file-handling"></a>

不支援的內容  
**問題：**PDF 處理失敗  
**原因：**  
+ 具有 CMYK 顏色描述PDFs 
+ 包含 SVG 影像PDFs 
**解決方案**：  
+ 將 PDFs轉換為 RGB 顏色設定檔
+ 在 PDFs 中包含 之前，先光柵化 SVG 映像

權杖估算  
**問題：**使用 PDFs 的非預期字符用量  
**指導方針：**每個標準 8.5×11" PDF 頁面估計約 2，560 個字符  
**解決方案：**根據文件長度`maxTokens`相應地調整