05 루프 완성하기

퍼실리테이터용 동반 문서: 05 루프 완성하기.

소요 시간

총 ~25분.

• 5분 — 프로덕션에서 파생된 세 개의 레코드를 만들고 승격합니다.
• 5분 — 짝을 이루는 policy-v1, policy-v2 실험을 실행합니다.
• 5분 — 정확도를 비교하고 business-policy-adherence를 보정합니다.
• 5분 — 가드가 걸린 관찰 규칙을 활성화하고 네 가지 지표 유형을 리플레이합니다.
• 5분 — 근거를 점검하고 롤백, 비용, 다음 피드백 루프를 논의합니다.

두 실험과 비동기 평가자는 이 진행 블록보다 더 오래 걸릴 수 있습니다. 실행을 지체 없이 시작하고, 대기 시간을 개념적인 토크 트랙에 활용하며, 전날 미리 제공업체 지연을 리허설해 두세요.

진행자 사전 점검

세션 전에 실습 루트에서 다음의 비변경(non-mutating) 명령어 점검을 실행하고, 선택한 구성이 존재하는지 확인하세요.

cd ClickHouse_Demos/workshops/agent_arena
.venv/bin/python -m scripts.promote_to_golden --help
.venv/bin/python -m scripts.provision_online_evaluators --help
.venv/bin/python -m eval.harness --help
.venv/bin/python -m scripts.verify_online_scores --help

그다음 다음을 확인하세요.

• 모듈 03에 sql-execution-success=true와 불리언 user-thumbs=false를 가진 권한 있는 루트 chat_turn이 하나 존재하는지;
• 모듈 04의 UI 전용 production-investigation-<session> 작업이 완료되었고, 수정된 SQL이 실행되었으며, 실제 트레이스 ID를 비공개로 확보했고, Langfuse가 노출할 때 어노테이션 작업 ID가 기록되었는지;
• reviewed.json이 그 진짜 검토로부터 생성될 것이며, 추적된 합성 픽스처가 아닌지;
• WINNER_MODEL, WINNER_PROMPT, WINNER_CONFIG_ID가 모두 같은 룸의 우승자를 가리키는지;
• Langfuse LLM 연결 agent-arena-openrouter가 설정된 심사 모델에 도달할 수 있고 유효한 자격 증명을 가지고 있는지;
• 심사자의 구조화된 범주형 출력이 정확히 PASS, FAIL, NOT_APPLICABLE만 허용하며 추론(reasoning)을 함께 반환하는지; 그리고
• 평가자 디스패처가 정상이며 룸이 비동기 점수를 받을 수 있는지.

리허설을 할 때마다 고유한 접미사를 만들고 베이스라인/후보 쌍을 함께 유지하세요.

export LOOP_RUN_SUFFIX="$(date +%Y%m%d-%H%M%S)"
export BASELINE_RUN_ID="online-loop-baseline-${LOOP_RUN_SUFFIX}"
export CANDIDATE_RUN_ID="online-loop-candidate-${LOOP_RUN_SUFFIX}"

이전 세션의 실행 ID를 재사용하지 마세요. 하니스가 정책 버전과 구성을 뒤에 붙이므로, 고유한 기본 ID를 사용해야 학습자들이 무관하거나 부분적으로 덮어씌워진 근거를 비교하는 일이 없습니다.

수동 어노테이션의 경계

모듈 04의 사람 어노테이션은 의도적으로 자동화되지 않습니다. 런타임 스크립트는 큐를 만들거나, 사람의 판단을 채우거나, 수정된 출력을 입력하거나, 항목을 승인하거나, 작업을 완료하지 않습니다. 실제 검토가 없을 때 진행자 리허설에는 추적된 합성 픽스처가 유용하지만, 이는 여전히 source=synthetic-reviewed-fixture로 남으며 사람 어노테이션 루프가 완료되었음을 증명하지 못합니다.

학습자 경로에서는 진짜이며 (git에서) 무시되는 reviewed.json을 사용하세요. 원문 문구는 실제 사용자 피드백에서 나온 질문 하나입니다. 나머지 두 개의 정확한 입력은 그 검토된 사건에서 파생된, 검토자가 작성한 바꿔 쓴 표현(paraphrase)입니다.

How many active customers do we have?
What is our active customer count right now?
How many customers qualify as active under our business definition?

세 가지 모두 동일한 실제 소스 트레이스와 어노테이션 출처(provenance)를 보존합니다. 학습자들이 하나의 프로덕션 사건을 세 개의 독립된 피드백 트레이스로 오해하지 않도록 이 점을 소리 내어 말해 주세요.

승격의 신뢰성과 출처

룸이 승격을 실행하기 전에, reviewed.json을 투영(project)하지 않고 그대로 점검하세요. 파일에는 정확한 수정된 읽기 전용 SQL, 필수 프로덕션 출처, 그리고 세 개의 고유하고 안전한 ID가 포함되어야 합니다. 승격은 먼저 로컬 배치 전체를 검증한 다음, ClickHouse 실행이나 데이터셋 upsert보다 앞서 인증된 메타데이터 읽기를 수행합니다. 메타데이터를 읽을 수 없으면 실패로 닫히며(fail closed), 서로 다른 진짜 프로덕션 출처를 가진 충돌 ID는 거부합니다.

동일한 진짜 승격은 아이디엠포턴트(idempotent)합니다. 합성 픽스처는 명시적인 --synthetic-fixture 플래그가 필요하며, 직접 경로로 전달할 수도 없고 reviewed.json과 결합할 수도 없습니다. 실제 승격 이후에는 절대 실행하지 마세요. 충돌이 보고되면 두 소스를 모두 보존하고, 기존 데이터셋 항목을 조사하며, 항목들이 실제로 서로 다른 검토 사례를 나타낼 때에만 새로 검증된 ID를 선택하세요.

실험 규칙과 관찰 규칙

이 두 컨텍스트를 슬라이드나 화이트보드에 계속 보이게 두세요.

프로비저너는 고객 수 전용 평가자가 아니라, 카탈로그 기반의 범용 평가자 하나를 설치합니다. 그 policy-v2 카탈로그는 활성 고객 수, 매출, 조회-대비-구매 전환율, 매출 총이익을 다루며, 관련 없는 질문은 NOT_APPLICABLE이어야 합니다.

--business-policy-experiments 단계는 반드시 online rule enabled=False를 보고해야 합니다. 두 번째 안전장치로 Langfuse 규칙 UI를 확인하세요. 이후의 활성화 명령은 데이터셋 범위의 business-policy-adherence 점수가 하나 이상 존재함을 증명하지만, 진행자의 전체 보정 검토를 대체할 수는 없습니다.

보정 게이트

베이스라인과 후보를 동일한 항목 ID, 모델, 프롬프트로 비교하세요. 저장소에는 YAML 질문이 20개 있지만 q019와 q020은 few-shot holdout이므로, 깨끗한 project는 Experiment 항목 18개로 시작해 세 항목 승격 후 21개가 됩니다. 검증에 사용한 재사용 shared project가 22개였던 이유는 이전의 무관한 승인 항목 한 개가 남아 있었기 때문입니다. 그 project의 최신 짝지은 실행은 16/22에서 19/22로 이동했습니다. 이는 조건이 붙은 검증 근거이며, 학습자에게 요구할 항목 수나 확률적 제공업체가 매번 같은 집계를 재현한다는 보장이 아닙니다.

모든 게이트를 통과하지 않으면 활성화하지 마세요.

• 세 개의 prod-active-* 케이스 모두가 policy-v1에서의 FAIL·오답에서 policy-v2에서의 PASS·정답으로 이동한다;
• 후보의 매출(q005)과 전환율(q018)이 PASS이다;
• 단순 카운트(q001)는 NOT_APPLICABLE이다;
• 기존에 존재하던 모든 항목의 correctness를 항목별로 비교했을 때 1→0으로의 회귀가 없다;
• 집계 정확도가 회귀하지 않는다; 그리고
• 모든 Experiment 항목이 correctness, agent-arena-llm-judge, 그리고 정확히 일치하는 business-policy-adherence 점수를 유효한 구조화 출력과 함께 가지고 있다.

모든 카운트를 PASS로 표시하는 심사자는 후보가 좋아 보이더라도 보정에 실패한 것입니다. NOT_APPLICABLE 프로브를 사용해 정책 적용 가능성 판단이 실제 분류 단계임을 보여 주세요.

비동기 채점과 점수 없음 문제 해결

실험 평가와 관찰 평가는 모두 비동기입니다. 하니스는 필수 실험 점수를 기다리고, scripts.verify_online_scores는 기본적으로 180초 동안 실시간 트레이스 점수를 폴링합니다. 점수가 대기 중이라는 이유만으로 빠르게 새로고침하거나, 규칙을 재생성하거나, 조기에 활성화하지 마세요.

점수가 나타나지 않으면 다음을 확인하세요.

1. 정확한 예상 이름을 확인합니다. 실험에는 business-policy-adherence를, 서빙 관찰에는 agent-arena-business-policy-online을 사용합니다.
2. 평가자 디스패처/실행 워커가 정상인지 확인합니다.
3. agent-arena-openrouter 연결과 심사 모델의 가용성을 확인합니다. 제공업체 지연, 레이트 리밋, 또는 라우팅 제한은 에이전트 응답이 성공했더라도 평가를 대기 상태나 실패 상태로 남길 수 있습니다.
4. 실험 규칙이 arena-golden 데이터셋을 대상으로 하고, 관찰 규칙이 루트 chat_turn 관찰을 대상으로 하는지 확인합니다. 매핑은 $.question과 $.sql을 노출해야 합니다.
5. 구조화된 출력을 점검합니다. 범주가 없거나, 세 가지 허용값 밖의 범주이거나, 추론(reasoning)이 없는 경우는 보정 실패입니다.
6. 프로비저닝이 모호한 규칙 이름을 보고하면, 멈추고 Langfuse에서 중복된 정확한 규칙 이름을 해결한 뒤 재시도하세요. 어느 중복이 업데이트되었는지 추측하지 마세요.

실패한 트레이스와 평가자 근거를 보존하세요. 제공업체 장애를 조작된 PASS로 바꾸거나 점수 누락 게이트를 건너뛰지 마세요.

리플레이 가이드

활성화 후에는 서빙을 명시적으로 policy-v2로 재시작하고 학습자의 정확한 네 가지 질문을 사용하세요.

How many active customers do we have?
What was revenue in the last 30 days?
What is our view-to-purchase conversion rate for the last 7 days?
How many products are there?

모든 트레이스에서 운영상 성공을 요구하세요. 활성 고객 수, 매출, 전환율은 agent-arena-business-policy-online=PASS여야 하고, 제품 개수는 NOT_APPLICABLE이어야 합니다.

전환율 요청에는 검증된 확률적(stochastic) 경계가 있습니다. 동일한 구성으로 최대 한 번의 재시도만 허용하고, 두 트레이스 ID와 결과를 모두 보존하며, 두 시도 모두 통과하지 못하면 중단하세요. 반복된 실패는 초록불이 뜰 때까지 반복할 이유가 아니라 조사해야 할 새로운 프로덕션 근거입니다.

샘플링, 비용, 신뢰성

워크숍 규칙은 샘플링 1을 사용해 대상이 되는 모든 트레이스가 눈에 보이는 근거를 남기도록 합니다. 프로덕션 볼륨에서는 모든 요청에 LLM 심사자를 붙이면 제공업체 비용이 늘고, 레이트 리밋을 소모하며, 사용자 응답 이후에 점수가 나올 수 있습니다. 트래픽, 인시던트 리스크, 평가자 비용/지연, 필요한 커버리지에 따라 샘플링을 선택하세요. 결정론적인 운영 점검은 넓게 유지하고, 비용이 큰 시맨틱 판단은 그 비용을 정당화할 트래픽과 지표에만 아껴 쓰세요.

평가자는 모니터링이며 요청 경로상의 승인 절차가 아닙니다. 지연된 심사자가 서빙 응답을 조용히 막아서는 안 됩니다. 점수 누락, 범주 드리프트, 신호 불일치는 시스템의 서비스 수준 목표(SLO)에 따라 운영 알림이나 리뷰 백로그로 라우팅하세요.

롤백과 리셋

활성화 이후 관찰 심사자가 거짓 통과, 거짓 실패, 잘못된 형식의 출력, 또는 받아들일 수 없는 비용/지연을 만들어 낸다면:

1. Langfuse Evaluations를 열어 정확한 관찰 규칙 agent-arena-business-policy-online을 찾아 disabled로 전환합니다.
2. 새로운 chat_turn 관찰이 더 이상 그 온라인 규칙 점수를 받지 않는지 확인합니다.
3. policy-v2, sql-execution-success, 👍/👎는 자체 근거가 다르게 말하지 않는 한 계속 실행 상태로 유지하세요. 결함 있는 심사자를 비활성화하는 것이 이미 알고 있는 낡은 정책을 다시 들여와서는 안 됩니다.
4. 영향을 받은 트레이스를 접미사가 붙은 사람 어노테이션 큐에 추가하고, 평가자 카탈로그/프롬프트와 골든 데이터를 개선한 다음, 다시 활성화하기 전에 짝을 이룬 실험 보정을 반복하세요.

원격 근거를 삭제하지 않고 로컬 서비스를 중지하려면:

scripts/arena.sh stop

scripts/arena.sh down은 워크숍 ClickHouse 데이터베이스와 읽기 전용 사용자도 제거하지만, Langfuse 데이터셋, Experiment 실행, 어노테이션 큐, 점수는 삭제하지 않습니다. 이를 평가자 롤백으로 사용하지 마세요.

토크 트랙: 루프는 계속 열려 있다

• 기존 평가자는 그 계약(contract)이 오직 "SQL이 실행되었는가"였기 때문에 통과했습니다. 사용자의 👎는 그 계약 밖에 있던 값 오류를 드러냈습니다.
• 사람의 검토는 불확실한 신호를 검증된 진단과 수정으로 바꾸었습니다.
• 프로덕션 출처는 그 사건이 골든 세트에 들어갈 때 감사 가능하게 만들었고, 바꿔 쓴 표현들은 추가 사용자 트레이스를 만들어 내지 않으면서 문구 커버리지를 향상시켰습니다.
• 짝을 이룬 실험은 정책 변경을 모델/프롬프트 변경과 분리하고, 범용 심사자를 프로덕션에 앞서 테스트했습니다.
• 온라인 PASS가 사용자 피드백을 쓸모없게 만들지는 않습니다. 미래의 agent-arena-business-policy-online=PASS와 user-thumbs=false의 조합은 정확히 조사를 다시 시작해야 하는 종류의 불일치입니다.

완료 게이트

룸이 다음 여섯 가지 아티팩트를 모두 보여줄 수 있을 때까지 이 모듈을 마치지 마세요.

1. 운영상 통과와 부정적 사용자 신호를 가진 프로덕션 트레이스;
2. 완료된 사람 어노테이션과 검증된 수정 SQL;
3. 진짜 프로덕션 출처를 가진 세 개의 골든 항목;
4. 기존 정확도 회귀가 없는 동일 데이터셋 베이스라인/후보 근거;
5. 보정된 FAIL, PASS, NOT_APPLICABLE Experiment 근거; 그리고
6. 활성 고객 수, 매출, 전환율, 단순 카운트 전반에 걸쳐 활성화된 실시간 점수, 그리고 다음 루프를 위해 계속 사용할 수 있는 👍/👎.