View a markdown version of this page

问题排查 - Amazon Nova
身份验证和设置访问模型被拒区域可用性问题超时配置API 响应问题推理模式错误工具使用问题

问题排查

本节提供了在使用 Amazon Nova 模型时遇到的常见问题的解决方案。

身份验证和设置

缺少权限

症状：无法访问 Nova 模型或功能

解决方案：

  • 确保 IAM 角色具有 AmazonBedrockFullAccess 或相应的权限

  • 通过 Amazon Bedrock 控制台请求特定的模型访问权限

  • 验证模型访问权限和工具使用权限

访问模型被拒

症状：模型访问请求失败

解决方案：

  • 通过 Amazon Bedrock 控制台请求特定的模型访问权限

  • 验证是否已向账户授予对所请求模型的访问权限

  • 检查模型的区域可用性

区域可用性问题

症状：所选区域中功能不可用

解决方案：

  • Web Grounding 功能仅在使用美国 CRIS 配置文件的美国区域可用

  • 验证所选区域中模型和功能是否可用

  • 如有必要，切换到受支持的区域

超时配置

症状：请求未完成即超时

原因：默认超时时间过短，无法满足复杂操作

解决方案：配置更长的超时设置

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 响应问题

终止原因说明：

end_turn

正常完成。无需任何操作。

max_tokens

已达到词元限制。

解决方案：在 inferenceConfig 中增加 maxTokens 参数值。

content_filtered

内容违反 AWS 负责任的人工智能政策。

解决方案：检查并修改输入内容，使其符合内容政策。

malformed_model_output

输出格式无效。

解决方案：检查输出架构和约束条件；确认 JSON 架构格式正确无误。

malformed_tool_use

工具调用格式无效。

解决方案：确认工具定义符合预期架构；检查工具输入参数格式是否正确。

service_unavailable

内置工具服务不可用。

解决方案：稍候重试请求；查看 AWS 服务运行状况控制面板。

invalid_query

对内置工具的查询无效。

解决方案：检查查询格式和参数；确保查询符合工具要求。

max_tool_invocations

工具重试次数已用尽。

解决方案：简化任务或将其拆分为更小步骤；查看工具错误信息以定位具体问题。

推理模式错误

推理强度过高导致响应被截断

解决方案：进行高强度推理时，请取消以下参数设置：temperature、topP、maxToken。这允许模型为复杂的推理任务使用最佳设置。

推理所需词元不足

错误：maxTokens is insufficient

解决方案：提高上限后自动重试

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

工具使用问题

模式验证失败

工具架构验证错误

解决方案：

  • 为获得最佳性能，将 JSON 架构限制为两层嵌套

  • 确保所有必填字段均已正确定义

  • 根据 JSON 架构规范验证架构

模型未正确使用工具

解决方案：

  • 确保工具名称清晰描述其用途

  • 详细说明工具功能

  • 明确定义输入架构并清晰描述参数

  • 必要时在描述中附上示例

工具调用行为不一致

解决方案：将工具调用的温度值设为 0：

inferenceConfig={
    "temperature": 0,
    "maxTokens": 10000
}

这将启用贪婪解码，提升工具使用的可靠性。

工具选择冲突

问题：将自定义工具与 Web 搜索或代码解释器结合使用时出错

解决方案：切勿创建名称为 nova_grounding 的自定义 toolSpec，该名称会与系统工具冲突。请改用系统工具配置：

# 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 问题

访问控制问题

问题：Web Grounding 和代码解释器无法正常工作

解决方案：确保 IAM 策略包含以下内容：

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeTool"],
      "Resource": ["arn:aws:bedrock::{YOUR_ACCOUNT_ID}:system-tool/amazon.nova_grounding"]
    }
  ]
}
服务控制策略问题

问题：Web Grounding 被 SCP 阻止

解决方案：若服务控制策略中配置了 aws:requestedRegion 条件，请更新策略，为 Web Grounding 功能允许“未指定”区域。

媒体处理限制

对图像/视频中多语言内容理解不佳

限制：Nova 模型对视觉媒体中的多语言内容理解能力有限

解决办法：

  • 在提供图像的同时附上文本翻译

  • 尽可能使用基于文本的输入来处理多语言内容

人物识别

问题：模型拒绝识别图像中的人物

预期行为：出于隐私与安全考虑，模型会拒绝识别或标注图像、文档或视频中的个人身份

解决办法：询问整体特征或场景信息而非具体身份

空间推理限制

问题：定位或布局分析结果不准确

局限：精确空间推理能力有限

解决办法：

  • 使用边界框检测进行物体定位

  • 在提示中提供清晰的参考点

  • 将复杂的空间查询拆分为更简单的部分

图像/视频中的小字

问题：无法读取媒体中的小字

解决方案：

  • 裁剪图像，聚焦相关文字区域

  • 提高源媒体分辨率

  • 如有文字，请单独提供

文档与文件处理

不支持的内容

问题：PDF 处理失败

原因：

  • 使用 CMYK 颜色配置文件的 PDF

  • 包含 SVG 图像的 PDF

解决方案：

  • 将 PDF 转换为 RGB 颜色配置文件

  • 在置入 PDF 前先将 SVG 图像栅格化

词元估算

问题：PDF 产生预期外的词元消耗

参考标准：标准 8.5x11 英寸 PDF 页面，每页约按 2560 个词元估算

解决方案：根据文档长度相应调整 maxTokens