# 문제 해결
이 섹션에서는 Amazon Nova 모델 작업 시 발생하는 일반적인 문제에 대한 해결 방법을 제공합니다.
## 인증 및 설정
권한 누락
**증상:** Nova 모델이나 기능에 액세스할 수 없음
**해결 방법**:
+ IAM 역할에 AmazonBedrockFullAccess 또는 적절한 권한이 있는지 확인
+ Amazon Bedrock 콘솔을 통해 특정 모델 액세스 요청
+ 모델 액세스 및 도구 사용에 대한 권한 확인
## 모델 액세스 거부됨
**증상:** 모델 액세스 요청 실패
**해결 방법**:
+ Amazon Bedrock 콘솔을 통해 특정 모델 액세스 요청
+ 요청된 모델에 대한 액세스 권한이 계정에 부여되었는지 확인
+ 모델의 리전별 가용성 확인
## 리전별 가용성 문제
**증상:** 선택한 리전에서 기능을 사용할 수 없음
**해결 방법**:
+ 웹 그라운딩은 미국 리전, 미국 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의 책임 있는 AI 정책을 위반했습니다.
해결 방법: 콘텐츠 정책을 준수하도록 입력을 검토하고 수정합니다.
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 스키마를 중첩 계층 2개로 제한
+ 모든 필수 필드가 올바르게 정의되었는지 확인
+ JSON 스키마 사양을 기반으로 스키마 검증
모델이 도구를 올바르게 사용하지 않음
**해결 방법**:
+ 도구 이름에서 목적을 명확하게 설명하는지 확인
+ 도구 기능에 대한 자세한 설명 제공
+ 명확한 파라미터 설명을 통해 명시적으로 입력 스키마 정의
+ 도움이 되는 경우 설명에 예제 포함
일관되지 않은 도구 직접 호출 동작
**해결 방법:** 도구 직접 호출 시 온도를 0으로 설정합니다.
```
inferenceConfig={
"temperature": 0,
"maxTokens": 10000
}
```
그러면 보다 신뢰할 수 있는 도구 사용을 위한 복잡한 디코딩이 가능합니다.
도구 선택 충돌
**문제:** 웹 검색 또는 코드 인터프리터와 함께 사용자 지정 도구를 사용할 때 오류 발생
**해결 방법:** 이름이 `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", ...}
# }]
# }
```
### 웹 그라운딩 문제
액세스 제어 문제
**문제:** 웹 그라운딩 및 코드 인터프리터가 작동하지 않음
**해결 방법:** IAM 정책에 다음이 포함되었는지 확인합니다.
```
{
"Statement": [
{
"Effect": "Allow",
"Action": ["bedrock:InvokeTool"],
"Resource": ["arn:aws:bedrock::{YOUR_ACCOUNT_ID}:system-tool/amazon.nova_grounding"]
}
]
}
```
서비스 제어 정책 문제
**문제:** SCP에 의해 웹 그라운딩이 차단됨
**해결 방법:** `aws:requestedRegion` 조건을 포함하는 서비스 제어 정책이 있는 경우 웹 그라운딩 기능에 대해 'unspecified' 리전을 허용하도록 업데이트합니다.
### 미디어 처리 제한 사항
이미지/비디오에서 다국어 콘텐츠에 대한 이해 부족
**제한 사항:** Nova 모델은 시각적 미디어에서 다국어 콘텐츠에 대한 이해가 제한적임
**해결 방법:**
+ 이미지와 함께 텍스트 번역 제공
+ 가능한 경우 다국어 콘텐츠에 대해 텍스트 기반 입력 사용
사람 식별
**문제:** 모델이 이미지에서 사람 식별을 거부함
**예상 동작:** 모델은 개인 정보 보호 및 안전상의 이유로 이미지, 문서 또는 비디오에서 개인을 식별하거나 이름을 지정하는 작업을 거부함
**해결 방법:** 특정 자격 증명 대신 일반적인 특성이나 컨텍스트에 대해 질문
공간 추론 제한 사항
**문제:** 부정확한 현지화 또는 레이아웃 분석
**제한 사항:** 정확한 공간 추론의 제한된 기능
**해결 방법:**
+ 객체 현지화에 대해 경계 상자 탐지 사용
+ 프롬프트에서 명확한 참조 지점 제공
+ 복잡한 공간 쿼리를 더 단순한 구성 요소로 구분
이미지/비디오의 작은 텍스트
**문제:** 미디어에서 작은 텍스트를 읽을 수 없음
**해결 방법**:
+ 관련 텍스트 섹션에 초점을 맞추도록 이미지 자르기
+ 소스 미디어 해상도 증가
+ 사용 가능한 경우 별도로 텍스트 제공
### 문서 및 파일 처리
지원되지 않는 콘텐츠
**문제:** PDF 처리 실패
**원인:**
+ CMYK 색상 프로필을 포함하는 PDF
+ SVG 이미지를 포함하는 PDF
**해결 방법**:
+ PDF를 RGB 색상 프로필로 변환
+ PDF에 포함하기 전에 SVG 이미지 래스터화
토큰 추정
**문제:** PDF에서 예기치 않은 토큰 사용
**지침:** 표준 8.5×11" PDF 페이지당 약 2,560개의 토큰 추정
**해결 방법:** 문서 길이에 따라 적절히 `maxTokens` 조정