프롬프트 변경으로 인한 성능 저하를 CI에서 방지하기 — LLM 회귀 테스트 도구 llm-canary 제작

LLM 앱 특유의 「조용한 성능 저하 (Degradation)」 문제

LLM을 도입한 앱을 운영하다 보면 다음과 같은 사고가 발생합니다.

• 시스템 프롬프트 (System Prompt)를 한 줄 수정했더니, 기존에 잘 지켜지던 JSON 출력 형식이 깨졌다
• RAG의 전처리 (Pre-processing)를 바꿨더니, 거절해야 할 질문에 답변하기 시작했다
• 모델을 교체했더니, 답변은 정확하지만 토큰 비용이 2배가 되었다

무서운 점은, 일반적인 CI (Continuous Integration)로는 이를 알아차릴 수 없다는 것입니다. 코드 테스트는 통과합니다. 타입 (Type)도 맞습니다. 하지만 AI의 「행동 (Behavior)」이 변해 있습니다. 사용자로부터 클레임이 들어온 후에야 비로소 발견되는 것이 전형적인 패턴입니다.

이 문제를 해결하기 위해, OSS 회귀 테스트 도구인 llm-canary를 만들었습니다. 탄광의 카나리아처럼, AI의 상태가 이상해지면 릴리스 전에 알려주는 도구입니다.

pip install llm-canary
llm-canary init && llm-canary run canary.yaml # API 키 없이 이대로 동작함

무엇을 할 수 있는가

1. YAML로 선언하는 프롬프트 테스트

name: support-bot
providers:
- name: openai
...

llm-canary run suite.yaml # 전부 OK라면 종료 코드 0, 실패 시 1

어서션 (Assertion)은 11종류: 부분 일치, 정규 표현식 (Regular Expression), JSON Schema 검증, 의미적 유사도 (Semantic Similarity), LLM-as-judge, 비용/레이턴시 (Latency)/토큰 예산 등. matrix:를 통해 「화난 고객 × 3개 언어」와 같은 데카르트 곱 (Cartesian Product) 전개도 가능합니다.

2. 정답 데이터 없는 회귀 감지

LLM의 출력은 바이트 단위로 안정적이지 않기 때문에, 스냅샷 테스트 (Snapshot Test)는 사용할 수 없습니다. llm-canary는 「모범 사례를 기록 → 의미적 유사도와 비용 드리프트 (Cost Drift)로 비교」하는 방식을 취합니다.

llm-canary record suite.yaml # 현재 출력을 베이스라인 (Baseline)으로 저장
llm-canary check suite.yaml # 의미가 어긋나거나 비용이 급증하면 실패

사람이 정답 데이터를 준비할 필요가 없습니다. 「이전과 크게 달라지면 알려줘」라고 하는 것만으로 회귀 감지가 성립됩니다.

3. 에이전트의 「행동」을 정책으로 검사

LLM 앱은 이제 단순히 「말하는 것」뿐만 아니라, 도구를 사용하여 행동합니다. 리스크는 「무엇을 말했는가」에서 「무엇을 했는가」로 옮겨갔습니다.

llm-canary는 에이전트의 행동 로그 (JSONL)를 정책 (Policy)으로 검사할 수 있습니다.

# policy.yaml
max_steps: 10
max_cost_usd: 0.05
...

llm-canary trace trace.jsonl --policy policy.yaml

4. 「순수 모델」이 아닌 「당신의 봇」을 검사하기

이 부분이 설계상 가장 공을 들인 지점입니다. 카나리아가 의미를 갖는 것은, 당신이 변경하는 것 (시스템 프롬프트, RAG, 전후처리)이 테스트 실행 경로에 포함되어 있을 때뿐입니다. 순수 LLM API에 테스트용 프롬프트를 던지는 것만으로는 그것은 「LLM 테스트」일 뿐 「당신의 앱 테스트」가 아닙니다.

그래서 어떤 구조의 앱이라도 검사 대상으로 삼을 수 있는 두 가지 프로바이더 (Provider)를 준비했습니다.

providers:
# 실행 가능한 것이라면 무엇이든 (stdout이 응답으로 반환됨)
- name: command
...

CI에서는 자신의 봇을 기동하고 카나리아를 향하게 하기만 하면 됩니다.

- run: docker compose up -d my-chatbot
- run: llm-canary run suite.yaml

5. 셀프 호스트형 평가 서버

llm-canary serve를 통해 사내에 상주시키면 실행 이력, 대시보드, 팀 공유 베이스라인을 사용할 수 있습니다. 프롬프트도 에이전트 로그도 외부로 나가지 않습니다 (SQLite에 저장). 평가 SaaS에 데이터를 보낼 수 없는 조직에서도 사용할 수 있습니다.

설계 방침: 오프라인 퍼스트 (Offline-first)

개발 과정에서 철저히 지킨 것은 「API 키 없이 전부 동작한다」는 것입니다. 테스트 91건은 모두 오프라인으로 돌아가며, 동봉된 샘플도 키 없이 작동합니다. echo / fixture라는 결정적인 가짜 프로바이더를 동봉하고 있으므로, 우선 무료로 메커니즘을 접해볼 수 있습니다.

promptfoo / DeepEval과의 차이점

기존 도구들은 강력하지만, 틈새 시장(niche)이 존재합니다.

promptfoo / DeepEval	llm-canary
프롬프트 평가 (Prompt Evaluation)	◎ 충실함
...

"평가 데이터를 외부로 유출할 수 없다" 또는 "에이전트 (Agent)의 행동을 제약하고 싶다" 중 어느 하나라도 해당되는 분들은 시도해 보시기 바랍니다.

리포지토리 (Repository)

MIT 라이선스, Python 3.11+。Issue/PR은 일본어 또는 영어 모두 환영합니다.

Discussion