기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Bedrock Guardrails에서 자동 추론 검사란 무엇입니까?
## 자동 추론 검사의 기능
대규모 언어 모델(LLM)의 주요 과제는 응답의 정확성을 보장하는 것입니다. 검증이 없으면 LLMs 신뢰를 약화시키는 할루시네이션 또는 부정확한 정보를 생성할 수 있습니다. Amazon Bedrock Guardrails의 자동 추론 검사는 수학적 기법을 사용하여 자연어 콘텐츠를 정의한 정책과 비교하여 검증함으로써이 문제를 해결하는 데 도움이 됩니다.
패턴 일치를 기반으로 콘텐츠를 차단하거나 필터링하는 기존 가드레일 구성 요소와 달리 자동 추론 검사는 공식 로직을 사용하여 응답이 올바르거나 잘못된 *이유*에 대한 구조화된 피드백을 제공합니다. 이 피드백은 정책과 거의 일치하는 콘텐츠를 생성하기 위해 LLM을 유도하는 데 사용할 수 있습니다. 특히 자동 추론 검사는 다음을 수행할 수 있습니다.
+ 생성된 콘텐츠가 정책 규칙과 모순된다는 것을 수학적으로 증명하여 LLM 응답에서 **사실적으로 충돌하는 문을 탐지**합니다.
+ 응답이 정책과 일치하지만 모든 관련 규칙을 다루지 않아 응답이 불완전할 수 있는 경우 **설명되지 않은 가정을 강조** 표시합니다.
+ 결론을 지원하는 특정 정책 규칙 및 변수 할당을 참조하여 정확한 문이 올바른 이유에 대해 **수학적으로 검증 가능한 설명을 제공합니다**.
이러한 기능을 사용하면 자동 추론 검사가 다른 Amazon Bedrock Guardrails 구성 요소와 다릅니다. 콘텐츠 필터 및 주제 정책은 콘텐츠를 차단하거나 허용하는 바이너리 게이트 역할을 합니다. 자동 추론 검사는 프로그래밍 방식으로 응답을 개선하는 데 사용할 수 있는 상세하고 실행 가능한 피드백을 제공하는 확인 계층 역할을 합니다.
## 자동 추론 검사를 사용해야 하는 경우
자동화된 추론 검사는 LLM의 응답에 대한 사실적 근거를 입증해야 할 때 가장 유용합니다. 애플리케이션에 다음이 포함된 경우 이를 사용하는 것이 좋습니다.
+ 잘못된 정보가 법률 또는 규정 준수 결과를 초래할 수 있는 의료, 인사 및 금융 서비스와 같은 **규제 대상 산업**.
+ 모기지 승인, 영역법, 보험 자격 또는 직원 혜택과 같은 **복잡한 규칙 세트**로, 여러 조건이 상호 작용하여 결과를 결정합니다.
+ 응답이 정책과 일치한다는 수학적으로 확인 가능한 증거가 포함된 감사 가능한 AI 응답이 필요한 **규정 준수 시나리오**입니다.
+ 회사 정책, 제품 자격 또는 서비스 조건에 대한 질문에 답변하는 챗봇과 같이 잘못된 지침이 신뢰를 약화시킬 수 있는 **고객 대면 애플리케이션**입니다.
## 자동 추론 검사에서 수행하지 않는 작업
올바른 기대치를 설정하려면 다음 제한 사항에 유의하세요.
+ **프롬프트 주입 보호가 없습니다.** 자동 추론 검사는 전송하는 내용을 정확하게 검증합니다. 악의적이거나 조작된 콘텐츠가 입력으로 제공되는 경우 해당 콘텐츠에 대해 있는 그대로 검증이 수행됩니다. 프롬프트 인젝션 공격을 탐지하고 차단하려면 [콘텐츠 필터](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-components.html#guardrails-content-filters)를 자동 추론 검사와 함께 사용합니다.
+ **비주제 감지가 없습니다.** 자동 추론은 정책과 관련된 텍스트만 분석합니다. 관련 없는 콘텐츠를 무시하고 응답이 비주제인지 여부를 알 수 없습니다. 비주제 응답을 감지하려면 [주제 정책을](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-components.html#guardrails-topic-policies) 사용합니다.
+ **스트리밍은 지원되지 않습니다.** 자동 추론 검사는 스트리밍 APIs 지원하지 않습니다. 전체 응답을 검증해야 합니다.
+ **영어 전용.** 자동 추론 검사는 현재 영어(미국)만 지원합니다.
+ **범위가 정책으로 제한됩니다.** `VALID` 결과는 정책 변수를 통해 캡처된 입력 부분에 대해서만 유효성을 보장합니다. 정책의 변수 범위를 벗어나는 문은 검증되지 않습니다. 예를 들어 "가짜 의사 메모가 있어 숙제를 늦게 제출할 수 있습니다"는 정책에 의사 메모가 가짜인지 여부를 캡처할 변수가 없는 경우 유효한 것으로 간주될 수 있습니다.
자동 추론 검사는 콘텐츠 필터 및 주제 정책과 같은 다른 Amazon Bedrock Guardrails 기능을 보완합니다. 최상의 보호를 위해 함께 사용하세요. 자세한 내용은 [핵심 구성 요소](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-components.html)를 참조하세요.
## End-to-end 워크플로 개요
자동 추론 검사 사용에는 정책 생성, 테스트, 가드레일에 배포, 애플리케이션에 통합이라는 네 단계가 포함됩니다.
```
Source Document ──► Extracted Policy ──► Testing ──► Deployment ──► Integration
(rules) (formal logic) (verify) (guardrail) (validate responses
and act on feedback)
```
1. **정책을 생성합니다.** 적용하려는 규칙이 포함된 소스 문서를 업로드합니다. 자동 추론은 문서에서 공식 로직 규칙과 변수 스키마를 추출합니다. 각 규칙과 변수를 소스 콘텐츠의 특정 문에 다시 연결하는 적용 범위 및 정확도 점수와 자세한 근거와 함께 추출된 정책이 소스 문서를 얼마나 정확하게 나타내는지 측정하는 충실도 보고서가 자동으로 생성됩니다. 추출된 정책 및 충실도 보고서를 검토하여 정책이 규칙을 올바르게 캡처하는지 확인합니다. 자세한 내용은 [자동 추론 정책 생성](create-automated-reasoning-policy.md) 단원을 참조하십시오.
1. **테스트 및 구체화.** 테스트를 통해 정책 자체를 변경하는 동안에도 정책이 생성된 콘텐츠를 정확하게 검증할 수 있습니다. 사용자가 묻는 질문과 LLM이 생성할 수 있는 응답을 모방하는 테스트를 생성합니다. 자동 추론 검사는 기본 모델을 사용하여 자연어를 로직으로 변환합니다. 생성된 시나리오를 사용하여 규칙 정확성을 검증하고 QnA 테스트를 사용하여 논리 번역 정확도에 대한 자연어를 검증합니다. 테스트 결과를 기반으로 정책을 구체화합니다. 자세한 내용은 [자동 추론 정책 테스트](test-automated-reasoning-policy.md) 단원을 참조하십시오.
1. **배포.** 테스트된 정책의 변경 불가능한 버전을 저장하고 가드레일에 연결합니다. CloudFormation 또는 CI/CD 파이프라인을 사용하여 배포를 자동화할 수 있습니다. 자세한 내용은 [애플리케이션에 자동 추론 정책 배포](deploy-automated-reasoning-policy.md) 단원을 참조하십시오.
1. **를 통합합니다.** 런타임 시 자동 추론 조사 결과는 Amazon Bedrock Guardrails 구성 `Converse`, `InvokeModel`, `InvokeAgent`및 독립 실행형 APIs를 지원하는 `ApplyGuardrail` API`RetrieveAndGenerate`를 통해 반환됩니다. 조사 결과를 검사하여 응답을 제공할지, 피드백을 사용하여 다시 작성할지 또는 사용자에게 설명을 요청합니다. 자동 추론 검사는 *감지 모드에서*만 작동하며 콘텐츠를 차단하는 대신 조사 결과와 피드백을 반환합니다. 애플리케이션에 자동 추론 검사를 통합하는 방법에 대한 자세한 내용은 섹션을 참조하세요[애플리케이션에 자동 추론 검사 통합](integrate-automated-reasoning-checks.md). 자동 추론 검사를 활성화하는 데 필요한 권한에 대한 자세한 내용은 섹션을 참조하세요[ApplyGuardrail을 통한 자동 추론 정책에 대한 권한](guardrail-automated-reasoning-permissions.md).
## 가용성 및 언어 지원
Amazon Bedrock Guardrails의 자동 추론 검사는 일반적으로 다음 리전에서 사용할 수 있습니다.
+ 미국 동부(버지니아 북부)
+ 미국 서부(오레곤)
+ 미국 동부(오하이오)
+ EU(프랑크푸르트)
+ EU(파리)
+ EU(아일랜드)
자동 추론 검사는 현재 영어(미국)만 지원합니다.
## 제한 사항 및 고려 사항
자동 추론 검사를 구현하기 전에 다음과 같은 기술적 제한 사항에 유의하세요.
+ **문서 복잡성.** 소스 문서는 명확하고 모호하지 않은 규칙으로 잘 구성되어야 합니다. 중첩 조건 또는 모순되는 설명이 있는 매우 복잡한 문서는 공식 로직으로 명확하게 추출되지 않을 수 있습니다. 입력 문서의 크기는 5MB, 문자 수는 50,000자로 제한됩니다. 더 큰 문서를 분할하고 각 섹션을 정책에 병합할 수 있습니다. 문서의 이미지와 테이블도 입력 문자 수에 영향을 미칩니다.
+ **처리 시간.** 자동 추론 검사 검증은 애플리케이션 응답에 지연 시간을 추가합니다. 특히 변수가 많은 복잡한 정책의 경우 추가 처리 시간을 계획합니다. 정책의 변수 수는 검증 지연 시간 증가에 직접 기여합니다.
+ **정책 범위.** 유지 관리가 더 쉬운 정책을 생성하려면 각 정책은 단일 정책에서 여러 관련 없는 영역을 다루려고 하지 않고 특정 도메인(예: HR, 재무, 법률)에 집중해야 합니다.
+ **변수 및 규칙 제한.** 변수 수가 많거나 규칙 상호 작용이 지나치게 복잡한 정책은 처리 한도에 도달하거나 TOO\$1COMPLEX 결과를 반환할 수 있습니다. [Amazon Bedrock 제한 설명서](https://docs.aws.amazon.com/hgeneral/latest/gr/bedrock.html#limits_bedrock) 및 섹션을 참조하세요[검증 결과 참조](automated-reasoning-checks-concepts.md#ar-concept-validation-results).
+ **자연어 종속성.** 검증의 정확도는 사용자 프롬프트 및 모델 응답의 자연어를 정책의 공식 로직 변수로 변환할 수 있는 정도에 따라 달라집니다. 자동 추론 검사는 기본 모델을 사용하여 자연어를 로직 표현으로 변환합니다. 변수 설명은이 번역의 품질에 영향을 미칩니다.
+ **비선형 산술.** 제약 조건에 비선형 산술(예: 비합리적 숫자 또는 지수)을 사용한 추론이 포함된 경우 자동 추론 검사가 시간 초과되거나 TOO\$1COMPLEX를 반환할 수 있습니다.
## 가격 책정
Amazon Bedrock Guardrails의 자동 추론 검사는 처리된 검증 요청 수에 따라 요금이 부과됩니다. 현재 요금 정보는 [Amazon Bedrock 요금 페이지](https://aws.amazon.com/bedrock/pricing/)를 참조하세요.
결과(예: VALID, INVALID, TRANSLATION\$1AMBIGUOUS)에 관계없이 각 검증 요청에 대해 요금이 발생합니다. 비용 최적화:
+ 적절한 신뢰도 임계값을 사용하여 정확도와 처리 요구 사항의 균형을 맞춥니다.
+ 사용 사례에 적합한 경우 동일하거나 유사한 쿼리에 대한 캐싱 검증 결과를 고려합니다.
+ 사용량 패턴을 모니터링하고 정책을 조정하여 불필요한 검증 요청을 줄입니다.
## 정책 작업에 대한 교차 리전 추론
자동 추론은 교차 리전 추론을 활용하여 정책 생성 및 테스트 작업의 성능과 가용성을 최적화합니다. 특정 API 작업은 안정적인 서비스 제공을 보장하기 위해 지리적 경계 내의 AWS 리전 간에 처리를 자동으로 분산합니다.
다음 자동 추론 API 작업은 교차 리전 추론을 사용합니다.
+ `StartAutomatedReasoningPolicyBuildWorkflow` - 소스 문서에서 정책 생성 및 컴파일 중에 호출됩니다.
+ `StartAutomatedReasoningPolicyTestWorkflow` - 정책 검증 및 테스트 절차 중에 호출됩니다.
이러한 작업은 대규모 언어 모델을 간접적으로 호출하여 소스 문서에서 공식 로직 규칙을 추출하고 자연어 구문을 구조화된 논리적 표현으로 변환합니다. 최적의 성능과 가용성을 보장하기 위해 요청 처리는 다음 지리적 라우팅에 따라 배포됩니다.
+ **미국 리전:** 미국 동부(버지니아 북부), 미국 서부(오리건) 또는 미국 동부(오하이오)에서 시작된 API 요청은 지원되는 모든 미국 리전에서 처리될 수 있습니다.
+ **유럽 연합 리전:** EU(프랑크푸르트), EU(파리) 또는 EU(아일랜드)에서 시작된 API 요청은 지원되는 모든 EU 리전에서 처리될 수 있습니다.
**중요**
고객 데이터는 원래의 지리적 경계 내(미국 또는 유럽 연합)에 유지되며 AWS 데이터 레지던시 약정에 따라 처리됩니다. 교차 리전 추론은 성능 및 서비스 가용성을 최적화하기 위해 동일한 지리적 리전 내에서만 요청을 라우팅합니다.
교차 리전 추론은 고객이 구성할 필요가 없으며 투명하게 작동합니다. API 기능은 요청을 처리하는 특정 리전에 관계없이 일관성을 유지합니다.
**Topics**
+ [자동 추론 검사의 기능](#automated-reasoning-what-it-does)
+ [자동 추론 검사를 사용해야 하는 경우](#automated-reasoning-when-to-use)
+ [자동 추론 검사에서 수행하지 않는 작업](#automated-reasoning-what-it-doesnt-do)
+ [End-to-end 워크플로 개요](#automated-reasoning-workflow-overview)
+ [가용성 및 언어 지원](#automated-reasoning-availability)
+ [제한 사항 및 고려 사항](#automated-reasoning-limitations)
+ [가격 책정](#automated-reasoning-pricing)
+ [정책 작업에 대한 교차 리전 추론](#automated-reasoning-cross-region-inference)
+ [자동 추론 검사 개념](automated-reasoning-checks-concepts.md)
+ [자동 추론 정책 생성](create-automated-reasoning-policy.md)
+ [자동 추론 정책 모범 사례](automated-reasoning-policy-best-practices.md)
+ [자동 추론 정책 테스트](test-automated-reasoning-policy.md)
+ [자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md)
+ [자동 추론 정책과 함께 Kiro CLI 사용](kiro-cli-automated-reasoning-policy.md)
+ [애플리케이션에 자동 추론 정책 배포](deploy-automated-reasoning-policy.md)
+ [애플리케이션에 자동 추론 검사 통합](integrate-automated-reasoning-checks.md)
# 자동 추론 검사 개념
이 페이지에서는 자동 추론 검사의 구성 요소를 설명합니다. 이러한 개념을 이해하면 효과적인 정책을 생성하고, 테스트 결과를 해석하고, 문제를 디버깅하는 데 도움이 됩니다. 자동 추론 검사가 수행하는 작업과 이를 사용하는 시기에 대한 개략적인 개요는 섹션을 참조하세요[규칙](#ar-concept-rules).
## 정책
자동 추론 *정책은* 공식 로직 규칙 세트, 변수 스키마 및 선택적 사용자 지정 유형을 포함하는 AWS 계정의 리소스입니다. 이 정책은 LLM 응답을 검증하려는 비즈니스 규칙, 규정 또는 지침을 인코딩합니다.
정책은 자연어로 규칙을 설명하는 HR 핸드북, 규정 준수 매뉴얼 또는 제품 사양과 같은 소스 문서에서 생성됩니다. 정책을 생성하면 자동 추론 검사는 문서에서 규칙과 변수를 추출하여 수학적으로 확인할 수 있는 공식 로직으로 변환합니다.
정책, 가드레일과 애플리케이션 간의 관계는 다음과 같습니다.
```
Source Document ──► Automated Reasoning Policy ──► Guardrail ──► Your Application
(natural (rules + variables + (references (calls guardrail
language) custom types) a policy APIs to validate
version) LLM responses)
```
정책의 주요 특성:
+ 각 정책은 Amazon 리소스 이름(ARN)으로 식별되며 특정 AWS 리전에 존재합니다.
+ 정책에는 개발 중에 편집하는 `DRAFT` 버전(콘솔에서 "초안 작성"이라고 함)과 배포를 위해 생성한 번호가 매겨진 변경 불가능한 버전이 있습니다.
+ 가드레일은 초안 정책 또는 번호가 지정된 특정 버전을 참조할 수 있습니다. 번호가 매겨진 버전을 사용하면 배포된 가드레일에 영향을 주지 `DRAFT` 않고를 업데이트할 수 있습니다.
+ 각 정책은 관련 없는 여러 영역을 다루려고 하지 않고 특정 도메인(예: HR 혜택, 대출 자격, 제품 반환 규칙)에 초점을 맞춰야 합니다.
정책 생성에 대한 step-by-step 지침은 섹션을 참조하세요[자동 추론 정책 생성](create-automated-reasoning-policy.md).
## Fidelity 보고서
*충실도 보고서는* 추출된 정책이 생성된 소스 문서를 얼마나 정확하게 나타내는지 측정합니다. 보고서는 소스 문서에서 정책을 생성할 때 자동으로 생성되며, 모든 규칙 및 변수를 소스 콘텐츠의 특정 문에 다시 연결하는 자세한 근거 정보와 함께 두 가지 주요 점수를 제공합니다.
충실도 보고서는 비기술 주제 전문가가 공식 로직을 이해할 필요 없이 정책을 탐색하고 검증할 수 있도록 설계되었습니다. 콘솔의 **소스 문서** 탭에는 충실도 보고서가 문서에서 추출된 번호가 매겨진 원자성 문 테이블로 표시되며, 각 문이 근거하는 규칙과 변수를 보여줍니다. 특정 규칙 또는 변수를 기준으로 필터링하고 문 내에서 콘텐츠를 검색할 수 있습니다.
충실도 보고서에는 각각 0.0\$11.0 범위의 두 가지 점수가 포함됩니다.
+ **적용 범위 점수** - 정책이 소스 문서의 문을 얼마나 잘 포함하는지 나타냅니다. 점수가 높을수록 정책에 더 많은 소스 콘텐츠가 표시됩니다.
+ **정확도 점수** - 정책 규칙이 소스 구성 요소를 얼마나 충실하게 나타내는지 나타냅니다. 점수가 높을수록 추출된 규칙이 원본 문서의 의도와 더 가깝게 일치함을 의미합니다.
충실도 보고서는 집계 점수 외에도 정책의 각 규칙 및 변수에 대한 자세한 근거를 제공합니다.
+ **규칙 보고서** - 각 규칙에 대해 보고서는 이를 지원하는 소스 문서에서 특정 문(접지 문)을 식별하고, 해당 문이 규칙을 정당화하는 방법(접지 정당화)을 설명하고, 개별 정확도 점수에 정당화를 제공합니다.
+ **변수 보고서** - 각 변수에 대해 보고서는 변수 정의를 지원하는 소스 문을 식별하고, 정당화를 설명하고, 개별 정확도 점수를 제공합니다.
+ **문서 소스** - 소스 문서는 텍스트에서 추출된 개별적이고 보이지 않는 사실인 원자성 문으로 구분됩니다. 각 규칙과 변수를 원본 문서의 정확한 위치로 다시 추적할 수 있도록 문서 콘텐츠에 행 번호가 주석으로 달립니다.
## 규칙
규칙은 자동 추론 정책의 핵심입니다. 각 규칙은 변수 간의 관계를 캡처하는 공식 로직 표현식입니다. 규칙은 자동 추론 검사가 수학적 검증에 사용하는 공식 로직의 표준 형식인 [SMT-LIB](https://smtlib.cs.uiowa.edu/) 구문의 하위 집합을 사용하여 표현됩니다. [자동 추론 정책에 대한 KMS 권한](create-automated-reasoning-policy.md#automated-reasoning-policy-kms-permissions) 섹션을 참조하세요
대부분의 규칙은 *if-then*(가시적) 형식을 따라야 합니다. 즉, 규칙에 암시 연산자에 의해 연결된 조건("if" 부분)과 결론("then" 부분)이 있어야 합니다`=>`.
**올바른 형식의 규칙(if-then 형식):**
```
;; If the employee is full-time AND has worked for more than 12 months,
;; then they are eligible for parental leave.
(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)
;; If the loan amount is greater than 500,000, then a co-signer is required.
(=> (> loanAmount 500000) requiresCosigner)
```
**베어 어설션( if-then 구조가 없는 규칙)은 항상 true인 문인 axiom을 생성합니다.** 이는 양수 값이 있는 계정 밸런스와 같은 경계 조건을 확인하는 데 유용하지만 특정 조건을 논리적으로 불가능하게 만들고 검증 중에 예상치 못한 `IMPOSSIBLE` 결과를 초래할 수도 있습니다. 예를 들어, 베어 어설션은 자동 추론 검사가 이를 사용자가 상위 휴가 자격이 있는 것으로 취급한다는 것을 `(= eligibleForParentalLeave true)` 의미합니다. 자격이 없다고 언급하는 모든 입력은이 어시옴과 모순`IMPOSSIBLE`되므로의 검증 결과를 생성합니다.
```
;; GOOD: Useful to check impossible conditions such as
;; negative account balance
(>= accountBalance 0)
;; BAD: This asserts eligibility as always true, regardless of conditions.
eligibleForParentalLeave
```
규칙은 다음 로직 연산자를 지원합니다.
| 연산자 | 의미 | 예제 |
| --- | --- | --- |
| => | 암시(if-then) | (=> isFullTime eligibleForBenefits) |
| and | Logical AND | (and isFullTime (> tenure 12)) |
| or | Logical OR | (or isVeteran isTeacher) |
| not | 논리적 NOT | (not isTerminated) |
| = | Equality | (= employmentType FULL\$1TIME) |
| >, <, >=, <= | 비교 | (>= creditScore 700) |
효과적인 규칙 작성에 대한 모범 사례는 섹션을 참조하세요[자동 추론 정책 모범 사례](automated-reasoning-policy-best-practices.md).
## 변수
변수는 자동 추론 검사가 자연어를 공식 로직으로 변환하고 규칙을 평가하는 데 사용하는 도메인의 개념을 나타냅니다. 각 변수에는 이름, 유형 및 설명이 있습니다.
자동 추론 검사는 다음 변수 유형을 지원합니다.
| Type | 설명 | 예제 |
| --- | --- | --- |
| bool | true 또는 false 값 | isFullTime - 직원이 정규직으로 근무하고 있는지 여부 |
| int | 정수 | tenureMonths - 직원이 근무한 개월 수 |
| real | 십진수 | interestRate - 10진수 형태의 연간 이자율(0.05는 5%를 의미함) |
| 사용자 지정 유형( 열거형) | 정의된 집합의 값 1개 | leaveType — PARENTAL, MEDICAL, BEREAVEMENT, PERSONAL 중 하나 |
### 변수 설명의 중요한 역할
변수 설명은 번역 정확도에서 가장 중요한 단일 요소입니다. 자동 추론 검사는 자연어를 공식 로직으로 변환할 때 변수 설명을 사용하여 텍스트에 언급된 개념에 해당하는 변수를 결정합니다. 모호하거나 불완전한 설명은 `TRANSLATION_AMBIGUOUS` 결과 또는 잘못된 변수 할당으로 이어집니다.
**예: 설명이 번역에 미치는 영향**
사용자가 다음과 같이 질문한다고 가정해 보겠습니다. "여기에서 2년 동안 일했습니다. 육아 휴가 자격이 있나요?"
| 모호한 설명(실패할 가능성 있음) | 세부 설명(성공할 가능성이 높음) |
| --- | --- |
| tenureMonths: "직원의 근무 기간" | tenureMonths: "직원이 지속적으로 고용된 전체 개월 수입니다. 사용자가 서비스 연도를 언급하면 월로 변환합니다(예: 2년 = 24개월). 신규 채용의 경우 0으로 설정합니다.” |
모호한 설명에서 자동 추론 검사는 "2년"을 24개월로 변환할지 모르거나 변수를 전혀 할당하지 않을 수 있습니다. 자세한 설명과 함께 번역은 모호하지 않습니다.
좋은 변수 설명은 다음과 같아야 합니다.
+ 변수가 일반 언어로 무엇을 나타내는지 설명합니다.
+ 단위와 형식을 지정합니다(예: "월", "십진수로, 0.15는 15%를 의미함").
+ 사용자가 사용할 수 있는 비명확한 동의어와 대체 표현을 포함합니다(예: 사용자가 '정규' 또는 '정규 근무'라고 언급하면 ' true로 설정').
+ 경계 조건을 설명합니다(예: "신규 채용의 경우 0으로 설정").
## 사용자 지정 유형( 열거형)
사용자 지정 유형은 변수가 취할 수 있는 명명된 값 집합을 정의합니다. 프로그래밍 언어의 열거형( 열거형)과 동일합니다. 변수가 고정된 값 집합이 있는 범주를 나타내는 경우 사용자 지정 유형을 사용합니다.
**예**:
| 이름 입력 | 가능한 값 | 사용 사례: |
| --- | --- | --- |
| LeaveType | 부모, 의료, 사별, 개인 | 직원이 요청하는 휴가 유형 분류 |
| Severity | CRITICAL, MAJOR, MINOR | 문제 또는 인시던트의 심각도 분류 |
**열거형과 부울을 사용하는 경우:**
+ 값이 *상호 배타적인* 경우 열거형을 사용합니다. 변수는 한 번에 하나의 값일 수 있습니다. 예를 들어는 PARENTAL 또는 MEDICAL일 `leaveType` 수 있지만 둘 다 동시에 사용할 수는 없습니다.
+ 상태가 *공존*할 수 있는 경우 별도의 부울 변수를 사용합니다. 예를 들어, 사람은 재향 군인이자 교사일 수 있습니다. 열거형을 사용하면 두 열거형 간에 선택이 강제로 적용`customerType = {VETERAN, TEACHER}`되어 둘 다 적용될 때 논리적 모순이 발생합니다. 대신 `isVeteran` 및 라는 두 개의 부울을 사용합니다`isTeacher`.
**작은 정보**
변수에 열거형의 값이 없을 수 있는 경우 `OTHER` 또는 `NONE` 값을 포함합니다. 이렇게 하면 입력이 정의된 값과 일치하지 않을 때 번역 문제가 방지됩니다.
## 번역: 자연어에서 공식 로직으로
번역은 자동 추론 검사가 자연어(사용자 질문 및 LLM 응답)를 정책 규칙에 따라 수학적으로 확인할 수 있는 공식 로직 표현식으로 변환하는 프로세스입니다. 이 프로세스를 이해하는 것은 문제를 디버깅하고 효과적인 정책을 만드는 데 중요합니다.
자동 추론 검사는 다음 두 단계로 콘텐츠를 검증합니다.
1. **번역** - 자동 추론 검사는 파운데이션 모델(LLMs)을 사용하여 자연어 입력을 공식 로직으로 변환합니다. 이 단계에서는 텍스트의 개념을 정책의 변수에 매핑하고 관계를 논리적 문으로 표현합니다. 이 단계에서는 LLMs 사용하기 때문에 *오류가 있을* 수 있습니다. 자동 추론 검사는 여러 LLMs 사용하여 입력 텍스트를 변환한 다음 중복 번역의 의미상 동등성을 사용하여 신뢰도 점수를 설정합니다. 번역 품질은 변수 설명이 입력에 사용된 언어와 얼마나 잘 일치하는지에 따라 달라집니다.
1. **검증** - 자동 추론 검사는 수학적 기법(SMT 솔버를 통해)을 사용하여 변환된 로직이 정책 규칙과 일치하는지 확인합니다. 이 단계는 *수학적으로 적*당합니다. 번역이 올바르면 검증 결과가 일관됩니다.
**중요**
이 2단계 구분은 디버깅에 매우 중요합니다. 정책의 규칙이 올바른지 확신하는 경우 테스트가 실패하거나 예기치 않은 결과를 반환하면 2단계(검증)가 아닌 1단계(번역)에서 문제가 발생할 가능성이 큽니다. 수학 검증은 적당하며 번역이 입력의 의미를 올바르게 캡처하면 검증 결과가 정확합니다. 변수 설명을 개선하고 번역이 올바른 변수에 올바른 값을 할당하도록 하는 데 디버깅 노력을 집중합니다.
**예: 작업 중 번역**
변수`isFullTime`(bool), (int), `tenureMonths` (`eligibleForParentalLeave`bool) 및 입력이 포함된 정책이 주어짐:
+ **질문:** "저는 정규직 직원이며 18개월 동안 근무했습니다. 육아 휴가를 사용할 수 있나요?"
+ **답변:** "예, 육아 휴가 자격이 있습니다."
1단계(번역)는 다음을 생성합니다.
```
Premises: isFullTime = true, tenureMonths = 18
Claims: eligibleForParentalLeave = true
```
2단계(검증)는 이러한 할당을 정책 규칙`(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)`과 비교하여 확인하고 클레임이 인지 확인합니다`VALID`.
번역 정확도를 높이려면:
+ 사용자가 일상적인 언어로 개념을 참조하는 방법을 다루는 자세한 변수 설명을 작성합니다.
+ 번역을 혼동시킬 수 있는 중복 또는 거의 중복된 변수를 제거합니다(예: `tenureMonths` 및 `monthsOfService`).
+ 규칙에서 참조하지 않는 미사용 변수를 삭제합니다. 그러면 변환 프로세스에 노이즈가 추가됩니다.
+ question-and-answer 테스트를 사용하여 실제 사용자 입력으로 번역 정확도를 검증합니다. 자세한 내용은 [자동 추론 정책 테스트](test-automated-reasoning-policy.md) 단원을 참조하십시오.
## 결과 및 검증 결과
자동 추론 검사가 콘텐츠를 검증하면 *결과* 집합이 생성됩니다. 각 결과는 검증 결과, 사용된 변수 할당 및 결론을 지원하는 정책 규칙과 함께 입력에서 추출된 사실적 클레임을 나타냅니다. 전체(집계된) 결과는 심각도에 따라 결과를 정렬하고 최악의 결과를 선택하여 결정됩니다. 최악의 심각도부터 최상의 심각도 순서는 `TRANSLATION_AMBIGUOUS`, `IMPOSSIBLE`, `INVALID`, `SATISFIABLE`, 입니다`VALID`.
### 조사 결과의 구조
결과 유형에 따라 결과에 존재하는 필드가 결정됩니다. 각 결과 유형에 대한 자세한 설명은 [검증 결과 참조](#ar-concept-validation-results) 섹션을 참조하세요. 그러나 대부분의 결과 유형은 다음 구성 요소가 포함된 공통 `translation` 객체를 공유합니다.
`premises`
클레임 평가 방법에 영향을 미치는 입력에서 추출된 컨텍스트, 가정 또는 조건입니다. 질의응답 형식에서 전제는 질문 자체인 경우가 많습니다. 답변에는 제약 조건을 설정하는 온프레미스도 포함될 수 있습니다. 예를 들어 "I'm a full-time employee with 18 months of service"에서 온프레미스는 `isFullTime = true` 및 입니다`tenureMonths = 18`.
`claims`
자동 추론 검사가 정확도를 평가하는 사실적 문입니다. 질의응답 형식에서 주장은 보통 답변입니다. 예를 들어 "예, 육아 휴가 자격이 있습니다"에서 클레임은 입니다`eligibleForParentalLeave = true`.
`confidence`
특정 자동 추론 검사가 자연어에서 공식 로직으로의 번역에 대한 것인지를 나타내는 0.0에서 1.0까지의 점수입니다. 점수가 높을수록 확실성이 높음을 나타냅니다. 신뢰도 1.0은 동일한 해석에 합의된 모든 번역 모델을 의미합니다.
`untranslatedPremises`
온프레미스에 해당하지만 공식 로직으로 변환할 수 없는 원본 입력 텍스트의 일부에 대한 참조입니다. 이는 자동 추론이 관련성이 있다고 인식했지만 정책 변수에 매핑할 수 없는 입력 부분을 강조 표시합니다.
`untranslatedClaims`
클레임에 해당하지만 공식 로직으로 변환할 수 없는 원본 입력 텍스트의 일부에 대한 참조입니다. `VALID` 결과는 번역된 클레임만 다루며 번역되지 않은 클레임은 검증되지 않습니다.
### 검증 결과 참조
각 결과는 정확히 다음 유형 중 하나입니다. 유형에 따라 결과의 의미, 결과에서 사용할 수 있는 필드, 애플리케이션에 대한 권장 작업이 결정됩니다. `translation` 필드를 포함하는 모든 결과 유형에는 변환에 정책 규칙과 무관한 논리적 문제(예: 항상 true 또는 항상 false인 문)가 포함된 경우 존재하는 `logicWarning` 필드도 포함됩니다.
| 결과 | 결과 필드 | 권장 조치 |
| --- | --- | --- |
| VALID | `translation` - 번역된 온프레미스, 클레임, 신뢰도 점수 및 번역되지 않은 참조입니다. `supportingRules` - 클레임이 정확함을 증명하는 정책 규칙입니다. 각 규칙에는 식별자와 정책 버전 ARN이 포함됩니다. `claimsTrueScenario` - 클레임이 논리적으로 어떻게 적용되는지 보여주는 시나리오(변수 할당 세트)입니다. | 사용자에게 응답을 제공합니다. 감사 claimsTrueScenario 목적의 로그 supportingRules 및 - 수학적으로 검증 가능한 유효성 증명을 제공합니다. 검증되지 않은 입력 부분이 untranslatedClaims 있는지 untranslatedPremises 및를 확인합니다. |
| INVALID | `translation` - 번역된 온프레미스, 클레임, 신뢰도 점수 및 번역되지 않은 참조입니다. `contradictingRules` - 클레임이 위반하는 정책 규칙입니다. 각 규칙에는 식별자와 정책 버전 ARN이 포함됩니다. | 응답을 제공하지 마십시오. translation (요청된 내용을 보려면) 및 contradictingRules (위반된 규칙을 보려면)를 사용하여 응답을 다시 작성하거나 차단합니다. 재작성 루프에서 모순되는 규칙과 잘못된 클레임을 LLM에 전달하여 수정된 응답을 생성합니다. |
| SATISFIABLE | `translation` - 번역된 온프레미스, 클레임, 신뢰도 점수 및 번역되지 않은 참조입니다. `claimsTrueScenario` - 클레임이 논리적으로 어떻게 사실일 수 있는지 보여주는 시나리오입니다. `claimsFalseScenario` - 다양한 조건에서 클레임이 논리적으로 거짓일 수 있는 방법을 보여주는 시나리오입니다. | claimsTrueScenario 및 claimsFalseScenario를 비교하여 누락된 조건을 식별합니다. 응답을 다시 작성하여를 만드는 데 필요한 추가 정보를 포함하거나VALID, 누락된 조건에 대한 설명을 사용자에게 요청하거나, 불완전할 수 있다는 경고와 함께 응답을 제공합니다. |
| IMPOSSIBLE | `translation` - 번역된 온프레미스, 클레임, 신뢰도 점수 및 번역되지 않은 참조입니다. 온프레미스를 검사하여 모순을 식별합니다. `contradictingRules` - 온프레미스 또는 서로 충돌하는 정책 규칙입니다. 채워지면 정책 자체에 모순이 있을 수 있습니다. | 입력에 모순되는 문이 포함되어 있는지 확인합니다(예: "I'm full-time and also part-time"). 입력이 유효하면 정책에 모순이 있을 수 있습니다. 품질 보고서를 contradictingRules 확인하고 검토합니다. [자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md)을(를) 참조하세요. |
| TRANSLATION\$1AMBIGUOUS | `translation` 객체를 포함하지 않습니다. 대신는 다음을 제공합니다. `options` - 경쟁 논리 해석(최대 2개). 각 옵션에는 온프레미스, 클레임 및 신뢰도`translations`가 포함된 자체 옵션이 포함되어 있습니다. 옵션을 비교하여 모델이 동의하지 않는 부분을 확인합니다. `differenceScenarios` - 모호성의 실제 영향을 강조하는 변수 할당과 함께 다양한 해석의 의미를 보여주는 시나리오(최대 2개)입니다. | 를 검사options하여 불일치를 이해합니다. 모호성을 줄이거나, 겹치는 변수를 병합 또는 제거하거나, 사용자에게 설명을 요청하도록 변수 설명을 개선합니다. 신뢰도 임계값을 조정할 수도 있습니다. 단원을 참조하십시오[신뢰도 임계값](#ar-concept-confidence-thresholds). |
| TOO\$1COMPLEX | `translation`, 규칙 또는 시나리오를 포함하지 않습니다. 볼륨 또는 복잡성으로 인해 입력이 처리 용량을 초과했습니다. | 입력을 더 작은 조각으로 나누어 단축하거나 변수 수를 줄여 정책을 단순화하고 복잡한 산술(예: 지수 또는 비합리적 숫자)을 방지합니다. 정책을 더 작고 집중적인 정책으로 분할할 수 있습니다. |
| NO\$1TRANSLATIONS | `translation`, 규칙 또는 시나리오를 포함하지 않습니다. 입력의 일부만 번역할 수 있는 경우 다른 결과와 함께 표시될 수 있습니다. | 다른 NO\$1TRANSLATIONS 결과 중 하나에 번역되지 않은 온프레미스 또는 클레임이 포함될 때마다 결과가 출력에 포함됩니다. 다른 조사 결과를 살펴보고 변환되지 않은 입력 부분을 확인합니다. 콘텐츠가 관련성이 있어야 하는 경우 정책에 변수를 추가하여 누락된 개념을 캡처합니다. 콘텐츠가 주제가 아닌 경우 주제 정책을 사용하여 자동 추론 검사에 도달하기 전에 필터링하는 것이 좋습니다. |
**참고**
`VALID` 결과는 변환된 온프레미스 및 클레임의 정책 변수를 통해 캡처된 입력 부분만 포함합니다. 정책의 변수 범위를 벗어나는 문은 검증되지 않습니다. 예를 들어 "가짜 의사 메모가 있어 숙제를 늦게 제출할 수 있습니다"는 정책에 의사 메모가 가짜인지 여부를 캡처할 변수가 없는 경우 유효한 것으로 간주될 수 있습니다. 자동 추론 확인에는 결과에 번역되지 않은 전제로서 "가짜 의사 메모"가 포함될 수 있습니다. 번역되지 않은 콘텐츠와 `NO_TRANSLATIONS` 조사 결과를 경고 신호로 취급합니다.
## 신뢰도 임계값
자동 추론 검사는 여러 파운데이션 모델을 사용하여 자연어를 공식 로직으로 변환합니다. 각 모델은 자체 번역을 독립적으로 생성합니다. *신뢰도 점수는* 이러한 번역 간의 일치 수준, 특히 의미상 동등한 해석을 생성한 모델의 비율을 나타냅니다.
*신뢰도 임계값*은 변환이 검증하기에 충분히 신뢰할 수 있는 것으로 간주되는 데 필요한 최소 계약 수준을 결정하는 설정한 값(0.0\$11.0)입니다. 적용 범위와 정확도 간의 균형을 제어합니다.
+ **높은 임계값**(예: 0.9): 번역 모델 간에 강력한 동의가 필요합니다. 더 적은 조사 결과를 생성하지만 정확도는 더 높습니다. 더 많은 입력은 로 플래그가 지정됩니다`TRANSLATION_AMBIGUOUS`.
+ **하한 임계값**(예: 0.5): 덜 일치하는 번역을 수락합니다. 더 많은 결과를 생성하지만 잘못된 번역의 위험이 더 높습니다. 더 적은 입력이 로 플래그 지정됩니다`TRANSLATION_AMBIGUOUS`.
**임계값 작동 방식:**
1. 여러 파운데이션 모델은 각각 입력을 독립적으로 변환합니다.
1. 임계값과 같거나 높은 비율의 모델이 지원하는 번역은 최종 결과(`VALID`, `INVALID`등)가 있는 신뢰도가 높은 결과가 됩니다.
1. 하나 이상의 번역이 임계값 아래로 떨어지면 자동 추론 검사에서 추가 `TRANSLATION_AMBIGUOUS` 조사 결과가 표시됩니다. 이 결과에는 변수 설명을 개선하거나 사용자에게 설명을 요청하는 데 사용할 수 있는 모델 간의 불일치에 대한 세부 정보가 포함됩니다.
**작은 정보**
기본 임계값으로 시작하고 테스트 결과에 따라 조정합니다. 명확해야 하는 입력에 대한 `TRANSLATION_AMBIGUOUS` 결과가 너무 많으면 임계값을 낮추지 말고 변수 설명을 개선하는 데 집중하세요. 임계값을 낮추면 `TRANSLATION_AMBIGUOUS` 결과가 줄어들 수 있지만 잘못된 검증의 위험이 증가합니다.
# 자동 추론 정책 생성
자동 추론 정책을 생성하면 소스 문서가 공식 로직 규칙 세트와 변수 및 유형의 스키마로 변환됩니다. 이 페이지에서는 문서 준비, 정책 생성 및 결과 검토를 안내합니다.
Amazon Bedrock은 AWS Key Management Service(KMS)를 사용하여 자동 추론 정책을 암호화합니다. 기본적으로 Amazon Bedrock은 서비스 소유 키를 사용합니다. 선택적으로 정책 데이터의 암호화를 추가로 제어하기 위해 고객 관리형 KMS 키를 지정할 수 있습니다.
자동 추론 정책을 테스트하고 사용하려면 [적절한 권한이](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrail-automated-reasoning-permissions.html) 있는지 확인합니다.
## 소스 문서 준비
콘솔을 열거나 API를 호출하기 전에 자동 추론이 규칙 및 변수를 추출하는 데 사용할 문서를 준비합니다. 정책의 품질은이 입력의 품질에 따라 달라집니다.
### 문서 구조 및 명확성
자동 추론 검사는 명확하고 모호하지 않은 규칙이 포함된 문서에 가장 적합합니다. 각 규칙은 조건과 결과를 명시해야 합니다. 문서에 없는 외부 컨텍스트에 의존하는 모호한 언어, 주관적 기준 또는 규칙을 피합니다.
**예: 명확한 규칙과 모호한 규칙 비교**
| 지우기(추출에 적합) | 모호함(추출 불량) |
| --- | --- |
| “연속 근무 기간이 12개월 이상인 정규직 직원은 육아 휴가 자격이 있습니다.” | “자격을 갖춘 직원은 관리자의 승인에 따라 육아휴직을 신청할 수 있습니다.” |
| “환불 요청은 구매 후 30일 이내에 제출해야 합니다. 항목은 원래 패키징에 있어야 합니다.” | “환불은 case-by-case 처리됩니다.” |
### 크기 제한 및 대용량 문서 분할
원본 문서의 크기는 5MB, 문자 수는 50,000자로 제한됩니다. 문서의 이미지와 테이블도 문자 제한에 포함됩니다.
문서가 이러한 제한을 초과하거나 관련이 없는 여러 도메인을 포함하는 경우 해당 문서를 중점 섹션으로 분할합니다. 예를 들어 직원 핸드북을 휴가 정책, 혜택 자격 및 비용 환급을 위한 별도의 문서로 분할합니다. 첫 번째 섹션으로 정책을 생성한 다음 반복 정책 구축(이 페이지의 뒷부분에서 설명)을 사용하여 추가 섹션을 동일한 정책에 병합합니다.
### 복잡한 문서 사전 처리
표준 문안, 법적 고지 사항 또는 적용하려는 규칙과 관련이 없는 콘텐츠가 많이 포함된 문서는 불필요한 변수 및 규칙이 있는 노이즈가 많은 정책을 생성합니다. 업로드하기 전에 다음 사항을 고려하세요.
+ 규칙이 포함되지 않은 헤더, 바닥글, 목차 및 부록을 제거합니다.
+ 사용 사례와 관련된 규칙이 포함된 섹션만 추출합니다.
+ 가능한 경우 복잡한 테이블을 일반 텍스트 문으로 단순화합니다.
**작은 정보**
규칙의 중점 하위 집합부터 시작합니다. 정책을 철저히 생성하고 테스트한 다음 후속 반복에서 콘텐츠를 점진적으로 추가합니다. 이 접근 방식은 문제를 조기에 식별하고 해결하는 데 도움이 되며 문제를 더 쉽게 해결할 수 있습니다.
### (선택 사항) LLM을 사용하여 문서를 논리적 규칙으로 다시 작성
서술 전문가, 법적 언어 또는 복잡한 형식이 포함된 문서의 경우 자동 추론 검사에 업로드하기 전에 고급 추론 기능이 있는 경계 모델을 사용하여 콘텐츠를 명확하고 논리적인 규칙으로 다시 작성하는 것이 좋습니다. 이 일회성 사전 처리 단계는 텍스트를 자동 추론 검사가 보다 정확하게에서 추출할 수 있는 형식으로 변환하므로 사용되지 않는 변수와 베어 어설션이 적은 고품질 정책이 생성됩니다.
**참고**
원본 문서로 사용하기 전에 항상 원본 문서와 비교하여 LLM의 출력을 검토합니다.
문서의 복잡성과 추출에 대한 제어 정도에 따라 LLM 사전 처리에 대한 두 가지 접근 방식이 있습니다.
#### 접근 방식 1: 일반 텍스트 규칙 추출
LLM에 문서를 번호가 매겨진 if-then 규칙 목록으로 다시 작성하도록 요청합니다. 이 접근 방식은 간단하며 소스에서 규칙이 비교적 명확한 짧은 중점 문서에 적합합니다.
**프롬프트 예제:**
```
You are a logical reasoning expert. Your task is to analyze the provided
source text and rewrite it as a set of clear, logical rules using if-then
statements.
Instructions:
1. Extract the key relationships, conditions, and outcomes from the source text.
2. Convert these into logical implications using "if-then" format.
3. Use clear, precise language that captures the original meaning.
4. Number each rule for easy reference.
5. Ensure rules are mutually consistent and non-contradictory.
Format:
- Rule [N]: If [condition], then [consequence].
- Use "and" to combine multiple conditions.
- Use "or" for alternative conditions.
- Include negations when relevant: If not [condition], then [consequence].
Example:
Source: "Students who complete all assignments and attend at least 80% of
classes will pass the course."
Rule 1: If a student completes all assignments and attends at least 80% of
classes, then they will pass the course.
Source Text:
[Paste your document here]
```
#### 접근 방식 2: 구조화된 규칙 추출
복잡하거나 긴 문서의 경우 LLM에 각 규칙에 대한 메타데이터와 함께 규칙을 구조화된 JSON으로 추출하도록 요청합니다. 이 접근 방식은 각 규칙의 출처, 추출 신뢰도, 직접 명시하지 않고 추론되는 규칙을 감사하는 데 도움이 되는 더 풍부한 출력을 생성합니다. 또한 LLM에 "나이가 음수가 아니어야 함"과 같은 상식 경계 제약 조건인 안전 규칙을 생성하도록 요청합니다. 이는 자동 추론 정책이 사용하는 경계 규칙으로 직접 변환됩니다. 경계 규칙에 대한 자세한 내용은 섹션을 참조하세요[숫자 값의 범위 검증](automated-reasoning-policy-best-practices.md#bp-validate-ranges).
**프롬프트 예제:**
```
You are a logical reasoning expert. Extract formal logical rules from the
provided text.
Output Format:
For each rule, provide:
- Rule ID: [unique identifier]
- Conditions: [ALL preconditions — preserve compound conditions with AND/OR/NOT]
- Consequence: [the outcome/action]
- Confidence: [high/medium/low based on text clarity]
- Source Reference: [quote or paraphrase from source]
- Rule Type: [explicit/implicit/sanity]
Critical Guidelines:
1. PRESERVE ALL CONDITIONS: Do not drop or simplify conditions.
2. PRESERVE LOGICAL OPERATORS: Maintain AND, OR, NOT relationships exactly.
3. PRESERVE QUANTIFIERS: Keep "all", "any", "at least", numeric thresholds.
4. PRESERVE EXCEPTIONS: Include "unless", "except when" clauses.
5. Make implicit conditions explicit only when clearly implied by context.
6. Use consistent terminology across rules.
7. Flag ambiguities such as unclear, incomplete, or contradictory statements.
8. Add sanity rules for common-sense constraints:
- Numeric ranges (e.g., "age must be between 0 and 150")
- Temporal constraints (e.g., "start date must be before end date")
- Physical limits (e.g., "quantity cannot be negative")
- Mutual exclusivity (e.g., "status cannot be both active and inactive")
Output Requirements:
- Produce final JSON only (no text or markdown).
- Use the following JSON keys:
- "rules" for the rules array
- "ambiguities" for the ambiguities array
Source Text:
[Paste your document here]
```
구조화된 추출을 실행한 후 JSON 출력을 검토합니다. 다음 사항에 특히 주의하십시오.
+ 의 규칙 `confidence: low` - 소스 문서에 대한 수동 확인이 필요할 수 있습니다.
+ 의 규칙 `ruleType: implicit`- 직접 명시하지 않고 추론되었습니다. 소스의 의도를 정확하게 반영하는지 확인합니다.
+ `ambiguities` 배열 - 소스 문서가 명확하지 않고 추출 전에 다시 작성해야 할 수 있는 영역을 강조 표시합니다.
자동 추론 정책을 생성할 때 소스 문서로 사용할 수 있도록 검토된 JSON 규칙을 일반 텍스트로 변환합니다.
## 효과적인 지침 작성
정책을 생성할 때 자동 추론이 소스 문서를 처리하는 방법을 안내하는 선택적 지침을 제공할 수 있습니다. 선택 사항이지만 올바른 지침은 추출된 규칙 및 변수의 품질을 크게 개선합니다.
효과적인 지침은 다음 세 가지를 포함해야 합니다.
1. **사용 사례를 설명합니다.** 애플리케이션이 수행하는 작업과 정책에서 검증할 콘텐츠 유형을 설명합니다. 예: "이 정책은 직원의 휴가 자격에 대한 질문에 답변하는 HR 챗봇을 검증합니다."
1. **사용자가 묻는 질문 유형을 설명합니다.** 실제 사용자 질문의 예를 제공합니다. 예: '사용자는 '9개월 동안 근무한 경우 육아 휴가 자격이 있습니까?'와 같은 질문을 합니다. 또는 '얼마나 며칠 동안 사별 휴가를 사용할 수 있나요?'
1. **추출에 초점을 맞춥니다.** 문서에 여러 주제가 포함된 경우 Automated Reasoning에 집중할 부분과 무시할 부분을 확인합니다. 예: “휴가 정책을 다루는 섹션 3\$15에 집중합니다. 섹션 1의 일반 회사 개요와 섹션 2의 조직도를 무시합니다.”
**예제 지침:**
```
This policy will validate HR questions about leave eligibility. The document
has sections on different leave types (parental, medical, bereavement, personal).
Users will ask questions like "Am I eligible for parental leave if I've worked
here for 9 months?" or "Can part-time employees take bereavement leave?"
Focus on the eligibility criteria for each leave type. Capture variables that
help determine whether an employee is eligible for a specific type of leave.
```
## 콘솔에서 정책 생성
1. 왼쪽 탐색에서 **자동 추론**을 선택한 다음 **정책 만들기**를 선택합니다.
1. 정책의 **이름**을 입력합니다.
1. (선택 사항) 정책에 대한 **설명**을 입력합니다.
1. **소스**에 지식 도메인의 규칙 및 정책을 설명하는 문서를 제공합니다. 해결 방법:
1. **수집 메서드**에서 다음 중 하나를 수행합니다.
1. **문서 업로드**를 선택한 다음 **파일 선택**을 선택합니다. 소스 콘텐츠의 PDF 문서를 업로드합니다.
1. **텍스트 입력**을 선택합니다. 소스 콘텐츠를 붙여넣거나 입력합니다.
1. (권장) **지침은** 소스 문서를 처리하는 방법에 대한 지침을 제공합니다. 포함할 내용은 [효과적인 지침 작성](#write-effective-instructions) 단원을 참조하십시오.
1. (선택 사항) **태그**에서 **새 태그 추가**를 선택하여 정책에 태그를 추가합니다.
1. (선택 사항) **암호화**에서 정책을 암호화할 KMS 키를 선택합니다. 기본 서비스 소유 키를 사용하거나 고객 관리형 키를 선택할 수 있습니다.
1. **정책 생성**을 선택합니다.
**작은 정보**
애플리케이션에 특정 변수 집합이 필요한 경우 콘텐츠를 가져오기 전에 스키마를 미리 정의할 수 있습니다. `CreateAutomatedReasoningPolicy` API 또는를 사용하여 원하는 변수와 유형이 포함되지만 규칙`policyDefinition`이 포함되지 않은 정책을 CloudFormation 생성합니다. 그런 다음 [반복적 정책 구축](#iterative-policy-building)를 사용하여 소스 문서를 가져옵니다. 자동 추론은 사전 정의된 스키마를 시작점으로 사용하고 변수를 참조하는 규칙을 추가합니다.
## API를 사용하여 정책 생성
자동 추론 정책은 Amazon 리소스 이름(ARN)으로 식별되는 AWS 계정의 리소스입니다. API를 통한 정책 생성은 2단계 프로세스로, 먼저 정책 리소스를 생성한 다음 문서에서 규칙을 추출하는 빌드 워크플로를 시작합니다.
### 1단계: 정책 리소스 생성
`CreateAutomatedReasoningPolicy` API를 사용하여 정책 리소스를 생성합니다.
`name`(필수)
정책의 이름입니다. AWS 계정 및 리전 내에서 고유해야 합니다.
`description` (선택 사항)
정책의 용도에 대한 설명입니다.
`policyDefinition` (선택 사항)
규칙, 변수 및 사용자 지정 유형이 포함된 초기 정책 정의입니다. 시작하려는 스키마가 이미 있는 경우이 옵션을 사용합니다.
`kmsKeyId` (선택 사항)
정책을 암호화하기 위한 KMS 키 식별자입니다. 지정하지 않으면 Amazon Bedrock은 서비스 소유 키를 사용합니다.
`tags` (선택 사항)
정책과 연결할 태그입니다.
`clientRequestToken` (선택 사항)
작업이 한 번 이상 완료되지 않도록 하기 위한 멱등성 토큰입니다.
**예:**
```
aws bedrock create-automated-reasoning-policy \
--name "MyHRPolicy" \
--description "Validates HR chatbot responses about leave eligibility" \
--kms-key-id arn:aws:kms:us-east-1:111122223333:key/12345678-1234-1234-1234-123456789012
```
응답 예제:
```
{
"createdAt": "2025-07-21T14:43:52.692Z",
"definitionHash": "f16ba1ceca36e1d21adce559481add6a...",
"name": "MyHRPolicy",
"policyArn": "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk",
"updatedAt": "2025-07-21T14:43:52.692Z",
"version": "DRAFT"
}
```
### 2단계: 규칙을 추출하는 빌드 워크플로 시작
`StartAutomatedReasoningPolicyBuildWorkflow` API를 1단계의 정책 ARN과 함께 사용하여 소스 문서에서 규칙과 변수를 추출합니다.
`policyArn`(필수)
1단계에서 생성된 정책 리소스의 ARN입니다.
`buildWorkflowType`(필수)
문서에서 규칙을 추출`INGEST_CONTENT`하려면 로 설정합니다.
`sourceContent`(필수)
처리할 문서와 선택적 시작 정책 정의를 포함합니다.
**예:**
```
# Encode your PDF to base64
PDF_BASE64=$(base64 -i your-policy.pdf | tr -d '\n')
# Start the build workflow
aws bedrock start-automated-reasoning-policy-build-workflow \
--policy-arn arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk \
--build-workflow-type INGEST_CONTENT \
--source-content "{
\"policyDefinition\": {
\"version\": \"1.0\",
\"types\": [],
\"rules\": [],
\"variables\": []
},
\"workflowContent\": {
\"documents\": [
{
\"document\": \"$PDF_BASE64\",
\"documentContentType\": \"pdf\",
\"documentName\": \"HR Leave Policy\",
\"documentDescription\": \"Validates HR chatbot responses about leave eligibility. Users ask questions like 'Am I eligible for parental leave?'\"
}
]
}
}"
```
응답 예제:
```
{
"policyArn": "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk",
"buildWorkflowId": "d40fa7fc-351e-47d8-a338-53e4b3b1c690"
}
```
를 사용하여 빌드 상태를 확인합니다`ListAutomatedReasoningPolicyBuildWorkflows`.
```
aws bedrock list-automated-reasoning-policy-build-workflows \
--policy-arn arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk
```
## 추출된 정책 검토
빌드가 완료되면 테스트를 시작하기 전에 추출된 정책 정의를 검토합니다. 이 단계에서 문제를 포착하면 나중에 실패한 테스트를 통해 문제를 발견하는 것보다 시간이 절약됩니다.
콘솔에서 정책을 열고 **정의** 페이지로 이동합니다. API를 통해 `--asset-type POLICY_DEFINITION`를와 `GetAutomatedReasoningPolicyBuildWorkflowResultAssets` 함께 사용하여 추출된 정의를 검색하고 품질 보고서를 `--asset-type QUALITY_REPORT` 검색합니다. `--asset-type ASSET_MANIFEST` 파라미터를 사용하여 충실도 보고서와 같이 워크플로 중에 생성된 자산의 전체 목록을 볼 수 있습니다.
다음과 같은 문제가 있는지 확인합니다.
1. **사용되지 않는 변수입니다.** 콘솔에서 변수 옆에 있는 경고 표시기를 찾습니다. 이러한 플래그 변수는 어떤 규칙에서도 참조되지 않습니다. 사용되지 않는 변수 삭제 - 번역 프로세스에 노이즈를 추가하고 `TRANSLATION_AMBIGUOUS` 결과를 초래할 수 있습니다. API에서 미사용 변수는 `QUALITY_REPORT` 자산에 나열됩니다.
1. **변수가 중복되거나 거의 중복됩니다.** 변수 목록에서 `tenureMonths` 및와 같이 겹치는 의미가 있는 변수를 스캔합니다`monthsOfService`. 자동 추론 검사는 지정된 개념에 사용할 변수를 결정할 수 없으므로 중복 변수는 번역 프로세스를 혼동합니다. 중복 항목을 병합하거나 삭제합니다.
1. **베어 어설션(규칙이 if-then 형식이 아님).** 규칙을 건너뛰고와 같이 if-then 형식이 아닌 규칙을 찾습니다`(= eligibleForParentalLeave true)`. 베어 어설션은 항상 true인 문인 어시옴을 생성하여 특정 조건을 논리적으로 불가능하게 만들고 검증 중에 예상치 못한 `IMPOSSIBLE` 결과를 초래합니다. 조건부(예: `(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)`)로 다시 작성하거나 삭제합니다. 베어 어설션은와 같은 경계 조건에만 적합합니다`(>= accountBalance 0)`.
1. **충돌하는 규칙.** 품질 보고서는 서로 모순되는 규칙에 플래그를 지정합니다. 충돌하는 규칙으로 인해 충돌하는 규칙과 관련된 모든 검증 요청에 `IMPOSSIBLE` 대해 정책이 반환됩니다. 규칙을 병합하거나 규칙을 삭제하여 충돌을 해결합니다.
1. **규칙 또는 변수가 누락되었습니다.** 추출된 정책을 소스 문서와 비교합니다. 중요한 규칙이나 개념이 누락된 경우 이를 수동으로 추가하거나 더 나은 지침에 따라 정책을 다시 생성할 수 있습니다.
**작은 정보**
또한 품질 보고서는 변수를 공유하지 않는 규칙 그룹인 결합 해제된 규칙 세트를 식별합니다. 연결 해제된 규칙 세트는 반드시 문제가 되는 것은 아니지만(정책에서 독립적인 주제를 다룰 수 있음), 변수가 관련 규칙 간의 연결이 누락되었음을 나타낼 수 있습니다.
## 충실도 보고서 검토
소스 문서에서 정책을 생성하면 추출된 정책과 함께 충실도 보고서가 자동으로 생성됩니다. 충실도 보고서는 정책이 소스 콘텐츠를 얼마나 정확하게 나타내는지 측정하고 각 규칙과 변수를 문서의 특정 문에 다시 연결하는 자세한 근거를 제공합니다. 충실도 보고서 개념에 대한 자세한 내용은 섹션을 참조하세요[Fidelity 보고서](automated-reasoning-checks-concepts.md#ar-concept-fidelity-report).
### 콘솔에서 충실도 보고서 검토
콘솔에서 정책을 열고 **소스 문서** 탭(**정의** 옆)을 선택합니다. **소스 콘텐츠** 보기에는 문서에서 추출된 각 원자성 문이 테이블의 번호가 매겨진 행으로 표시됩니다. 각 행에는 다음이 표시됩니다.
+ 문 번호 및 추출된 텍스트입니다.
+ 문이 시작된 소스 **문서**입니다.
+ 해당 문에 기반한 **규칙** 수입니다.
+ 해당 문**에 기반한 변수** 수입니다.
테이블 상단의 **규칙** 및 **변수** 드롭다운 필터를 사용하여 특정 규칙 또는 변수를 뒷받침하는 문에 초점을 맞춥니다. 검색 창을 사용하여 추출된 문 내에서 특정 콘텐츠를 찾습니다.
예를 들어 규칙을 수정하거나 변수를 추가하여 초기 추출 후 정책을 편집하는 경우 현재 정책 정의를 반영하도록 충실도 보고서를 업데이트하려면 **재생성** 버튼을 선택합니다.
### API를 사용하여 충실도 보고서 검토
와 `GetAutomatedReasoningPolicyBuildWorkflowResultAssets` 함께 `--asset-type FIDELITY_REPORT`를 사용하여 충실도 보고서를 검색합니다. 정책을 변경한 후 보고서를 다시 생성하려면 빌드 워크플로 유형`GENERATE_FIDELITY_REPORT`과 `StartAutomatedReasoningPolicyBuildWorkflow` 함께를 사용하고 `generateFidelityReportContent` 필드에 소스 문서를 제공합니다. 워크플로는 현재 정책 정의를 기준으로 문서를 다시 분석하고 새 충실도 보고서를 생성합니다. `--asset-id` 파라미터와 `--asset-type SOURCE_DOCUMENT` 함께를 사용하여 이전 빌드 워크플로에서 원본 소스 문서를 검색할 수도 있습니다(자산 매니페스트에서 자산 ID 가져오기).
### 확인할 항목
APIs의 충실도 보고서를 검토할 때는 다음 사항에 유의하세요.
+ **낮은 적용 범위 점수.** 낮은 적용 범위 점수는 소스 문서의 상당 부분이 정책에 캡처되지 않았음을 나타냅니다. 소스 콘텐츠 보기에서 규칙이 0이고 변수가 0인 문을 찾아 문서의 어떤 부분이 누락되었는지 식별하고, 반복 정책 구축을 사용하여 누락된 콘텐츠를 추가하는 것이 좋습니다. [반복적 정책 구축](#iterative-policy-building)을(를) 참조하세요.
+ **개별 규칙의 정확도 점수가 낮습니다.** 각 규칙에는 고유한 정확도 점수와 근거가 있습니다. 정확도 점수가 낮은 규칙은 소스 구성 요소를 충실하게 나타내지 않을 수 있습니다. **규칙** 필터를 사용하여 특정 규칙에 대한 근거문을 격리하고 규칙의 공식 로직과 비교하여 잘못된 해석을 식별합니다.
+ **근거 없는 규칙 또는 변수.** 근거 문이 없는 규칙 또는 변수는 문서에서 직접 추출하지 않고 추론했을 수 있습니다. 이러한 항목이 올바른지 확인하거나 의도를 반영하지 않는 경우 제거합니다.
**작은 정보**
충실도 보고서는 소스 문서를 작성한 도메인 전문가와의 협업에 특히 유용합니다. **소스 문서** 보기를 공유하면 공식 로직 규칙을 직접 읽을 필요 없이 정책이 의도를 올바르게 캡처하는지 확인할 수 있습니다.
## 반복적 정책 구축
복잡한 도메인의 경우 단일 문서 업로드에서 모든 것을 캡처하려고 하지 않고 정책을 점진적으로 빌드합니다. 규칙의 중점 하위 집합으로 시작하여 정책을 생성 및 테스트한 다음 후속 반복에 콘텐츠를 더 추가합니다.
### 콘솔에서 콘텐츠 추가
1. 콘솔에서 자동 추론 정책을 엽니다.
1. **정의** 페이지에서 **가져오기**를 선택합니다.
1. 옵션을 선택하여 새 콘텐츠를 기존 정책 정의와 병합합니다.
1. 추가 소스 콘텐츠를 업로드하거나 붙여 넣습니다.
1. 업데이트된 정책 정의를 검토하고 새로운 충돌 또는 중복을 해결합니다.
### API를 사용하여 콘텐츠 추가
`StartAutomatedReasoningPolicyBuildWorkflow`를 사용하여를 호출`INGEST_CONTENT`하고 새 문서와 함께 전체 현재 정책 정의를 전달합니다. 새 콘텐츠가 기존 정책을 대체하는 대신 병합되도록 규칙, 변수 및 유형과 같은 기존 정의 전체를 포함해야 합니다.
```
# First, retrieve the current policy definition
aws bedrock get-automated-reasoning-policy \
--policy-arn arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk
# Encode the new document
PDF_BASE64=$(base64 -i additional-rules.pdf | tr -d '\n')
# Start a build workflow with the existing definition + new document
aws bedrock start-automated-reasoning-policy-build-workflow \
--policy-arn arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk \
--build-workflow-type INGEST_CONTENT \
--source-content "{
\"policyDefinition\": EXISTING_POLICY_DEFINITION_JSON,
\"workflowContent\": {
\"documents\": [
{
\"document\": \"$PDF_BASE64\",
\"documentContentType\": \"pdf\",
\"documentName\": \"Additional Benefits Rules\",
\"documentDescription\": \"Additional rules covering medical and bereavement leave eligibility.\"
}
]
}
}"
```
**중요**
API는 정책당 최대 2개의 빌드 워크플로를 지원하며, `IN_PROGRESS` 한 번에 1개만 허용됩니다. 새 빌드를 시작해야 하는데 이미 2개의 워크플로가 있는 경우 먼저를 사용하여 이전 워크플로를 삭제합니다`DeleteAutomatedReasoningPolicyBuildWorkflow`.
## 자동 추론 정책에 대한 KMS 권한
고객 관리형 KMS 키를 지정하여 자동 추론 정책을 암호화하는 경우 Amazon Bedrock이 사용자를 대신하여 키를 사용하도록 허용하는 권한을 구성해야 합니다.
### 키 정책 권한
Amazon Bedrock이 자동 추론 정책에 키를 사용할 수 있도록 KMS 키 정책에 다음 문을 추가합니다.
```
{
"Sid": "PermissionsForAutomatedReasoningPolicy",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/role"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:bedrock:automated-reasoning-policy": [
"arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/policy-id",
"arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/policy-id:*"
],
"kms:ViaService": "bedrock.us-east-1.amazonaws.com"
}
}
}
```
### IAM 권한
자동 추론 정책과 함께 고객 관리형 KMS 키를 사용하려면 IAM 보안 주체에 다음 권한이 있어야 합니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowKMSForAutomatedReasoningPolicy",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-id",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:bedrock:automated-reasoning-policy": [
"arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/policy-id",
"arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/policy-id:*"
],
"kms:ViaService": "bedrock.us-east-1.amazonaws.com"
}
}
}
]
}
```
### 암호화 컨텍스트
Amazon Bedrock은 암호화 컨텍스트를 사용하여 자동 추론 정책에 대한 추가 보안을 제공합니다. 암호화 컨텍스트는 정책을 암호화하고 해독할 때 추가 인증 데이터로 사용되는 키-값 페어 세트입니다.
자동 추론 정책의 경우 Amazon Bedrock은 다음 암호화 컨텍스트를 사용합니다.
+ **키**: `aws:bedrock:automated-reasoning-policy`
+ **값:** 자동 추론 정책의 Amazon 리소스 이름(ARN)
# 자동 추론 정책 모범 사례
이 페이지에서는 자동 추론 정책을 생성하고 유지 관리하기 위한 모범 사례를 통합합니다. 첫 번째 정책을 생성하기 전에이 내용을 읽고 문제를 디버깅할 때 다시 참조하세요. 이러한 사례의 개념적 기반은 섹션을 참조하세요[자동 추론 검사 개념](automated-reasoning-checks-concepts.md). step-by-step 생성 지침은 섹션을 참조하세요[자동 추론 정책 생성](create-automated-reasoning-policy.md).
## 간단한 시작 및 반복
자동 추론 정책을 생성할 때 가장 일반적인 실수는 전체 복잡한 문서를 한 번에 캡처하는 것입니다. 대신 규칙의 중점 하위 집합으로 시작하여 점진적으로 빌드합니다.
1. 소스 문서의 잘 정의된 단일 섹션(예: HR 핸드북의 육아 휴가 자격)을 선택합니다.
1. 해당 섹션에서 정책을 생성하고 추출된 규칙 및 변수를 검토합니다.
1. 해당 섹션의 주요 시나리오를 다루는 테스트를 작성합니다.
1. 콘텐츠를 추가하기 전에 문제를 해결합니다.
1. 반복적 정책 구축을 사용하여 추가 섹션을 한 번에 하나씩 병합합니다. 자세한 내용은 [반복적 정책 구축](create-automated-reasoning-policy.md#iterative-policy-building) 단원을 참조하십시오.
이 접근 방식에는 두 가지 이점이 있습니다. 즉, 문제를 더 쉽게 격리할 수 있고(어떤 섹션에 문제가 발생했는지 알 수 있음) 개발 중에 정책을 관리할 수 있습니다. 잘 테스트된 규칙 10개가 있는 정책은 테스트되지 않은 규칙 100개가 있는 정책보다 더 유용합니다.
## LLM을 사용하여 문서 사전 처리
길이가 길거나 서술 내용을 포함하거나 규칙이 아닌 콘텐츠(예: 법적 고지 사항 또는 조직 배경)와 혼합된 문서의 경우 자동 추론 검사에 업로드하기 전에 LLM을 통해 문서를 실행합니다. LLM에 콘텐츠를 명시적인 if-then 규칙으로 추출하도록 요청합니다. 자동 추론 검사는 구조화되지 않은 텍스트가 아닌 명확하고 선언적인 문에서 가장 잘 작동하므로이 사전 처리 단계는 추출된 정책의 품질을 크게 개선합니다.
사전 처리 프롬프트를 작성할 때 LLM에 대한 다음 지침을 포함합니다.
+ 명확한 조건과 결과를 사용하여 if-then 형식으로 규칙을 추출합니다.
+ 모든 조건, 논리 연산자(AND, OR, NOT), 한정자("최소", "최대") 및 예외 절("단순", "시간 제외")을 보존합니다.
+ "계정 잔액은 부정일 수 없습니다" 또는 "크레딧 점수는 300\$1850이어야 합니다"와 같은 상식적 제약 조건에 대한 안전 규칙을 추가하여 정책의 경계 규칙으로 변환합니다( 참조[숫자 값의 범위 검증](#bp-validate-ranges)).
**중요**
원본 문서로 사용하기 전에 항상 원본 문서와 비교하여 LLM의 출력을 검토합니다. LLMs 소스에 없는 규칙을 할루시네이션하거나, 조건을 잘못 해석하거나, 중요한 예외를 삭제할 수 있습니다. 사전 처리 단계는 인적 검토를 대체하는 것이 아니라 시작점입니다.
자세한 프롬프트 템플릿과 step-by-step 사전 처리 워크플로는 섹션을 참조하세요[(선택 사항) LLM을 사용하여 문서를 논리적 규칙으로 다시 작성](create-automated-reasoning-policy.md#preprocess-with-llm).
## 영향(=>)을 사용하여 규칙 구성
if-then 형식(`=>`암시 연산자 사용)은 가장 중요한 단일 규칙 작성 패턴입니다. 조건부 관계를 표현하는 모든 규칙은이 형식을 사용해야 합니다.
| 좋음: 암시 | 잘못된: 베어 어설션 |
| --- | --- |
| (=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave) | eligibleForParentalLeave |
| (=> (> loanAmount 500000) requiresCosigner) | requiresCosigner |
베어 어설션( if-then 구조가 없는 규칙)은 항상 true인 문인 axiom을 생성합니다. 어설션은 조건과 관계없이 육아 휴가 자격이 항상 참임을 자동 추론 검사에 `eligibleForParentalLeave` 알립니다. 사용자가 자격이 *없다는* 모든 입력은이 어시옴과 모순`IMPOSSIBLE`되므로를 반환합니다.
베어 어설션은 다음과 같이 항상 보유해야 하는 경계 조건에만 적합합니다.
```
;; Account balance can never be negative
(>= accountBalance 0)
;; Interest rate is always between 0 and 1
(and (>= interestRate 0) (<= interestRate 1))
```
추출된 정책에서 베어 어설션을 찾으면 조건부로 다시 작성하거나 삭제합니다. 추출된 정책 검토에 대한 자세한 내용은 섹션을 참조하세요[추출된 정책 검토](create-automated-reasoning-policy.md#review-extracted-policy).
## 포괄적인 변수 설명 작성
변수 설명은 번역 정확도의 기본 요소입니다. 자동 추론 검사는 자연어를 공식 로직으로 변환할 때 변수 설명을 사용하여 텍스트에 언급된 개념에 해당하는 변수를 결정합니다. 모호하거나 불완전한 설명은 `TRANSLATION_AMBIGUOUS` 결과의 가장 큰 원인입니다.
좋은 변수 설명은 네 가지 질문에 답해야 합니다.
1. **이 변수는 무엇을 의미합니까?** 개념을 일반 언어로 설명합니다.
1. **어떤 단위 또는 형식을 사용하나요?** 단위(월, 달러, 백분율을 십진수로) 및 변환 규칙을 지정합니다.
1. **사용자가이 개념을 어떻게 참조할 수 있습니까?** 동의어, 대체 문구 및 사용자가 일상적인 언어로이 개념을 표현하는 일반적인 방법을 포함합니다.
1. **경계 조건은 무엇입니까?** 엣지 케이스, 기본값 및 변수가 특정 값으로 설정될 때 무엇을 의미하는지 설명합니다.
**예: 이전 및 이후**
| 모호함(번역 실패 발생) | 세부 정보(신뢰할 수 있는 번역) |
| --- | --- |
| tenureMonths: "직원의 근무 기간" | tenureMonths: "직원이 지속적으로 고용된 전체 개월 수. 사용자가 서비스 연도를 언급하면 월로 변환합니다(예: 2년 = 24개월). 첫 달을 아직 완료하지 않은 신규 채용의 경우 0으로 설정합니다.” |
| isFullTime: "정규직 상태". | isFullTime: "직원이 정규직(true)인지 아니면 시간제(false)인지 여부. 사용자가 '정규 근무', '정규 근무' 또는 주당 40시간 이상 근무한다고 언급하면 true로 설정합니다. 사용자가 '파트 타임', '시간 단축' 또는 주당 40시간 미만'으로 언급하면 false로 설정합니다. |
| interestRate: "이자율" | interestRate: "10진수 값으로 표현되는 연간 이자율. 여기서 0.05는 5%를 의미하고 0.15는 15%를 의미합니다. 사용자가 '5%'와 같은 백분율을 언급하면 10진수 형식(0.05)으로 변환합니다." |
## 비독점 상태에 부울 사용
공존할 수 있는 상태를 모델링하는 경우 단일 열거형 대신 별도의 부울 변수를 사용합니다. 사람은 재향 군인이자 교사일 수 있습니다. 열거형을 사용하면 두 열거형 간에 선택이 `customerType = {VETERAN, TEACHER}` 강제로 적용되므로 둘 다 적용될 때 논리적 모순이 발생합니다.
| 좋음: 별도의 부울 | 잘못된: 비독점 상태의 열거형 |
| --- | --- |
| `isVeteran` (bool): "고객이 군인인지 여부" `isTeacher` (bool): "고객이 교사인지 여부" | `customerType` ( 열거형: VETERAN, TEACHER, STUDENT): "고객 유형" 문제: 재향 군인과 교사인 고객은 대표할 수 없습니다. |
(직원`leaveType = {PARENTAL, MEDICAL, BEREAVEMENT}`은 한 번에 한 가지 유형의 휴가만 요청할 수 있음)과 같이 한 번에 하나의 값만 적용할 수 있는 상호 배타적인 범주에 대한 열거형을 예약합니다. 사용자 지정 유형에 대한 자세한 내용은 섹션을 참조하세요[사용자 지정 유형( 열거형)](automated-reasoning-checks-concepts.md#ar-concept-custom-types).
## 변수 설명에서 단위 및 형식 지정
단위에 대한 모호성은 번역 오류의 일반적인 원인입니다. 사용자가 "2년 동안 근무했습니다"라고 말하고 변수가 인 경우 `tenureMonths`번역은 연도를 개월로 변환하기 위해 알아야 합니다. 변수 설명에서 단위를 지정하지 않는 경우 변환에서 `tenureMonths = 2` 대신를 할당할 수 있습니다`tenureMonths = 24`.
항상 다음을 지정합니다.
+ 측정 단위(월, 일, 달러, 백분율).
+ 형식(10진수 대 백분율, 날짜 형식, 통화).
+ 일반적인 대체 표현식에 대한 변환 규칙(예: "2년 = 24개월").
**예**:
+ `loanAmount`: "미국 달러 단위의 총 대출 금액. 사용자가 수천 단위로 금액을 언급하면(예: '500K') 전체 숫자(500,000)로 변환합니다."
+ `submissionDate`: "제출이 이루어진 기한 이후의 일수입니다. 값이 0이면 제출이 정시에 완료되었음을 의미합니다. 양수 값은 제출 지연을 나타냅니다.”
## 숫자 값의 범위 검증
숫자 변수의 경우 유효한 범위를 제한하는 경계 규칙을 추가합니다. 이렇게 하면 논리적으로 불가능한 시나리오를 방지하고 자동 추론 검사가 더 의미 있는 결과를 생성하는 데 도움이 됩니다.
```
;; Account balance cannot be negative
(>= accountBalance 0)
;; Interest rate must be between 0 and 1 (0% to 100%)
(and (>= interestRate 0) (<= interestRate 1))
;; Credit score ranges from 300 to 850
(and (>= creditScore 300) (<= creditScore 850))
;; Tenure in months cannot be negative
(>= tenureMonths 0)
```
이러한 경계 규칙이 없는 경우 자동 추론 검사는 마이너스 계정 잔액 또는 크레딧 점수가 1000을 초과하는 시나리오를 고려할 수 있으며, 이는 도메인에서 의미가 없습니다. 경계 규칙은 베어 어설션(규칙이 if-then 형식이 아님)이 적절한 몇 가지 경우 중 하나입니다.
## 추상화에 중간 변수 사용
여러 규칙이 공통 조건을 공유하는 경우 해당 조건을 중간 부울 변수로 추출합니다. 이렇게 하면 규칙이 간소화되고 정책을 더 쉽게 유지할 수 있습니다.
**예: 멤버십 티어**
모든 혜택 규칙에서 멤버십 조건을 반복하는 대신:
```
;; Without intermediate variable (repetitive)
(=> (and (> purchaseTotal 1000) (> accountAge 12)) eligibleForFreeShipping)
(=> (and (> purchaseTotal 1000) (> accountAge 12)) eligibleForPrioritySupport)
(=> (and (> purchaseTotal 1000) (> accountAge 12)) eligibleForEarlyAccess)
```
중간 변수를 정의하고 참조합니다.
```
;; With intermediate variable (cleaner)
(=> (and (> purchaseTotal 1000) (> accountAge 12)) isPremiumMember)
(=> isPremiumMember eligibleForFreeShipping)
(=> isPremiumMember eligibleForPrioritySupport)
(=> isPremiumMember eligibleForEarlyAccess)
```
이 패턴을 사용하면 나중에 멤버십 기준을 더 쉽게 업데이트할 수 있습니다. 규칙을 3개가 아닌 1개만 변경하면 됩니다.
## 범주화에 열거형 사용
변수가 고정된 상호 배타적 값 집합이 있는 범주를 나타내는 경우 여러 부울 또는 문자열 대신 사용자 지정 유형( 열거형)을 사용합니다. 열거형은 가능한 값을 제한하고 규칙을 더 명확하게 만듭니다.
| 양호: 열거형 | 회피: 배타적 상태에 대한 여러 부울 |
| --- | --- |
| 유형: `LeaveType = {PARENTAL, MEDICAL, BEREAVEMENT, PERSONAL}` 변수: `leaveType` (LeaveType) 규칙: `(=> (= leaveType PARENTAL) (>= leaveDays 60))` | `isParentalLeave` (bool) `isMedicalLeave` (bool) `isBereavementLeave` (bool) 문제: 여러 부울이 동시에 true가 되는 것을 방지하는 것은 없습니다. |
**작은 정보**
입력이 정의된 범주와 일치하지 않을 수 있는 경우 열거형에 `OTHER` 또는 `NONE` 값을 포함합니다. 이렇게 하면 입력이 정의된 값 중 하나에 깔끔하게 맞지 않을 때 번역 문제가 방지됩니다.
## 프로시저가 아닌 로직 선언적 유지
자동 추론 정책은 *계산 방법이* 아니라 *사실에 대해* 설명합니다. 순차적 단계 또는 우선 순위 로직이 있는 코드처럼 보이는 규칙을 작성하지 마세요.
| 좋음: 선언적 | 회피: 절차적 사고 |
| --- | --- |
| “직원이 정규직이고 재직 기간이 12개월 이상인 경우 육아 휴가 자격이 있습니다.” 이는 조건과 결과 간의 관계에 대한 사실을 설명합니다. | “직원이 정규직인지 먼저 확인합니다. 그렇다면 재직 기간을 확인합니다. 재직 기간이 12개월을 초과하는 경우 자격을 true로 설정합니다.” 논리적 관계가 아닌 프로시저에 대해 설명합니다. |
마찬가지로 규칙 간에 인코딩 우선 순위 또는 우선 순위를 사용하지 마세요. 공식 로직에서는 모든 규칙이 동시에 적용됩니다. 한 조건이 다른 조건을 재정의한다는 것을 표현해야 하는 경우 규칙 조건에서 명시적으로 인코딩합니다.
```
;; GOOD: Explicit exception handling
;; General rule: full-time employees with 12+ months get parental leave
(=> (and isFullTime (> tenureMonths 12) (not isOnProbation))
eligibleForParentalLeave)
;; BAD: Trying to encode precedence
;; "Rule 1 takes priority over Rule 2" — this concept doesn't exist
;; in formal logic. Instead, combine the conditions into a single rule.
```
## 이름 지정 규칙
일관된 이름 지정을 통해 정책을 더 쉽게 읽고 유지 관리하고 디버깅할 수 있습니다. 다음 규칙을 따릅니다.
+ **부울 변수:** `is` 또는 `has` 접두사를 사용합니다. 예, `isFullTime`, `hasDirectDeposit`, `isEligibleForLeave`.
+ **숫자 변수:** 이름에 단위를 포함합니다. 예, `tenureMonths`, `loanAmountUSD`, `creditScore`.
+ **열거형 유형:** 유형 이름에는 PascalCase를 사용하고 값에는 UPPER\$1SNAKE\$1CASE를 사용합니다. 예를 들어 `LeaveType = {PARENTAL, MEDICAL, BEREAVEMENT}`입니다.
+ **변수: camelCase를** 사용합니다. camelCase 예, `tenureMonths`, `isFullTime`, `leaveType`.
모호할 수 있는 약어는 사용하지 마세요. `tenureMonths` 대신 `tenMo`를 사용하고 `isFullTime` 대신를 사용합니다`ft`. 명확한 이름은 인적 검토자와 번역 프로세스 모두에 도움이 됩니다.
## 일반적인 안티 패턴
다음 패턴은 자동 추론 정책에서 문제를 자주 일으킵니다. 예기치 않은 테스트 결과가 발생하는 경우 정책에 이러한 안티 패턴이 포함되어 있는지 확인합니다.
### 영향 대신 Axiom
에 설명된 대로 [영향(=>)을 사용하여 규칙 구성](#bp-use-implications)베어 어설션은 항상 true인 어시옴을 생성합니다. 이는 가장 일반적인 안티 패턴이며 가장 해롭습니다. 전체 입력 범주가를 반환합니다`IMPOSSIBLE`.
**증상:** `IMPOSSIBLE` 대신 반환`VALID`되거나 `INVALID` 반환되어야 하는 테스트입니다.
**수정:** 규칙에서 베어 어설션을 찾아 영향으로 다시 작성하거나 경계 조건을 나타내지 않는 경우 삭제합니다.
### 겹치는 변수
동일하거나 유사한 개념(예: `tenureMonths` 및 `monthsOfService`)을 나타내는 두 개의 변수가 있으면 번역 프로세스가 혼동됩니다. 자동 추론 검사는 지정된 개념에 사용할 변수를 결정할 수 없으므로 번역 및 `TRANSLATION_AMBIGUOUS` 결과가 일관되지 않습니다.
**증상:** 명확하고 모호하지 않은 입력 텍스트가 `TRANSLATION_AMBIGUOUS` 있더라도 테스트가 반환됩니다.
**수정 사항:** 겹치는 변수를 포괄적인 설명과 함께 단일 변수로 병합합니다. 삭제된 변수를 참조하는 모든 규칙을 업데이트합니다.
### 지나치게 복잡한 정책
변수가 너무 많거나, 조건이 깊이 중첩되거나, 비선형 산술이 있는 정책은 처리 제한을 초과하고 `TOO_COMPLEX` 결과를 반환할 수 있습니다.
**증상:** 테스트가 반환`TOO_COMPLEX`되거나 시간 초과됩니다.
**수정:** 정책을 간소화합니다. 사용하지 않는 변수를 제거하고, 중간 변수를 사용하여 복잡한 규칙을 더 간단한 규칙으로 나누고, 비선형 산술(지수, 비합리적인 숫자)을 방지합니다. 도메인이 실제로 복잡한 경우 여러 개의 집중된 정책으로 분할하는 것이 좋습니다.
### 모순되는 규칙
서로 모순되는 규칙으로 인해 자동 추론 검사가 결론에 도달할 수 없습니다. 예를 들어 한 규칙은 정규직 직원에게 휴가 자격이 있다고 하고, 다른 규칙은 첫 해에 정규직 직원에게 어떤 일이 발생하는지 지정하지 않고 첫 해의 직원에게는 자격이 없다고 합니다.
**증상:** 테스트는 충돌하는 규칙과 관련된 `IMPOSSIBLE` 입력을 반환합니다.
**수정:** 품질 보고서에 충돌하는 규칙이 있는지 확인합니다. 규칙을 명시적 조건과 함께 단일 규칙으로 병합하거나 충돌하는 규칙 중 하나를 삭제하여 충돌을 해결합니다. 자세한 내용은 [추출된 정책 검토](create-automated-reasoning-policy.md#review-extracted-policy) 단원을 참조하십시오.
### 사용되지 않는 변수
규칙에서 참조하지 않는 변수는 번역 프로세스에 노이즈를 추가합니다. 변환은 미사용 변수에 값을 할당하여 처리 용량을 낭비하고 미사용 변수가 유사한 활성 변수와 경쟁할 때 잠재적으로 `TRANSLATION_AMBIGUOUS` 결과를 초래할 수 있습니다.
**증상:** 예상치 못한 `TRANSLATION_AMBIGUOUS` 결과 또는 규칙에 영향을 주지 않는 변수에 값을 할당하는 변환입니다.
**수정:** 사용되지 않는 변수를 삭제합니다. 콘솔에서 변수 옆에 있는 경고 표시기를 찾습니다. API를 통해를 `GetAutomatedReasoningPolicyBuildWorkflowResultAssets` 사용하여의 품질 보고서를 확인합니다`--asset-type QUALITY_REPORT`.
### 열거형 값 누락
열거형에 사용자가 언급할 수 있는 가능한 모든 범주에 대한 값이 포함되지 않은 경우 입력이 정의된 값과 일치하지 않으면 번역이 실패하거나 예기치 않은 결과가 발생할 수 있습니다.
**증상:** 테스트는 입력이 열거형에 없는 범주를 언급할 `NO_TRANSLATIONS` 때 `TRANSLATION_AMBIGUOUS` 또는를 반환합니다.
**수정:** 열거형에 `OTHER` 또는 `NONE` 값을 추가하여 정의된 범주와 일치하지 않는 입력을 처리합니다. 열거형 값 설명을 업데이트하여 각 값이 적용되는 시기를 명확히 합니다.
# 자동 추론 정책 테스트
테스트는 정책의 규칙이 올바른지, 자동 추론 검사가 자연어를 공식 로직으로 정확하게 변환할 수 있는지 확인합니다. 검증을 위해 자연어 문을 전송한 다음 피드백을 검사하여 변환이 올바른 변수를 사용하고 규칙이 예상 결과를 생성하는지 확인하여 정책을 테스트합니다.
두 가지 보완적인 테스트 접근 방식, 즉 생성된 시나리오와 question-and-answer(QnA) 테스트가 있습니다. 각는 검증 파이프라인의 서로 다른 부분을 대상으로 합니다. 권장되는 워크플로는 시나리오로 시작하여 규칙 정확성을 검증한 다음 QnA 테스트를 추가하여 번역 정확도를 검증하는 것입니다.
## 테스트 전략: 시나리오와 QnA 테스트 비교
자동 추론 검사는 두 단계로 콘텐츠를 검증합니다. 먼저 파운데이션 모델은 자연어를 공식 로직으로 변환한 다음 수학 기법은 정책 규칙에 따라 로직을 확인합니다. 각 테스트 접근 방식은이 파이프라인의 다른 단계를 대상으로 합니다.
### 생성된 시나리오(테스트 규칙 정확성)
생성된 시나리오는 *정책 규칙에 인코딩된 의미 체계를 직접 테스트합니다*. 방정식에서 자연어 번역의 불확실성을 제거하여 규칙 자체가 올바른지 여부를 격리합니다.
시나리오는 정책 규칙에서 생성되며 이러한 규칙을 고려할 때 논리적으로 가능한 상황을 나타냅니다. 가장 likely-to-be-wrong 높은 시나리오를 먼저 표시하도록 정렬됩니다. 각 시나리오에 대해 변수 할당을 검토하고 다음을 결정합니다.
+ **썸업** - 시나리오는 현실적이며 실제로 가능해야 합니다. 테스트로 저장합니다`SATISFIABLE`.
+ **썸 다운 **- 뭔가 꺼졌습니다. 도메인 지식을 고려할 때 시나리오가 가능해서는 안 됩니다. 이유를 설명하는 자연어 피드백을 제공하면 자동 추론 검사가 필요한 규칙 변경을 추론하려고 시도합니다.
**예:** 정책에는 재직 기간이 12개월 이상인 정규직 직원이 육아 휴가 자격이 있다고 명시되어 있습니다. 생성된 시나리오에가 표시될 수 있습니다`isFullTime = true, tenureMonths = 3, eligibleForParentalLeave = true`. 이 시나리오가 가능해서는 안 되는 경우(3개월이 12개월 미만이기 때문), 직원에게 최소 12개월의 재직 기간이 필요하다고 설명해야 합니다. 이는 규칙이 누락되었거나 잘못되었음을 나타냅니다.
시나리오를 *첫 번째* 테스트 단계로 사용합니다. QnA 테스트 작성에 시간을 투자하기 전에 규칙 문제를 파악하는 데 도움이 됩니다.
### QnA 테스트(테스트 번역 정확도)
QnA 테스트는 *전체 파이프라인 end-to-end*, 즉 자연어 번역과 규칙 검증을 함께 검증합니다. 실제 사용자 상호 작용을 모방하고 시나리오에서 감지할 수 없는 번역 문제를 포착합니다.
각 QnA 테스트는 다음으로 구성됩니다.
+ **입력**(선택 사항) - 사용자가 애플리케이션에 질문할 수 있는 질문입니다.
+ **출력** - 파운데이션 모델이 생성할 수 있는 응답입니다.
+ **예상 결과** - 예상한 검증 결과입니다(예: `VALID` 또는 `INVALID`).
**예:** 동일한 육아 휴가 정책의 경우 QnA 테스트는 입력 = "여기에서 2년 동안 정규직으로 근무했습니다. 육아 휴가를 사용할 수 있나요?", 출력 = "예, 육아 휴가를 사용할 수 있습니다.", 예상 결과 = `VALID`. 이 테스트는 자동 추론 검사가 "2년"을 로`tenureMonths = 24`, "풀타임"을 로 올바르게 변환하는지 여부를 테스트합니다`isFullTime = true`.
**작은 정보**
유효한 시나리오와 잘못된 시나리오를 모두 포함하는 테스트를 생성합니다. 예를 들어 정책에 "직원은 육아 휴가에 1년 근무가 필요합니다"라고 명시되어 있는 경우이 규칙을 올바르게 명시하는 응답에 대한 테스트를 *생성하고* 다른 요구 사항을 잘못 명시하는 응답에 대한 테스트를 생성합니다.
### 권장 테스트 워크플로
1. **시나리오를 생성하고 검토합니다.** 여기에서 시작하여 규칙이 올바른지 확인합니다. 계속하기 전에 규칙 문제를 해결합니다.
1. **주요 사용 사례에 대한 QnA 테스트를 작성합니다.** 사용자가 질문할 가능성이 가장 높은 질문과 LLM이 생성할 가능성이 가장 높은 응답에 집중합니다. 엣지 케이스 및 경계 조건을 포함합니다.
1. **모든 테스트를 실행합니다.** 시나리오와 QnA 테스트가 모두 통과했는지 확인합니다.
1. **반복하십시오.** 테스트가 실패하면 문제가 규칙(정책 수정) 또는 변환(변수 설명 개선)에 있는지 확인합니다. 자세한 내용은 [자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md) 단원을 참조하십시오.
## 콘솔에서 테스트 시나리오 자동 생성
1. 테스트하려는 자동 추론 정책(예: **MyHrPolicy**)으로 이동합니다.
1. **테스트 보기**를 선택한 다음 **생성**을 선택합니다.
1. **시나리오 생성** 대화 상자에서 생성된 시나리오와 관련 규칙을 검토합니다. 각 시나리오는 정책 규칙을 고려할 때 논리적으로 가능한 변수 할당 세트를 보여줍니다. 시나리오가 도메인에서 현실적인지 평가합니다.
+ 도메인에서 시나리오가 발생할 수 있는 경우(*만족할 수 있는* 경우) 썸업 아이콘을 선택합니다. 이렇게 하면 시나리오가 `SATISFIABLE` 결과를 기대하는 테스트로 저장됩니다.
+ 시나리오가 가능하지 않은 경우 썸다운 아이콘을 선택합니다. 이유를 설명하는 주석을 제공합니다. 예를 들어 "직원은 육아 휴가에 최소 12개월의 재직 기간이 필요하지만이 시나리오에서는 3개월이 적격으로 표시됩니다." 자동 추론 검사는 피드백을 사용하여이 시나리오를 방해하는 규칙 변경을 추론합니다.
+ 다른 시나리오를 원하는 경우 **시나리오 재생성을** 선택합니다.
**작은 정보**
시나리오의 공식 로직 버전을 검사하려면 **SMT-LIB 표시를** 활성화합니다. 이는 관련된 규칙 및 변수 할당을 정확하게 이해하는 데 유용합니다.
1. **저장 및 닫기**를 선택하여 테스트를 저장하거나 **저장 및 다른 추가**를 선택하여 시나리오 검토를 계속합니다.
1. 시나리오에 주석(썸다운 피드백)을 제공한 경우 **주석 적용을** 선택합니다. 자동 추론 검사는 피드백에 따라 정책에 변경 사항을 적용하는 빌드 워크플로를 시작합니다.
1. **정책 변경 사항 검토** 화면에서 정책의 규칙, 변수 및 변수 유형에 대해 제안된 변경 사항을 검토합니다. 그런 다음 **변경 사항 수락**을 선택합니다.
## API를 사용하여 테스트 시나리오 자동 생성
`GetAutomatedReasoningPolicyNextScenario` API를 사용하여 정책의 규칙에 따라 생성된 테스트 시나리오를 가져옵니다.
`policyArn`(필수)
자동 추론 정책의 ARN입니다.
`buildWorkflowId`(필수)
생성된 시나리오에 대한 빌드 워크플로의 식별자입니다. `ListAutomatedReasoningPolicyBuildWorkflows` API를 사용하여 최신 빌드 워크플로를 검색합니다.
**예:**
```
aws bedrock get-automated-reasoning-policy-next-scenario \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--build-workflow-id d40fa7fc-351e-47d8-a338-53e4b3b1c690
```
응답에는 변수 할당 및 관련 정책 규칙이 있는 생성된 시나리오가 포함됩니다. 시나리오를 검토하고 `CreateAutomatedReasoningPolicyTestCase` API를 사용하여 테스트로 저장하거나 시나리오에서 규칙 문제가 발견되면 주석 APIs를 사용하여 피드백을 제공합니다.
## 콘솔에서 수동으로 QnA 테스트 생성
1. 테스트하려는 자동 추론 정책(예: **MyHrPolicy**)으로 이동합니다.
1. **테스트 보기**를 선택한 다음 **추가**를 선택합니다.
1. **테스트 추가** 대화 상자에서 다음을 수행합니다.
1. **입력**(선택 사항)에 사용자가 할 수 있는 질문을 입력합니다. **출력**에 파운데이션 모델이 제공할 수 있는 응답을 입력합니다. 이들은 함께 정책이 실제 사용자 상호 작용을 검증하는 방법을 테스트하는 QnA 페어를 형성합니다.
1. 테스트에서 예상되는 결과(예: **유효** 또는 **유효하지 않음**)를 선택합니다.
1. (선택 사항) 로직 검증의 최소 신뢰도 수준인 신뢰도 **임계값**을 선택합니다. 자동 추론 검사는 여러 LLMs를 조사 결과로 변환합니다. LLM 번역의 상당 부분이 지원하는 조사 결과만 반환합니다. 신뢰도 임계값은 변환이 유효한 결과가 있는 조사 결과가 되는 데 필요한 최소 지원 비율을 정의합니다. 임계값 미만의 결과는 로 표시됩니다`TRANSLATION_AMBIGUOUS`.
1. **저장**을 선택하여 테스트를 생성합니다.
## API를 사용하여 QnA 테스트 생성
`CreateAutomatedReasoningPolicyTestCase` API를 사용하여 프로그래밍 방식으로 테스트를 생성합니다.
`policyArn`(필수)
자동 추론 정책의 ARN입니다.
`queryContent` (선택 사항)
사용자 질문과 같이 콘텐츠를 생성한 입력 쿼리 또는 프롬프트입니다. 이는 검증을 위한 컨텍스트를 제공합니다.
`guardContent`(필수)
검증할 출력 콘텐츠 - 정확도를 확인할 파운데이션 모델 응답입니다.
`expectedAggregatedFindingsResult` (선택 사항)
예상 검증 결과(예: `VALID` 또는 `INVALID`). 실제 결과는 심각도에 따라 결과를 정렬하고 최악의 결과를 선택하여 결정됩니다. 최악의 심각도부터 최상의 심각도 순서는 `TRANSLATION_AMBIGUOUS`, `IMPOSSIBLE`, `INVALID`, `SATISFIABLE`, 입니다`VALID`.
`confidenceThreshold` (선택 사항)
로직 검증을 위한 최소 신뢰도 수준입니다.
**예:**
```
aws bedrock create-automated-reasoning-policy-test-case \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--query-content "Can I take a leave of absence if I'm a part-time employee?" \
--guard-content "No, only full-time employees are eligible for leave of absence." \
--expected-aggregated-findings-result "VALID" \
--confidence-threshold 0.8
```
응답 예제:
```
{
"testCaseId": "test-12345abcde",
"policyArn": "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk"
}
```
## 테스트 실행
### 콘솔에서 테스트 실행
1. 검증하려는 자동 추론 정책(예: **MyHrPolicy**)으로 이동합니다.
1. **테스트 보기**를 선택합니다.
1. 다음 중 하나를 수행하세요.
+ 모든 테스트를 실행하려면 **모든 테스트 검증을** 선택합니다.
+ 단일 테스트를 실행하려면 테스트 옆의 **작업** 버튼을 선택하고 **검증**을 선택합니다.
### API를 사용하여 테스트 실행
`StartAutomatedReasoningPolicyTestWorkflow` API를 사용하여 테스트를 실행하고 `GetAutomatedReasoningPolicyTestResult` API를 사용하여 결과를 검색합니다.
`policyArn`(필수)
자동 추론 정책의 ARN입니다.
`buildWorkflowId`(필수)
테스트를 실행할 빌드 워크플로의 식별자입니다. `ListAutomatedReasoningPolicyBuildWorkflows` API를 사용하여 최신 빌드 워크플로를 검색합니다.
`testCaseIds` (선택 사항)
실행할 테스트 식별자 목록입니다. 제공하지 않으면 정책에 대한 모든 테스트가 실행됩니다.
**예:**
```
# Run tests
aws bedrock start-automated-reasoning-policy-test-workflow \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--build-workflow-id d40fa7fc-351e-47d8-a338-53e4b3b1c690
# Get results for a specific test
aws bedrock get-automated-reasoning-policy-test-result \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--build-workflow-id d40fa7fc-351e-47d8-a338-53e4b3b1c690 \
--test-case-id test-12345abcde
```
응답에는 검증 결과 및 실행 상태와 함께 자세한 테스트 결과가 포함됩니다. 빌드 워크플로에 대한 모든 테스트 결과를 나열하려면 `ListAutomatedReasoningPolicyTestResults` API를 사용합니다.
## 테스트 결과 이해
테스트가 완료되면 *결과* 세트를 받게 됩니다. 각 결과는 검증 결과, 사용된 변수 할당 및 결론을 지원하는 정책 규칙과 함께 테스트 입력에서 추출된 사실적 클레임을 나타냅니다. 결과 구조 및 모든 검증 결과 유형에 대한 자세한 설명은 섹션을 참조하세요[결과 및 검증 결과](automated-reasoning-checks-concepts.md#ar-concept-findings).
### 테스트 결과의 구조
각 테스트 결과에는 다음이 포함됩니다.
+ **예상 결과** - 테스트를 생성할 때 설정한 결과입니다.
+ **실제 결과** - 테스트 실행의 집계된 결과입니다. 이는 심각도에 따라 조사 결과를 정렬하고 최악의 결과를 선택하여 결정됩니다. 최악의 심각도부터 최상의 심각도 순서는 `TRANSLATION_AMBIGUOUS`, `IMPOSSIBLE`, `INVALID`, `SATISFIABLE`, 입니다`VALID`. 예를 들어 두 개의 `VALID` 조사 결과와 한 개의 `IMPOSSIBLE` 조사 결과가 있는 테스트의 집계 결과는 입니다`IMPOSSIBLE`.
+ **실행 결과** - 테스트가 통과(예상 결과와 실제 결과가 일치)했는지 또는 실패했는지 여부입니다.
+ **결과 **- 개별 검증 결과입니다. 각 결과에는 번역된 온프레미스 및 클레임, 신뢰도 점수, 변수 할당 및 결론을 지원하는 정책 규칙이 포함됩니다.
### 결과의 실제 해석
다음 표에는 각 검증 결과가 실제로 무엇을 의미하는지와 테스트에서 확인할 때 취해야 할 조치가 요약되어 있습니다. 결과 필드 및 자세한 설명을 포함한 전체 참조는 섹션을 참조하세요[검증 결과 참조](automated-reasoning-checks-concepts.md#ar-concept-validation-results).
| 결과 | 의미 | 수행할 작업 |
| --- | --- | --- |
| VALID | 응답의 클레임은 온프레미스 및 정책 규칙을 고려하여 수학적으로 올바르게 증명됩니다. 결과에는 클레임을 증명supportingRules하는과 클레임이 어떻게 적용되는지 claimsTrueScenario 보여주는이 포함됩니다. | 예상 결과인 경우 테스트가 통과합니다. untranslatedPremises 및에서 검증되지 않은 입력 부분이 untranslatedClaims 있는지 확인합니다. VALID 결과는 변환된 클레임만 포함합니다. |
| INVALID | 클레임은 정책 규칙과 모순됩니다. 조사 결과에는 위반된 규칙을 contradictingRules 보여주는 것이 포함됩니다. | 예상 결과인 경우 테스트가 통과합니다. 예기치 않은 경우 규칙이 올바른지 또는 번역에 잘못된 변수가 할당되었는지 확인합니다. contradictingRules를 검토하여 결과를 유발한 규칙을 파악합니다. |
| SATISFIABLE | 클레임은 정책과 일치하지만 모든 관련 규칙을 다루지는 않습니다. 응답은 일부 조건에서는 정확하지만 전부는 아닙니다. 결과에는 클레임이 true 및 false인 조건을 claimsTrueScenario claimsFalseScenario 보여주는 및가 모두 포함됩니다. | 두 시나리오를 비교하여 누락된 조건을 식별합니다. 이는 일반적으로 응답이 불완전하다는 것을 의미합니다. 잘못된 것은 아니지만 모든 요구 사항을 언급하지는 않습니다. 테스트에서 예상해야 하는지 SATISFIABLE 또는 응답이 더 완전해야 하는지 고려합니다. |
| IMPOSSIBLE | 온프레미스가 모순되거나 정책 자체에 충돌하는 규칙이 포함되어 있기 때문에 자동 추론 검사는 클레임을 평가할 수 없습니다. | 테스트 입력에 모순되는 문이 포함되어 있는지 확인합니다(예: "I'm full-time and also part-time"). 입력이 유효하면 정책에서 충돌이 발생할 수 있습니다. 품질 보고서에서 충돌하는 규칙을 확인하세요. [자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md)을(를) 참조하세요. |
| TRANSLATION\$1AMBIGUOUS | 자연어에서 공식 로직으로의 번역은 모호했습니다. 번역에 사용된 여러 LLMs 입력을 해석하는 방법에 대해 일치하지 않았습니다. 결과에는 의견 차이를 이해하는 데 도움이 되는 대체 해석이 포함되어 있습니다. | 이는 일반적으로 변수 설명 문제입니다. 대체 해석을 검토하여 불일치가 있는 위치를 파악한 다음 관련 변수 설명을 개선합니다. 일반적인 원인: 겹치는 변수, 모호한 설명 또는 모호한 입력 텍스트. [자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md)을(를) 참조하세요. |
| TOO\$1COMPLEX | 입력에 지연 시간 제한 내에서 자동 추론 검사를 처리하기에 너무 많은 정보가 포함되어 있습니다. | 테스트 입력을 간소화합니다. 문제가 지속되면 정책이 너무 복잡할 수 있습니다. 여러 개의 집중된 정책으로 분할하거나 비선형 산술과 관련된 규칙을 단순화하는 것이 좋습니다. |
| NO\$1TRANSLATIONS | 입력을 공식 로직으로 변환할 수 없습니다. 이는 일반적으로 입력이 정책의 도메인과 관련이 없거나 정책에 입력의 개념을 모델링하는 변수가 없음을 의미합니다. | 입력이 정책과 관련이 있어야 하는 경우 누락된 변수를 추가하고 규칙을 업데이트합니다. 입력이 실제로 비주제인 경우이 결과가 예상됩니다. 애플리케이션이 비주제 콘텐츠를 별도로 처리해야 합니다(예: 주제 정책 사용). |
### 실패한 테스트에 대한 팁 디버깅
테스트가 실패하면(실제 결과가 예상 결과와 일치하지 않음) 다음 접근 방식을 사용하여 문제를 진단합니다.
1. **먼저 번역을 확인합니다.** 조사 결과에서 온프레미스와 클레임을 살펴봅니다. 올바른 변수가 할당되나요? 값이 정확합니까? 변환이 잘못된 경우 규칙이 아닌 변수 설명에 문제가 있는 것입니다. 예를 들어 "2년"이 `tenureMonths = 2` 대신 로 변환된 경우 `tenureMonths = 24`변수 설명은 단위 변환을 지정해야 합니다.
1. **규칙을 확인합니다.** 번역이 정확해 보이면 정책 규칙에 문제가 있는 것입니다. 조사 결과`contradictingRules`에서 `supportingRules` 또는를 살펴보고 관련된 규칙을 식별합니다. 이를 소스 문서와 비교합니다.
1. **번역되지 않은 콘텐츠가 있는지 확인합니다.** `untranslatedPremises` 및를 살펴봅니다`untranslatedClaims`. 입력의 중요한 부분이 번역되지 않은 경우 이러한 개념을 캡처하기 위해 변수를 추가해야 할 수 있습니다.
1. **신뢰도 점수를 확인합니다.** 신뢰도 점수가 낮으면 번역 모델이 일치하지 않음을 나타냅니다. 이는 변수 설명이 이러한 유형의 입력에 대해 모호함을 시사합니다.
자세한 문제 해결 지침은 섹션을 참조하세요[자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md).
# 자동 추론 정책 문제 해결 및 구체화
실제 결과가 예상 결과와 일치하지 않는 자동 추론 정책 테스트가 실패하면 문제는 번역(자연어가 잘못된 변수 또는 값에 매핑됨) 또는 규칙(정책 로직이 도메인과 일치하지 않음)에 있습니다. 이 페이지에서는 두 가지 유형의 문제를 모두 진단하고 수정할 수 있는 체계적인 접근 방식을 제공합니다.
문제 해결을 시작하기 전에에 설명된 2단계 검증 프로세스(번역 후 검증)를 이해해야 합니다[번역: 자연어에서 공식 로직으로](automated-reasoning-checks-concepts.md#ar-concept-translation). 이러한 구분은 효율적인 디버깅의 핵심입니다.
**참고**
**자습서 비디오:** 다음 자습서를 시청하여 자동 추론 정책을 개선하고 문제를 해결하는 단계별 연습을 살펴봅니다.
[자습서 데모 3 - 자동 추론 정책 개선](https://youtu.be/YmohVGWr_PA)
## 워크플로 디버깅
테스트가 실패하면 실제 결과를 사용하여 문제의 유형을 식별하고 관련 섹션으로 이동합니다.
| 실제 결과 | 가능한 원인 | 살펴볼 위치 |
| --- | --- | --- |
| TRANSLATION\$1AMBIGUOUS | 변환 모델은 입력을 해석하는 방법에 동의하지 않았습니다. 일반적으로 겹치는 변수, 모호한 설명 또는 모호한 입력 텍스트로 인해 발생합니다. | [번역 문제 해결](#fix-translation-issues) |
| NO\$1TRANSLATIONS | 입력을 정책 변수에 매핑할 수 없습니다. 입력이 주제를 벗어나거나 정책에 언급된 개념에 대한 변수가 누락되었습니다. | [번역 문제 해결](#fix-translation-issues) |
| TOO\$1COMPLEX | 입력 또는 정책이 처리 한도를 초과합니다. 종종 비선형 산술 또는 상호 작용 규칙이 너무 많은 정책으로 인해 발생합니다. | [제한 사항 및 고려 사항](guardrails-automated-reasoning-checks.md#automated-reasoning-limitations) |
| IMPOSSIBLE | 온프레미스가 서로 모순되거나 정책 자체에 충돌하는 규칙이 포함되어 있습니다. | [불가능한 결과 수정](#fix-impossible-results) |
| VALID, INVALID또는 SATISFIABLE (예상한 것은 아님) | 먼저 조사 결과에서 번역을 확인합니다. 올바른 변수가 올바른 값으로 할당되면 규칙에서 문제가 발생합니다. 변환이 잘못된 경우 변수 설명에 문제가 있는 것입니다. | 번역 오류: [번역 문제 해결](#fix-translation-issues). 잘못된 규칙: [규칙 문제 해결](#fix-rule-issues). |
**작은 정보**
항상 먼저 번역을 확인합니다. 대부분의 경우 수학 검증(2단계)이 정확합니다. 문제는 자연어가 공식 로직(1단계)으로 변환된 방식입니다. 변수 설명 수정은 규칙을 변경하는 것보다 빠르고 위험도가 낮습니다.
## 번역 문제 해결
번역 문제는 자동 추론 검사가 자연어를 정책의 변수에 안정적으로 매핑할 수 없을 때 발생합니다. 가장 가시적인 증상은 `TRANSLATION_AMBIGUOUS` 결과이지만 잘못된 변수 또는 값이 할당되면 변환 문제로 인해 잘못된 `VALID``INVALID`, 또는 `SATISFIABLE` 결과가 발생할 수도 있습니다.
### TRANSLATION\$1AMBIGUOUS 결과 진단
`TRANSLATION_AMBIGUOUS` 결과에는 불일치를 이해하는 데 도움이 되는 두 가지 주요 필드가 포함되어 있습니다.
+ `options` - 경쟁 논리 해석(최대 2개). 각 옵션에는 온프레미스, 클레임 및 신뢰도가 포함된 자체 번역이 포함되어 있습니다. 옵션을 비교하여 번역 모델이 동의하지 않는 부분을 확인합니다.
+ `differenceScenarios` - 모호성의 실제 영향을 강조하는 변수 할당과 함께 다양한 해석의 의미를 보여주는 시나리오(최대 2개)입니다.
이러한 필드를 검토하여 특정 모호성 원인을 식별한 다음 다음 목록에서 적절한 수정 사항을 적용합니다.
### 겹치는 변수 정의
여러 변수가 동일한 개념을 합리적으로 나타낼 수 있는 경우, 번역 모델은 어떤 변수를 사용할지에 대해 불일치합니다.
**증상:** `TRANSLATION_AMBIGUOUS` 결과의는 다른 변수`options`에 할당된 것과 동일한 개념을 보여줍니다. 예를 들어 한 옵션은에 "2년 서비스"를 할당`tenureMonths = 24`하고 다른 옵션은에 할당합니다`monthsOfService = 24`.
**수정:** 겹치는 변수를 포괄적인 설명과 함께 단일 변수로 병합합니다. 나머지 변수를 사용하도록 삭제된 변수를 참조하는 모든 규칙을 업데이트합니다.
**예:**
| 이전(중첩) | 이후(병합됨) |
| --- | --- |
| `tenureMonths`: "직원이 몇 개월 동안 근무했는지" `monthsOfService`: "직원의 근무 월" | `tenureMonths`: "직원이 지속적으로 고용된 전체 개월 수입니다. 사용자가 서비스 연도를 언급하면 월로 변환합니다(예: 2년 = 24개월). 이 변수는 고용 기간, 근무 기간, 회사 근무 시간 또는 연공서에 대한 모든 참조를 캡처합니다.” (규칙을 삭제`monthsOfService`하고 업데이트합니다.) |
### 불완전한 변수 설명
사용자가 일상적인 언어로 개념을 참조하는 방법에 대한 세부 정보가 부족한 변수 설명으로 인해 입력을 올바른 변수에 매핑하기가 어렵습니다.
**증상:**는 올바른 변수를 `options` 표시하지만 값이 다르거나 번역은 사용자가 말한 것과 일치하지 않는 값을 할당합니다. 예를 들어 "2년"은 `tenureMonths = 2` 대신 로 변환됩니다`tenureMonths = 24`.
**수정:** 단위 변환 규칙, 동의어 및 대체 문구를 포함하도록 변수 설명을 업데이트합니다. 자세한 지침은 섹션을 참조[포괄적인 변수 설명 작성](automated-reasoning-policy-best-practices.md#bp-variable-descriptions)하세요.
**예:**
| 이전(미완료) | 이후(종합) |
| --- | --- |
| isFullTime: "정규직" | isFullTime: "직원이 정규직(true)인지 아니면 시간제(false)인지 여부. 사용자가 '정규 근무', '정규 근무' 또는 주당 40시간 이상 근무한다고 언급하면 true로 설정합니다. 사용자가 '파트 타임', '시간 단축' 또는 주당 40시간 미만'으로 언급하면 false로 설정합니다. |
### 일관되지 않은 값 형식 지정
번역 모호성은 시스템에서 숫자, 날짜 또는 백분율과 같은 값의 형식을 지정하는 방법을 잘 모르는 경우에 발생할 수 있습니다.
**증상:**는 동일한 변수를 `options` 표시하지만 값 형식은 다릅니다. 예를 들어 한 옵션은 "5%"를 로 변환`interestRate = 5`하고 다른 옵션은 로 변환합니다`interestRate = 0.05`.
**수정:** 변수 설명을 업데이트하여 예상 형식을 지정하고 변환 규칙을 포함합니다. [변수 설명에서 단위 및 형식 지정](automated-reasoning-policy-best-practices.md#bp-units-formats)을(를) 참조하세요.
### 모호한 입력 텍스트
입력 자체가 모호한 경우도 있습니다. 여기에는 모호한 대명사, 불분명한 참조 또는 여러 방식으로 해석할 수 있는 문이 포함되어 있습니다.
**증상:**는 동일한 텍스트에 대한 근본적으로 다른 해석을 `options` 보여줍니다. 예: "떠날 수 있나요?" 는 모든 직원 유형을 참조할 수 있습니다.
**수정:** 테스트인 경우 입력을 더 구체적으로 다시 작성합니다. 런타임 시 애플리케이션은 `TRANSLATION_AMBIGUOUS` 결과를 수신할 때 사용자에게 설명을 요청해야 합니다. 통합 패턴은 섹션을 참조하세요[애플리케이션에 자동 추론 검사 통합](integrate-automated-reasoning-checks.md).
### 신뢰도 임계값 조정
경계가 모호한 입력에 대한 `TRANSLATION_AMBIGUOUS` 결과가 표시되면 신뢰도 임계값을 조정할 수 있습니다. 임계값을 낮추면 모델 계약이 적은 번역을 검증으로 진행할 수 있으므로 `TRANSLATION_AMBIGUOUS` 결과가 줄어들지만 잘못된 번역의 위험이 높아집니다.
**중요**
임계값 조정은 최후의 수단이어야 합니다. 대부분의 경우 변수 설명을 개선하거나 겹치는 변수를 제거하는 것이 더 나은 해결 방법입니다. 근본 원인을 해결하기 때문입니다. 임계값 작동 방식에 대한 자세한 내용은 섹션을 참조하세요[신뢰도 임계값](automated-reasoning-checks-concepts.md#ar-concept-confidence-thresholds).
## 규칙 문제 해결
규칙 문제는 변환이 올바르지만 정책 로직이 도메인과 일치하지 않을 때 발생합니다. 올바른 변수가 올바른 값으로 할당되었음을 확인했지만 검증 결과는 여전히 잘못되었습니다.
### INVALID 예상 시 VALID 가져오기
정책에는 클레임을 금지하는 규칙이 없습니다. 응답은 도메인 지식과 모순되지만 정책은 이를 허용합니다.
**진단:** 조사 결과`supportingRules`에서를 살펴봅니다. 다음은 클레임이 유효함을 증명하는 규칙입니다. 이러한 규칙이 올바른지 또는 규칙이 누락되었는지 확인합니다.
**일반적인 원인 및 수정 사항:**
+ **규칙이 누락되었습니다.** 정책에이 조건을 다루는 규칙이 없습니다. 제약 조건을 캡처하는 새 규칙을 추가합니다. 예를 들어 정책에서 모든 정규직 직원에게 육아 휴가를 허용하지만 12개월의 재직 기간이 필요한 경우 다음을 추가합니다. `(=> (and isFullTime (<= tenureMonths 12)) (not eligibleForParentalLeave))`
+ **규칙이 너무 허용적입니다.** 기존 규칙은 예상보다 많은 것을 허용합니다. 규칙을 편집하여 누락된 조건을 추가합니다. 예를 들어를 `(=> isFullTime eligibleForParentalLeave)`로 변경합니다. `(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)`
+ **변수가 누락되었습니다.** 정책에는 관련 개념을 캡처하는 변수가 없습니다. 변수를 추가하고, 명확한 설명을 작성하고, 변수를 참조하는 규칙을 생성합니다.
### VALID 예상 시 INVALID 가져오기
정책에 클레임을 잘못 금지하는 규칙이 있습니다.
**진단:** 조사 결과`contradictingRules`에서를 살펴봅니다. 다음은 클레임을 거부하는 규칙입니다. 이러한 규칙이 올바른지 확인합니다.
**일반적인 원인 및 수정 사항:**
+ **규칙이 너무 제한적입니다.** 기존 규칙은 유효한 시나리오를 차단합니다. 규칙을 편집하여 조건을 완화하거나 예외를 추가합니다. 예를 들어 규칙에 24개월의 재임 기간이 필요하지만 정책에 12개만 필요한 경우 임계값을 업데이트합니다.
+ **규칙이 잘못 추출되었습니다.** 자동 추론 검사에서 소스 문서를 잘못 해석했습니다. 의도한 로직과 일치하도록 규칙을 편집하거나 규칙을 삭제하고 올바른 규칙을 수동으로 추가합니다.
### VALID가 예상될 때 만족하기
응답은 일부 조건에서는 정확하지만 전부는 아닙니다. 정책에는 응답이 다루지 않는 추가 규칙이 있습니다.
**진단:** 결과의 `claimsTrueScenario` 및 `claimsFalseScenario`를 비교합니다. 이들 간의 차이는 응답이 언급하지 않는 조건을 보여줍니다.
**일반적인 원인 및 수정 사항:**
+ **응답이 불완전합니다.** 테스트 출력에는 정책에 필요한 모든 조건이 언급되어 있지 않습니다. 누락된 조건을 포함하도록 테스트 출력을 업데이트하거나 불완전한 응답이 사용 사례에 적합한 `SATISFIABLE` 경우 예상 결과를 로 변경합니다.
+ **정책에 불필요한 규칙이 있습니다.** 이 정책에는이 시나리오와 관련이 없는 조건이 필요합니다. 추가 규칙을 적용해야 하는지 검토하고 적용하지 않으면 제거합니다.
## 불가능한 결과 수정
`IMPOSSIBLE` 결과는 온프레미스가 모순되거나 정책 자체에 충돌하는 규칙이 포함되어 있기 때문에 자동 추론 검사가 클레임을 평가할 수 없음을 의미합니다. 두 가지 고유한 원인이 있습니다.
### 입력의 모순
테스트 입력에는 서로 모순되는 문이 포함되어 있습니다. 예를 들어 "I'm a full-time employee and also part-time"은 `isFullTime = true` 및를 `isFullTime = false` 동시에 설정하므로 논리적으로 불가능합니다.
**진단:** 조사 결과에서 `translation` 온프레미스를 검사합니다. 모순되는 값이 할당된 변수를 찾습니다.
**수정:** 테스트인 경우 입력을 다시 작성하여 모순을 제거합니다. 런타임 시 애플리케이션은 사용자에게 입력을 명확히 하도록 요청하여 `IMPOSSIBLE` 결과를 처리해야 합니다.
### 정책의 충돌
정책에는 서로 모순되는 규칙이 포함되어 있으므로 자동 추론 검사가 충돌하는 규칙과 관련된 입력에 대한 결론에 도달할 수 없습니다.
**진단:** 입력이 유효하면(상반되는 온프레미스 없음) 정책에 문제가 있는 것입니다. 결과의 `contradictingRules` 필드를 확인하여 충돌하는 규칙을 식별합니다. 또한 품질 보고서를 확인합니다( 참조[품질 보고서 사용](#use-quality-report)). 충돌하는 규칙에 자동으로 플래그를 지정합니다.
**일반적인 원인 및 수정 사항:**
+ **모순되는 규칙.** 두 규칙은 동일한 조건에 대해 반대 결론에 도달합니다. 예를 들어 한 규칙은 정규직 직원에게 휴가 자격이 있다고 하고, 다른 규칙은 첫 해에 정규직 직원에게 어떤 일이 발생하는지 지정하지 않고 첫 해의 직원에게는 자격이 없다고 합니다. 규칙을 명시적 조건의 단일 규칙으로 병합합니다. `(=> (and isFullTime (> tenureMonths 12)) eligibleForLeave)`
+ **베어 어설션.** 와 같은 베어 어설션`(= eligibleForLeave true)`을 사용하면 입력에서 사용자가 적합하지 않다고 주장할 수 *없습니다*. 베어 어설션을 영향으로 다시 작성합니다. [영향(=>)을 사용하여 규칙 구성](automated-reasoning-policy-best-practices.md#bp-use-implications)을(를) 참조하세요.
+ **순환 종속성.** 논리적 루프를 생성하는 방식으로 서로 의존하는 규칙입니다. 규칙을 단순화하여 주기를 해제하거나 중간 변수를 사용하여 로직을 명시적으로 만듭니다.
## 주석을 사용하여 정책 복구
주석은 테스트가 실패할 때 정책에 적용하는 대상 수정입니다. 규칙 및 변수를 수동으로 편집하는 대신 주석을 사용하여 원하는 변경 사항을 설명하고 자동 추론 검사가 이를 적용하도록 할 수 있습니다. 주석은 콘솔과 API를 통해 사용할 수 있습니다.
### 콘솔에서 주석 적용
1. 실패한 테스트를 열고 결과를 검토하여 문제를 이해합니다.
1. 테스트 조건을 수정하고(예: 온프레미스 추가 또는 예상 결과 변경) 테스트를 다시 실행합니다. 수정된 테스트가 예상한 결과를 반환하는 경우이 수정을 주석으로 적용할 수 있습니다.
1. **주석 적용을** 선택합니다. 자동 추론 검사는 피드백에 따라 정책에 변경 사항을 적용하는 빌드 워크플로를 시작합니다.
1. **정책 변경 사항 검토** 화면에서 정책의 규칙, 변수 및 유형에 대해 제안된 변경 사항을 검토합니다. 그런 다음 **변경 사항 수락**을 선택합니다.
### API를 사용하여 주석 적용
`StartAutomatedReasoningPolicyBuildWorkflow` API를와 함께 사용하여 프로그래밍 방식으로 주석을 `REFINE_POLICY` 적용합니다. 주석과 함께 전체 현재 정책 정의를 전달합니다.
주석 유형은 다음과 같습니다.
+ **변수 주석:** `addVariable`, `updateVariable`, `deleteVariable`- 누락된 변수를 추가하거나, 설명을 개선하거나, 중복을 제거합니다.
+ **규칙 주석:** `addRule`, `updateRule`, `deleteRule`, `addRuleFromNaturalLanguage`- 잘못된 규칙을 수정하거나, 누락된 규칙을 추가하거나, 충돌하는 규칙을 제거합니다. `addRuleFromNaturalLanguage`를 사용하여 규칙을 일반 영어로 설명하고 자동 추론 검사를 통해 공식 로직으로 변환할 수 있습니다.
+ **유형 주석:** `addType`, `updateType`, `deleteType`- 사용자 지정 유형( 열거형)을 관리합니다.
+ **피드백 주석:** `updateFromRulesFeedback`, `updateFromScenarioFeedback`- 특정 규칙 또는 시나리오에 대한 자연어 피드백을 제공하고 자동 추론 검사를 통해 필요한 변경 사항을 추론할 수 있습니다.
**예: 주석을 사용하여 누락된 변수 및 규칙 추가**
```
aws bedrock start-automated-reasoning-policy-build-workflow \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--build-workflow-type REFINE_POLICY \
--source-content "{
\"policyDefinition\": EXISTING_POLICY_DEFINITION_JSON,
\"workflowContent\": {
\"policyRepairAssets\": {
\"annotations\": [
{
\"addVariable\": {
\"name\": \"tenureMonths\",
\"type\": \"int\",
\"description\": \"The number of complete months the employee has been continuously employed. When users mention years of service, convert to months (for example, 2 years = 24 months).\"
}
},
{
\"addRuleFromNaturalLanguage\": {
\"naturalLanguage\": \"If an employee is full-time and has more than 12 months of tenure, then they are eligible for parental leave.\"
}
}
]
}
}
}"
```
### 주석 예제
**예제 1: 누락된 재직 기간 요구 사항 수정**
문제: 정책은 모든 정규직 직원의 육아 휴가를 승인하지만 소스 문서에는 12개월 이상의 재직 기간이 필요합니다.
| Before | 주석 이후 |
| --- | --- |
| 규칙: `(=> isFullTime eligibleForParentalLeave)` `tenureMonths` 변수가 없습니다. | 새 변수: `tenureMonths` (int) - "직원이 지속적으로 고용된 전체 개월 수" 업데이트된 규칙: `(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)` |
**예제 2: TRANSLATION\$1AMBIGUOUS를 유발하는 중복 변수 수정**
문제: 두 변수(`tenureMonths` 및 `monthsOfService`)는 동일한 개념을 나타내며 일관되지 않은 번역을 일으킵니다.
주석:
1. `deleteVariable`(`monthsOfService`일 때)
1. `updateVariable` 사용자가 고용 기간을 참조할 수 있는 모든 방법을 다루는 개선된 설명이 `tenureMonths` 포함된 용 .
1. `updateRule`를 참조한 모든 규칙에 대해 `monthsOfService`를 사용하도록 변경합니다`tenureMonths`.
**예제 3: 잘못된 결과를 유발하는 베어 어설션 수정**
문제: 규칙`(= eligibleForParentalLeave true)`은 모든 입력이 사용자가 적합하지 않다고 주장할 수 없도록 하는 베어 어설션입니다.
주석:
1. `deleteRule` 베어 어설션에 대한 입니다.
1. `addRuleFromNaturalLanguage`: “직원이 정규직이고 재직 기간이 12개월 이상인 경우 육아 휴가 자격이 있습니다.”
## 품질 보고서 사용
품질 보고서는 각 빌드 워크플로 후에 생성되며 테스트 실패를 일으킬 수 있는 정책의 구조적 문제를 식별합니다. 콘솔에서 품질 보고서 문제는 **정의** 페이지에 경고로 표시됩니다. API를 통해를 `GetAutomatedReasoningPolicyBuildWorkflowResultAssets`와 함께 사용합니다`--asset-type QUALITY_REPORT`.
품질 보고서에는 다음 문제가 플래그로 표시됩니다.
### 충돌하는 규칙
두 개 이상의 규칙이 동일한 조건 집합에 대해 모순되는 결론에 도달합니다. 충돌하는 규칙으로 인해 충돌하는 규칙과 관련된 모든 검증 요청에 `IMPOSSIBLE` 대해 정책이 반환됩니다.
**예:** 규칙 A는 `(=> isFullTime eligibleForLeave)`를 나타내고 규칙 B는를 나타냅니다`(=> (<= tenureMonths 6) (not eligibleForLeave))`. 재직 기간이 3개월인 정규직 직원의 경우 규칙 A는 자격이 있다고 하고 규칙 B는 자격이 없다고 하는데, 이는 모순입니다.
**수정:** 규칙을 명시적 조건이 있는 단일 규칙으로 병합합니다`(=> (and isFullTime (> tenureMonths 6)) eligibleForLeave)`. 또는 충돌하는 규칙 중 하나를 잘못 추출한 경우 삭제합니다.
### 미사용 변수
규칙에서 참조하지 않는 변수입니다. 사용하지 않는 변수는 번역 프로세스에 노이즈를 추가하며 동일한 개념에 대해 유사한 활성 변수와 경쟁할 때 `TRANSLATION_AMBIGUOUS` 결과를 초래할 수 있습니다.
**수정:** 향후 반복에서 참조하는 규칙을 추가하려는 경우가 아니면 사용하지 않는 변수를 삭제합니다.
### 미사용 유형 값
규칙에서 참조하지 않는 사용자 지정 유형( 열거형)의 값입니다. 예를 들어 `LeaveType` 열거형에 PARENTAL, MEDICAL, BEREAVEMENT 및 PERSONAL 값이 있지만 개인을 참조하는 규칙이 없는 경우 사용되지 않은 것으로 플래그가 지정됩니다.
**수정 사항:** 사용하지 않는 값을 참조하는 규칙을 추가하거나 열거형에서 제거합니다. 입력에서 개념을 언급하지만 이를 처리하는 규칙이 없는 경우 사용하지 않는 값으로 인해 번역 문제가 발생할 수 있습니다.
### 연결 해제 규칙 세트
변수를 공유하지 않는 규칙 그룹입니다. 분리된 규칙 세트는 반드시 문제가 되는 것은 아닙니다. 정책은 의도적으로 독립적인 주제(예: 휴가 자격 및 비용 환급)를 포함할 수 있습니다. 그러나 변수에 관련 규칙 간의 연결이 누락되었음을 나타낼 수 있습니다.
**조치 시기:** 결합 해제 규칙 세트가 관련되어야 하는 경우(예: 둘 다 직원 혜택을 처리하지만 동일한 개념에 다른 변수 이름을 사용함) 겹치는 변수를 병합하여 연결합니다. 규칙 세트가 실제로 독립된 경우 별도의 조치가 필요하지 않습니다.
## 정책 구체화에 Kiro CLI 사용
Kiro CLI는 정책 문제를 진단하고 수정할 수 있는 대화형 채팅 인터페이스를 제공합니다. 자연어 대화를 통해 정책 정의 및 품질 보고서를 로드하고, 테스트가 실패하는 이유를 설명하고, 변경 사항을 제안하고, 주석을 적용할 수 있습니다.
Kiro CLI는 다음과 같은 경우에 특히 유용합니다.
+ **실패에 대한 이해.** Kiro CLI에 실패한 테스트를 로드하도록 요청하고 예상 결과를 반환하지 않는 이유를 설명합니다. Kiro CLI는 정책 정의, 테스트 결과 및 품질 보고서를 분석하여 근본 원인을 식별합니다.
+ **품질 보고서 문제 해결.** Kiro CLI에 품질 보고서를 요약하고 충돌하는 규칙, 미사용 변수 및 중첩되는 변수 설명에 대한 수정 사항을 제안하도록 요청합니다.
+ **규칙 변경을 제안합니다.** 예상되는 동작을 설명하고 Kiro CLI에 필요한 변수 및 규칙 변경을 제안하도록 요청합니다. 제안을 검토하고 Kiro CLI에 주석으로 적용하도록 지시합니다.
**워크플로 예제:**
```
You: The test with ID test-12345 is not returning the expected result.
Can you load the test definition and findings, look at the policy
definition, and explain why this test is failing?
Kiro: [analyzes the test and policy] The test expects VALID but gets
INVALID because rule R3 requires 24 months of tenure, while the
test input specifies 18 months. The source document says 12 months.
Rule R3 appears to have been misextracted.
You: Can you suggest changes to fix this?
Kiro: I suggest updating rule R3 to change the tenure threshold from 24
to 12 months. Here's the updated rule: ...
You: Looks good. Can you use the annotation APIs to submit these changes?
Kiro: [applies annotations via the API]
```
자동 추론 정책과 함께 Kiro CLI를 설정하고 사용하는 방법에 대한 전체 지침은 섹션을 참조하세요[자동 추론 정책과 함께 Kiro CLI 사용](kiro-cli-automated-reasoning-policy.md).
# 자동 추론 정책과 함께 Kiro CLI 사용
Kiro CLI를 사용하여 자동 추론 정책에 대해 질문하고, 다양한 규칙의 동작을 이해하고, 정책 자체의 실패한 테스트 또는 모호성을 해결하는 변경을 요청할 수 있습니다. Kiro CLI는 정책 정의를 로드하고, 테스트 결과를 분석하고, 자연어 대화를 통해 주석을 적용할 수 [자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md) 있으므로에 설명된 반복 세분화 워크플로에 특히 유용합니다.
## 사전 조건
자동 추론 정책과 함께 Kiro CLI를 사용하려면 먼저 다음 단계를 완료해야 합니다.
+ 최신 버전의 [Kiro CLI](https://kiro.dev/cli/)를 설치합니다.
+ AWS CLI의 최신 버전을 설치합니다.
+ 콘솔 또는 APIs를 통해 문서를 사용하여 자동 추론 정책을 생성합니다. 빠르게 시작하려면 콘솔의 기본 제공 샘플 홈워크 정책을 사용합니다. 자세한 내용은 [자동 추론 정책 생성](create-automated-reasoning-policy.md) 단원을 참조하십시오.
+ 자동 추론 검사 개념, 특히 정책, 규칙, 변수 및 조사 결과를 숙지합니다. 자세한 내용은 [자동 추론 검사 개념](automated-reasoning-checks-concepts.md) 단원을 참조하십시오.
+ 에 제공된 컨텍스트 프롬프트의 콘텐츠를 복사[자동 추론 정책 API 컨텍스트 프롬프트](#kiro-cli-context-prompt)하여 프로젝트 폴더의 마크다운 파일에 저장합니다. 이 프롬프트는 Kiro CLI가 자동 추론 정책 컨트롤 플레인을 사용하고 API를 올바르게 테스트하는 데 도움이 됩니다.
**참고**
아래 프롬프트 예제에서는 샘플 숙제 정책을 사용합니다. 프롬프트는 다른 정책과 마찬가지로 작동해야 하며 강조 표시된 주제를 변경하기만 하면 됩니다.
**참고**
자동화된 추론 정책은 복잡할 수 있으며 Kiro CLI가 복잡한 논리적 구조를 통해 추론해야 합니다. 최상의 성능을 위해 Anthropic Sonnet 4.5와 같은 더 큰 LLMs 사용하는 것이 좋습니다. Kiro CLI에서 모델을 변경하려면 `/model` 명령을 사용합니다.
## 시작하기
Kiro CLI를 사용하여 워크플로를 시작하려면 생성한 자동 추론 정책의 ARN이 필요합니다.
1. 콘솔을 사용하여 자동 추론 정책을 열고 **정책 개요** 페이지에서 **정책 세부 정보** 탭을 엽니다.
1. **정책 세부 정보** 탭에서 정책 ARN을 찾아 클립보드에 복사합니다.
1. 터미널을 사용하여 다음 명령을 사용하여 Kiro CLI 세션을 시작합니다.
```
kiro-cli
```
1. 첫 번째 프롬프트에서 Kiro에게 사전 조건의 일부로이 페이지에서 복사한 마크다운 파일에 대한 지침을 찾도록 요청합니다. 예제:
```
We will be using Automated Reasoning checks control plane APIs. I have saved an instructions file called your_file_name.md in this folder. Read this file as it will give you the context you need to work with the APIs.
```
1. Kiro CLI가 자동 추론 검사의 APIs를 로드하고 이해한 후 정책의 최신 빌드를 로드하고 탐색을 시작하도록 요청합니다. 복사한 ARN과 함께 다음 프롬프트의 변형을 사용합니다.
```
Load the policy assets for the latest build of the policy with ARN YOUR_POLICY_ARN. Make sure you understand the policy with all its rules and variables. Give a high-level description of the policy and the type of content it is capable of validating.
```
이때 Kiro CLI는 정책의 규칙 및 변수에 대한 간략한 설명을 제공해야 합니다. 또한 Kiro CLI는 정책 품질 보고서를 로드하고 미사용 유형 및 변수와 같은 문제를 요약해야 합니다.
## 정책 문제 해결
Kiro CLI를 사용하여 정책 보고서에 보고된 정책 문제를 해결할 수 있습니다. 먼저 Kiro에게 품질 보고서 요약을 제공하도록 요청합니다.
```
Can you give me a summary of the quality report for this policy?
```
품질 보고서에는 미사용 변수, 충돌하는 규칙, 연결 해제된 규칙 및 정책의 기타 잠재적 문제 목록이 포함됩니다. 품질 보고서 해석에 대한 자세한 내용은 섹션을 참조하세요[품질 보고서 사용](address-failed-automated-reasoning-tests.md#use-quality-report).
규칙이 충돌하면 정책이 모든 검증 요청에 로 응답`IMPOSSIBLE`합니다. 충돌하는 규칙과 이를 해결하는 방법에 대한 자세한 내용은 섹션을 참조하세요[정책의 충돌](address-failed-automated-reasoning-tests.md#fix-impossible-policy-conflicts). Kiro CLI에 충돌을 설명하고 솔루션을 제안하도록 요청할 수 있습니다.
```
Can you look at the conflicting rules, explain how they are used in the policy, why they conflict, and suggest a change such as deleting one of the rules or merging the logic from the two into a single rule?
```
사용되지 않는 변수로 인해 검증 결과가 `TRANSLATION_AMBIGUOUS` 결과를 반환할 수 있습니다. 미사용 변수가 문제를 일으키는 이유에 대한 자세한 내용은 섹션을 참조하세요[사용되지 않는 변수](automated-reasoning-policy-best-practices.md#bp-anti-unused-variables). Kiro CLI에이 문제에 대한 도움을 요청할 수 있습니다.
```
I see the quality report lists some unused variables, can you get rid of them?
```
마찬가지로 의미상 유사한 모호한 변수로 인해 검증 결과가 `TRANSLATION_AMBIGUOUS` 결과를 반환할 수 있습니다. 겹치는 변수와 이를 수정하는 방법에 대한 자세한 내용은 [겹치는 변수](automated-reasoning-policy-best-practices.md#bp-anti-overlapping-variables) 및 섹션을 참조하세요[겹치는 변수 정의](address-failed-automated-reasoning-tests.md#fix-overlapping-variables). Kiro CLI에이 문제에 대한 도움을 요청할 수 있습니다.
```
Automated Reasoning checks translate input natural language into logical statements that use the schema of variables from the policy. Variables that are semantically similar - ambiguous - can cause issues with inconsistent translations. Can you take a look at the schema of variables and help me identify variables that have potentially overlapping meanings? If you find any, suggest changes like removing one of them or merging them. Variable changes are also likely to require corresponding rule changes.
```
**참고**
일부 변경 사항을 처리한 후 Kiro CLI는 변경 사항 적용 확인을 요청합니다. 이때 Bedrock 콘솔 사용자 인터페이스를 사용하여 diff 화면에서 제안된 변경 사항을 검토할 수 있습니다. 콘솔을 사용하여 변경 사항을 검토하고 승인하는 경우 정책 정의의 최신 빌드를 다시 로드하도록 Kiro CLI에 알리는 것을 잊지 마세요.
## 정책과의 상호 작용
Kiro CLI를 사용하여 정책을 탐색할 수 있습니다. 예를 들어 Kiro CLI에 특정 영역과 관련된 정책 규칙을 요약하도록 요청할 수 있습니다. 샘플 숙제 정책을 예로 들어 Kiro CLI에 수학 숙제를 구체적으로 제약하는 규칙에 대해 알려주도록 요청할 수 있습니다.
```
Can you tell me about the rules that constrain math homework? Explain the rules themselves and how they fit in the broader policy.
```
Kiro CLI를 사용하여 정책에 기능을 추가할 수도 있습니다. 자동 추론 정책은 종종 사용자 의도를 캡처하는 일부 주요 출력 변수를 다룹니다. 예를 들어 샘플 숙제 제출 정책은 `isSubmissionAcceptable` 변수를 규칙의 출력으로 사용합니다. Kiro CLI를 사용하여 정책을 변경하여 다른 가능한 사용자 질문을 캡처할 수 있습니다. 새 규칙을 추가할 때는 [자동 추론 정책 모범 사례](automated-reasoning-policy-best-practices.md), 특히에 설명된 모범 사례를 따르십시오[영향(=>)을 사용하여 규칙 구성](automated-reasoning-policy-best-practices.md#bp-use-implications).
## 정책 편집 또는 수정
정책이 사용자의 특정 질문을 검증할 수 있는지 Kiro CLI에 문의할 수 있습니다. 예를 들어 숙제 정책은 숙제 제출이 허용되는지 여부를 결정하는 데 중점을 둡니다. 다음 질문을 통해 Kiro CLI에서 긍정적인 답변을 기대할 수 있습니다.
```
Can this policy validate answers about whether homework submissions are acceptable?
```
샘플 숙제 정책에서 숙제 제출 지연에 대해 질문하는 경우 Kiro CLI는 정책이 다음 질문에 답할 수 없다고 설명합니다.
```
Can this policy validate answers about permissible delays in homework submissions?
```
Kiro CLI는 정책이 수행할 수 있는 작업과 수행할 수 없는 작업을 설명합니다.
```
> Yes, but with limitations. The policy can validate whether a late submission is acceptable, but it cannot answer general questions about permissible delays.
What it CAN validate:
- Whether a specific late submission is acceptable given the circumstances
- Example: "Student submitted 2 days late with a doctor's note because they were sick before the deadline" → The policy will determine if this is acceptable (it would be)
What it CANNOT validate:
- General questions like "How many days late can a student submit homework?"
- Questions about delay policies without specific submission details
- Hypothetical scenarios without concrete variable values
The late submission logic:
The policy allows late submissions (submissionDate > 0) ONLY if:
1. The student has a valid doctor's note (hasDoctorNote = true), AND
2. The student was sick before the original deadline (wasSickPriorToDeadline = true)
Without both conditions met, any submission after the due date (submissionDate > 0) is automatically rejected.
So it's designed to validate specific submission instances against the rules, not to answer policy interpretation questions.
```
정책에서 수행할 수 없는 작업을 발견하면 다음 프롬프트를 사용하여이 정보를 캡처하도록 Kiro CLI에 정책을 업데이트하도록 요청할 수 있습니다.
```
I would like the policy to also validate answers about by how many days homework submissions can be delayed. Homework submissions accompanied by a doctor note can be up to 7 days late. Suggest the necessary variables and rules to capture these new questions.
```
이 프롬프트에 대한 응답으로 Kiro CLI는 새로운 유형의 질문을 검증하기 위해 정책에 추가할 수 있는 변수 및 규칙 세트를 제안합니다. 제안을 검토하고 의도와 일치하는 경우 Kiro CLI에 자동 추론 검사의 주석 APIs를 사용하여 정책을 다음과 같이 변경하도록 지시할 수 있습니다.
```
Looks good. Can you use the annotation APIs to submit these changes to the policy.
```
Kiro CLI에서 주석이 준비되었음을 확인하면 콘솔에서 정책을 열어 주석을 검토할 수 있습니다. 주석이 올바른 경우 **주석 적용을** 선택합니다.
주석을 적용한 후 Kiro CLI에 정책의 최신 빌드를 다시 로드하도록 요청하여 Kiro CLI가 현재 복사본으로 작업하고 있는지 확인합니다.
```
I applied the annotations. Reload the latest build of the policy.
```
## 실패한 테스트 해결
자동 추론 정책이 애플리케이션에서 생성된 자연어를 검증할 수 있는지 테스트하는 좋은 방법은 테스트를 사용하는 것입니다. 예상 결과와 함께 테스트 Q&A를 생성한 후 Kiro CLI를 사용하여 테스트가 예상 결과를 반환하지 않은 이유를 이해하고 정책을 조정할 수 있습니다. 테스트 생성 및 실행에 대한 자세한 내용은 섹션을 참조하세요[자동 추론 정책 테스트](test-automated-reasoning-policy.md). Kiro CLI 없이 테스트 실패를 진단하는 체계적인 접근 방식은 섹션을 참조하세요[자동 추론 정책 문제 해결 및 구체화](address-failed-automated-reasoning-tests.md).
1. 첫 번째 단계로 실패한 테스트를 로드하도록 Kiro CLI에 요청하고 정책 정의를 기반으로 예상 결과를 반환하지 않는 이유를 설명합니다. 콘솔 또는 APIs를 사용하여 실패한 테스트의 테스트 ID를 복사합니다. 콘솔에서 테스트 ID는 테스트를 나열하는 테이블과 각 테스트의 세부 정보 페이지에서 모두 사용할 수 있습니다.
```
The test with ID YOUR_TEST_ID is not returning the expected result. Can you load the test definition and findings, look at the policy definition, and explain why this test is failing.
```
1. Kiro CLI의 설명은 정책이 올바른 작업을 수행하고 있는지(그리고 테스트에 대한 예상 결과를 변경해야 하는지) 또는 정책이 잘못된지에 대한 지침을 제공합니다. 테스트가 예상 결과를 반환하도록 Kiro CLI에 정책 변경을 제안하도록 요청할 수 있습니다.
```
Can you suggest changes to the policy to ensure this test returns the expected result? Explain why you are suggesting these changes. Only create rules in if/then format.
```
**참고**
규칙 변경을 제안할 때 Kiro CLI는 특정 예제에 과적합을 시도하고 다른 사용 사례에서 유용하지 않은 규칙을 만들 수 있습니다. 테스트 출력을 확인하고 올바른 문제에 집중하도록 Kiro CLI 지침을 제공합니다. 효과적인 규칙 작성에 대한 지침은 섹션을 참조하세요[자동 추론 정책 모범 사례](automated-reasoning-policy-best-practices.md).
예를 들어 `SATISFIABLE` 테스트가를 반환하도록 Kiro에 샘플 홈워크 정책을 변경하도록 요청하면 Kiro는를 나타내는 규칙 생성과 같이 테스트를 항상 통과하도록 하는 정책에 액시옴을 추가할 것을 제안할 `VALID`수 있습니다`(false isHomeworkSubmissionAcceptable)`. 이렇게 하면 값이 항상 false가 됩니다. 이렇게 하면 문제가 있는 테스트가 기술적으로 해결되지만 전체 정책 기능에는 해가 됩니다. `SATISFIABLE` 테스트 결과에서 반환된 시나리오를 분석하면가 Kiro CLI에 테스트에 지정된 제약 조건만 포함하는 새 규칙을 생성하거나 기존 규칙을 업데이트하여 테스트 제약 조건만 확인하도록 더 나은 지침을 제공한다는 것을 알 수 있습니다.
1. 제안된 변경 사항에 만족하면 Kiro CLI에 주석을 제출하고 콘솔 사용자 인터페이스를 사용하여 검토하도록 요청합니다.
```
Looks good. Can you start a build workflow to apply these changes to the policy.
```
1. 변경 사항을 적용하고 다음 실패 테스트로 이동한 후 Kiro CLI에 정책의 최신 빌드를 다시 로드하도록 요청합니다.
```
I applied the changes. Reload the latest build of the policy.
```
## 다음 단계
자동 추론 정책에 만족하면 Amazon Bedrock Guardrails에서 사용할 수 있도록 배포할 수 있습니다. 자세한 내용은 [애플리케이션에 자동 추론 정책 배포](deploy-automated-reasoning-policy.md) 단원을 참조하십시오.
정책을 배포한 후 런타임 시 자동 추론 검사를 사용하여 LLM 응답을 검증하고 피드백에 따라 조치를 취하는 방법에 [애플리케이션에 자동 추론 검사 통합](integrate-automated-reasoning-checks.md) 대한 지침은 섹션을 참조하세요.
## 자동 추론 정책 API 컨텍스트 프롬프트
다음 콘텐츠를 복사하여 Kiro CLI용 프로젝트 폴더의 마크다운 파일에 저장합니다. 이 프롬프트는 자동 추론 정책 APIs 올바르게 사용하는 데 필요한 컨텍스트를 Kiro CLI에 제공합니다.
```
# Automated Reasoning Policy APIs and Workflows
## Table of Contents
### Core APIs
- Policy Management
- Policy Versions
- Build Workflows
- Test Management
- Annotations & Scenarios
### Build Workflow Types
- INGEST_CONTENT Workflow
- REFINE_POLICY Workflow
- IMPORT_POLICY Workflow
- GENERATE_FIDELITY_REPORT Workflow
### Annotation Type Reference
- Type Management Annotations
- Variable Management Annotations
- Rule Management Annotations
- Natural Language Rule Creation
- Feedback-Based Updates
### Common Workflows
1. Getting Started (New Policy)
2. Building Policy from Document
3. Policy Development Cycle
4. REFINE_POLICY Workflow (Annotation-Based)
### Testing Workflow
1. Primary Approach: Scenarios API (Recommended)
2. Secondary Approach: Test Cases (User Experience)
3. Test Result Analysis and Troubleshooting
### Build Workflow Monitoring
- Check Build Status
- List Build History
- Best Practice: Clean Build Management
- Troubleshooting Build Failures
### Build Workflow Assets
- Asset Types
- Understanding Conflicting Rules
- Understanding Disjoint Rule Sets
- Advanced Quality Report Analysis
### Additional Topics
- Policy Version Export
- Key Concepts
- Important Format Requirements
- Policy Modeling Best Practices
- ARN Formats
## Core APIs
### Policy Management
- `create-automated-reasoning-policy` - Create initial policy (returns policy ARN). Supports optional `--description`, `--kms-key-id` (for encryption with a customer managed AWS KMS key), `--tags` (up to 200 tags), and `--client-request-token` (idempotency token).
- `get-automated-reasoning-policy` - Retrieve policy (DRAFT version by default with unversioned ARN). Returns `policyId`, `definitionHash`, and `kmsKeyArn` (if a KMS key was provided at creation).
- `update-automated-reasoning-policy` - Update DRAFT policy with new definition. Accepts optional `--name` and `--description` updates alongside `--policy-definition` (required).
- `delete-automated-reasoning-policy` - Delete policy. Supports optional `--force` flag: when true, deletes the policy and all its artifacts (versions, test cases, test results) without validation; when false (default), validates that all artifacts have been deleted first.
- `list-automated-reasoning-policies` - List all policies. Supports optional `--policy-arn` filter to list only versions of a specific policy.
### Policy Versions
- `create-automated-reasoning-policy-version` - Snapshot DRAFT into numbered version. Requires `--last-updated-definition-hash` (concurrency token from get/create/update response). Supports optional `--tags` (up to 200 tags) and `--client-request-token`.
- `export-automated-reasoning-policy-version` - Export specific policy version definition including rules, variables, and types.
### Build Workflows
- `start-automated-reasoning-policy-build-workflow` - Start build process. Valid `--build-workflow-type` values: `INGEST_CONTENT`, `REFINE_POLICY`, `IMPORT_POLICY`, `GENERATE_FIDELITY_REPORT`. Supports optional `--client-request-token` (idempotency token, passed as header).
- `get-automated-reasoning-policy-build-workflow` - Get build workflow status. Status values: `SCHEDULED`, `CANCEL_REQUESTED`, `PREPROCESSING`, `BUILDING`, `TESTING`, `COMPLETED`, `FAILED`, `CANCELLED`.
- `cancel-automated-reasoning-policy-build-workflow` - Cancel running build
- `delete-automated-reasoning-policy-build-workflow` - Delete build workflow. Requires `--last-updated-at` (concurrency token timestamp).
- `list-automated-reasoning-policy-build-workflows` - List build workflows
- `get-automated-reasoning-policy-build-workflow-result-assets` - Get compiled policy assets. Requires `--asset-type`. Valid asset types: `BUILD_LOG`, `QUALITY_REPORT`, `POLICY_DEFINITION`, `GENERATED_TEST_CASES`, `POLICY_SCENARIOS`, `FIDELITY_REPORT`, `ASSET_MANIFEST`, `SOURCE_DOCUMENT`. Supports optional `--asset-id` (required when retrieving `SOURCE_DOCUMENT` assets if multiple source documents were used; obtain from the `ASSET_MANIFEST`).
### Test Management
- `create-automated-reasoning-policy-test-case` - Create test case. Requires `--guard-content` and `--expected-aggregated-findings-result`. Supports optional `--query-content`, `--confidence-threshold` (Double, 0 to 1, minimum confidence level for logic validation), and `--client-request-token`.
- `get-automated-reasoning-policy-test-case` - Get test case details (includes `confidenceThreshold` if set)
- `update-automated-reasoning-policy-test-case` - Update test case. Requires `--guard-content`, `--expected-aggregated-findings-result`, and `--last-updated-at` (concurrency token). Supports optional `--query-content`, `--confidence-threshold`, and `--client-request-token`.
- `delete-automated-reasoning-policy-test-case` - Delete test case. Requires `--last-updated-at` (concurrency token).
- `list-automated-reasoning-policy-test-cases` - List test cases
- `start-automated-reasoning-policy-test-workflow` - Run tests against a completed build. Requires `--build-workflow-id` (the build workflow must show COMPLETED status). Supports optional `--test-case-ids` (array of test case IDs to run; if not provided, all tests for the policy are run) and `--client-request-token`.
- `get-automated-reasoning-policy-test-result` - Get test result for a specific test case. Requires `--build-workflow-id` and `--test-case-id`.
- `list-automated-reasoning-policy-test-results` - List test results. Requires `--build-workflow-id`.
### Annotations & Scenarios
- `get-automated-reasoning-policy-annotations` - Get policy annotations for a build workflow. Requires `--build-workflow-id`. Returns `annotations`, `annotationSetHash` (concurrency token), `buildWorkflowId`, `name`, `policyArn`, and `updatedAt`.
- `update-automated-reasoning-policy-annotations` - Update annotations for a build workflow. Requires `--build-workflow-id`, `--annotations` (array of annotation objects, max 10), and `--last-updated-annotation-set-hash` (concurrency token from get-annotations response). Returns updated `annotationSetHash`.
- `get-automated-reasoning-policy-next-scenario` - Get next test scenario
**Important**: Do NOT use `get-automated-reasoning-policy-annotations` or
`update-automated-reasoning-policy-annotations` for the `REFINE_POLICY` workflow. Annotations are passed directly in the `start-automated-reasoning-policy-build-workflow` call.
## Build Workflow Types
1. **INGEST_CONTENT** - Process documents to create/extract policy rules
2. **REFINE_POLICY** - Refine and improve existing policies using annotations
3. **IMPORT_POLICY** - Import policies from external sources
4. **GENERATE_FIDELITY_REPORT** - Generate a fidelity report for the policy
### INGEST_CONTENT Workflow
- **Purpose**: Extract policy rules from documents (PDF/TXT)
- **Input**: Documents + optional existing policy definition
- **Use Cases**: Document-to-policy conversion, incremental policy building
- **Content Structure**: `workflowContent.documents[]`
**CRITICAL: Complete Policy Definition for Incremental Building**
When adding documents to an existing policy, you must include the complete current policy definition:
```json
// CORRECT - Incremental policy building
{
"policyDefinition": {
"version": "1.0",
"types": [/* ALL existing types */],
"rules": [/* ALL existing rules */],
"variables": [/* ALL existing variables */]
},
"workflowContent": {
"documents": [/* New documents to process */]
}
}
```
### REFINE_POLICY Workflow
- **Purpose**: Iteratively improve policies with targeted modifications
- **Input**: Policy definition + annotations for specific changes
- **Use Cases**: Kiro CLI suggestions, test-driven improvements, feedback-based refinement
- **Content Structure**: `workflowContent.policyRepairAssets.annotations[]`
**CRITICAL: Complete Policy Definition Required**
ALL build workflows require the COMPLETE existing policy definition in the `policyDefinition` section, not just the changes you want to make.
**REFINE_POLICY Annotation Types:**
**Top-Level Annotations:**
- **Type Management**: `addType`, `updateType`, `deleteType`
- **Variable Management**: `addVariable`, `updateVariable`, `deleteVariable`
- **Rule Management**: `addRule`, `updateRule`, `deleteRule`
- **Natural Language Rules**: `addRuleFromNaturalLanguage`
- **Feedback-Based Updates**: `updateFromRulesFeedback`, `updateFromScenarioFeedback`
**Sub-Operations (only within `updateType`):**
- `addTypeValue`, `updateTypeValue`, `deleteTypeValue` - Used to modify values within an existing custom type
**important**: Only create rules in if/then format.
## Annotation Type Reference
### Type Management Annotations
#### `addType` - Create New Custom Type
```json
{
"addType": {
"name": "ApprovalStatus",
"description": "Status values for approval requests",
"values": [
{
"value": "PENDING",
"description": "Request is awaiting approval"
},
{
"value": "APPROVED",
"description": "Request has been approved"
},
{
"value": "REJECTED",
"description": "Request has been rejected"
}
]
}
}
```
#### `updateType` - Modify Existing Custom Type
```json
{
"updateType": {
"name": "ApprovalStatus",
"newName": "RequestStatus",
"description": "Updated status values for all request types",
"values": [
{
"addTypeValue": {
"value": "ESCALATED",
"description": "Request escalated to higher authority"
}
},
{
"updateTypeValue": {
"value": "PENDING",
"newValue": "WAITING",
"description": "Request is waiting for review"
}
},
{
"deleteTypeValue": {
"value": "REJECTED"
}
}
]
}
}
```
#### `deleteType` - Remove Custom Type
```json
{
"deleteType": {
"name": "ObsoleteType"
}
}
```
### Variable Management Annotations
#### `addVariable` - Create New Variable
```json
{
"addVariable": {
"name": "requestAmount",
"type": "real",
"description": "The monetary amount of the approval request in USD"
}
}
```
#### `updateVariable` - Modify Existing Variable
```json
{
"updateVariable": {
"name": "requestAmount",
"newName": "approvalAmount",
"description": "The monetary amount requiring approval in USD (updated description)"
}
}
```
#### `deleteVariable` - Remove Variable
```json
{
"deleteVariable": {
"name": "obsoleteVariable"
}
}
```
### Rule Management Annotations
#### `addRule` - Create New Rule (SMT-LIB)
```json
{
"addRule": {
"expression": "(=> (and (= userRole MANAGER) (< requestAmount 10000)) (not approvalRequired))"
}
}
```
#### `updateRule` - Modify Existing Rule
```json
{
"updateRule": {
"ruleId": "A1B2C3D4E5F6",
"expression": "(=> (and (= userRole MANAGER) (< requestAmount 5000)) (not approvalRequired))"
}
}
```
#### `deleteRule` - Remove Rule
```json
{
"deleteRule": {
"ruleId": "G7H8I9J0K1L2"
}
}
```
### Natural Language Rule Creation
#### `addRuleFromNaturalLanguage` - Convert Natural Language to Rule
```json
{
"addRuleFromNaturalLanguage": {
"naturalLanguage": "Managers can approve expense requests up to $5,000 without additional authorization. Senior managers can approve up to $25,000."
}
}
```
### Feedback-Based Updates
#### `updateFromRulesFeedback` - Improve Rules Based on Performance
```json
{
"updateFromRulesFeedback": {
"ruleIds": ["A1B2C3D4E5F6", "G7H8I9J0K1L2"],
"feedback": "These rules are too restrictive for emergency scenarios. Add exception handling for urgent requests with proper escalation paths."
}
}
```
#### `updateFromScenarioFeedback` - Improve Based on Test Scenarios
```json
{
"updateFromScenarioFeedback": {
"ruleIds": ["A1B2C3D4E5F6"],
"scenarioExpression": "(and (= requestType EMERGENCY) (= userRole MANAGER) (> requestAmount 10000))",
"feedback": "Emergency requests should have different approval thresholds. Current rule blocks legitimate emergency expenses."
}
}
```
**Important**: Do NOT use `get-automated-reasoning-policy-annotations` or `update-automated-reasoning-policy-annotations` for the `REFINE_POLICY` workflow. Annotations are passed directly in the `start-automated-reasoning-policy-build-workflow` call.
## Common Workflows
### 1. Getting Started (New Policy)
**CRITICAL: Always Create Policy First**
You must create a policy before starting any build workflows.
```bash
# Step 1: Create initial policy (REQUIRED FIRST STEP)
aws bedrock create-automated-reasoning-policy \
--region us-west-2 \
--name "YourPolicyName"
# Step 2: Extract the policyArn from the response above, then start build workflow
aws bedrock start-automated-reasoning-policy-build-workflow \
--region us-west-2 \
--policy-arn "arn:aws:bedrock:us-west-2:123456789012:automated-reasoning-policy/abcd1234efgh" \
--build-workflow-type INGEST_CONTENT \
--source-content
# Step 3: Get build results
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--region us-west-2 \
--policy-arn "arn:aws:bedrock:us-west-2:123456789012:automated-reasoning-policy/abcd1234efgh" \
--build-workflow-id
```
### 2. Building Policy from Document
**RECOMMENDED: Using CLI Input JSON File**
```bash
# Step 1: Encode PDF to base64 and create JSON file with base64 content
PDF_BASE64=$(base64 -i your-policy.pdf | tr -d '\n')
cat > ingest-policy.json << EOF
{
"policyArn": "arn:aws:bedrock:us-west-2:123456789012:automated-reasoning-policy/your-actual-policy-id",
"buildWorkflowType": "INGEST_CONTENT",
"sourceContent": {
"policyDefinition": {
"version": "1.0",
"types": [],
"rules": [],
"variables": []
},
"workflowContent": {
"documents": [
{
"document": "$PDF_BASE64",
"documentContentType": "pdf",
"documentName": "Company Policy Document",
"documentDescription": "Main policy document containing business rules and organizational guidelines."
}
]
}
}
}
EOF
# Step 2: Use the JSON file
aws bedrock start-automated-reasoning-policy-build-workflow \
--region us-west-2 \
--cli-input-json file://ingest-policy.json
```
### 3. Policy Development Cycle
```bash
# 1. Import/process policy definition
aws bedrock start-automated-reasoning-policy-build-workflow \
--build-workflow-type IMPORT_POLICY
# 2. Update DRAFT with processed definition
aws bedrock update-automated-reasoning-policy \
--policy-arn \
--policy-definition
# 3. Create versioned snapshot of DRAFT (definitionHash from step 2 response)
aws bedrock create-automated-reasoning-policy-version \
--policy-arn \
--last-updated-definition-hash
```
## Testing Workflow
### Primary Approach: Scenarios API (Recommended)
Use `get-automated-reasoning-policy-next-scenario` for comprehensive policy validation.
The Scenarios API is superior for testing because it:
- Tests formal logic directly - Validates policy rules work correctly
- AI-generated scenarios - Comprehensive coverage of edge cases and rule interactions
- Targets specific rules - Tests individual rules and combinations
- Always works - No natural language translation issues
- Intelligent test generation - AI understands policy logic deeply
```bash
# Generate intelligent test scenarios automatically
aws bedrock get-automated-reasoning-policy-next-scenario \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123"
```
### Secondary Approach: Test Cases (User Experience)
Use manual test cases to validate natural language translation.
```bash
# Create test cases for natural language validation
aws bedrock create-automated-reasoning-policy-test-case \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--guard-content "It is 2:30 PM on a clear day" \
--query-content "What color should the sky be?" \
--expected-aggregated-findings-result "VALID" \
--confidence-threshold 0.8
```
### Test Result Analysis and Troubleshooting
**Understanding Test Results:**
**Scenarios API Results:**
- `expectedResult: SATISFIABLE` - Policy logic works correctly
- API errors or logic conflicts - Policy needs fixing with REFINE_POLICY
**Common Test Case Failure Modes:**
1. **TRANSLATION_AMBIGUOUS**
- Problem: AI can't map natural language to policy variables
- Solution: Improve variable descriptions with more natural language synonyms
2. **SATISFIABLE when expecting VALID**
- Problem: Your expected result label is likely WRONG, not the policy
- SATISFIABLE = "This scenario is logically consistent with the policy rules"
- VALID = "This is the correct/expected answer according to the policy"
- Solution: Change `expectedAggregatedFindingsResult` from `VALID` to `SATISFIABLE`
3. **Empty testFindings arrays**
- Problem: Translation issues, not rule violations
- Solution: Focus on improving natural language descriptions, not policy logic
**Valid values for `expectedAggregatedFindingsResult`:**
- `VALID` - The claims are true, implied by the premises and the policy
- `INVALID` - The claims are false, not implied by the premises and policy
- `SATISFIABLE` - The claims can be true or false depending on assumptions
- `IMPOSSIBLE` - Automated Reasoning can't make a statement (e.g., conflicting policy rules)
- `TRANSLATION_AMBIGUOUS` - Ambiguity in translation prevented validity checking
- `TOO_COMPLEX` - Input too complex for Automated Reasoning to process within latency limits
- `NO_TRANSLATION` - Some or all of the input wasn't translated into logic
### Running Tests Against a Build
After creating test cases, run them against a completed build workflow:
```bash
# Run all tests against a completed build
aws bedrock start-automated-reasoning-policy-test-workflow \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123"
# Run specific tests only
aws bedrock start-automated-reasoning-policy-test-workflow \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--test-case-ids '["A1B2C3D4E5F6"]'
# Get result for a specific test case
aws bedrock get-automated-reasoning-policy-test-result \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--test-case-id "A1B2C3D4E5F6"
# List all test results for a build
aws bedrock list-automated-reasoning-policy-test-results \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123"
```
## Build Workflow Monitoring
**Critical Build Limits**: The API supports maximum 2 total build workflows per policy, with only 1 allowed to be IN_PROGRESS at any time. When a build workflow completes, you can instruct the user to review the output using the console.
### Check Build Status
```bash
aws bedrock get-automated-reasoning-policy-build-workflow \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123"
```
### List Build History
```bash
aws bedrock list-automated-reasoning-policy-build-workflows \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--max-results 50
```
### Best Practice: Clean Build Management
```bash
# 1. Check existing builds before starting new ones
aws bedrock list-automated-reasoning-policy-build-workflows \
--policy-arn \
--max-results 10
# 2. Delete old/completed builds if you have 2 already
aws bedrock delete-automated-reasoning-policy-build-workflow \
--policy-arn \
--build-workflow-id "old-workflow-id" \
--last-updated-at "2025-11-15T00:41:18.608000+00:00"
# 3. Now start your new build
aws bedrock start-automated-reasoning-policy-build-workflow \
--policy-arn \
--build-workflow-type INGEST_CONTENT \
--source-content
```
## Build Workflow Assets
After a build workflow completes successfully, you can retrieve various assets. After you complete a build workflow, you can ask the user to check the build diff using the Automated Reasoning checks console.
### Asset Types
#### 1. ASSET_MANIFEST - Index of All Assets
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "ASSET_MANIFEST"
```
**What it contains:**
- A manifest listing all available assets and their IDs for the build workflow
- Use this to discover asset IDs needed for retrieving assets
#### 2. POLICY_DEFINITION - The Main Output
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "POLICY_DEFINITION"
```
**What it contains:**
- Compiled policy with extracted/refined rules, variables, and types
- SMT-LIB expressions for all rules
- Complete policy structure ready for deployment
#### 3. BUILD_LOG - Build Process Details
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "BUILD_LOG"
```
**What it shows:**
- Document processing steps - What content was analyzed
- Extraction results - What rules, variables, and types were found
- Processing warnings - Content that couldn't be interpreted
- Success/failure status for each extraction step
#### 4. QUALITY_REPORT - Policy Quality Analysis
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "QUALITY_REPORT"
```
**What it contains:**
- Conflicting rules - Rules that contradict each other
- Unused variables - Variables not referenced by any rules
- Unused type values - Enum values not used in rules
- Disjoint rule sets - Groups of rules that don't interact
#### 5. GENERATED_TEST_CASES - Auto-Generated Tests
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "GENERATED_TEST_CASES"
```
**What it contains:**
- Automatically generated test cases based on the policy rules
#### 6. POLICY_SCENARIOS - Policy Test Scenarios
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "POLICY_SCENARIOS"
```
**What it contains:**
- AI-generated scenarios for comprehensive policy validation
#### 7. FIDELITY_REPORT - Policy Fidelity Analysis
```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "FIDELITY_REPORT"
```
**What it contains:**
- Fidelity analysis results from a GENERATE_FIDELITY_REPORT build workflow
#### 8. SOURCE_DOCUMENT - Original Source Documents
```bash
# Requires --asset-id obtained from the ASSET_MANIFEST
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
--policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
--build-workflow-id "workflow-123" \
--asset-type "SOURCE_DOCUMENT" \
--asset-id "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5"
```
**What it contains:**
- The original source document used in the build workflow
- The `--asset-id` parameter is required because multiple source documents may have been used
```
# 애플리케이션에 자동 추론 정책 배포
자동 추론 정책을 테스트하고 성능에 만족하면 Amazon Bedrock Guardrails에서 애플리케이션에 사용할 수 있도록 배포할 수 있습니다. 이 페이지에서는 변경 불가능한 버전 저장, 가드레일에 연결,를 사용한 배포 자동화 CloudFormation, CI/CD 파이프라인에 통합 등 전체 배포 워크플로를 다룹니다.
## 자동 추론 정책 버전 저장
정책 테스트를 마치면 변경할 수 없는 버전을 생성합니다. 변경 불가능한 버전은 초안을 계속 편집할 때 가드레일에 연결된 정책이 예기치 않게 변경되지 않도록 합니다. 각 버전은 숫자 버전 번호(1, 2, 3, ...)로 식별되며 생성 후에는 수정할 수 없습니다.
### 콘솔 사용
1. 왼쪽 탐색 창에서 **자동 추론**을 선택합니다.
1. 애플리케이션에 사용하려는 자동 추론 정책을 선택합니다.
1. **새 버전으로 저장**을 선택합니다. 이 버전의 정책을 가드레일과 함께 사용할 수 있습니다.
### API 사용
`CreateAutomatedReasoningPolicyVersion` API를 사용하여 변경 불가능한 버전의 자동 추론 정책을 생성합니다.
#### 요청 파라미터
`policyArn`(필수)
버전을 생성할 자동 추론 정책의 Amazon 리소스 이름(ARN)입니다.
`lastUpdatedDefinitionHash`(필수)
새 버전에 대한 정책 정의의 해시입니다. `GetAutomatedReasoningPolicy` API에서이 해시를 검색합니다. 이렇게 하면 테스트한 정확한 정책 정의의 버전을 관리할 수 있습니다.
#### 예제
```
# Get the current definition hash
aws bedrock get-automated-reasoning-policy \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--query "definitionHash" --output text
# Create the version
aws bedrock create-automated-reasoning-policy-version \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk" \
--last-updated-definition-hash "583463f067a8a4f49fc1206b4642fd40..."
```
응답 예제:
```
{
"policyArn": "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk",
"version": "1",
"name": "MyHRPolicy"
}
```
## 가드레일에 자동 추론 정책 추가
자동 추론 정책의 저장된 버전이 있으면 가드레일에 추가합니다. 가드레일은 애플리케이션이 LLM 응답을 검증하기 위해 호출하는 런타임 구성 요소입니다. 자동 추론 정책을 새 가드레일 또는 기존 가드레일에 추가할 수 있습니다.
### 콘솔 사용
1. 왼쪽 탐색 창에서 **가드레일을** 선택한 다음 **가드레일 생성을** 선택합니다(또는 기존 가드레일을 선택하고 **편집**을 선택합니다).
1. **자동 추론 검사 추가** 화면으로 이동하면 **자동 추론 정책 활성화**를 선택합니다.
1. **정책 이름**에서 자동 추론 정책의 저장된 버전을 선택한 후 **다음**을 선택합니다.
1. 가드레일 생성 또는 업데이트를 완료합니다.
### API 사용
`CreateGuardrail` 또는 `UpdateGuardrail` API를 사용하여 가드레일에 자동 추론 정책을 추가합니다. 버전이 지정된 정책 ARN에 `automatedReasoningConfig` 파라미터를 포함합니다.
#### 요청 파라미터
`automatedReasoningConfig`
Amazon Bedrock Guardrails의 자동 추론 검사를 위한 구성입니다.
`policyArn`(필수)
가드레일과 함께 사용할 자동 추론 정책 버전의 ARN입니다. 버전이 지정되지 않은 ARN이 아닌 버전이 지정된 ARN(`:1`, `:2`등으로 끝남)을 사용합니다.
#### 예제
```
aws bedrock create-guardrail \
--name "HR-Policy-Guardrail" \
--description "Guardrail for HR policy validation" \
--automated-reasoning-policy-config policies="arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk:1" \
--cross-region-config '{"guardrailProfileIdentifier": "us.guardrail.v1:0"}' \
--blocked-input-messaging "I cannot process this request." \
--blocked-outputs-messaging "I cannot provide this response."
```
**중요**
버전이 지정된 정책 ARN(예: `arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk:1`)을 사용합니다. 버전이 지정되지 않은 ARN을 사용하는 경우 API는 오류를 반환합니다. 먼저를 사용하여 버전을 생성합니다`CreateAutomatedReasoningPolicyVersion`.
**중요**
자동 추론 검사를 사용하는 가드레일에는 교차 리전 추론 프로파일이 필요합니다. 리전 접두사와 `guardrailProfileIdentifier` 일치하는에 `--cross-region-config` 파라미터를 포함합니다(예: 미국 리전의 `us.guardrail.v1:0` 경우 , EU 리전의 `eu.guardrail.v1:0` 경우 ). 이 파라미터를 생략하면 API가를 반환합니다`ValidationException`.
## 배포를 위한 정책 버전 내보내기
CloudFormation 또는 CI/CD 파이프라인을 통해 정책을 배포하려면 정책 정의 JSON이 필요합니다. `ExportAutomatedReasoningPolicyVersion` API를 사용하여 저장된 버전에서 모든 규칙, 변수 및 사용자 지정 유형을 포함한 전체 정책 정의를 내보냅니다.
내보낸 정의는 `AWS::Bedrock::AutomatedReasoningPolicy` 리소스의 `PolicyDefinition` 속성에서 CloudFormation 허용하는 것과 동일한 형식입니다. 이렇게 하면 대화형 콘솔 워크플로에서 자동 배포로 정책을 쉽게 이동할 수 있습니다.
```
# Export the policy definition from version 1
aws bedrock export-automated-reasoning-policy-version \
--policy-arn "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk:1" \
--query "policyDefinition" \
--output json > policy-definition.json
```
내보낸 JSON의 구조는 다음과 같습니다.
```
{
"version": "1.0",
"variables": [
{
"name": "isFullTime",
"type": "BOOL",
"description": "Whether the employee works full-time (true) or part-time (false)."
},
{
"name": "tenureMonths",
"type": "INT",
"description": "The number of complete months the employee has been continuously employed."
}
],
"rules": [
{
"id": "A1B2C3D4E5F6",
"expression": "(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)"
}
],
"types": []
}
```
이 파일을 CloudFormation 템플릿과 함께 버전 제어에 저장합니다. 정책을 업데이트할 때 새 버전을 내보내고 파일을 업데이트하여 배포를 트리거합니다.
## 를 사용하여 배포 자동화 CloudFormation
CloudFormation 를 사용하여 자동화된 추론 정책과 가드레일을 코드형 인프라로 배포합니다. `AWS::Bedrock::AutomatedReasoningPolicy` 리소스는 API 또는 콘솔에서 내보내는 정책 정의가 포함된 정책을 생성합니다. 와 함께 전체 검증 스택을 단일 템플릿에 배포할 `AWS::Bedrock::Guardrail`수 있습니다.
**참고**
CloudFormation 는 사용자가 제공한 정책 정의로 정책 리소스를 생성합니다. 빌드 워크플로를 실행하거나 소스 문서에서 규칙을 추출하지 않습니다. 먼저 대화형으로 정책을 생성하고 테스트한 다음(콘솔, API 또는 Kiro CLI 사용) 템플릿에 사용할 테스트된 정책 정의를 내보내야 합니다. 자세한 내용은 [배포를 위한 정책 버전 내보내기](#export-policy-version) 단원을 참조하십시오.
정책 리소스의 전체 속성 참조는 템플릿 참조의 [AWS::Bedrock::AutomatedReasoningPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-automatedreasoningpolicy.html)를 참조하세요. *CloudFormation *
### 예: 정책 및 가드레일 배포
다음 CloudFormation 템플릿은 정책 정의와 이를 참조하는 가드레일을 사용하여 자동 추론 정책을 생성합니다. 정책 정의를 테스트된 정책에서 내보낸 JSON으로 바꿉니다.
```
AWSTemplateFormatVersion: '2010-09-09'
Description: Deploy an Automated Reasoning policy and guardrail
Parameters:
PolicyName:
Type: String
Default: MyHRPolicy
Description: Name of the Automated Reasoning policy
GuardrailName:
Type: String
Default: HR-Policy-Guardrail
Description: Name of the guardrail
Resources:
AutomatedReasoningPolicy:
Type: AWS::Bedrock::AutomatedReasoningPolicy
Properties:
Name: !Ref PolicyName
Description: Validates HR chatbot responses about leave eligibility
PolicyDefinition:
Version: '1.0'
Variables:
- Name: isFullTime
Type: BOOL
Description: >-
Whether the employee works full-time (true) or part-time (false).
Set to true when users mention being full-time or working 40+ hours
per week.
- Name: tenureMonths
Type: INT
Description: >-
The number of complete months the employee has been continuously
employed. When users mention years of service, convert to months
(for example, 2 years = 24 months).
- Name: eligibleForParentalLeave
Type: BOOL
Description: >-
Whether the employee is eligible for parental leave based on
employment status and tenure.
Rules:
- Id: A1B2C3D4E5F6
Expression: >-
(=> (and isFullTime (> tenureMonths 12))
eligibleForParentalLeave)
- Id: G7H8I9J0K1L2
Expression: >-
(=> (or (not isFullTime) (<= tenureMonths 12))
(not eligibleForParentalLeave))
Types: []
Tags:
- Key: Environment
Value: Production
- Key: Team
Value: HR
Guardrail:
Type: AWS::Bedrock::Guardrail
Properties:
Name: !Ref GuardrailName
Description: Guardrail with Automated Reasoning checks for HR policy
BlockedInputMessaging: I cannot process this request.
BlockedOutputsMessaging: I cannot provide this response.
AutomatedReasoningPolicyConfig:
Policies:
- !GetAtt AutomatedReasoningPolicy.PolicyArn
CrossRegionConfig:
GuardrailProfileArn: !Sub "arn:aws:bedrock:${AWS::Region}:${AWS::AccountId}:guardrail-profile/us.guardrail.v1:0"
Outputs:
PolicyArn:
Description: ARN of the Automated Reasoning policy
Value: !GetAtt AutomatedReasoningPolicy.PolicyArn
PolicyId:
Description: ID of the Automated Reasoning policy
Value: !GetAtt AutomatedReasoningPolicy.PolicyId
GuardrailId:
Description: ID of the guardrail
Value: !Ref Guardrail
```
**작은 정보**
프로덕션 배포의 경우 정책 정의를 별도의 JSON 파일에 보관하고 `Fn::Include`를 사용하거나 템플릿 파라미터로 로드하여 참조합니다. 이렇게 하면 템플릿을 정리하고 정책 정의를 독립적으로 더 쉽게 업데이트할 수 있습니다.
**중요**
자동 추론 검사를 사용하는 가드레일에는 교차 리전 추론 프로파일이 필요합니다. `CrossRegionConfig` 속성은 리전의 가드레일 프로파일 ARN을 지정합니다. 리전 접두사(`us`)를 배포 리전(예: `eu` EU 리전)에 적합한 접두사로 바꿉니다. 이 속성을 생략하면 가드레일 생성이 실패합니다.
### 예: 고객 관리형 KMS 키를 사용하여 배포
고객 관리형 KMS 키로 정책을 암호화하려면 `KmsKeyId` 속성을 추가합니다. 또한 Amazon Bedrock이 키를 사용할 수 있도록 키 정책을 구성해야 합니다. 필요한 키 정책 권한은 섹션을 참조하세요[자동 추론 정책에 대한 KMS 권한](create-automated-reasoning-policy.md#automated-reasoning-policy-kms-permissions).
```
AutomatedReasoningPolicy:
Type: AWS::Bedrock::AutomatedReasoningPolicy
Properties:
Name: !Ref PolicyName
Description: Validates HR chatbot responses about leave eligibility
KmsKeyId: !GetAtt PolicyEncryptionKey.Arn
PolicyDefinition:
# ... policy definition ...
Tags:
- Key: Environment
Value: Production
```
**중요**
`KmsKeyId` 속성을 변경하려면 리소스를 교체해야 합니다. CloudFormation 는 기존 정책을 삭제하고 새 ARN으로 새 정책을 생성합니다. 이전 정책 ARN을 참조하는 가드레일을 업데이트합니다.
## 다음 단계
정책 및 가드레일을 배포한 후 자동화된 추론 검사를 애플리케이션에 통합하여 런타임 시 LLM 응답을 검증합니다. 자세한 내용은 [애플리케이션에 자동 추론 검사 통합](integrate-automated-reasoning-checks.md) 단원을 참조하십시오.
# 애플리케이션에 자동 추론 검사 통합
가드레일에 자동 추론 정책을 배포한 후( 참조[애플리케이션에 자동 추론 정책 배포](deploy-automated-reasoning-policy.md)) 런타임에 이를 사용하여 LLM 응답을 검증하고 피드백에 따라 조치를 취할 수 있습니다. 이 페이지에서는 검증 API를 호출하고, 결과를 프로그래밍 방식으로 해석하고, 잘못된 응답을 다시 작성하고, 명확한 질문을 하는 등의 일반적인 통합 패턴을 구현하는 방법을 설명합니다.
자동 추론 검사는 *감지 모드에서*만 작동하며 콘텐츠를 차단하는 대신 조사 결과와 피드백을 반환합니다. 애플리케이션은 응답을 제공하거나, 다시 작성하거나, 설명을 요청하거나, 기본 동작으로 돌아가는 등 조사 결과를 사용하여 수행할 작업을 결정할 책임이 있습니다.
## 통합 개요
런타임 시 통합은 다음 흐름을 따릅니다.
```
User question ──► LLM generates response ──► ApplyGuardrail validates response
│
┌─────────┴─────────┐
│ │
VALID Not VALID
│ │
▼ ▼
Serve response Inspect findings
to user │
┌────────┴────────┐
│ │
OTHER FINDING TRANSLATION_
TYPES AMBIGUOUS / SATISFIABLE
│ │
▼ ▼
Rewrite using Ask user for
AR feedback clarification
│ │
▼ ▼
Validate again Validate with
clarified input
```
자동 추론 조사 결과는 Amazon Bedrock Guardrails 구성을 지원하는 API를 통해 반환됩니다.
+ `ApplyGuardrail` - 독립 실행형 검증 API. LLM 호출과 독립적으로 콘텐츠를 검증하려는 경우이 옵션을 사용합니다. 이는 자동화된 추론 확인에 권장되는 접근 방식입니다. 검증되는 콘텐츠와 시기를 완벽하게 제어할 수 있기 때문입니다.
+ `Converse` 및 `InvokeModel` - 가드레일 구성을 사용하는 LLM 호출 APIs. 자동 추론 조사 결과는 응답의 `trace` 필드에 반환됩니다.
+ `InvokeAgent` 및 `RetrieveAndGenerate`- 가드레일 구성을 사용하는 에이전트 및 지식 기반 APIs.
이 페이지에서는 아래에 설명된 재작성 및 설명 패턴을 구현할 수 있는 가장 유연한 기능을 제공하므로 `ApplyGuardrail` API에 중점을 둡니다. 다른 APIs. [https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use.html](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use.html)
## 오픈 소스 재작성 챗봇 샘플
이 페이지에 설명된 패턴을 완전히 프로덕션 방식으로 구현하려면 GitHub에서 [챗봇을 재작성하는 자동 추론 검사를](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot) 참조하세요. 이 샘플 애플리케이션은 다음을 보여줍니다.
+ AR 피드백에 따라 잘못된 응답이 자동으로 수정되는 반복 재작성 루프입니다.
+ LLM이 정확하게 다시 쓰기 위해 사용자의 추가 컨텍스트가 필요한 경우의 후속 질문입니다.
+ 사용자가 설명 질문에 응답하지 않을 때 처리를 자동으로 재개하는 제한 시간 메커니즘입니다.
+ LLM이 재작성 중에 전체 정책 규칙을 참조할 수 있도록 LLM 프롬프트에 정책 컨텍스트 삽입.
+ 규정 준수 및 디버깅에 대한 모든 검증 반복의 JSON 감사 로깅입니다.
이 샘플은 React 프런트엔드가 있는 Python/Flask 백엔드를 사용하고 LLM 추론을 위해 Amazon Bedrock과 통신하고 `ApplyGuardrail` API를 통해 검증을 위해 Amazon Bedrock 가드레일과 통신합니다.
**참고**
샘플 애플리케이션은 문서 업로드 없이 자동 추론 정책을 지원하기 위해 LLM 생성 프롬프트에 직접 정책 콘텐츠를 포함합니다. 프로덕션 배포에서는 일반적으로 자동화된 추론 정책 소스 코드 대신 RAG 콘텐츠를 사용하거나 LLM에 원래 자연어 문서를 제공합니다.
## 자동 추론 검사를 사용하여 ApplyGuardrail 호출
`ApplyGuardrail` API를 사용하여 가드레일에 대한 콘텐츠를 검증합니다. API는 하나 이상의 콘텐츠 블록을 수락하고 자동 추론 조사 결과를 포함하는 평가를 반환합니다.
### 요청 구조
`guardrailIdentifier`(필수)
가드레일 ID 또는 ARN입니다. 자동 추론 정책이 연결된 가드레일을 사용합니다.
`guardrailVersion`(필수)
가드레일 버전 번호(예: `1`). 프로덕션 워크로드에는가 아닌 번호가 매겨진 버전을 사용합니다`DRAFT`.
`source`(필수)
LLM 응답을 검증할 `OUTPUT` 때를 로 설정합니다. 사용자 프롬프트를 검증할 `INPUT` 때를 로 설정합니다. 자동 추론 검사의 경우 일반적으로 LLM 출력을 검증합니다.
`content`(필수)
검증할 콘텐츠 블록의 배열입니다. 각 블록에는 확인할 내용이 포함된 `text` 필드가 포함되어 있습니다. 사용자 질문과 LLM 응답을 별도의 콘텐츠 블록으로 전달하거나 단일 블록으로 결합할 수 있습니다.
### 예:를 사용하여 LLM 응답 검증 AWS CLI
```
aws bedrock-runtime apply-guardrail \
--guardrail-identifier "your-guardrail-id" \
--guardrail-version "1" \
--source OUTPUT \
--content '[
{
"text": {
"text": "User: Am I eligible for parental leave if I have been working here for 2 years full-time?\nAssistant: Yes, you are eligible for parental leave."
}
}
]'
```
### 예: Python(boto3)을 사용하여 LLM 응답 검증
```
import boto3
import json
bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-east-1")
response = bedrock_runtime.apply_guardrail(
guardrailIdentifier="your-guardrail-id",
guardrailVersion="1",
source="OUTPUT",
content=[
{
"text": {
"text": (
"User: Am I eligible for parental leave if I have been "
"working here for 2 years full-time?\n"
"Assistant: Yes, you are eligible for parental leave."
)
}
}
],
)
# The AR findings are in the assessments
for assessment in response.get("assessments", []):
ar_assessment = assessment.get("automatedReasoningPolicy", {})
findings = ar_assessment.get("findings", [])
for finding in findings:
# Each finding is a union — exactly one key is present
# Possible keys: valid, invalid, satisfiable, impossible,
# translationAmbiguous, tooComplex, noTranslations
print(json.dumps(finding, indent=2, default=str))
```
### 응답 구조
`ApplyGuardrail` 응답에는 `assessments` 배열이 포함됩니다. 각 평가에는 `findings` 배열이 있는 `automatedReasoningPolicy` 객체가 포함됩니다. 각 결과는 조합 유형입니다. 다음 키 중 정확히 하나가 있습니다.
+ `valid`
+ `invalid`
+ `satisfiable`
+ `impossible`
+ `translationAmbiguous`
+ `tooComplex`
+ `noTranslations`
각 결과 유형 및 해당 필드에 대한 자세한 설명은 섹션을 참조하세요[결과 및 검증 결과](automated-reasoning-checks-concepts.md#ar-concept-findings).
## 런타임 시 AR 조사 결과 해석
프로그래밍 방식으로 자동 추론 조사 결과에 대응하려면 애플리케이션에서 조사 결과 유형, 번역 세부 정보 및 지원 또는 모순되는 규칙을 추출해야 합니다. 다음 섹션에서는 결과의 각 부분을 구문 분석하는 방법을 설명합니다.
### 결과 유형 결정
각 결과는 하나의 조합입니다. 정확히 하나의 키가 있습니다. 어떤 키가 존재하는지 확인하여 결과 유형을 결정합니다.
```
def get_finding_type(finding):
"""Return the finding type and its data from an AR finding union."""
for finding_type in [
"valid", "invalid", "satisfiable", "impossible",
"translationAmbiguous", "tooComplex", "noTranslations"
]:
if finding_type in finding:
return finding_type, finding[finding_type]
return None, None
```
### 번역 읽기
대부분의 결과 유형에는 자동 추론 검사가 자연어 입력을 공식 로직으로 변환한 방법을 보여주는 `translation` 객체가 포함됩니다. 번역에는 다음이 포함됩니다.
+ `premises` - 입력에서 추출된 조건(예: , `isFullTime = true``tenureMonths = 24`).
+ `claims` - 검증할 어설션입니다(예: `eligibleForParentalLeave = true`).
+ `untranslatedPremises` - 정책 변수에 매핑할 수 없는 입력의 일부입니다. 이러한 부분은 검증되지 않습니다.
+ `untranslatedClaims` - 정책 변수에 매핑할 수 없는 클레임입니다.
`untranslatedPremises` 및 `untranslatedClaims`를 확인하여 검증 범위를 이해합니다. `VALID` 결과는 번역된 클레임만 다루며 번역되지 않은 콘텐츠는 확인되지 않습니다.
### 지원 또는 모순 규칙 읽기
결과 유형에 따라 결과에는 결과를 설명하는 규칙이 포함됩니다.
+ `valid` 결과에는 클레임`supportingRules`이 정확함을 입증하는 정책 규칙이 포함됩니다.
+ `invalid` 결과에는 클레임`contradictingRules`이 위반하는 정책 규칙이 포함됩니다.
+ `satisfiable` 결과에는 `claimsTrueScenario` 클레임이 true 및 false인 조건을 `claimsFalseScenario` 보여주는 a와 a가 모두 포함됩니다.
이러한 규칙 및 시나리오는에 설명된 재작성 패턴의 주요 입력입니다[AR 피드백을 사용하여 잘못된 응답 다시 쓰기](#rewrite-invalid-responses).
### 집계 결과 확인
단일 검증 요청은 여러 결과를 반환할 수 있습니다. 전체 결과를 확인하려면 조사 결과를 심각도별로 정렬하고 최악의 결과를 선택합니다. 최악의 심각도부터 최상의 심각도 순서는 `TRANSLATION_AMBIGUOUS`, `IMPOSSIBLE`, `INVALID`, `SATISFIABLE`, 입니다`VALID`.
```
SEVERITY_ORDER = {
"tooComplex": 0,
"translationAmbiguous": 0,
"impossible": 1,
"invalid": 2,
"satisfiable": 3,
"valid": 4,
"noTranslations": 5,
}
def get_aggregate_result(findings):
"""Return the worst finding type from a list of findings."""
worst = None
worst_severity = float("inf")
for finding in findings:
finding_type, _ = get_finding_type(finding)
severity = SEVERITY_ORDER.get(finding_type, 0)
if severity < worst_severity:
worst_severity = severity
worst = finding_type
return worst
```
## 애플리케이션에서 검증 결과 처리
집계 결과를 사용하여 애플리케이션이 다음에 수행할 작업을 결정합니다. 다음 표에는 각 결과 유형에 대한 권장 작업이 요약되어 있습니다.
| 결과 | 의미 | 권장 조치 |
| --- | --- | --- |
| valid | 응답은 온프레미스 및 정책 규칙을 고려하여 수학적으로 올바르게 증명됩니다. | 사용자에게 응답을 제공합니다. 감사 목적으로 결과를 로깅합니다( 참조[감사 추적 구축](#build-audit-trail)). |
| invalid | 응답은 정책 규칙과 모순됩니다. contradictingRules 필드는 위반된 규칙을 식별합니다. | AR 피드백을 사용하여 응답을 다시 작성합니다( 참조[AR 피드백을 사용하여 잘못된 응답 다시 쓰기](#rewrite-invalid-responses)). 여러 번 시도한 후 다시 쓰지 못하면 응답을 차단하고 대체 메시지를 반환합니다. |
| satisfiable | 응답은 일부 조건에서는 정확하지만 전부는 아닙니다. 잘못된 것은 아니지만 불완전합니다. 모든 요구 사항을 언급하지는 않습니다. | 누락된 조건을 포함하도록 응답을 다시 작성합니다. claimsFalseScenario를 사용하여 누락된 항목을 식별합니다. 또는 LLM이 사용자에게 질문을 명확히 하도록 할 수 있습니다. |
| impossible | 온프레미스가 모순되거나 정책에 충돌하는 규칙이 포함되어 있습니다. | 사용자에게 입력을 명확히 하도록 요청합니다( 참조[명확한 질문하기](#ask-clarifying-questions)). 문제가 지속되면 정책 문제를 나타낼 수 있습니다. 품질 보고서를 검토하세요. |
| translationAmbiguous | 입력에는 유효한 해석이 여러 개 있습니다. 번역 모델은 자연어를 정책 변수에 매핑하는 방법에 대해 의견이 일치하지 않았습니다. | 사용자에게 모호성을 해결하기 위한 설명을 요청합니다. options 및 differenceScenarios 필드를 사용하여 대상 확인 질문을 생성합니다. |
| tooComplex | 입력이 논리적 분석에 대한 처리 제한을 초과합니다. | 입력을 더 작은 부분으로 나누어 단순화하거나 응답을 확인할 수 없음을 설명하는 대체 메시지를 반환합니다. |
| noTranslations | 입력은 정책의 도메인과 관련이 없습니다. 정책 변수를 매핑할 수 없습니다. | 콘텐츠는이 정책의 주제가 아닙니다. AR 검증 없이 응답을 제공하거나 다른 가드레일 구성 요소(예: 주제 정책)를 사용하여 비주제 콘텐츠를 처리합니다. |
## AR 피드백을 사용하여 잘못된 응답 다시 쓰기
자동 추론 검사의 가장 강력한 통합 패턴은 *재작성 루프*입니다. 응답이 `invalid` 또는 인 경우 `satisfiable`애플리케이션은 원래 응답, 특정 결과 및 정책 규칙을 포함하는 프롬프트를 구성한 다음 LLM에 정책과 일치하도록 응답을 다시 작성하도록 요청합니다. 다시 작성된 응답이 다시 검증되고 응답이 `valid`되거나 최대 반복 횟수에 도달할 때까지 루프가 계속됩니다.
### 루프 흐름 재작성
```
LLM generates initial response
│
▼
Validate with ApplyGuardrail ◄──────────────────┐
│ │
▼ │
┌─────┴─────┐ │
│ │ │
VALID Not VALID │
│ │ │
▼ ▼ │
Done Construct rewriting prompt │
with findings + rules │
│ │
▼ │
LLM rewrites response │
│ │
▼ │
Max iterations? ──── No ────────────────┘
│
Yes
│
▼
Return best response
with warning
```
### 재작성 프롬프트 구성
재작성 프롬프트에는 AR 조사 결과의 세 가지 정보가 포함되어야 합니다.
1. 검증에 실패한 원래 응답입니다.
1. 번역된 온프레미스, 클레임, 모순되거나 지원되는 규칙을 포함한 특정 조사 결과입니다.
1. 정책 규칙과 일치하도록 응답을 다시 작성하라는 지침입니다.
**프롬프트 템플릿 재작성 예제:**
```
The following response was checked against our policy and found to be
{finding_type}.
Original response:
{original_response}
The validation found the following issue:
- Premises (what was understood from the input): {premises}
- Claims (what was asserted): {claims}
- Contradicting rules: {contradicting_rules}
Please rewrite the response so that it is consistent with the policy document.
Keep the same helpful tone and answer the user's question
accurately based on the rules. If you cannot provide an accurate answer
without more information, explain what additional information is needed.
```
**작은 정보**
LLM이 다시 작성할 때 필요한 모든 컨텍스트를 가질 수 있도록 항상 Retrieval Augmented Generation(RAG) 콘텐츠를 재작성 요청 또는 정책 규칙에 포함하세요. 재작성 프롬프트 템플릿은 특정 결과 세부 정보를 제공하는 반면, 시스템 프롬프트는 더 광범위한 정책 컨텍스트를 제공합니다. 이 이중 컨텍스트 접근 방식은 [오픈 소스 챗봇 재작성 샘플](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot)에 설명되어 있습니다.
### 모범 사례 재작성
+ **최대 반복 횟수를 설정합니다.** 무한 루프를 방지하려면 재작성 루프에 하드 제한(일반적으로 2\$15회 반복)이 있어야 합니다. 응답이 여전히 최대 반복 `valid` 이후가 아닌 경우 경고와 함께 최상의 응답을 반환하거나 기본 메시지로 돌아갑니다.
+ **조사 결과를 우선순위에 따라 처리합니다.** 여러 조사 결과가 반환되면 가장 심각한 조사 결과를 먼저 해결합니다. 심각도 순서는 `translationAmbiguous`, `impossible`, `invalid`, `satisfiable`, 입니다`valid`.
+ **시스템 프롬프트에 정책 컨텍스트를 포함합니다.** LLM을 정확하게 다시 작성하려면 소스 문서 또는 전체 정책 규칙에 대한 액세스 권한이 필요합니다. [ 지식 기반을](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) 사용하여 생성 요청에 문서를 포함하거나 `ExportAutomatedReasoningPolicyVersion` API를 사용하여 정책 정의를 검색하고 LLM에 맞게 형식을 지정할 수 있습니다.
+ **각 반복을 로깅합니다.** 각 반복에 대해 원본 응답, 결과, 재작성 프롬프트 및 재작성된 응답을 기록합니다. 이 감사 추적은 디버깅 및 규정 준수에 유용합니다( 참조[감사 추적 구축](#build-audit-trail)).
## 명확한 질문하기
자동 추론 검사에서 `translationAmbiguous`, `satisfiable`또는 `impossible` 결과가 반환되면 LLM에 응답을 정확하게 다시 쓸 수 있는 충분한 정보가 없을 수 있습니다. 이러한 경우 애플리케이션은 사용자에게 설명을 요청한 다음 다음 검증 시도에 답변을 통합할 수 있습니다.
### 설명을 요청해야 하는 경우
+ **`translationAmbiguous`** - 입력에는 유효한 해석이 여러 개 있습니다. `options` 필드는 경쟁 해석을 보여주고 `differenceScenarios` 필드는 실제로 어떻게 다른지 보여줍니다. 이를 사용하여 특정 모호성에 대한 대상 질문을 생성합니다.
+ **`satisfiable`** - 일부 조건에서는 응답이 올바르지만 전부는 아닙니다. 는 응답이 올바르지 않은 조건을 `claimsFalseScenario` 보여줍니다. 사용자에게 이러한 특정 조건에 대해 질문합니다.
+ **`impossible`** - 입력에 모순되는 문이 포함되어 있습니다. 사용자에게 모순을 명확히 하도록 요청합니다.
+ **재작성 실패** - LLM이 여러 번 시도한 `valid` 후 응답을 로 재작성할 수 없는 경우 사용자의 추가 컨텍스트가 필요할 수 있습니다. LLM에 조사 결과를 기반으로 명확한 질문을 생성하도록 요청합니다.
### 설명 패턴
설명 흐름은 다음과 같이 작동합니다.
1. AR 조사 결과에서 모호한 변수 또는 누락된 조건을 추출합니다.
1. 결과 필드에서 프로그래밍 방식으로 또는 LLM에 결과를 기반으로 질문을 공식화하도록 요청하여 명확한 질문을 생성합니다.
1. 사용자에게 질문을 제시하고 답변을 수집합니다.
1. 답변을 컨텍스트에 통합하고 새 응답을 생성합니다.
1. 를 사용하여 새 응답을 검증합니다`ApplyGuardrail`.
**예: `satisfiable` 결과에서 명확한 질문 생성**
```
def generate_clarifying_questions(finding_data, user_question):
"""Ask the LLM to generate clarifying questions from a SATISFIABLE finding."""
claims_true = json.dumps(
finding_data.get("claimsTrueScenario", {}), indent=2, default=str
)
claims_false = json.dumps(
finding_data.get("claimsFalseScenario", {}), indent=2, default=str
)
prompt = (
f"A user asked: {user_question}\n\n"
f"The answer is correct when these conditions hold:\n{claims_true}\n\n"
f"But incorrect when these conditions hold:\n{claims_false}\n\n"
f"Generate 1-3 short, specific questions to ask the user to determine "
f"which conditions apply to their situation. Format each question on "
f"its own line."
)
return generate_response(prompt, "You are a helpful assistant.")
```
## 감사 추적 구축
자동 추론 조사 결과는 수학적으로 검증 가능한 유효성 증명을 제공합니다. 규제 산업 및 규정 준수 시나리오의 경우이 증명은 주요 차별화 요소입니다. 패턴 일치 또는 확률적 평가뿐만 아니라 특정 변수 할당이 있는 특정 정책 규칙에 대해 AI 응답이 검증되었음을 입증할 수 있습니다.
효과적인 감사 추적을 구축하려면 각 검증 요청에 대해 다음 정보를 기록합니다.
+ **타임스탬프 및 요청 ID입니다.** 검증이 발생한 시기와 요청에 대한 고유 식별자입니다.
+ **콘텐츠를 입력합니다.** 검증된 사용자 질문 및 LLM 응답입니다.
+ **결과 유형 및 세부 정보입니다.** 검증 결과(`valid``invalid`, 등), 번역된 온프레미스 및 클레임, 지원 또는 모순되는 규칙.
+ **취해진 조치.** 애플리케이션이 조사 결과를 사용하여 수행한 작업 -가 응답을 처리했거나, 다시 작성했거나, 설명을 요청했거나, 차단했습니다.
+ **기록 재작성.** 응답을 다시 작성한 경우 원본 응답, 재작성 프롬프트, 재작성된 응답, 각 반복에 대한 검증 결과 등 각 반복을 기록합니다.
+ **정책 버전.** 검증에 사용되는 가드레일 버전 및 정책 버전입니다. 이렇게 하면 나중에 검증 결과를 재현할 수 있습니다.
**예: 감사 로그 항목 구조**
```
{
"timestamp": "2025-07-21T14:30:00Z",
"request_id": "req-abc123",
"guardrail_id": "your-guardrail-id",
"guardrail_version": "1",
"user_question": "Am I eligible for parental leave?",
"llm_response": "Yes, you are eligible for parental leave.",
"validation_result": "valid",
"findings": [
{
"type": "valid",
"premises": "isFullTime = true, tenureMonths = 24",
"claims": "eligibleForParentalLeave = true",
"supporting_rules": ["A1B2C3D4E5F6"]
}
],
"action_taken": "served_response",
"rewrite_iterations": 0
}
```
**작은 정보**
객체 잠금이 활성화된 Amazon CloudWatch Logs 또는 Amazon S3와 같은 내구성이 뛰어난 변조 방지 저장소에 감사 로그를 저장합니다. 규정 준수 시나리오의 경우 Lake를 사용하여 조직 전체의 감사 로그를 쿼리하는 것이 좋습니다.