Spider2-Lite → nl2sql 품질 게이트
nl2sql 제품의 Spider2-Lite local* 품질 게이트 준비 스펙. UI Playwright 스모크(Playwright-Frontend-UI-Smoke-Pattern.md)와 축이 다름 — 본 문서는 exec_result 채점·스모크·preflight·in-cluster 엔드포인트만 다룬다.
1. 채점 정본
- 정본은 EX / exec_result: 예측 SQL 실행 결과 ↔ gold CSV.
- SQL 문자열 일치가 아님. 배경은 T2SQL-Benchmarks-2026.md.
- 외부 참고: Spider2 evaluation_suite, spider2-claude-code.
2. 스코프 (스펙/AC)
- 스모크 set + preflight + 주간
opik.command배선. - 단계(Option A): P0 gold-sql 주간 hard → P1
--task agentchat SSE → P2 ~10 local* opt-in(후속). - 1차 스모크 instance는 2건 (
local008,local022). FakeAgent는 EX 품질에 쓰지 않는다.
3. 스모크 instance set
상수 QUALITY_SMOKE_INSTANCE_IDS:
| ID | DB |
|---|---|
local008 | Baseball |
local022 | IPL |
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 env | SPIDER2_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가 agentpass_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:5432 | TCP 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/apiNodePort / *.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 checkOK;gold-sqlsmokelocal008,local022→spider2_exec_matchavg 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.06. gold-sql vs --task agent
| 축 | 용도 | 함정 |
|---|---|---|
gold-sql | PG exec_result 베이스라인·주간 hard | 제품 chat 경로를 대체하지 않음 |
--task agent | chat SSE path A → 마지막 event: sql | runner 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 또는 STSenvFrom/shared secret이 필요. - Opik:
OPIK_URL_OVERRIDE=http://opik-frontend.opik.svc.cluster.local:5173/api, datasetspider2-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:
- smoke window에 context BadRequest/overflow 0
- SSE 단말
sql또는error+done(hang 금지) - 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+done | hard OK (context/serving) |
pass_rate(soft)=0 · fail reason empty SQL / warehouse_sql null | agent 출력 SQL 공허 — soft report-only; 제품 hard gate로 승격하지 않음 |
Opik evaluation_task + backend LangGraph tags | eval-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/HTTPExceptioncatch +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로 올릴 때:
- 스키마 힌트: Opik item
schema를 chat에[Spider2 schema: …]로 prefix — 질문만으로는 도메인 모호. - schema-scoped search: soft 프롬프트만으로는 keyword가 타 DB 모델을 끌어온다 →
search_tables.schema하드 핀(+ ContextVar 전달). - 페이로드 트림·온디맨드 describe: LLM-Tool-Payload-Context-Trim.md, On-Demand-Schema-Describe-Tools.md.
- SSE warehouse 진실성: Agent-SSE-Failfast-and-Tool-Flood-Guard.md — unwrap·stash·warehouse-only·stash lifetime·abort emit.
- invent / incomplete SQL 금지: MDL에 없는 테이블명 invent 차단; SELECT-without-FROM은 fixture 전용; compound invent + FROM-clause retry 프롬프트 금지.
- task-guard: 빈
task({})·silent stop에 EnsureAnalystTaskMiddleware로 analyst 경로 강제. - 채점 입력: Execute SSE에 MDL invent fallback 넣지 않음 — warehouse-shaped SQL만 채점.
- DB GRANT: runner 역할에 Spider2 스키마
USAGE/SELECT없으면 check/exec가 왜곡된다. - 주간 wrapper: gold hard OK + agent pass_rate=0 → NF를 열려면 exit 코드를 맞출 것(§4.2 함정). Soft-Gate-Exit-Code-vs-Pass-Rate.md
- 카탈로그 tip 갭: PG에 스키마가 있어도 tip
*.model.json이 없으면search_tables0 → empty_sql. 파일이 있어도 영문 질문 vocab이 한국어-only description에 없으면 같은 증상. vocab Boy Scout + metadata git push 후 MCP PVC SHA 확인 — Metadata-Git-PVC-Resync.md. - 부분 seed:
pit_stops=0인데lap_times만 채워진 상태. SQLite PK NULL이 PG NOT NULL에 막히면 surgical UPDATE 후 COPY. 소스 zip은 앱 PVC에 있을 수 있음(ephemeral checkout과 혼동 금지). - live 판정:
/readyz가 SPA HTML을 주면 tip-live가 아님./api/health+ chat SSE. 스코어보드 JSON에instance_id가 없으면 Opik item에서 재구성. - 잔여 클러스터 우선순위: 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. 수치 스냅샷은 위키에 두지 않는다. - SSE 후행 이벤트 오염 방지: chat SSE 파싱 시, 정상적인 execute SSE 이벤트 이후
AnalystResponse의warehouse_sql(source=null)이 재방출되어 마지막 SQL을 덮어쓰지 않도록extract_last_sql_from_sse는 소스가 명시된 execute 이벤트를 우선 추출한다. - 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. 최소 완료선 (품질 테스트 “준비”)
- 스모크 instance set 문서화 (본 §3)
- preflight(
check/gold-sql) 재현 (본 §4) - agent 배선 AC + runner env + MDL seed (본 §4.1·§7)
🔗 관련 문서
- T2SQL-Benchmarks-2026.md
- AV-SQL-Agentic-Views-Spider-2-0.md
- Playwright-Frontend-UI-Smoke-Pattern.md
- LLM-Tool-Payload-Context-Trim.md
- Agent-SSE-Failfast-and-Tool-Flood-Guard.md
- On-Demand-Schema-Describe-Tools.md
- MCP-Host-Allowlist-DNS-Rebinding.md
- Agentic-Software-Factory.md
- MDL-Only-Domain-Knowledge.md
- MCP-Search-Short-Column-Reverse-Match.md
- Semantic-View-Single-Master.md
- Composite-Grain-Join-Keys.md
- RefSql-Seal-for-EX-Mismatch.md
- Schema-Disjoint-Metadata-Parallel.md
- Soft-Gate-Exit-Code-vs-Pass-Rate.md
- Metadata-Git-PVC-Resync.md
- Shared-Postgres-Cgroup-Limit-vs-Statement-Timeout.md
- RefSql-Unparser-Identifier-Quoting.md