stillsane — LLM 드리프트 캐너리

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

stillsane은 배포된 LLM 엔드포인트를 외부에서 주기적으로 호출해 응답을 기준선과 비교함으로써 에러 없이 조용히 진행되는 품질 저하를 찾아내는 경량 도구다. 각 프로브의 정상 변동성을 학습해 MAD·IQR 기반의 분산 밴드를 만들고, 밴드를 크게 벗어나면 drift로 표시해 CI나 웹훅으로 알린다. 설치와 구성은 간단하며 기준선은 자동 갱신되지 않아 의도치 않은 재기준화를 막고, 판사는 실패 프로브에 한해 선택적으로 설명을 생성한다.

섹션별 상세

배포된 LLM 애플리케이션은 에러나 지연 없이도 품질이 떨어질 수 있고, 그런 변화는 사용자 불만이 나오기 전까지 감지되지 않는다는 문제가 있다. stillsane은 외부에서 주기적으로 소규모 프롬프트 집합을 현재 엔드포인트에 호출해 응답을 기준선과 비교하는 방식으로 이 문제를 해결한다. 이 접근은 계정·SDK·호스팅 서비스를 필요로 하지 않으며 단일 구성 파일과 명령으로 운영할 수 있도록 설계되었다.

변화 감지의 핵심은 '프로브별 분산 밴드'를 학습하는 것이다. 기준선에서 여러 샘플을 수집해 샘플들 사이의 거리 분포를 구하고, 점검 시 새 샘플과 기준선 샘플 사이 거리 분포가 올라갔는지를 비교해 드리프트를 판정한다. 이렇게 하면 템플릿처럼 거의 동일한 JSON 추출과 매번 다른 문장 요약 같은 서로 다른 변동 특성을 프로브별로 자동으로 고려할 수 있어 오탐과 미탐을 줄인다.

근거

기준선은 자동으로 업데이트되지 않으며 오직 명시적 baseline 명령으로만 교체할 수 있다. — 본문에서 'Baselines never update themselves. Only stillsane baseline replaces one.'라는 문장과 구성 파일 해시로 변경을 감지한다고 적힌 부분.

통계 처리에서는 MAD와 median을 기본으로 쓰고, MAD가 붕괴할 때는 IQR로 폴백하며 그래도 측정 불가능하면 바닥값을 쓴다. 이동량의 크기는 z로 보고하며 z는 (관측−중앙값)/(1.4826×MAD)로 계산해 표준 점수의 강건한 유사치를 제공한다. 이 수치는 정규성 가정 없이 스케일-프리한 크기 비교를 가능하게 하고, 부수적으로 Mann–Whitney p-value를 보조 근거로 제시한다.

근거

z는 (observed − median) / (1.4826 × MAD)로 계산해 분포 가정 없이 이동 크기를 스케일-프리로 나타낸다. — variance 섹션에서 z 계산식을 명시하고 1.4826의 용도를 MAD를 표준편차와 비교 가능하게 하기 위한 보정으로 설명한 단락.

사용성 관점에서 설치와 기동은 간단하고 비용 구조도 명확하다. pip로 설치한 뒤 init으로 구성 파일을 만들고 baseline을 한 번만 수집하면 그 이후 check를 CI나 스케줄러에서 정기적으로 실행해 드리프트가 나오면 비정상 종료 코드로 파이프라인을 실패시킬 수 있다. 임베더는 첫 실행에 약 32MB를 내려받고 캐시되며, 로컬 해시 모드를 써 완전히 오프라인으로 운영할 수도 있다.

bash

pip install stillsane
stillsane init
stillsane baseline
stillsane check

이 명령들은 프로젝트를 빠르게 배포된 엔드포인트 감시 대상으로 만드는 최소 단계이다. 첫 줄은 패키지를 설치하는 명령이고 init은 샘플 구성 파일을 생성해 엔드포인트를 가리키게 만든다. baseline은 기준선 샘플을 수집하고 check는 현재 동작을 기준선과 비교해 드리프트를 감지한다.

yaml

targets:
- name: prod
  type: openai_compatible
  base_url: https://api.example.com/v1
  model: some-model-id
  api_key_env: PROVIDER_API_KEY
  watch_fingerprint: true
  probes:
  - id: extract_invoice
    prompt: "Extract the total and due date as JSON from: ..."
    baseline_samples: 5
    check_samples: 3
    checks:
    - valid_json
    - has_keys: [total, due_date]
    - semantic_similarity: auto
  alerts:
    webhook: https://hooks.example.com/...

구성 파일은 단순한 YAML로 저장해 깃에서 코드처럼 관리하도록 설계되어 있다. targets에 엔드포인트와 모델 정보를 적고 probes에 검사할 프롬프트와 샘플 수, 적용할 체크를 나열한다. baseline_samples는 한 번만 비용이 발생하는 기준선 샘플 수이며 check_samples는 주기적 체크에서 지불되는 샘플 수다.

근거

판정 실패 프로브에 대해서만 선택적 LLM 판사가 호출되며, 판사는 실패 원인을 한 문장으로 요약한다. — judge 블록 설명에서 'it only runs on probes that already failed their band'와 예시 출력 '-> breaking: Still valid JSON, but now wrapped in conversational prose.'가 나오는 부분.

실행 상태와 밴드의 건전성 자체를 점검하는 도구를 별도로 제공한다. status 명령은 최근 실행 기록과 에러 유형(전송 에러·타임아웃 등)을 보여줘 모니터 자체의 멈춤을 드러내고, bands 명령은 각 신호의 밴드가 합리적으로 측정되었는지 여부(예: collapsed)를 판별해 CI에서 실패시킬 수 있다. 이로 인해 '모니터가 멈춘 채 성공으로 보이는' 실패 모드를 구분할 수 있다.

bash

stillsane init --from-logs requests.jsonl --limit 20 --merge-distance 0.12 --probes-only

로그에서 대량의 실제 요청을 클러스터링해 프로브로 자동 변환하는 명령이다. 기본적으로 빈도 상위 N개 클러스터를 선택하고 유사도 임계값으로 병합 정도를 제어할 수 있다. 생성된 프로브는 주석으로 체크 제안이 달려 나오므로 사용자가 최종 검사를 결정해야 한다.

범위와 한계가 명확히 규정되어 있어 통합 전략을 선택하기 쉽다. stillsane은 사전 배포 평가나 트레이싱 기반 관찰, 대규모 평가 프레임워크를 대체하려고 하지 않으며 대신 관측성이나 SDK 삽입이 어려운 경우의 외부 합성 모니터링을 목적으로 한다. 웹 대시보드·호스팅 서비스·추적 통합 등은 비목표로 남아 있어 도구가 가벼운 편이라는 장단점이 동시에 존재한다.

json

{
  "signal": "semantic_distance",
  "finding": "collapsed",
  "suspect": true,
  "unit": "pairs",
  "n": 31
}

bands 명령이 출력하는 구조화된 예시 JSON로, 프로브별 밴드 상태를 기계가 읽기 좋게 보여준다. collapsed 표기는 MAD와 중앙값이 0이어서 스케일이 측정되지 않았음을 뜻하며 이 경우 해당 밴드는 신뢰하기 어렵다. CI에서 --json 플래그로 동일한 구조를 받아 실패 기준으로 삼을 수 있다.

근거

stillsane은 OpenAI 호환 엔드포인트와 임의 HTTP 엔드포인트를 대상으로 작동한다. — Design constraints와 targets 예시에서 type: openai_compatible과 arbitrary HTTP 타깃을 지원한다고 적힌 부분.

용어 해설

드리프트 캐너리(drift canary): — 드리프트 캐너리는 배포된 LLM 애플리케이션에서 성능 저하를 조용히 탐지하는 합성 모니터다. 주기적으로 샘플 프롬프트를 같은 엔드포인트에 호출해 응답을 기준선과 비교하고, 정상 변동 범위를 벗어나면 경고를 만든다. 네트워크 관찰만으로 동작하며 SDK나 계정이 필요하지 않다는 점이 설계상의 특징이다.
기준선 샘플링(baseline sampling): — 기준선 샘플링은 각 프로브의 정상 변동을 측정하기 위해 기초 시점에서 여러 번 호출해 샘플을 수집하는 과정이다. 이 샘플들로부터 프로브별 분포를 산출해 이후 체크에서 관측치가 정상인지 판단하는 밴드를 만든다. 기준선은 자동으로 갱신되지 않으며 오직 명시적 동작으로만 대체될 수 있다.
분산 밴드(variance band): — 분산 밴드는 프로브별 정상 변동 범위를 수치로 표현한 값으로, 각 신호의 중앙값과 스케일(MAD 또는 IQR)을 이용해 경계가 정해진다. 체크 시 새 샘플들과 기준선 샘플 사이의 거리 분포가 이 밴드에서 크게 벗어나면 드리프트로 판정한다. 밴드는 통계적 널리움이 아니라 해당 프로브의 경험적 변동성을 반영한다.
중앙값 절대편차(MAD (median absolute deviation)): — MAD는 이상치에 강건한 스케일 측정치로 중앙값으로부터 절대편차의 중앙값을 취한 값이다. stillsane는 평균과 표준편차 대신 MAD를 기본 스케일로 사용해 소수의 극단 샘플이 밴드를 망가뜨리지 않게 했다. MAD가 0으로 수렴할 때는 대체로 IQR(사분위범위)을 쓰고, 그것도 실패하면 바닥값을 쓴다.
프로바이더 지문(provider fingerprint): — 프로바이더 지문은 응답에서 관찰 가능한 제공자 식별자와 모델 ID, 토큰 비용 같은 메타신호를 합쳐 모델 변경을 추적하는 신호다. 엔드포인트 뒤에서 모델이 바뀌면 본문 품질 이전에 지문 신호가 움직일 수 있어 조기 경고가 된다. stillsane는 이 지문 변화를 구조적 신호로 항상 수집한다.

기술

Python
OpenAI-compatible endpoints
embeddings
SQLite
GitHub Actions
gpt-4o-mini

활용 사례

배포된 에이전트나 LLM 파이프라인에서 조용히 일어나는 품질 저하를 조기 탐지하는 데 사용한다.
일일 CI 잡으로 체크해 프로바이더 측 모델 변경이 사용자 영향으로 이어지기 전 경고를 받는다.
과거 요청 로그를 클러스터링해 실제 사용 형태를 대표하는 프로브를 자동 생성하고 유지보수 비용을 낮춘다.