00 환경 준비

학습자 수업 00 환경 준비에 대한 진행자용 안내서입니다.

세션 전 — 공용 학습자 키 발급 (공정한 사용량)

공개된 강사 주도 세션에서는 낯선 사람들로 가득한 강의실에 개인 OpenRouter 키나 한도 없는 키를 나눠주지 마세요. OpenRouter에는 하드 크레딧 한도가 걸린 목적 전용 키를 프로그래밍 방식으로 발급하는 Management(프로비저닝) API가 있습니다. 이렇게 하면 워크숍의 지출이 제한되고 공정해집니다.

1. Management 키 만들기 (일회성). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. 이 키는 다른 키를 만들고, 조회하고, 삭제할 수 있으며 여러분의 계정에서 비용을 쓸 수 있습니다. 관리자 자격 증명으로 취급하세요.

export OPENROUTER_PROVISIONING_KEY=sk-or-v1-<management-key>   # instructor only — never share

2. 하드 한도가 걸린 공용 학습자 키 발급. 저장소에는 POST https://openrouter.ai/api/v1/keys를 호출하는 헬퍼 (scripts/provision_workshop_keys.py) 가 포함되어 있습니다.

# one shared key the whole room uses, capped at $20 total (reset daily at 00:00 UTC):
python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 20 --daily

생성 응답은 키 문자열을 한 번만 출력합니다. 복사해서 학습자들의 OPENROUTER_API_KEY로 전달하세요. 그 이후에는 hash만 조회할 수 있습니다(조회 또는 삭제용). raw curl을 선호하나요? 같은 호출입니다.

curl -s https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $OPENROUTER_PROVISIONING_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Agent Arena workshop","limit":20}'

python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 2 --count 30

3. 관찰하고 정리하기. 세션 중간에 지출을 확인하고, 끝나면 키를 삭제하세요.

python -m scripts.provision_workshop_keys --list
python -m scripts.provision_workshop_keys --delete <keyHash>

규모 산정: 로스터는 저렴한 flash-lite 등급이고 그리드는 6 × 3 = 18개 구성뿐이므로, $20 공용 한도로 강의실 전체가 Arena를 몇 번 돌리기에 넉넉합니다. 이 한도는 빡빡한 예산이 아니라 폭주하는 루프에 대한 안전장치입니다.

타이밍

계정이 이미 있다면 총 ~25–30분. 계정 생성이 필요하면 더 여유를 두세요.

• 5분 — 전날 미리 하지 않았다면 세 계정(OpenRouter, Langfuse Cloud, ClickHouse Cloud)을 만듭니다.
• 5분 — 저장소 클론, 가상환경 생성, 의존성 설치.
• 5분 — .env 채우기.
• 5분 — source .env && scripts/arena.sh up, 대시보드가 http://localhost:5174에서 로드되는지 확인.

세션 전에 OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention을 열고 Non-frontier를 끈(회색/off) 다음, 학습자 키로 Qwen을 테스트하세요. Qwen은 Alibaba의 non-ZDR 엔드포인트로 라우팅되므로, non-frontier ZDR을 켜면 Alibaba가 허용되어 있고 키/워크스페이스 가드레일이 느슨해도 No endpoints available matching your guardrail restrictions and data policy가 발생합니다. 이것은 계정 수준 설정이며 Management API나 요청 파라미터로 완화할 수 없습니다. 이 설정은 합성 워크숍 워크로드에만 사용하고, 실제 데이터에는 조직의 데이터 처리 요구사항을 염두에 두세요.

토크 트랙

• 세 계정 — OpenRouter, ClickHouse Cloud, Langfuse Cloud — 을 처음부터 함께 언급하며 시작하고, Langfuse가 그중 하나이며 모델을 하나도 고르기 전인 가장 첫 모듈에 들어온다는 점을 명시하세요. 그것이 핵심입니다. Langfuse는 Module 04에서 덧붙이는 프로덕션 부가물이 아니라, 다음 모듈에서 경쟁을 실행하는 도구입니다.
• 아키텍처 다이어그램을 가리키며 공유되는 하나의 코드 경로를 짚어 주세요. agents/는 eval/harness.py(벤치마크)와 serving/api.py(프로덕션)가 모두 사용하므로, 오늘 측정한 것은 Module 04에서 출시되는 것과 갈라지지 않습니다.
• scripts/arena.sh up이 실행되는 동안 실제로 무엇을 하는지 해설하세요. arena 데이터베이스 생성, arena_ro 읽기 전용 사용자 생성, 합성 이커머스 데이터를 ClickHouse에 직접 생성, v_* 뷰 구축, 그리고 대시보드 API + 웹 UI 시작입니다.
• 이 모듈이 끝날 때 Leaderboard 탭이 비어 있을 것이라는 기대를 미리 심어 주세요. 그것은 버그가 아니라 정상이며, Module 01로 넘어가는 클리프행어입니다.

흔한 실패

• OPENROUTER_API_KEY가 sk-or-... 자리표시자로 남아 있음 — 하네스는 셋업 자체가 아니라 Module 01에서 처음 모델을 호출할 때 401로 실패합니다. 나중에 디버깅하기 비싸지기 전에, 지금 .env에 실제 키가 있는지 학습자들에게 다시 확인시키세요.
• ARENA_RO_PASSWORD가 비어 있음 — scripts/arena.sh up은 여전히 arena_ro 사용자를 만들지만 빈 비밀번호로 만들고, ClickHouse Cloud 서비스의 비밀번호 정책에 따라 에이전트의 읽기 전용 클라이언트가 이를 거부할 수 있습니다. 학습자에게 비어 있지 않은 아무 값이나 설정하도록 하세요.
• ClickHouse Cloud 서비스가 아직 프로비저닝 중 — 방금 만든 서비스는 연결을 받기까지 1~2분이 걸릴 수 있습니다. 너무 일찍 실행하면 scripts/arena.sh up이 연결 오류로 즉시 실패합니다. 기다린 뒤 다시 실행하면 됩니다.
• 스크립트 실행 전에 .env를 source하지 않음 — source .env && scripts/arena.sh up이 한 줄인 데는 이유가 있습니다. 새 셸에서 scripts/arena.sh up만 실행하면 CLICKHOUSE_CLOUD_* 환경 변수가 없어 실패합니다.
• 5174(또는 8000) 포트가 이미 사용 중 — 이전 실행에서 남은 프로세스입니다. scripts/arena.sh stop으로 로컬 서버를 정리한 뒤 up을 다시 실행하세요.

리셋 절차

• 처음부터 다시 시딩: source .env && scripts/arena.sh up — 멱등하며 Aurora, ClickPipes, ClickStack을 사용하지 않습니다. arena 데이터베이스, arena_ro 사용자, 합성 데이터, v_* 뷰를 다시 만들고 대시보드 API와 웹 UI를 재시작합니다. 벤치마크 결과는 Langfuse에 그대로 남습니다.
• ClickHouse가 아니라 로컬 서버만 멈춰 있다면, scripts/arena.sh stop 다음 scripts/arena.sh serve가 전체 up보다 빠릅니다.
• 언제든 scripts/arena.sh status로 상태를 확인하세요. 대시보드 API와 웹 UI가 올라와 있는지 알려주고 각 v_* 뷰의 행 수를 출력합니다.
• 학습자의 .env에 여전히 자리표시자 값이 있다면 우회로는 없습니다. 실제 키/자격 증명을 받아 scripts/arena.sh up을 다시 실행하세요.