데이터 정책
데이터 정책 (Data policy)
LLM Gateway에서 민감 데이터를 리댁션하고 추적 콘텐츠를 제어하는 데이터 정책을 만들어요.
참고: LLM Gateway는 베타 단계예요.
LLM Gateway의 Data Policy 탭은 데이터 정책을 담아요. 단일 데이터 정책은 생성 양식의 두 섹션과 일치하는 두 영역을 다룹니다:
- 데이터 보존 (Data retention): 게이트웨이가 요청·응답 본문을 LangSmith 추적에 기록하는지 여부.
- 데이터 보호 (Data protection): 게이트웨이가 LLM 프로바이더에 요청이 도달하기 전에 스캔하고 리댁션하는 민감 데이터, 그 스캔이 실행될 수 있는 시간, 한도 초과 시 요청이 진행되는지 여부.
가용성 (Availability)
데이터 정책은 LLM Gateway에 접근할 수 있는 모든 조직에서 사용할 수 있어요. Data Policy 탭이 제공하는 것을 형성하는 두 가지 entitlements가 있어요:
- Data protection은 기본적으로 켜져 있어요. 이 entitlement가 꺼지면 클라우드 Enterprise 조직은 Request access 링크와 함께 회색 처리된 탭을 보고, 그 외 모든 조직은 탭을 전혀 보지 못해요.
- PII redaction은 기본적으로 꺼져 있으며 선택된 조직에 활성화돼요. 이 entitlement가 없으면 PII 옵션이 생성·편집 양식에서 사용할 수 없게 되고, API는 PII를 감지하도록 구성된 정책을 거부해요.
둘 중 하나를 변경하려면 계정 팀에 문의하세요.
데이터 보존 (Data retention)
LLM Gateway를 통한 모든 호출은 LangSmith로 추적돼요. Trace content 토글은 요청·응답 본문이 그 추적에 저장되는지 제어해요. 모든 조직에서 꺼져 있고, 데이터 정책이 그 정책과 일치하는 요청에 대해 켜요. 추적 콘텐츠가 비활성화되면 게이트웨이는 여전히 토큰 사용량, 지연 시간, 상태, 모델 정보, 정책 평가 결과 같은 메타데이터를 기록해요. 켜지면 동일한 메타데이터에 호출 콘텐츠가 추가로 기록돼요.
게이트웨이 추적은 호출자 API 키와 연결된 워크스페이스의 gateway라는 공유 프로젝트와, UI에서 트래픽을 격리하는 호출자별 프로젝트에 기록돼요. 프로젝트 명명 체계, 추적이 담는 메타데이터, 추적 가시성을 제한하는 방법은 추적 및 접근 제어를 참고하세요.
데이터 보호 (Data protection)
데이터 정책이 감지를 활성화하면 게이트웨이는 LLM 프로바이더에 도달하기 전에 아웃바운드 요청을 스캔해요. 감지된 값은 요청이 업스트림으로 전달되기 전에 자리 표시자로 교체되므로 프로바이더는 리댁션된 페이로드만 보게 돼요. 성공적인 응답의 경우 게이트웨이는 응답을 호출자에게 반환하기 전에 자리 표시자를 원래 값으로 복원해요.
콘텐츠는 LLM에 전송될 때만 리댁션돼요. 응답이 반환되면 그 콘텐츠는 호출자에게 반환되기 전에 수화(rehydration)돼요. 추적 콘텐츠 캡처가 켜져 있으면 게이트웨이 추적은 리댁션된 자리 표시자를 포함해 프로바이더가 본 것을 반영해요. 게이트웨이 밖의 애플리케이션 추적은 여전히 그 응답에서 받은 복원된 값을 캡처할 수 있어요.
PII와 Secrets 토글은 독립적이에요. 새 정책에서 PII 감지는 (entitlement가 있는 조직의 경우) 모든 규칙이 선택된 채 켜지고, 시크릿 감지는 꺼진 채 시작돼요.
PII 감지 (PII detection)
Personally Identifiable Information(PII) 토글은 이름, 이메일, 미국 전화번호, 주소, 미국 SSN을 다룹니다. 그 아래에 6개의 규칙이 있으며, 각각 독립적으로 선택할 수 있고 게이트웨이가 감지하는 방식별로 그룹화돼요.
규칙 기반 범주는 정규 표현식으로 일치하며 감지 속도가 빨라요:
| 범주 | 감지되는 패턴 |
|---|---|
| Emails | 이메일 주소 패턴 |
| US phone numbers | 일반적인 미국 형식, 예: 415-555-1234 및 +1 (415) 555-1234. 단독 10자리 숫자는 일치하지 않음 |
| US Social Security numbers | 미국 SSN 패턴, 예: 123-45-6789 |
모델 기반 범주는 Presidio로 일치하며 감지 속도가 더 느려요:
| 범주 | 예시 |
|---|---|
| Names | 자연어의 사람 이름 |
| Locations | 주소, 도시, 국가 |
| Nationality, religious, and political groups | 국적, 종교 소속, 정치 소속 |
시크릿 감지 (Secrets detection)
Secrets 토글은 일반적인 API 키, 토큰, 자격 증명을 감지해 요청에서 리댁션해요:
| 범주 | 감지되는 패턴 |
|---|---|
| LangSmith | 개인 액세스 토큰, 서비스 키, 레거시 API 키 |
| AWS | 액세스 토큰 |
| GitHub | 개인 액세스 토큰, 세밀한 PAT, OAuth 토큰, 앱 토큰 |
| GitLab | 개인 액세스 토큰 |
| AI providers | OpenAI API 키, Anthropic API 키 |
| Cloud platforms | GCP API 키, Azure AD 클라이언트 시크릿, Google OAuth 액세스 토큰 |
| Collaboration tools | Slack 봇, 사용자, 앱 토큰, Slack 웹훅 URL, Datadog 액세스 토큰 |
| Package registries | PyPI 업로드 토큰, npm 액세스 토큰 |
| Cryptographic | 비공개 키, JWT |
| Other | Stripe 액세스 토큰, SendGrid API 토큰 |
감지는 의도적으로 좁아요: 인식 가능한 토큰 모양에 고정된 규칙만 적용되므로 프롬프트의 고엔트로피 산문은 리댁션을 트리거하지 않아요.
스캔 시간 및 타임아웃 동작 (Scan time and timeout behavior)
각 데이터 정책은 스캔 파이프라인이 실행될 수 있는 시간을 상한으로 두고 상한에 도달했을 때 무엇이 일어날지 결정해요:
- Max processing time (seconds): 기본 2, 0.1~30으로 구성 가능.
- On timeout: 기본 Allow request. 스캔이 제때 끝나지 않는 요청을 거부하려면 Block request로 설정.
두 필드 모두 PII 감지 entitlement가 있는 조직에서만 나타나요. 다른 곳에서는 정책이 기본값을 사용해요.
데이터 정책 만들기 (Create a data policy)
경고: 정책 생성·관리에는
organization:manage권한이 필요해요.
- LangSmith 사이드바에서 LLM Gateway를 클릭해요.
- Data Policy 탭을 엽니다.
- Create data policy를 클릭해요.
- 범위를 선택해요: Organization, Workspace, User 또는 API Key.
- Policy name을 입력하거나 생성된 것을 유지해요.
- 워크스페이스, 사용자 또는 API 키 범위의 경우 정책이 적용되는 특정 대상을 선택해요.
- (선택) Data retention 아래에서 Trace content를 활성화해 추적에 요청·응답 본문을 저장해요.
- Data protection 아래에서 Secrets, PII 또는 둘 다 활성화해요. PII의 경우 적용할 규칙을 선택해요.
- (선택) Max processing time (seconds) 및 On timeout을 설정해요.
- Create data policy를 클릭해요.
데이터 정책은 구성된 범위에서 게이트웨이를 통과하는 모든 요청에 적용돼요. 즉시 적용돼요.
리댁션된 콘텐츠가 나타나는 방식 (How redacted content appears)
PII 또는 시크릿이 감지되면 콘텐츠는 프로바이더에 보내는 요청과 LangSmith 추적 모두에서 자리 표시자로 교체돼요. 예를 들어:
원본 요청 (Original request):
Please process the refund for John Smith, SSN 123-45-6789.
업스트림 리댁션 (Upstream redaction):
## disclaimer: Some values have been redacted by a reverse proxy and replaced with placeholders containing unique identifiers.
Please process the refund for [SAFE_TO_USE:PERSON_kbqdjxyz], SSN [SAFE_TO_USE:US_SSN_abqxlmwp].
게이트웨이는 면책 조항(disclaimer)을 앞에 붙여 모델이 자리 표시자를 그대로 재사용할 수 있는 값으로 취급하게 해요.
자리 표시자는 [SAFE_TO_USE:<CATEGORY>_<suffix>] 형식을 따릅니다:
- SAFE_TO_USE: 값을 리댁션된 자리 표시자로 표시하는 고정 접두사.
: 감지된 유형. 예:PERSON,LOCATION,US_SSN,US_PHONE_NUMBER,OPENAI_API_KEY,GITHUB_PAT,LANGSMITH_PERSONAL_TOKEN.: 8자리 태그. 한 요청에서 두 번 나타나는 값은 두 번 모두 동일한 자리 표시자를 받으며, 태그는 요청 간에 상관될 수 없어요.
LangSmith의 추적은 리댁션된 버전과 함께 리댁션이 발생했으며 어떤 범주가 감지됐는지 나타내는 메타데이터를 보여줘요.
다운스트림 디리댁션 응답 (Downstream de-redacted response):
업스트림 프로바이더가 성공적인 응답을 반환하면 게이트웨이는 자리 표시자를 호출자의 원래 값으로 교체해요. 스트리밍 응답은 이벤트별로 다시 쓰여져 디리댁션이 스트림을 지연시키지 않아요. 예를 들어 에이전트는 이 응답을 볼 수 있어요:
Confirming John Smith's SSN as 123-45-6789. I will process the full refund.
리댁션이 다루는 범위 (What redaction covers)
다루는 것:
- 아웃바운드 요청 콘텐츠(LLM 프로바이더에 보내는 메시지)는 게이트웨이를 떠나기 전에 스캔되고 리댁션돼요.
- LangSmith 추적에 나타나는 것은 리댁션된 버전이에요.
- 성공적인 프로바이더 응답의 자리 표시자(스트리밍 여부와 무관)는 응답이 호출자에게 도달하기 전에 원래 값으로 복원돼요.
다루지 않는 것:
- LLM 프로바이더의 응답: 모델이 응답에서 민감 데이터를 생성하면 그 콘텐츠는 스캔되거나 리댁션되지 않아요. 요청만 스캔돼요.
- 프로바이더 오류: 프로바이더가 400 이상의 상태를 반환하면 게이트웨이는 본문을 그대로 통과시켜 호출자가 원래 값이 아닌 자리 표시자를 보게 돼요.
- 이미 추적에 있는 데이터: 리댁션은 게이트웨이를 통과하는 요청에만 적용돼요. 게이트웨이를 우회해 LangSmith API에 직접 기록된 추적은 스캔되지 않아요.
- 플랫폼 수준 수집: 도착 방식과 무관하게 PII가 LangSmith에 들어가는 것을 방지하는 것이 요구사항이라면(예: 데이터 상주 규정 준수) 게이트웨이 리댁션만으로는 충분하지 않아요. 이를 위해서는 수집 수준 리댁션이 필요하며, 이는 별도 기능이에요.
- 시스템 및 개발자 프롬프트: 이들은 단일 JSON 문자열로 도착하는 어시스턴트 도구 호출 메타데이터 및 도구 호출 인자와 함께 건너뛰어져요. 사용자 메시지, 도구 결과, 구조화된 도구 호출 인자는 스캔돼요.
스캐너 실패는 열림(fail open): 스캐너에 도달할 수 없거나 오류가 나면 요청은 그 단계가 만든 콘텐츠로 프로바이더에 계속 진행돼요. 요청을 차단할 수 있는 것은 스캔 타임아웃뿐이며, 그것도 정책의 타임아웃 동작이 Block request로 설정된 경우에만 그래요.
커버리지 경계가 중요해요. 보안 모델이 민감 데이터가 어떤 시스템에도(LLM 프로바이더뿐 아니라) 도달하지 못하게 하는 것을 요구한다면, 게이트웨이가 어떤 표면을 다루고 어떤 표면에 추가 제어가 필요한지 이해해야 해요.
다음 단계 (Next steps)
- 추적 및 접근 제어: 게이트웨이 추적이 어디에 들어가고 누가 읽을 수 있는지 보기.
- Spend policies: 데이터 보호와 함께 비용 제어 추가하기.
출처: 문서