04 · Guardrails 테스트 — 기대 동작 정의와 추적 해석
한 문장 요약: 가드레일은 규격 초안(DRAFT)에서 다양한 프롬프트로 반복 테스트한 뒤 버전으로 굳혀 배포하며, 테스트의 핵심은 "위반 횟수"가 아니라 추적(trace)에서 어느 정책(주제·콘텐츠·단어·민감정보)이 어떤 신뢰도로 개입했는지 해석하는 것이다.
- 태스크: T-DOC-04 · 연계 주차: 4주차(보안·거버넌스)
- 원본: docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/guardrails-test.html (2026-11-18 수집·본문 8,283자)
- 원문 사본:
downloads/09-guardrails/guardrails-test.html
개요
가드레일 생성 직후에는 규격 초안(DRAFT)이 사용 가능하고, 만족스러운 구성에 도달할 때까지 편집·테스트를 반복한다. 구성을 마치면 버전(규격 초안의 스냅샷)을 만들고, 버전을 사용해 프로덕션 배포를 간소화한다. 규격 초안이나 새 버전의 변경 사항은 애플리케이션이 새 버전을 명시적으로 사용하지 않는 한 반영되지 않는다 (원문).
핵심 메시지 3
1. 버전이 곧 배포 경계다 — DRAFT에서 아무리 고쳐도 앱은 묵묵부답, 명시적 버전 지정만이 반영된다. (에이전트의 DRAFT·버전·별칭 구조와 동일한 패턴)
2. 추적이 진짜 테스트 결과다 — 가드레일 점검은 위반 횟수만 알려주지만, 추적 보기는 필터를 통과·인식·차단된 주제와 유해 카테고리를 프롬프트/모델 응답 탭으로 나눠 보여준다.
3. PII 처리는 차단 아니면 마스킹이다 — sensitiveInformationPolicy의 action은 BLOCKED 또는 ANONYMIZED(식별자로 대체) 둘 중 하나다.
주제별 심화
테스트 경로 3가지
| 경로 | 방법 |
|---|---|
| 콘솔 테스트 창 | 가드레일 선택 → 규격 초안/버전 선택 → 모델 선택·적용 → 프롬프트 실행 → 가드레일 점검 + 추적 보기 |
| 텍스트 플레이그라운드 | 구성 창에서 플레이그라운드에 가드레일 지정 후 일반 플레이그라운드처럼 테스트 |
| API | InvokeModel/InvokeModelWithResponseStream/Converse + 헤더 X-Amzn-Bedrock-GuardrailIdentifier·X-Amzn-Bedrock-GuardrailVersion (+ X-Amzn-Bedrock-Trace: ENABLED) |
요청·응답 계약
- 본문
amazon-bedrock-guardrailConfig:tagSuffix(입력 태깅용) ·streamProcessingMode(SYNCHRONOUS/ASYNCHRONOUS— 스트리밍 전용) - 오류가 나는 3가지 상황(원문 주의): ① 가드레일 활성화 + 본문에 guardrailConfig 없음 ② 가드레일 비활성화 + guardrailConfig 지정 ③ contentType이 application/json 아님
- Cohere Command 모델은 가드레일 사용 시
num_generations에 세대 1개만 지정 가능 - 응답:
amazon-bedrock-guardrailAction(INTERVENED|NONE) +amazon-bedrock-trace(추적 활성화 시. 스트리밍에서는 마지막 청크에만 반환)
추적(trace) 구조 — 4개 정책군
| 정책군 | 필드 | 판독 포인트 | |
|---|---|---|---|
| topicPolicy | topics[{name, type, action}] | 거부 주제 위반 | |
| contentPolicy | filters[{type, confidence, filterStrength, action}] | 유해 카테고리 + 신뢰도 수준 — filterStrength 설정에 따라 결과가 달라짐 | |
| wordPolicy | customWords[{match, action}] · managedWordLists[{match, type, action}] | 관리형 type 예: PROFANITY(욕설) | |
| sensitiveInformationPolicy | piiEntities[{type, match, action}] · regexes[{name, regex, match, action}] | action = BLOCKED \ | ANONYMIZED |
| invocationMetrics | guardrailProcessingLatency · usage(정책별 유닛 수) · guardrailCoverage(textCharacters guarded/total) | 지연·과금 단위·적용 범위 |
input은 프롬프트 평가, outputs는 모델 응답 평가(같은 구조)다.
적용 체크리스트 (시험·실습 관점)
- ☐ 4주차 계획대로 입력 3종(정상·가짜 개인정보·금지 주제)의 기대 동작을 먼저 적고 테스트 창에서 대조했는가
- ☐ confidence·filterStrength의 관계(강도에 따라 차단 여부 변화)를 설명할 수 있는가 (도메인 3)
- ☐ PII의 두 action(BLOCKED vs ANONYMIZED)을 시나리오에 맞게 고를 수 있는가
- ☐ "DRAFT 변경은 앱에 자동 반영 안 됨"을 기억하는가
- ☐ 오류 3조건(config 불일치·contentType)을 트러블슈팅 답으로 낼 수 있는가
최종 정리
가드레일 테스트의 축은 "막혔나?"가 아니라 "어떤 정책이·어떤 신뢰도로·입력과 출력 각각에서 개입했나"다. 추적의 4정책군 표가 그 독해 도구이며, 버전·DRAFT 구조는 에이전트와 동일한 운영 감각으로 이어진다.
Provenance: 원문 인용·구조는 2026-11-18 수집 본문 기준. 기계 번역 한국어 문서로 원문 영어 우선 고지. 해석·체크리스트는 학습용 편집임.