03 릴리스하고 감지하기

다음 학습자 수업에 대응하는 진행자용 안내서입니다: 03 릴리스하고 감지하기의 진행자용 안내서입니다.

시간 배분

총 ~15분.

• 3분 — 운영 평가(operational evaluation)와 사용자 가치를 구분해 설명합니다.
• 4분 — 프리플라이트를 보여주고, 룸에서 선택한 설정을 policy-v1으로 릴리스합니다.
• 4분 — Chat에서 거버넌스 대상 질문을 던지고 해당 답변에 👎를 받습니다.
• 4분 — 해당 Chat 트레이스를 찾아 두 점수를 모두 확인하고, curl로 재현합니다.

전날 프리플라이트

룸이 선택할 것으로 예상되는 정확한 우승 설정으로 이것을 실행하세요. 검증된 대체(fallback) 설정은 qwen3.7-flash__P2_fewshot입니다:

cd ClickHouse_Demos/workshops/agent_arena
source .env
export WINNER_CONFIG_ID="${WINNER_CONFIG_ID:-qwen3.7-flash__P2_fewshot}"
.venv/bin/python -m schema.gen_schema_context
.venv/bin/python -m scripts.check_online_eval_scenario \
  --config-id "$WINNER_CONFIG_ID"
.venv/bin/python -m scripts.provision_online_evaluators --operational

프리플라이트는 어떤 표현의 첫 결과가 ok/unknown일 때만 제한적으로 한 번 재시도하며, 동일한 표현과 구성만 다시 사용합니다. 그 밖의 모든 실패는 최종 결과로 처리되고, 어떤 표현도 한 번을 초과해 재시도하지 않습니다.

기억에 의존해 진행하지 마세요. 룸의 실제 환경에서 다음을 모두 확인하세요:

• stale_count와 current_count가 모두 존재하며 서로 다른지;
• 세 분류(classification) 모두 policy-v1인지;
• 마지막 줄에 인시던트가 재현 가능하다고 나오는지;
• 평가자 sql-execution-success가 존재하는지; 그리고
• 규칙 agent-arena-sql-execution-online이 활성화되어 있는지.

Qwen의 경우, Alibaba 라우트가 적격해지도록 OpenRouter Settings → Privacy → Data Policies → Zero Data Retention → Non-frontier를 비활성화해야 합니다. 이 변경은 행사에 대한 데이터 처리 요구사항을 검토한 후에만 적용하세요. 학습자에게는 제한된 런타임 키가 필요하며, 절대 진행자의 프로비저닝 키를 사용해서는 안 됩니다.

진행 대본

• 룸의 실제 Module 02 우승 설정에서 시작하고, 모두가 볼 수 있는 곳에 WINNER_CONFIG_ID를 적어 두세요. 에이전트 코어와 선택된 구성은 변경되지 않으며, 배포된 비즈니스 정책 컨텍스트만 의도적으로 한 버전 뒤처져 있습니다.

• 결과를 보여주기 전에 평가자의 한계를 명확히 짚어 주세요: sql-execution-success는 ClickHouse가 SQL을 받아들였다는 것을 증명할 수 있을 뿐, 그 SQL이 오늘 기준의 거버넌스 메트릭 정의를 구현하고 있다는 것을 증명하지는 않습니다.

• Chat에서 질문을 던지고, 생성된 SQL, 결과, policy_version=policy-v1을 보여준 뒤 👎를 클릭하고 feedback sent를 기다립니다. 이 Chat 루트 트레이스가 유일한 권위 있는(authoritative) 인시던트입니다.

• 청중에게 현재 정의를 나란히 보여주세요:

  SELECT uniqExact(customer_id) FROM v_orders
  WHERE order_ts >= now() - INTERVAL 30 DAY
  AND status NOT IN ('cancelled', 'returned')

• 가입(signup) 기반으로 생성된 SQL이 모델에 전달된 오래된 policy-v1 기준으로는 유효하다는 점을 명확히 말하세요. 이는 릴리스/프로세스 실패이자 평가자의 사각지대이며, 모델이 명확한 지시를 무시했다는 주장이 아닙니다.

• Langfuse에서 user-thumbs = false로 필터링하고, 일치하는 가장 최신 Chat chat_turn을 열어 sql-execution-success=true와 user-thumbs=false를 나란히 보여주세요. 이 신호는 조사의 우선순위를 정해줄 뿐, 진단을 제공하거나 그 자체로 그라운드 트루스가 되지는 않습니다.

• 이후 필수 curl 재현을 등급이 매겨지지 않는(unrated) 진단 절차로 실행하세요. 그 식별자를 CURL_TRACE_ID로 이름 붙이고 sql-execution-success=true만 확인하며, 여기에는 절대 피드백을 POST하거나 Module 04 핸드오프로 사용하지 마세요.

• Module 04를 위해 루트 트레이스 ID/URL과 두 카운트를 기록하세요. 실제 식별자는 Langfuse 프로젝트와 워크숍 워크시트 안에만 보관하세요.

예상되는 트레이스 증거

자식인 llm_call만이 아니라 루트 chat_turn 관측치(observation)를 여세요. 다음을 기대합니다:

서빙(serving) 소스는 이 필드를 policy_version으로 명명하지만, OpenTelemetry 어댑터가 메타데이터 키를 영숫자로만 정리(sanitize)하기 때문에 Langfuse는 실제 전송된 키를 policyversion으로 표시합니다.

운영 평가자(operational evaluator)는 비동기적으로 동작합니다. 아직 나타나지 않은 점수를 실패로 간주하지 말고, 검증 도구를 사용하세요:

.venv/bin/python -m scripts.verify_online_scores "$CHAT_TRACE_ID" \
  sql-execution-success=true user-thumbs=false

흔한 실패 사례

• ZDR로 인한 프로바이더 차단 — OpenRouter의 non-frontier Zero Data Retention 요구사항이 활성화되어 적격 Alibaba 라우트가 허용되지 않으면, Qwen은 SQL을 생성하기 전에 실패합니다. 이 워크숍에서는 해당 ZDR 제한을 비활성화하거나, 프라이버시 요구사항을 검토한 후 공개된 대체(fallback) 설정을 사용하세요.
• 평가자 디스패처가 실행되지 않음 — 트레이스는 도착하지만 sql-execution-success가 전혀 나타나지 않습니다. Langfuse의 평가자 실행 서비스/디스패처가 정상 상태인지, agent-arena-sql-execution-online 규칙이 활성화되어 있는지 확인하세요. 평가 워커가 사용 불가능하면 규칙을 프로비저닝해도 점수가 처리되지 않습니다.
• OpenTelemetry 의존성 누락 — /ask가 응답을 반환해도 트레이스가 전혀 나타나지 않습니다. .venv/bin/python -m pip install -r requirements.txt로 고정된(pinned) 랩 요구사항을 재설치하세요. 런타임은 Langfuse v4 OpenTelemetry 경로를 사용하며 호환되는 OTel 패키지를 필요로 합니다.
• 오래된 서버 프로세스 — 셸 명령이 policy-v1이라고 말하는데도 응답은 policy-v2를 보고합니다. 이전 프로세스가 여전히 포트 8100을 점유하고 있는 것이므로, 시딩된 릴리스를 시작하기 전에 그 프로세스를 완전히 중지하세요.
• 잘못된 포트 — Chat UI는 기본적으로 http://localhost:8100을 사용합니다. 서빙이 다른 포트를 사용한다면 VITE_SERVING_BASE를 동일한 주소로 설정하거나, 실제 포트를 대상으로 원시 curl을 사용하세요.
• 중복 피드백 — 피드백은 결정론적(deterministic) 점수 ID인 user-thumbs-<trace_id>를 사용합니다. 트레이스당 한 번만 평가를 제출하세요. 같은 트레이스에 경쟁하는 평가를 재사용하면 피드백 서비스 오류가 발생하거나 데모가 모호해질 수 있으므로, 새 세션/트레이스를 만드세요.
• 점수가 아직 대기 중 — 평가는 비동기적입니다. 설정을 바꾸기 전에 scripts.verify_online_scores가 점수를 폴링하도록 기다리세요.
• 참조 카운트가 일치함 — 이 데이터 스냅샷에는 시딩된 대비(contrast)가 없는 경우입니다. 실패를 억지로 만들어내지 말고, 세션 전에 데이터를 다시 시딩하거나 진단하세요.

리셋 단계

기존 서버를 중지한 뒤, 깨끗한 policy-v1 프로세스를 시작하세요:

scripts/arena.sh stop
scripts/arena.sh serve
source .env
.venv/bin/python -m schema.gen_schema_context
AGENT_ARENA_POLICY_VERSION=policy-v1 \
  .venv/bin/uvicorn serving.api:app --port 8100

scripts/arena.sh serve는 서빙 API가 터미널을 점유하기 전에 백그라운드에서 대시보드와 웹 UI를 복구합니다. Chat 페이지를 새로고침해 새 세션을 만드세요. 원시 API를 사용한다면 새 세션 ID를 전달하거나 생략해서 /ask가 자동으로 세션을 생성하도록 하세요. 프리플라이트와 프로비저너를 두 번째 터미널에서 다시 실행하세요. 둘 다 반복 실행해도 안전합니다.

대체(fallback) 정책

룸의 우승 설정이 세 가지 질문으로 이루어진 프리플라이트에서 더 이상 명시적인 오래된(stale) 정책을 따르지 않을 때에만, 진행자의 검증된 qwen3.7-flash__P2_fewshot 설정을 사용하세요. 대체 사실을 소리 내어 말하세요: 이 대체 설정은 결정론적인 교육용 인시던트를 보존하는 것이고, 리더보드 우승 설정은 여전히 룸이 측정한 결과로 남습니다. 모델을 조용히 바꿔치기하지 말고, 동일한 카운트, 자격 증명, 프로바이더 라우팅, 또는 평가자 인프라 실패를 숨기기 위해 이 대체 설정을 사용하지 마세요.

Module 04로의 핸드오프

다음으로 넘어가기 전에, 워크시트에 권위 있는 Chat 루트 트레이스 ID/URL, stale count, current count, sql-execution-success=true, 그리고 Boolean user-thumbs=false가 담겨 있는지 확인하세요. Module 04는 바로 그 정확한 불일치(disagreement)에서 시작하여 인간의 판단을 더하는 것이며, 프로덕션 트레이스와 무관하게 미리 작성된 진단으로 시작해서는 안 됩니다.