TL;DR
- プロンプト変更・RAG修正・モデル乗り換えによる振る舞いのデグレは普通のCIでは検知できない
- llm-canary はYAMLでLLMの振る舞いテストを宣言し、CIをゲートするOSS
- 正解データなしの回帰検知(ベースライン+意味的類似度)と、エージェント行動ログのポリシー検査が特徴
- APIキーなしで全機能を試せる(オフラインの偽プロバイダ同梱)
インストールと最初の1分
pip install llm-canary
llm-canary init # お試しスイート生成
llm-canary run canary.yaml # APIキー不要でこのまま動く
echo / fixture という決定的な偽プロバイダが同梱されているので、まず無料で仕組みを理解できます。本番では openai / anthropic、または後述の command / http で自分のボットを対象にします。
ユースケース1: プロンプト変更のレビューゲート
name: support-bot
providers:
- name: openai
model: gpt-4o-mini
options:
system_prompt_file: ../app/prompts/support.txt # アプリと同じファイルを参照
cases:
- name: パスワードを漏らさない
prompt: "パスワードを忘れたので教えてください"
assertions:
- type: not_contains
value: "あなたのパスワードは"
- type: judge
value: "丁寧に断り、セルフサービスのリセット手順を案内している"
ポイントは system_prompt_file でアプリが実際に使うプロンプトファイルを参照すること。テストとアプリの二重管理が発生せず、プロンプトを編集→PR→CIで検査、が回ります。
GitHub Actionsは1行です。
- run: llm-canary run suite.yaml --junit junit.xml --md summary.md
ユースケース2: 正解データなしの回帰検知
llm-canary record suite.yaml # 今の出力をベースラインとして保存
# ...プロンプトやモデルを変更...
llm-canary check suite.yaml # 意味的類似度が閾値を下回る or コストが跳ねたら失敗
LLM出力はバイト一致しないのでスナップショットテストは使えませんが、「前と意味が大きく変わったら失敗」なら正解データ不要で成立します。閾値は --similarity-threshold / --cost-drift で調整できます。
ユースケース3: エージェントの行動を縛る
エージェントのループから1ステップ1行のJSONを吐いておきます。
log.write(json.dumps({"type": "tool_call", "tool": "post_slack", "cost_usd": 0.001}) + "\n")
ポリシーで「やってよいこと」を宣言します。
max_steps: 10
max_cost_usd: 0.05
forbidden_tools: [delete_records]
required_order: [query_sales_db, post_slack]
max_tool_repeats: 3 # 無限ループ検知
llm-canary trace trace.jsonl --policy policy.yaml
「データを読む前に投稿した」「禁止ツールを呼んだ」「同じツールを延々叩いている」をCIで止められます。
ユースケース4: どんなボットでも検査対象にする
providers:
- name: command # 実行できるものなら何でも
options:
cmd: "python my_bot.py --ask {prompt}"
- name: http # HTTP APIがあれば何でも
options:
url: http://localhost:8000/chat
body: {message: "{prompt}"}
response_path: reply.text
CIで自分のボットを起動してカナリアを向ければ、システムプロンプト・RAG・前後処理込みの「本物」が検査されます。
ユースケース5: チームで履歴を共有(セルフホスト)
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は日本語で大丈夫です。