LLM 애플리케이션의 '조용한 성능 저하(Degradation)'를 CI에서 검지하는 llm-canary 사용법

• 프롬프트 변경, RAG 수정, 모델 교체로 인한
  행동의 성능 저하(Degradation)는 일반적인 CI로는 검지할 수 없습니다 - llm-canary는 YAML로 LLM의 행동 테스트를 선언하고 CI를 게이트(Gate)하는 OSS입니다.
• 정답 데이터 없는 회귀 검지(Baseline + 의미적 유사도)와,
  **에이전트 행동 로그의 정책 검사(Policy Inspection)**가 특징입니다. - API 키 없이 모든 기능을 테스트할 수 있습니다(오프라인 가짜 프로바이더(Fake Provider) 포함)

pip install llm-canary
llm-canary init # 테스트 스위트(Suite) 생성
llm-canary run canary.yaml # API 키 없이 이대로 실행 가능

echo / fixture라는 결정적인 가짜 프로바이더가 포함되어 있어, 우선 무료로 메커니즘을 이해할 수 있습니다. 본 작업에서는 openai / anthropic, 또는 후술할 command / http를 통해 자신의 봇을 대상으로 합니다.

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

포인트는 system_prompt_file을 통해 애플리케이션이 실제로 사용하는 프롬프트 파일을 참조하는 것입니다. 테스트와 애플리케이션의 이중 관리가 발생하지 않으며, 프롬프트 편집 → PR → CI 검사로 이어지는 흐름을 만들 수 있습니다.

GitHub Actions는 한 줄이면 됩니다.

- run: llm-canary run suite.yaml --junit junit.xml --md summary.md

llm-canary record suite.yaml # 현재 출력을 베이스라인(Baseline)으로 저장
# ...프롬프트나 모델을 변경...
llm-canary check suite.yaml # 의미적 유사도가 임계값(Threshold)을 밑돌거나 비용이 급증하면 실패

LLM 출력은 바이트 단위로 일치하지 않으므로 스냅샷 테스트(Snapshot Test)는 사용할 수 없지만, "이전과 의미가 크게 달라지면 실패"라는 방식이라면 정답 데이터 없이도 성립합니다. 임계값은 --similarity-threshold / --cost-drift로 조정할 수 있습니다.

에이전트의 루프(Loop)에서 1스텝당 1행의 JSON을 출력하도록 합니다.

log.write(json.dumps({"type": "tool_call", "tool": "post_slack", "cost_usd": 0.001}) + "\n")

정책(Policy)으로 "해도 되는 일"을 선언합니다.

max_steps: 10
max_cost_usd: 0.05
forbidden_tools: [delete_records]
...

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

"데이터를 읽기 전에 게시했다", "금지된 도구를 호출했다", "같은 도구를 무한히 호출하고 있다" 등을 CI에서 차단할 수 있습니다.

providers:
- name: command # 실행 가능한 것이라면 무엇이든
options:
...

CI에서 자신의 봇을 기동하고 카나리(Canary)를 투입하면, 시스템 프롬프트·RAG·전후처리를 포함한 "진짜"가 검사됩니다.

docker compose up -d # 또는 pip install 'llm-canary[server]' && llm-canary serve

실행 이력 대시보드, 팀 공유 베이스라인, REST API가 구동됩니다. 데이터는 로컬의 SQLite에만 저장되며, 프롬프트와 로그 모두 외부로 유출되지 않습니다. 평가 SaaS에 데이터를 보낼 수 없는 환경에 적합합니다.

과제	명령어
프롬프트 변경에 따른 성능 저하 검지	llm-canary run
정답 데이터 없는 회귀 검지	record / check
에이전트 행동 검사	trace --policy
스위트의 정적 검증	validate
팀 공유 및 이력 관리	serve

리포지토리: https://github.com/okssusucha/llm-canary (MIT / Python 3.11+)

Issue 및 PR은 일본어로 작성해도 괜찮습니다.