아키텍처¶

English | 한국어

책임 경계¶

Spring AI Privacy Guardrails는 애플리케이션, 모델과 도구의 실행 경계에서 개인정보 보호 정책을 집행합니다. 탐지기는 용도에 맞게 교체할 수 있습니다.

source text -> analyzer evidence -> core policy -> protected text
                                             -> model/tool/output boundaries

호출자가 소유한 원문 텍스트가 위치(offset) 계산의 단일 기준입니다. 분석기는 탐지 근거를 반환하고, core는 개인정보를 변환하기 전에 이를 검증·정규화· 필터링·해석합니다. 요청별 세션은 토큰 식별 정보와 토큰-원문 매핑을 소유합니다.

라이브러리는 지원하는 경계를 통과하는 값만 보호합니다. 불투명한 애플리케이션 객체 안에 숨은 데이터를 찾아내거나, 애플리케이션의 권한 부여 정책을 대신하거나, 경계에 도달하기 전에 이미 저장된 데이터를 다시 작성하지 않습니다.

빌드 모듈 경계¶

이 저장소는 Gradle 멀티 모듈 라이브러리입니다. 주요 의존성 경계는 런타임 package 관례가 아니라 빌드 그래프가 강제합니다.

core <- analyzer adapters
core + Spring AI adapter <- base Boot starter
provider adapter + base Boot starter <- provider Boot starter
Spring AI adapter <- test support
core + Spring AI adapter <- benchmarks and samples

core는 Spring에 의존하지 않습니다. 분석기 adapter는 core 정책에 의존하지만 Spring AI에는 의존하지 않습니다. Spring AI adapter는 provider 설정을 소유하지 않으며 core를 프레임워크 실행에 연결합니다. Boot starter는 애플리케이션이 명시적으로 선택한 구성 요소를 조립합니다.

테스트 지원, 벤치마크와 샘플은 저장소 내부의 소비자입니다. 운영 정책을 정의하지 않으며 벤치마크 모듈은 배포하지 않습니다.

공개 API 경계¶

각 배포 artifact는 공개 API를 단일 최상위 package에 둡니다. Gradle 모듈은 core 정책, 분석기 provider, Spring AI 연동, Boot 자동 설정, 테스트 지원을 분리합니다. Package-private 협력 객체는 호환성 약속이 아니므로 변경될 수 있습니다.

공개 타입은 다음 네 가지 역할로 나뉩니다.

모든 배포 JAR는 안정적인 Automatic-Module-Name을 선언합니다. 이를 통해 module-info.java descriptor나 JPMS export graph를 제공한다고 주장하지 않으면서도 JPMS 사용자에게 항상 같은 모듈 이름을 제공합니다.

분석기와 해석 경계¶

각 PiiAnalyzer는 provider 식별자를 가지며 원문의 위치 범위를 PiiSpan 값으로 반환합니다. core는 애플리케이션 정책을 적용하기 전에 각 탐지 근거를 해당 provider에 귀속시킵니다. 분석기 점수는 provider 내부에서만 의미가 있으며, provider 사이에서 서로 보정되었다고 가정하지 않습니다.

엔티티 label은 신뢰할 수 없는 분석기 출력입니다. core는 형식이 올바른 label만 허용하고, 애플리케이션이 신뢰할 수 있는 매핑을 명시하지 않은 잘 알려지지 않은 label은 일반 보호 유형으로 매핑합니다.

호출자가 직접 제공한 범위는 provider 선택만 건너뜁니다. 범위 검증, 정규화, 필터링과 중첩 해석은 그대로 적용됩니다. 해석이 끝난 범위는 원문 부분 문자열을 복사하지 않고 위치와 출처 정보를 보존합니다.

설정된 분석기 인스턴스는 동시 요청 사이에서 공유될 수 있습니다. 따라서 사용자 정의 구현은 스레드 안전(thread-safe)하고 재진입 가능(reentrant)해야 합니다. 차단될 수 있는 작업에는 유한한 제한 시간을 두고 중단 요청에 협조해야 합니다.

provider 선택, 실패 정책, 임계값, 신뢰 규칙, 상한과 중첩 해석 규칙은 탐지와 해석에 설명된 설정 계약입니다.

요청과 세션 경계¶

PrivacySession은 core 직접 사용과 Spring AI 연동이 함께 사용하는 컨텍스트 모델입니다. 각 요청에는 새로운 불투명 프로세스 내부 handle과 토큰 이름 공간이 생성됩니다. 프레임워크 컨텍스트에는 handle만 전달되며, 원문 매핑은 모델이나 도구 payload에 직렬화되지 않습니다.

Registry는 다른 platform thread나 virtual thread에서 실행되는 도구도 지원합니다. 프로세스 전역 또는 ThreadLocal 대체 경로는 없습니다. 세션이 없거나, 알 수 없거나, 닫혀 있으면 라이브러리가 원문을 공개하거나 변환하기 전에 실패합니다.

세션 매핑은 정상 완료, 실패, 스트림 취소 시 제거됩니다. 이 작업은 라이브러리 참조를 해제할 뿐, 불변 문자열이나 애플리케이션·provider 코드가 보존한 사본을 안전하게 삭제하지는 않습니다.

core를 직접 사용하는 호출자는 같은 세션을 명시적으로 열고 닫습니다. Spring AI 연동은 보호된 클라이언트 실행을 둘러싼 세션 수명주기를 책임집니다.

Spring AI 실행 경계¶

Spring AI 연동은 지원하는 모델과 도구 흐름 전체를 하나의 요청 수명주기로 감쌉니다.

application input
  -> protected model request
  -> validated tool call
  -> capability-scoped tool execution
  -> protected tool result
  -> protected application output

관리형 configurer는 애플리케이션이 선택한 builder에만 완전한 개인정보 보호 묶음을 설치합니다. 모든 ChatClient를 전역으로 변경하거나, 필수 경계별 독립 스위치를 노출하거나, 관련 없는 advisor bean을 이 묶음의 대체물로 취급하지 않습니다.

각 구성 요소는 자신이 실제로 관찰한 세션과 데이터를 검증합니다. 불완전하거나 중복된 개인정보 보호 묶음은 보호된 실행 전에 안전하게 차단됩니다. 보호된 클라이언트에서 파생된 클라이언트도 같은 개인정보 보호 경계를 유지합니다.

사용자 정의 advisor는 콘텐츠, 옵션, 콜백, 응답을 추가하거나 교체할 수 있습니다. 해당 개인정보 보호 경계 밖에서 이루어지는 변경은 애플리케이션의 책임이며 별도로 보호해야 합니다. 지원하는 구성과 사용자 정의 규칙은 ChatClient 경계를 참고하세요.

모델과 출력 경계¶

지원하는 모든 모델 입력 텍스트는 provider 호출 전에 보호됩니다. 초기 입력뿐 아니라 클라이언트 흐름 도중에 추가된 지원 텍스트도 포함합니다. 텍스트를 숨길 수 있는 지원하지 않는 Message 구현은 알 수 없는 필드를 조용히 버리고 다시 만드는 대신 안전하게 차단됩니다.

출력 보호를 활성화하면 보호된 콘텐츠를 애플리케이션에 반환하기 전에 각 완성된 논리 응답에 정책을 적용합니다. 전체 응답 검사가 필요하면 스트리밍 응답을 버퍼링하므로 여러 frame에 나뉜 민감한 값이 정책을 우회할 수 없습니다.

알려진 텍스트 채널에는 설정된 개인정보 조치를 적용합니다. 불투명한 제어 데이터와 애플리케이션이 정의한 메타데이터는 애플리케이션이 별도로 분류·보호하지 않는 한 콘텐츠 검사 범위 밖입니다.

출력 조치, 지원하는 스트리밍 동작, 구조화 응답 처리와 검사 상한은 출력 정책과 스트리밍에 설명되어 있습니다.

도구 실행 경계¶

PrivacyToolCallbackFactory는 개인정보 보호가 적용된 콜백과 콜백 provider를 만드는 공개 경로입니다. 이 factory로 감싼 도구는 이를 만든 PrivacyService에 묶이며, 실행 중인 일치하는 요청 세션을 요구합니다.

도구 원문 공개는 기본 거부입니다. 애플리케이션은 정확한 도구 식별자에 정규 엔티티 유형 집합을 허가하며, 위임 대상 도구를 실행하기 직전에 그 값만 복원합니다. 등록만으로는 원문 공개 권한을 얻지 못합니다.

모델 경계를 통과하는 도구 정의와 실행 이름은 민감한 콘텐츠가 있는지 검사합니다. 도구 입력은 구조화 계약에 따라 보호한 뒤 허가 범위 안에서 원문을 공개합니다. 도구 결과는 모델이나 애플리케이션 경계로 돌아가기 전에 다시 보호됩니다.

PrivacyToolCallbackFactory가 관리하지 않는 애플리케이션 소유 도구 관리자, 해석기, 콜백과 변경은 신뢰하는 애플리케이션 기반 코드입니다. 라이브러리는 Spring AI가 노출하지 않는 경로의 출처를 추론하거나 원문 공개를 강제할 수 없습니다.

위임 대상 도구의 실패는 애플리케이션이 소유한 타입과 원인을 유지한 채 전파됩니다. 이러한 예외에는 공개된 값이 포함될 수 있으므로 예외 처리, 로그, 재시도와 관찰은 애플리케이션의 개인정보 보호 책임입니다.

JSON 처리, 원문 공개 설정, 직접 반환 동작과 자원 상한은 도구 원문 공개에 설명되어 있습니다.

실패와 진단 경계¶

라이브러리가 만든 실패에는 유형이 지정되어 있으며 개인정보를 노출하지 않습니다. 분석기 실패는 provider 메시지, 응답 본문, 원인이나 복사된 원문 대신 안정적인 provider, code, phase와 시도 횟수 메타데이터로 core 경계를 통과합니다.

선택형 PiiAnalyzerFailureObserver는 같은 안전한 이벤트를 받지만 분석 결과를 바꾸지는 못합니다. 안전한 상태 점검 정보는 상태와 안정적인 실패 유형만 노출합니다. 지표, 추적, 대시보드와 보호된 진단 저장소는 애플리케이션이 연동해야 합니다.

모델 provider, 도구, resource loader 또는 다른 애플리케이션 확장 구현이 소유한 실패는 원래 계약에 따라 전파됩니다. 애플리케이션은 이러한 실패와 SDK 로그에 민감한 콘텐츠가 포함될 수 있다고 가정해야 합니다. 실패 분류는 유형별 개인정보 보호 실패를 참고하세요.

자원과 취소 경계¶

라이브러리가 소유한 텍스트 변환, 구조 탐색, 분석기 결과 보존과 버퍼링 검사에는 상한이 있습니다. 정확한 상한과 단위는 설정에서 확인할 수 있습니다.

Reactor의 취소는 요청 세션을 닫지만, Java는 임의의 동기식 분석기나 신뢰 도구 코드를 강제로 중단할 수 없습니다. 이러한 협력 객체는 중단 요청을 준수하고 자체 네트워크 또는 실행 제한 시간을 두어야 합니다.

생성 횟수, 도구 반복 횟수, 비용, 부수 효과, 동시성과 호출량 제한은 라이브러리가 아니라 애플리케이션 또는 오케스트레이션 정책의 책임입니다.

테스트 경계¶

spring-ai-privacy-guardrails-test는 모델과 위임 대상 도구 경계에서 관찰한 콘텐츠를 기록합니다. 이를 통해 애플리케이션은 원격 모델 없이도 원문 공개 범위, 재토큰화와 세션 정리를 검증할 수 있습니다.

PrivacyTestProbe는 테스트 전용입니다. 명시적으로 비우거나 닫기 전까지 캡처한 원문 값을 보존할 수 있으므로 운영 관찰 도구로 사용하면 안 됩니다. 사용법은 테스트 지원에 설명되어 있습니다.

provider와 전송 경계¶

provider adapter는 provider 결과를 공통 분석기 SPI로 변환합니다. core의 해석이나 원문 공개 정책은 변경하지 않습니다. 원격 전송 보안, 자격 증명, 배포 구성, recognizer 또는 모델 품질은 provider와 애플리케이션의 책임입니다.

사용 가능한 원격·프로세스 내부 구성은 배포 artifact에 설명되어 있습니다.

영속성 경계¶

Advisor는 지원하는 모델 또는 도구 경계를 통과하는 메모리와 검색 콘텐츠의 사본을 보호합니다. ChatMemory, 벡터 저장소, 데이터베이스, 추적 정보, 로그 또는 provider 시스템에 이미 저장된 데이터를 다시 작성하지는 않습니다.

영속 데이터의 쓰기, 보존, 삭제, 접근 제어와 진단 정보는 애플리케이션이 별도로 보호해야 합니다. 자세한 내용은 영속성과 진단 경계를 참고하세요.