View a markdown version of this page

문제 해결 - Amazon Nova
인증 및 설정모델 액세스 거부됨리전별 가용성 문제제한 시간 구성API 응답 문제추론 모드 오류도구 사용 문제

문제 해결

이 섹션에서는 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 조정