Spider2-Lite → nl2sql 품질 게이트

nl2sql 제품의 Spider2-Lite local* 품질 게이트 준비 스펙. UI Playwright 스모크(Playwright-Frontend-UI-Smoke-Pattern.md)와 축이 다름 — 본 문서는 exec_result 채점·스모크·preflight·in-cluster 엔드포인트만 다룬다.

1. 채점 정본

2. 스코프 (스펙/AC)

  • 스모크 set + preflight + 주간 opik.command 배선.
  • 단계(Option A): P0 gold-sql 주간 hard → P1 --task agent chat SSE → P2 ~10 local* opt-in(후속).
  • 1차 스모크 instance는 2건 (local008,local022). FakeAgent는 EX 품질에 쓰지 않는다.

3. 스모크 instance set

상수 QUALITY_SMOKE_INSTANCE_IDS:

IDDB
local008Baseball
local022IPL

4. Preflight 순서

# 1) PG 적재
spider2-load-pg
# 2) Opik Dataset 업로드 (local* 135 → spider2-lite-local-exec)
spider2-opik-upload-exec
# 3) 연결/데이터셋 점검
spider2-opik check
# 4) gold-sql 스모크 (문자열 일치 아님 — exec_result)
#    + --instance-ids local008,local022
  • 이 repo spider2-eval은 PG 적재·Opik Dataset·--task gold-sql·--task agent(path A)까지 있음.

4.1 --task agent = chat SSE path A

항목AC
출력task_outputs["output"] = POST /api/chat SSE의 마지막 non-empty event: sql의 sql
채점scorer는 exec_result (문자열 일치 아님)
미적중output="" · 루프 계속(실험 abort 금지)
Runner envSPIDER2_AGENT_BASE_URL, SPIDER2_AGENT_TIMEOUT_SEC(기본 120), SPIDER2_AGENT_AUTH_USER+SPIDER2_AGENT_AUTH_EMAIL → X-Forwarded-*
Auth 함정test overlay에 NL2SQL_DEV_* 없으면 헤더 누락 → chat 401 → 빈 SQL

경로 B(MCP-only)는 제품 chat 경로와 어긋나 비채택.

4.2 주간 soft wrapper

# quality.yaml opik.command 개념
cd spider2-eval && uv run spider2-opik weekly
# = check → gold-sql hard → agent soft(non-blocking; SPIDER2_AGENT_BASE_URL 있을 때만)
  • gold-sql hard 실패 → wrapper non-zero(NF).
  • agent soft 실패 → 로그만, gold hard OK면 exit 0.
  • 함정: spider2-opik run/weekly가 agent pass_rate=0이어도 exit 0이면 주간 하드 게이트가 안 닫힌다. 제품 AC는 soft→hard 승격 시 pass_rate floor + empty-SQL count를 별도 assert하거나 wrapper non-zero로 승격한다.

4.3 Ephemeral checkout + Spider2 자산 (.tmp-spider2)

tenant-repo-sync depth-1 clone은 gitignored spider2-eval/.tmp-spider2(Spider2-Lite jsonl 등)를 포함하지 않는다. 첫 spider2-opik weekly/check가 missing …/.tmp-spider2/Spider2/…jsonl로 hard-fail한다.

# 선택 A: 이미 채워진 트리로 심볼릭 링크
ln -sfn /path/to/populated/.tmp-spider2 \
  /tmp/tenant-repos/<repo>/spider2-eval/.tmp-spider2
 
# 선택 B: env로 자산 루트 지정 후 weekly 재시작
export SPIDER2_TMP_DIR=/path/to/populated/.tmp-spider2
cd spider2-eval && uv run spider2-opik weekly
  • 게이트 키 없음 skip은 Tenant-Quality-Yaml-Gate-Skip-Pattern.md — 본 함정은 키가 있어 opik을 돌릴 때만 해당.
  • 앱 PVC에 소스 zip이 있어도 ephemeral checkout과 혼동하지 말 것(§7.4 #11).

5. In-cluster 엔드포인트

에이전트 러너 네임스페이스에서는 short/LAN 호스트 k8s-test / opik.k8s-test를 해석하지 못함(DNS search = *.svc.cluster.local).

실측 예:

대상결과
postgresql.postgres.svc.cluster.local:5432TCP OK
http://opik-frontend.opik.svc.cluster.local:5173 (+ /api)HTTP 200

.env / smoke용 ClusterIP FQDN:

# Postgres
PGHOST=postgresql.postgres.svc.cluster.local
PGPORT=5432
# Opik
OPIK_URL_OVERRIDE=http://opik-frontend.opik.svc.cluster.local:5173/api

NodePort / *.k8s-test는 hosts 주입 없이는 쓰지 말 것. 상세는 k8s-test README Opik 섹션.

5.1 Verified preflight (재현 메모)

  • Dataset spider2-lite-local-exec가 삭제된 Opik project id에 orphan되면 → 프로젝트 재생성 후 spider2-opik-upload-exec(135 items).
  • 검증: spider2-opik check OK; gold-sql smoke local008,local022 → spider2_exec_match avg 1.0 / pass_rate 1.0.
# in-cluster (sw-factory runner)
export PGHOST=postgresql.postgres.svc.cluster.local
export PGPORT=5432
export OPIK_URL_OVERRIDE=http://opik-frontend.opik.svc.cluster.local:5173/api
spider2-opik check
# gold-sql --instance-ids local008,local022  → pass_rate 1.0

6. gold-sql vs --task agent

축용도함정
gold-sqlPG exec_result 베이스라인·주간 hard제품 chat 경로를 대체하지 않음
--task agentchat SSE path A → 마지막 event: sqlrunner checkout이 agent 구현 이전이면 exit-2 stub; “미구현” 문구는 checkout SHA와 함께 쓸 것

제품 EX AC는 agent 축. gold-sql만 돌린 보고는 baseline으로 명시한다.

7. Runner env·MDL PVC (pass_rate>0 전제)

  • QA/agent runner에 MCP_POSTGRES_URL(또는 동등)와 Spider2 lite 경로가 없으면 spider2-opik check가 실패한다. SA가 secret get 불가하면 ephemeral PVC seed 또는 STS envFrom/shared secret이 필요.
  • Opik: OPIK_URL_OVERRIDE=http://opik-frontend.opik.svc.cluster.local:5173/api, dataset spider2-lite-local-exec(135).
  • 메타데이터 PVC에 모델 0개(빈 manifest)면 search_tables 공허 → analyst hang. Baseball/IPL 등 스모크 DB용 *.model.json을 backend·mcp 메타데이터 HEAD에 동일 commit으로 맞춘다(/admin/sync가 remote 없으면 tree 복사).
  • MCP Host 403은 토큰보다 allowlist일 수 있음 — MCP-Host-Allowlist-DNS-Rebinding.md.
  • 16K overflow / no-sql hang — LLM-Tool-Payload-Context-Trim.md, Agent-SSE-Failfast-and-Tool-Flood-Guard.md.

7.1 Backend OpikTracer (LangGraph) vs eval-runner

제품 chat SSE의 LangGraph OpikTracer(tags 예: nl2sql/deepagents)는 **backend ConfigMap에 OPIK_URL_OVERRIDE(+ OPIK_WORKSPACE)**가 있어야 켠다. eval-runner evaluation_task 트레이스와 축이 다름.

# test overlay ConfigMap patch (개념) — bearer는 Secret, CM에 넣지 않음
OPIK_URL_OVERRIDE: "http://opik-frontend.opik.svc.cluster.local:5173/api"
OPIK_WORKSPACE: "default"

kubectl apply -k …/overlays/test가 patch에 키를 없으면 live inject를 지운다 → tenant patch-configmap-*.yaml에 영속화.

7.2 Context-retest 스모크 게이트 (EX soft)

서빙 context 상향 재검증 티켓의 hard gate:

  1. smoke window에 context BadRequest/overflow 0
  2. SSE 단말 sql 또는 error+done(hang 금지)
  3. Opik experiment(+ 가능하면 backend Trace) 존재

pass_rate/warehouse_sql null은 EX soft(non-blocking) — Full EX와 혼동하지 않는다. UI Playwright CDN 차단은 env blocker로 분리 — Playwright-Frontend-UI-Smoke-Pattern.md.

7.3 Full EX soft report (local* 전수)

장시간 agent Full EX는 detach + nf-progress heartbeat로 세션을 유지하고, 완료 후 soft 보고만 한다.

관찰해석
Gate: BadRequest/overflow/flood/429 = 0 · SQL-or-error+donehard OK (context/serving)
pass_rate(soft)=0 · fail reason empty SQL / warehouse_sql nullagent 출력 SQL 공허 — soft report-only; 제품 hard gate로 승격하지 않음
Opik evaluation_task + backend LangGraph tagseval-runner vs product tracer 축 분리(§7.1)

Full EX를 스모크 hard와 섞지 않는다. pass_rate floor는 인간 결정 전까지 non-blocking.

2-instance agent EX ≠ Full EX. localA,localB pass_rate=1.0 은 그 두 instance 증거일 뿐 전수 peek/mismatch를 증명하지 않는다. on-request spider2-opik scoreboard 는 주간 canary가 아니다(detach + nf-progress). CLI scoreboard-*.json에 instance_id가 없으면 Opik experiment.get_items()로 재구성한다. 스코어보드는 tip live chat SSE (metadata PVC SHA)이지 러너 checkout/제품 merge SHA가 아니다. live tip meta_ref와 tenant-repo-sync checkout SHA가 어긋나도 정상 — 채점 축은 tip chat이다.

공유 Postgres가 Full EX 중 연결을 끊으면 cgroup limit을 먼저 본다 — Shared-Postgres-Cgroup-Limit-vs-Statement-Timeout.md.

7.3.1 Full EX SSE IncompleteRead · task_threads

Opik evaluate 기본 task_threads=16 + urllib SSE resp.read()가 http.client.IncompleteRead를 내면, chat_predict_sql에서 미포획 시 스코어보드 전체가 abort되어 report JSON/feedback_scores가 없다. 계약: 네트워크/스트림 오류 → output="" 후 루프 계속(§4.1 미적중과 동일).

# on-request Full EX 개념
cd spider2-eval && \
  SPIDER2_AGENT_BASE_URL=http://<backend>.svc.cluster.local:8080 \
  SPIDER2_SCOREBOARD_TASK_THREADS=2 \
  uv run spider2-opik scoreboard
# IncompleteRead/HTTPException → output="" continue; detach + tqdm 로그를 heartbeat로
# nf-progress.json 이 evaluate 끝날 때까지 done=0 이어도 abort로 보지 않음
  • 완화: IncompleteRead/HTTPException catch + SPIDER2_SCOREBOARD_TASK_THREADS=2(또는 낮은 동시성).
  • .tmp-spider2 심볼릭 링크는 §4.3을 먼저 맞춘다.

7.4 Agent EX hard 승격 체크리스트 (empty SQL / wrong schema)

스모크 local008(Baseball)·local022(IPL)에서 soft empty SQL/pass_rate=0을 제품 hard로 올릴 때:

  1. 스키마 힌트: Opik item schema를 chat에 [Spider2 schema: …]로 prefix — 질문만으로는 도메인 모호.
  2. schema-scoped search: soft 프롬프트만으로는 keyword가 타 DB 모델을 끌어온다 → search_tables.schema 하드 핀(+ ContextVar 전달).
  3. 페이로드 트림·온디맨드 describe: LLM-Tool-Payload-Context-Trim.md, On-Demand-Schema-Describe-Tools.md.
  4. SSE warehouse 진실성: Agent-SSE-Failfast-and-Tool-Flood-Guard.md — unwrap·stash·warehouse-only·stash lifetime·abort emit.
  5. invent / incomplete SQL 금지: MDL에 없는 테이블명 invent 차단; SELECT-without-FROM은 fixture 전용; compound invent + FROM-clause retry 프롬프트 금지.
  6. task-guard: 빈 task({})·silent stop에 EnsureAnalystTaskMiddleware로 analyst 경로 강제.
  7. 채점 입력: Execute SSE에 MDL invent fallback 넣지 않음 — warehouse-shaped SQL만 채점.
  8. DB GRANT: runner 역할에 Spider2 스키마 USAGE/SELECT 없으면 check/exec가 왜곡된다.
  9. 주간 wrapper: gold hard OK + agent pass_rate=0 → NF를 열려면 exit 코드를 맞출 것(§4.2 함정). Soft-Gate-Exit-Code-vs-Pass-Rate.md
  10. 카탈로그 tip 갭: PG에 스키마가 있어도 tip *.model.json이 없으면 search_tables 0 → empty_sql. 파일이 있어도 영문 질문 vocab이 한국어-only description에 없으면 같은 증상. vocab Boy Scout + metadata git push 후 MCP PVC SHA 확인 — Metadata-Git-PVC-Resync.md.
  11. 부분 seed: pit_stops=0인데 lap_times만 채워진 상태. SQLite PK NULL이 PG NOT NULL에 막히면 surgical UPDATE 후 COPY. 소스 zip은 앱 PVC에 있을 수 있음(ephemeral checkout과 혼동 금지).
  12. live 판정: /readyz가 SPA HTML을 주면 tip-live가 아님. /api/health + chat SSE. 스코어보드 JSON에 instance_id가 없으면 Opik item에서 재구성.
  13. 잔여 클러스터 우선순위: Full EX residual이 empty_sql / sql_exec / result_mismatch로 갈리면 각각 tip vocab·grain/refSql·seal 축으로 나눈다 — Semantic-View-Single-Master.md, RefSql-Seal-for-EX-Mismatch.md. 수치 스냅샷은 위키에 두지 않는다.
  14. SSE 후행 이벤트 오염 방지: chat SSE 파싱 시, 정상적인 execute SSE 이벤트 이후 AnalystResponse의 warehouse_sql(source=null)이 재방출되어 마지막 SQL을 덮어쓰지 않도록 extract_last_sql_from_sse는 소스가 명시된 execute 이벤트를 우선 추출한다.
  15. shallow clone 에셋 누락: 테넌트 repo sync(depth=1 shallow) 환경에서는 .tmp-spider2 에셋 디렉터리가 누락될 수 있으므로, 에셋이 완비된 워크스페이스 트리와 symlink로 연결한다.

UI Playwright는 LLM/SQL EX를 대체하지 않는다 — Playwright-Frontend-UI-Smoke-Pattern.md.

도메인 규칙은 프롬프트가 아니라 MDL — MDL-Only-Domain-Knowledge.md. grain/조인 — Composite-Grain-Join-Keys.md. 마스터 1개 — Semantic-View-Single-Master.md. mismatch seal — RefSql-Seal-for-EX-Mismatch.md.

8. 최소 완료선 (품질 테스트 “준비”)

  1. 스모크 instance set 문서화 (본 §3)
  2. preflight(check / gold-sql) 재현 (본 §4)
  3. agent 배선 AC + runner env + MDL seed (본 §4.1·§7)

🔗 관련 문서