Skip to content

문제 해결

English | 한국어

관찰한 증상에서 시작하세요. 같은 클라이언트 정책과 합성 입력으로 재현하고, Inspector의 로컬 구성과 비교합니다. 운영 로그에 원문이나 불투명 토큰 매핑을 남기지 마세요.

모델 입력에 원문이 남음

  1. 선택한 분석기가 해당 값을 탐지하는지 확인합니다. 로컬 규칙은 rules.enabled, presets, include, exclude와 지원 형식을 확인합니다. 엔티티 허용 목록과 점수 임계값도 확인하세요. 탐지가 빠졌다면 규칙 선택을 수정하거나 적합한 분석기를 선택합니다.
  2. privacy()를 선택한 정책과 guardrailsChatClientFactory.builder(chatModel, policy)로 만든 클라이언트를 호출하는지 확인합니다. 다른 ChatClient나 ChatModel 직접 호출은 해당 정책을 거치지 않습니다.
  3. 모델 입력 프로브로 요청을 반복합니다. 모델이 받은 프롬프트에서 탐지된 원문이 없어야 합니다. 모델이 생성한 답변만으로 보호 여부를 판단하지 마세요.

메모리·RAG 저장소에는 원문이 남을 수 있습니다. 보호 대상은 모델에 전달하는 복사본입니다. 앱의 책임 범위는 저장 데이터를 참고하세요.

등록한 규칙이 실행되지 않음

  1. Boot 자동 규칙 구성을 사용한다면 spring.ai.privacy.rules.enabled를 켜고 presets나 include로 등록된 ID를 선택합니다. PiiRule·PiiRulePreset 빈 등록만으로 활성화되지는 않습니다. COMMON도 명시적으로 선택해야 하며 분석 언어가 KR을 자동 선택하지 않습니다.
  2. 프리셋과 추가 ID 뒤에 적용되는 exclude를 확인합니다. RuleBasedPiiAnalyzer 빈을 직접 선언했다면 해당 빈의 카탈로그와 선택이 자동 구성을 대체합니다. 프로퍼티가 이 빈을 수정한다고 가정하지 말고 빈 자체를 구성하세요.
  3. 분석기의 ruleIds()·presetNames()를 확인하고 일치하는 합성 입력을 다시 실행합니다. 프리셋 선택을 참고하세요. addRule·addRules는 등록이며, 분석기 빌더의 presets·include·exclude가 실행 규칙을 선택합니다.

규칙 설정 후 시작 실패

  1. 설정 오류를 읽고 대소문자를 구분하는 프리셋 이름과 규칙 ID를 확인합니다. 알 수 없는 ID, 중복 정의, 빈 활성 규칙 목록은 오류입니다. exclude도 등록된 ID가 필요합니다. 내장 ID·이름과 같은 사용자 정의 규칙이나 프리셋을 등록하지 마세요.
  2. rules.enabled=true만 설정했다면 규칙이나 프리셋을 하나 이상 선택합니다. 제외 설정이 모든 규칙을 제거했는지도 확인합니다. 보호를 끄기보다 잘못된 선택을 수정하세요.
  3. 앱을 재시작하고 ruleIds()와 일치하는 입력을 확인합니다. 프로퍼티 철자는 설정 진단을 참고하세요.

도구가 원문 대신 토큰을 받음

  1. 원문 공개가 의도된 도구인지 먼저 확인합니다. 보호된 도구에는 기본적으로 토큰을 전달합니다.
  2. 정책의 도구 이름을 최종 ToolDefinition.name()과 비교합니다. 대소문자와 MCP 제공자의 접두사도 일치해야 합니다. ToolDisclosurePolicy가 토큰의 최종 엔티티 유형을 허용하는지 확인합니다.
  3. 합성 입력으로 도구 호출을 반복하고 도구 입력과 보호된 결과를 확인합니다. 허용된 유형만 복원되어야 합니다. 원문 공개 규칙을 참고하세요.

도구가 목록에 없거나 실행이 거부됨

  1. 모델 목록에 도구가 없다면 정의 단계의 인가 결과를 확인합니다. 일반적인 필터링은 거부 예외를 던지지 않습니다.
  2. 실행 거절은 예외의 code·phase, 등록된 도구 이름과 요청 시작 시 인증 정보를 확인합니다. 해당 권한이나 인증 정보 전달을 수정합니다. 거부 사유와 비동기 인증 정보를 참고하세요.
  3. 허용·비허용 사용자의 요청을 비교합니다. 모델에는 허용된 도구만 보이고 비허용 도구는 실행되지 않아야 합니다. Security 데모에서 두 경우를 재현할 수 있습니다.

스트리밍 응답이 마지막에 한꺼번에 옴

  1. 개인정보 출력 보호와 finalOutputInspectionEnabled를 확인합니다. 응답 조각에 나뉜 내용까지 검사하려고 전체 응답을 모으므로 이 지연은 정상 동작입니다.
  2. 즉시 전달이 필요하면 앱에 필요한 출력 검사를 먼저 판단한 뒤 정책을 변경합니다. 검사를 끄면 해당 보호도 사라집니다. 버퍼링하는 출력 보호를 유지한다면 응답 한도와 타임아웃을 설정하세요.
  3. 선택한 정책으로 다시 실행하고 전달 시점과 전달된 내용을 함께 확인합니다. 출력 보호와 검사 한도를 참고하세요.

검사기를 등록했는데 검사가 실행되지 않음

  1. 클라이언트 정책에서 inspection()을 선택했고 해당 클라이언트로 요청하는지 확인합니다. 최종 출력 검사는 별도로 켜야 합니다. 켠 방향에 검사기 빈에서 구성되거나 직접 제공한 InspectionService가 있는지도 확인하세요.
  2. 앞선 개인정보 처리나 인가 실패로 검사에 도달하지 못했는지, 검사기의 사전 조건에서 실패했는지 확인합니다. 보고된 단계와 실패 코드는 결과와 실패를 참고하세요.
  3. 검사기가 차단하도록 구성한 입력과 허용할 입력으로 각각 요청해 검사 보고서를 확인합니다.

ONNX 초기화 또는 실행 실패

  1. CONFIGURATION이면 모델·호환 토크나이저 파일, 필요한 외부 가중치 파일, 입력 이름·타입·형식과 출력 클래스 설정을 확인합니다. 앱의 작업 디렉터리를 기준으로 경로를 확인하세요. 모델 요구 사항을 참고하세요.
  2. MODEL_ERROR이면 출력 형식·수치가 logitCount와 활성화 설정에 맞는지 확인합니다.
  3. 고정 테스트 모델 준비를 실행해 알려진 모델과 비교합니다.