로그에 개인 데이터를 남기지 않는 AI 게이트웨이
지원 어시스턴트는 고객의 이름과 이메일 주소를 다루어야 하므로, 어시스턴트가 호출하는 모델은 이를 볼 수 있어야 합니다. 그 모델 앞에 있는 게이트웨이는 감사와 디버깅을 위해 로그를 남기며, 그 로그에는 이 정보가 남아서는 안 됩니다. 이 워크스페이스는 그러한 게이트웨이를 Kubernetes 매니페스트로 컴파일합니다.
이를 수행하는 것은 게이트웨이 자체의 값인 core/gateway/litellm의
values.log_masking입니다. 이 값은 게이트웨이가 로그에 넘기는 각 호출의 사본만
마스킹하며, 그 외에는 아무것도 하지 않습니다. 모델은 호출자가 보낸 그대로 요청을 받고,
호출자는 모델이 작성한 그대로 응답을 받습니다. 이것이
모델 자체로부터 텍스트를 숨기는 Feature core/data-masking과의 차이점입니다. 둘은 서로 대안이며, 아래의 둘 중 하나를
선택하는 방법에 관한 절에서 하나의 게이트웨이에 둘 다 설정했을 때 어떤 일이 일어나는지 보여 줍니다.
이 워크스페이스는 자체 카탈로그 엔티티를 작성하지 않습니다. 여기 있는 세 개의 엔티티 파일, 즉 Aggregate, Manifest, Release가 누구든 작성하는 내용의 전부입니다.
구성되는 내용
| 인스턴스 | 카탈로그 Component | 여기서의 역할 |
|---|---|---|
router | core/gateway/litellm | AI 게이트웨이: 게시된 별칭 하나 assistant를 models 소켓에 연결된 모델로부터 제공합니다 |
gpt | core/ai-model/openai | 그 별칭 뒤의 모델로, OpenAI 자체 API이며 참조로 연결됩니다. 이를 위해 클러스터에서 실행되는 것은 없습니다 |
analyzer | core/security/presidio-analyzer | 텍스트에서 민감한 구간을 찾습니다 |
anonymizer | core/security/presidio-anonymizer | 전달받은 구간을 치환합니다 |
uses 에지는 세 개입니다. 게이트웨이의 models 소켓에서 모델로 향하며 게이트웨이가 모델에 제시하는 키를
credential로 전달하는 에지, 그리고 게이트웨이의 pii_analyzer 소켓과
pii_anonymizer 소켓에서 두 인식기 서비스로 향하는 에지입니다. Aggregate는 시크릿을 지정하지 않고
그 자격 증명을 연결하며, Release는 연결의 infra에서 이를 지정합니다. 이는 네임스페이스가 이미 보유한 Secret으로, Manifest의
실현은 이를 참조할 뿐 렌더링하지 않습니다. 게이트웨이의 values.log_masking은
마스킹할 대상을 나열합니다. patterns 아래에는 회사 티켓 번호에 대한 정규 표현식이,
entities 아래에는 엔터티 유형 PERSON과 EMAIL_ADDRESS가 있습니다.
기본 목록은 없습니다. 둘 다 나열하지 않은 게이트웨이는 로그에서 아무것도 마스킹하지 않으며,
이 값이 없을 때와 정확히 똑같이 렌더링됩니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example ai-gateway-log-masking그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd ai-gateway-log-masking빌드
aggrega build --release release.yaml --auto-pullrelease는 빌드하기 전에 lockfile이 필요하며, lockfile은 배포되지 않고 생성되므로 새로 clone한 저장소에는 lockfile이 없습니다. 먼저 lockfile을 해석하여 생성하거나, 빌드가 채우도록 합니다:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build이 워크스페이스는 .aggrega-config.yaml이 지정하는 기본 레지스트리에서 카탈로그 엔터티를 해석합니다. 로그 마스킹은 게이트웨이 자체의 Recipe가 작성하므로, 빌드는 컴파일러에 내장된 플러그인 외에는 어떤 플러그인도 실행하지 않습니다.
빌드는 다음을 출력하며, <workspace>는 이 예제의 폴더를 나타냅니다.
[… omitted: the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 9 files written to <workspace>/distAI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `ai-gateway-log-masking` 폴더가 없으면 `example`에 `ai-gateway-log-masking`을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `ai-gateway-log-masking` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `ai-gateway-log-masking`, `release`에 `release.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `ai-gateway-log-masking/dist/` 아래에 있습니다.렌더링된 트리
dist/helm/├── analyzer-default-service.yaml├── analyzer-deployment.yaml├── anonymizer-default-service.yaml├── anonymizer-deployment.yaml├── gpt-service.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yaml이 값은 자체 파일을 가져오지 않습니다. 게이트웨이의 Recipe가 이 값을 게이트웨이의 구성에 기록하고, 그 구성이 로드하는 모듈을 게이트웨이의 ConfigMap에 추가합니다. 모델은 파일 하나, gpt-service.yaml을 렌더링합니다. 이는 클러스터 내부 이름을 OpenAI의 API 호스트인 api.openai.com에 매핑하는 Service입니다. 모델의 키는 아무 파일도 렌더링하지 않는데, 키를 담은 Secret이 이미 존재하기 때문입니다.
게이트웨이 구성 본문의 시작 부분인 라우팅 테이블에는 항목이 하나 있습니다. 이 항목은 모델이 게시하는 내용, 즉 엔드포인트인 OpenAI의 API 기본 URL과 모델 이름으로부터 작성되며, 게이트웨이의 Recipe가 연결의 키를 전달하는 변수의 이름을 지정합니다:
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY가드레일 항목
다음은 게이트웨이의 구성 본문, 즉
dist/helm/router/litellm-gateway-config/configmap.yaml의 config.yaml 키를
litellm_settings 섹션부터 보여 줍니다:
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - log_masking.withhold_failed_calls redact_messages_in_exceptions: trueguardrails: - guardrail_name: "router.log-masking" litellm_params: guardrail: log_masking.LogMasking default_on: true mode: logging_only patterns: - pattern_type: regex name: "ticket" pattern: "\\bTCK-[0-9]{6}\\b" action: MASK pii_entities_config: "PERSON": MASK "EMAIL_ADDRESS": MASKgeneral_settings: disable_error_logs: true게이트웨이의 Recipe는 이 전부를 values.log_masking에서 작성하며, 항목 이름을
게이트웨이 이름(여기서는 router)을 따라 짓되, 표준 라이브러리의 실현이 작성하는 가드레일 항목이
하이픈을 쓰는 자리에 점을 씁니다. 따라서 그쪽의 어떤 첨부도 이름이 무엇이든 이 항목을 대신할 수 없습니다. 여기서 읽어 낼 만한 점이 다섯 가지 있습니다.
mode: logging_only는 완료된 호출이 로그로 넘겨지는 곳에서만 실행되고
다른 곳에서는 실행되지 않는 가드레일을 위한 게이트웨이 고유의 모드입니다. 항목이 로드하는 클래스는
항목이 무엇을 지정하든 이 모드를 지키므로, 요청이 전달되기 전의 요청이나
응답이 반환되기 전의 응답에 대해서는 결코 호출되지 않습니다.
default_on: true는 모든 호출에서 이를 실행합니다. 호출자는 요청에서 이를 끌 수 없으며,
게이트웨이의 상시 활성 가드레일을 비활성화하라고 요청하는 경우도
마찬가지입니다.
패턴은 작성된 그대로 게이트웨이에 전달됩니다. 패턴은 게이트웨이 내부에서 대소문자를 무시하고
매칭되며, 일치하는 부분은 모두 대문자로 된 패턴 이름을 대괄호로 감싼 것으로
영구히 치환됩니다: [TICKET_REDACTED]. 게이트웨이는
시작할 때 표현식을 컴파일하며, 컴파일되지 않는 표현식은 게이트웨이의 시작을
막습니다. 컴파일러는 이 문자열을 읽지 않고 그대로 넘깁니다.
엔터티 유형은 두 인식기 서비스가 찾아냅니다. 항목은
주소를 지정하지 않습니다. 게이트웨이는 두 주소를 모두 환경에서 읽으며, 게이트웨이의
Recipe가 두 엣지로부터 이를 채웁니다. 다음은 dist/helm/router-deployment.yaml의
게이트웨이 컨테이너 env입니다:
env: - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: openai-api-key key: api-key - name: PRESIDIO_ANALYZER_API_BASE value: http://analyzer-default:3000 - name: PRESIDIO_ANONYMIZER_API_BASE value: http://anonymizer-default:3000첫 번째는 모델의 키로, Release가 지정하는 Secret에서 참조되며
결코 그대로 기록되지 않습니다. 나머지 둘은 인식기의 주소입니다. 사람의
이름은 <PERSON>이 되고 주소는 <EMAIL_ADDRESS>가 됩니다.
실패한 호출은 마스킹되지 않고 보류됩니다. 게이트웨이는 실패한 호출에 대해 로깅
가드레일을 실행하지 않으므로, 항목이 로드하는 모듈은
log_masking.withhold_failed_calls도 제공합니다. 이는 요청 가드 바로 뒤에 등록되며,
게이트웨이의 Recipe는 그 옆에 두 설정을 작성합니다. 이 콜백은
그 뒤에 등록된 어떤 콜백보다도 먼저 실패한 호출의 레코드를 넘겨받아, 호출자나 모델이 작성한 모든 텍스트를
일치 여부와 관계없이 [TEXT_WITHHELD]로, 오류의 텍스트를 [ERROR_TEXT_WITHHELD]로 치환하고,
재시도가 보내는 내용은 그대로 둡니다. disable_error_logs는 실패한 호출을 지출
로그에서 제외하고, redact_messages_in_exceptions는 게이트웨이가 오류에 첨부하는 세부 정보에서
요청의 메시지를 제외합니다.
같은 ConfigMap에는 두 번째 키인 log_masking.py가 있습니다. 이는 항목의
guardrail과 두 번째 callbacks 항목이 지정하는 모듈입니다. 게이트웨이의 Recipe는
values.log_masking에 무언가가 나열되어 있을 때만 이 모듈, 그 callbacks 항목, 가드레일 항목, 두 설정을
추가합니다. 따라서 아무것도 나열하지 않은 게이트웨이는
이들 중 어느 것도 없이 ConfigMap을 렌더링하며, 이는 값이 없는 게이트웨이와 바이트 단위로 동일합니다.
로그를 읽는 사람이 보는 것과 모델이 보는 것
요청에 다음 텍스트를 담은 호출자를 예로 들어 보겠습니다:
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.위의 블록과 아래의 세 블록은 실행 중인 게이트웨이가 이 텍스트를 어떻게 처리하는지 보여 주는 예시이며, 빌드의 출력이 아닙니다.
모델 provider는 호출자가 보낸 그대로 요청을 받고, 호출자는 모델의 응답을 온 그대로 받습니다. 게이트웨이가 호출을 넘기는 로깅 통합은 같은 메시지를 마스킹된 상태로 받습니다:
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.전화번호는 보낸 그대로 기록됩니다. attachment가
PHONE_NUMBER를 나열하지 않고 어떤 패턴도 이와 일치하지 않기 때문입니다. 나열된 어떤 것과도 일치하지 않는 텍스트는 절대
마스킹되지 않습니다.
게이트웨이가 로그로 넘기는 성공한 호출의 모든 사본은 같은 방식으로 마스킹됩니다. 메시지, 표준 로깅 페이로드의 메시지와 응답, 게이트웨이가 조립하는 스트리밍 응답, provider가 본 요청과 응답, 지출 로그가 보관하는 요청, 각 통합이 받는 응답이 그 대상입니다. 모델의 응답도 이 사본들에서 마스킹됩니다:
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].마스킹되지 않는 것
로그를 마스킹한다고 해서 다른 누구에게서 텍스트가 감춰지는 것은 아니며,
values.log_masking의 설명에도 그렇게 적혀 있습니다.
- 모델 provider는 모든 것을 마스킹되지 않은 채로 받으며, 게이트웨이와 두 인식기 서비스도 마찬가지입니다.
- 실패한 호출은 게이트웨이가 쓰는 어떤 로그에도 요청 텍스트를 남기지 않으며, 이로 인해
두 가지를 잃습니다. 실패한 호출에 대한 게이트웨이 자체의 로그 줄에는
An error was logged with its text withheld, as log masking is on: BadRequestError처럼 오류의 종류만 남으므로, provider의 메시지와 트레이스백은 그 로그에서 빠집니다. 또한 실패한 호출은 지출 로그와 일일 지출 합계에서도 빠지는데, 이들은 성공한 호출만 집계하기 때문입니다. 카탈로그 밖에서 구성된 로깅 통합은 실패한 호출이 지닌 예외에서 provider 자체의 오류 메시지를 여전히 읽을 수 있으며, 게이트웨이 자체 콜백보다 먼저 등록된 통합은 실패한 호출의 텍스트를 들어온 그대로 전달받습니다. - 마스킹을 거쳐 기록되는 로그만 대상입니다. 게이트웨이의 디버그 출력과 provider 자체의 로그는 해당하지 않습니다. 요청의 메타데이터, 도구 정의, 헤더는 보낸 그대로 기록됩니다.
- 사본을 마스킹할 수 없는 호출은 텍스트를 보류한 채 기록됩니다.
인식기에 연결할 수 없으면 일부만 마스킹된 사본은 기록되지 않습니다. 그 호출의 모든 사본에 있는
모든 텍스트가
[TEXT_WITHHELD]로 대체되고, 레코드는 평소처럼 로그에 전달되므로 그 호출은 여전히 지출 로그에 집계됩니다. 게이트웨이 자체 로그에는 그 호출의 텍스트가 보류되었다는 사실이 기록됩니다. 호출 자체에는 평소처럼 응답합니다.
카탈로그가 렌더링하는 이 게이트웨이는 로그를 어떤 로깅 통합에도 전달하지 않으며, 지출 로그에는 요청이나 응답 텍스트도, 실패한 호출도 남지 않습니다. 따라서 마스킹이 보호하는 사본은 게이트웨이에 구성된 통합이나 텍스트를 보관하는 지출 로그가 받게 될 사본입니다.
로그 마스킹인가 데이터 마스킹인가
core/data-masking은 나열된 텍스트를 모델로부터 숨기며, 이 게이트웨이에서 그 구현은 연결되어 있는 동안 게이트웨이의 메시지 내용 로깅을 끕니다. 그 옆에서는 로그 마스킹이 작용할 대상이 남지 않으며, 독자는 둘을 하나의 보호로 오해할 수 있습니다. 그래서 게이트웨이는 둘을 함께 쓰는 것을 거부합니다.
values.log_masking에 무언가가 나열되어 있는 동안 게이트웨이에 core/data-masking 연결이 있으면, 게이트웨이 자체 Component의 어서션에 의해 빌드가 중단됩니다.
masked라는 이름의 연결을 게이트웨이에 추가하고 그 구현을 Manifest에 바인딩하면 다음이 출력됩니다:
[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][DEVELOPER_ERROR E0033] Component/Feature assertions caused by: Component "core/gateway/litellm" instance "router" assertion "log_masking_not_beside_data_masking": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: "router" lists what to mask in its logs under values.log_masking, and the core/data-masking attachment "masked" is on it too: that attachment's realization turns the gateway's logging of message contents off, so log masking would have nothing left to act on, and a reader could take the two for one protection. Remove values.log_masking to mask what travels, or the "masked" attachment to mask only what is logged모델은 데이터를 보아야 하지만 로그에는 남지 않아야 하는 경우에는 로그 마스킹을 사용하고, 모델도 데이터를 보아서는 안 되는 경우에는 데이터 마스킹을 사용합니다. 둘 다 같은 patterns와 entities를 읽으므로, 하나의 목록은 어느 쪽에서든 같은 의미를 가집니다.
컴파일러가 해석하지 않는 부분
컴파일러는 패턴과 엔터티 유형을 문자열로 게이트웨이의 구성에 전달합니다. 컴파일러는 정규식을 컴파일하지 않고, 티켓 번호나 사람이 무엇인지 알지 못하며, 게이트웨이가 전달할 트래픽을 보지 않습니다. 이 워크스페이스에서 만날 수 있는 각 중단 — 인식기 소켓이 연결되지 않은 상태의 엔터티 유형, 분석기가 영어에서 인식하지 못하는 엔터티 유형, 하나의 게이트웨이에서 데이터 마스킹과 함께 쓰인 로그 마스킹, 자격 증명 없이 관리형 모델에 연결되는 연결 — 은 카탈로그 자체의 엔터티가 게이트웨이의 Component 또는 그 Recipe의 어서션으로 선언한 것이며, 그 어느 것도 텍스트에 대한 이해에 기반하지 않습니다.
응용하기
- 패턴만 마스킹합니다.
values.log_masking에서entities를 제거하고, 두 recognizer 컴포넌트와 그 엣지, 그리고 Release에 있는 해당 항목을 제거합니다. 패턴은 게이트웨이 내부에서 매칭되므로 두 서비스 모두 필요하지 않습니다. - 더 많은 엔티티 유형을 마스킹합니다. recognizer 자체의 어휘로
entities에 추가합니다. analyzer가 영어에서 인식하지 못하는 유형은 빌드를 중단시키고 인식하는 유형의 이름을 알려 줍니다. - 모델에서도 텍스트를 숨깁니다.
values.log_masking을 같은patterns와entities를 나열하는 게이트웨이의core/data-masking첨부로 바꾸고, Manifest에서 그 실현을 바인딩합니다. - 두 번째 모델을 제공합니다. 다른 모델 컴포넌트를 고유한 별칭으로
models소켓에 연결하고, 게이트웨이가 그 연결에서 해당 컴포넌트에 제시하는 키를 함께 지정합니다.values.model은 계속 게이트웨이가 게시하는 별칭을 가리킵니다. 마스킹은 게이트웨이가 제공하는 모든 별칭의 호출에 적용됩니다.