# 问题排查
本节提供了在使用 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`