00 ตั้งค่า

คู่มือของผู้ดำเนินกิจกรรมที่ใช้ควบคู่กับบทเรียน learner 00 ตั้งค่า

ก่อนเซสชัน — provision key สำหรับผู้เรียนแบบใช้ร่วมกัน (ใช้อย่างเป็นธรรม)

สำหรับการจัดแบบสาธารณะที่ผู้สอนนำ อย่ายื่น OpenRouter key ส่วนตัวของคุณหรือ key ที่ไม่มีเพดานให้คนแปลกหน้าทั้งห้อง OpenRouter มี Management (provisioning) API ที่ผลิต key เฉพาะกิจพร้อมเพดานเครดิตแบบตายตัวได้ด้วยโปรแกรม — ทำให้ค่าใช้จ่ายของเวิร์กช็อป ถูกจำกัดและเป็นธรรม

1. สร้าง Management key (ครั้งเดียว) OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key key นี้สร้าง ตรวจ และลบ key อื่นได้ และใช้จ่ายเงินในบัญชี ของคุณได้ — ให้ถือว่ามันเป็น credential ระดับ admin

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

2. Provision key ของผู้เรียนแบบใช้ร่วมกันพร้อมเพดานตายตัว repo มีตัวช่วยมาให้ (scripts/provision_workshop_keys.py) ซึ่งเรียก POST https://openrouter.ai/api/v1/keys:

# 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

response ของการสร้างพิมพ์สตริงของ key ออกมาครั้งเดียว — คัดลอกมันแล้วมอบให้ผู้เรียนเป็น OPENROUTER_API_KEY ของพวกเขา หลังจากนั้นจะดึงได้แค่ hash ของมัน (เพื่อตรวจหรือ ลบ) ชอบ 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. เฝ้าดูแล้วเก็บกวาด ตรวจการใช้จ่ายกลางเซสชันและลบ key เมื่อเสร็จ:

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 min — สร้างสามบัญชี (OpenRouter, Langfuse Cloud, ClickHouse Cloud) ถ้า ผู้เรียนยังไม่ได้ทำไว้ล่วงหน้าหนึ่งวัน
• 5 min — clone repo, สร้าง virtualenv, ติดตั้ง dependency
• 5 min — กรอก .env
• 5 min — source .env && scripts/arena.sh up ยืนยันว่า dashboard โหลดได้ที่ http://localhost:5174

ก่อนเซสชัน ให้เปิด OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention แล้วปิด Non-frontier (สีเทา/ปิด) จากนั้นทดสอบ Qwen ด้วย key ของ ผู้เรียน Qwen ถูกส่งไปที่ endpoint ที่ไม่ใช่ ZDR ของ Alibaba ดังนั้นการเปิด ZDR สำหรับ non-frontier จะทำให้เกิด No endpoints available matching your guardrail restrictions and data policy แม้ว่า จะอนุญาต Alibaba แล้วและ guardrail ระดับ key/workspace จะผ่อนปรนก็ตาม นี่เป็นค่าตั้ง ระดับบัญชีและผ่อนปรนผ่าน Management API หรือพารามิเตอร์ของ request ไม่ได้ ใช้ค่าตั้งนี้ สำหรับงานสังเคราะห์ของเวิร์กช็อปเท่านั้น; ให้คำนึงถึงข้อกำหนดการจัดการข้อมูลของ องค์กรคุณเมื่อทำกับข้อมูลจริง

แนวการพูด

• เปิดด้วยการเอ่ยถึงทั้งสามบัญชีตั้งแต่ต้น — OpenRouter, ClickHouse Cloud, Langfuse Cloud — และพูดชัด ๆ ว่า Langfuse เป็นหนึ่งในนั้น ในโมดูลแรกสุด ก่อนที่จะเลือกโมเดลแม้แต่ตัวเดียว นั่นคือประเด็นทั้งหมด: Langfuse ไม่ใช่ของ เสริมสำหรับ production ที่มาแปะในโมดูล 04 มันคือเครื่องมือที่คุมการแข่งขันใน โมดูลถัดไป
• ชี้ที่ไดอะแกรมสถาปัตยกรรมและเอ่ยถึงเส้นทางโค้ดที่ใช้ร่วมกันเส้นเดียว: agents/ ถูกใช้ ทั้งโดย eval/harness.py (benchmark) และ serving/api.py (production) — ดังนั้น ไม่มีอะไรที่วัดวันนี้ที่จะเบี่ยงออกจากสิ่งที่ปล่อยในโมดูล 04
• เล่าไปด้วยว่า scripts/arena.sh up ทำอะไรจริง ๆ ขณะที่มันรัน: สร้างฐานข้อมูล arena, สร้างผู้ใช้แบบอ่านอย่างเดียว arena_ro, สร้างข้อมูล e-commerce สังเคราะห์ ลงใน ClickHouse โดยตรง, สร้าง view v_* และเริ่ม dashboard API + web UI
• ตั้งความคาดหวังว่าแท็บ Leaderboard จะว่างเปล่าตอนจบโมดูลนี้ — นั่นถูกต้อง ไม่ใช่บั๊ก และมันคือปมค้างที่ทิ้งไว้เข้าโมดูล 01

ความล้มเหลวที่พบบ่อย

• ปล่อย OPENROUTER_API_KEY เป็น sk-or-... — harness จะล้มเหลวด้วย 401 ครั้งแรกที่มันเรียกโมเดลในโมดูล 01 ไม่ใช่ตอนตั้งค่าเอง ขอให้ ผู้เรียนตรวจซ้ำว่า .env มี key จริงตอนนี้เลย ก่อนที่จะกลายเป็นเรื่องแพงที่ต้องไปดีบัก ทีหลัง
• ปล่อย ARENA_RO_PASSWORD ว่าง — scripts/arena.sh up จะยังสร้างผู้ใช้ arena_ro อยู่ แต่ด้วยรหัสผ่านว่าง ซึ่ง client แบบอ่านอย่างเดียวของ agent อาจ ปฏิเสธ ขึ้นอยู่กับนโยบายรหัสผ่านของ ClickHouse Cloud service ให้ผู้เรียนตั้ง ค่าอะไรก็ได้ที่ไม่ว่าง
• ClickHouse Cloud service ยัง provision อยู่ — service ที่สร้างใหม่อาจใช้เวลา หนึ่งถึงสองนาทีก่อนจะรับการเชื่อมต่อ; scripts/arena.sh up จะล้มเร็วด้วย error ของการเชื่อมต่อถ้ารันเร็วเกินไป แค่รอแล้วรันใหม่
• ไม่ได้ source .env ก่อนรันสคริปต์ — source .env && scripts/arena.sh up เป็นบรรทัดเดียวด้วยเหตุผล; การรัน scripts/arena.sh up เดี่ยว ๆ ในเชลล์ใหม่ จะล้มเหลวเพราะไม่มี env var CLICKHOUSE_CLOUD_*
• พอร์ต 5174 (หรือ 8000) ถูกใช้อยู่แล้ว — โปรเซสค้างจากการรันครั้งก่อน scripts/arena.sh stop เคลียร์เซิร์ฟเวอร์ในเครื่องก่อนรัน up ใหม่

ขั้นตอนรีเซ็ต

• Seed ใหม่ตั้งแต่ต้น: source .env && scripts/arena.sh up — มันเป็น idempotent และ ไม่ใช้ Aurora, ClickPipes หรือ ClickStack; มันสร้างฐานข้อมูล arena, ผู้ใช้ arena_ro, ข้อมูลสังเคราะห์ และ view v_* ขึ้นใหม่ แล้วรีสตาร์ต dashboard API และ web UI ผลลัพธ์ benchmark ยังอยู่ใน Langfuse
• ถ้าติดขัดแค่เซิร์ฟเวอร์ในเครื่อง (ไม่ใช่ ClickHouse) การใช้ scripts/arena.sh stop ตามด้วย scripts/arena.sh serve เร็วกว่าการทำ up เต็มรูปแบบ
• ตรวจสถานะได้ทุกเมื่อด้วย scripts/arena.sh status — มันรายงานว่า dashboard API และ web UI ขึ้นอยู่หรือไม่ และพิมพ์จำนวนแถวของแต่ละ view v_*
• ถ้า .env ของผู้เรียนยังมีค่า placeholder อยู่ ก็ไม่มีทางลัด — หา key/credential จริงมาแล้วรัน scripts/arena.sh up ใหม่