Files

T

hyungi 59bde9a399 feat(search): phase-2q apply opt-in — production rollout 시작, 1주 관찰 (gemma-4)

plan pr-2q-apply-query-rewrite-1-bright-meadow.md. Phase 2Q Diagnose closure +
Rerank-Payload-Fix (main 0257a5d) 완료 후 Apply rollout. opt-in path 가 Phase 1B/2
부터 이미 production 가동 중 → 본 PR 의 production 영향 0 (marker PR).

rollout 정책:
  · default = rewrite_backend null (single-query path, baseline 회귀 0 invariant)
  · 명시 opt-in = ?rewrite_backend=cand_multi_query_macmini (추천 gemma-4)
  · 대안 = cand_multi_query_macbook (qwen3.6, mixed/english 강점, MacBook 가동 시)
  · 1주 관찰 (2026-05-24 ~ 2026-05-31) → metric 정상 시 default ON 별 PR

변경 (production 영향 0):
- docs/phase_2q_apply_opt_in.md 신규 — 사용자 가시화:
  · 사용 방법 (query param + SvelteKit fetch 예시)
  · 1주 관찰 metric 목표 (cache hit ≥ 50% / LLM warm p50 ≤ 1500 / 503 ≤ 5/day / Recall t≥3 ≥ 0.74)
  · 추천 LLM 사유 (decision md §4 4-factor) + 대안 명시
  · Phase 2 QueryAnalyzer sequencing 박제 (영향 0, ask_events 0건 운영 관찰 후 확정)
  · Follow-up PR 5건 명시 (Telemetry / Alert / Default-ON / Cache-Prewarm / Category-Analysis)
- app/api/search.py — rewrite_backend query param description 갱신.
  Apply 진입 박제 + 추천 LLM 표시 + docs 링크. 동작 변경 0.
- tests/search_eval/baselines/v0_2_phase2q_apply_smoke_2026-05-24.json — production smoke:
  · opt-in path HTTP 200 + total_ms 957 (cache hit) + rerank_ms 109 (정상 호출) + fallback 0
  · baseline path HTTP 200 + total_ms 207 + rerank_ms 19 + fallback 0 (회귀 0 확정)

38/38 unit test PASS (회귀 0). main HEAD 0257a5d 위 branch.

Closure gate PASS:
  · docs 가시화 / search.py description / smoke json 박제
  · production smoke 양쪽 path 정상 + 회귀 0 verify
  · 메모리 갱신 + 1주 관찰 종료일 2026-05-31 박제

Follow-up: 1주 후 PR-2Q-Apply-Default-ON-1 (metric 정상 시) 또는 fix PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-24 04:01:49 +00:00

4.6 KiB

Raw Blame History

Phase 2Q Apply — Multi-Query Rewrite (opt-in, 2026-05-24 진입)

개요

Phase 2Q Diagnose 결과 (decision md tests/search_eval/baselines/v0_2_phase2q_decision_2026-05-24.md) H1 (both backends 유의미 net 개선) 확정 + Rerank-Payload-Fix (commit b734fc5) 완료 후 Apply rollout 진입.

rollout 정책 = opt-in 1주 관찰 (2026-05-24 ~ 2026-05-31). 1주 후 metric 정상 시 default ON 전환 결정 (별 PR PR-2Q-Apply-Default-ON-1).

추천 LLM = cand_multi_query_macmini (gemma-4-26b-a4b-it-8bit, Mac mini). 4-factor weighted 사유 (decision md §4):

⭐ Availability — 24/7 가동 (qwen MacBook lap-top 의존)
NDCG 0.927 dominant (qwen 0.919 와 동등 단 noise level)
Cold latency 우세 (gemma 2757ms vs qwen 3647ms cold p50)
카테고리 standards/exam/korean 강점 (도메인 중심)

대안 = cand_multi_query_macbook (qwen3.6-27B, mixed/english 강점) — MacBook always-on 의향 시 가능.

사용 방법

Query parameter (opt-in)

GET /api/search/?q=<query>
  &mode=hybrid
  &limit=20
  &rewrite_backend=cand_multi_query_macmini   # opt-in, 미지정 시 single-query path

rewrite_backend 미지정 또는 baseline → 기존 single-query path 100% 그대로 (baseline 회귀 0 invariant, Phase 2Q Phase 2 + Rerank-Fix 측정 박제).
rewrite_backend=cand_multi_query_macmini → multi-query (3 variants) + unified RRF
- reranker.
rewrite_backend=cand_multi_query_macbook → qwen (MacBook 가동 시).
미지원 slug → HTTP 400 unknown_rewrite_backend.
LLM 호출 실패 → HTTP 503 rewrite_llm_unavailable (no silent fallback).

SvelteKit / fetch 예시

const res = await fetch(
  `/api/search/?q=${encodeURIComponent(q)}&mode=hybrid&limit=20&rewrite_backend=cand_multi_query_macmini`,
  { headers: { Authorization: `Bearer ${token}` } }
);

1주 관찰 metric (목표)

Metric	목표값	측정 source	회귀 시 action
Rewrite cache hit rate	≥ 50% (1주차)	`[rewrite-dispatch]` log `cache_hit=true` 비율	`PR-2Q-Cache-Prewarm` (nightly cron)
LLM latency warm p50	≤ 1500ms	`[rewrite-dispatch]` log `llm_latency_ms`	gemma 가동 상태 확인, semaphore 경쟁 진단
LLM latency cold p50	≤ 3000ms	동상	cache prewarm 도입 검토
503 누적	≤ 5/day	fastapi 응답 status 503	LLM endpoint health / circuit breaker 검토
Recall@10 t≥3	≥ 0.74 (production traffic 분석)	random sampling 또는 별 dashboard	NDCG 회귀 분석 + 카테고리 분포
사용자 negative feedback	0건	사용자 channel	즉시 rollback 또는 priority fix

1주 관찰 종료일 (2026-05-31) decision

4 metric 정상 + 사용자 negative feedback 0 → PR-2Q-Apply-Default-ON-1 진입 (default ON 전환)
1 metric 이상 회귀 → 별 fix PR 후 1주 추가 관찰
catastrophic 회귀 → rollback (rewrite_backend default null 영구 유지)

Phase 2 QueryAnalyzer sequencing

Phase 2 QueryAnalyzer (app/services/search/query_analyzer.py) 가 production 가동 중 이지만 retrieval path 영향 0 (debug 노출만, app/api/search.py:156 코멘트 박제, ask_events 0건 운영 관찰 후 확정). Phase 2Q multi-query rewrite 와 충돌 없음.

→ Apply 진입 시 두 layer 모두 가동, 결과 일치성 invariant 유지.

Follow-up PR (별 트랙)

PR-2Q-Apply-Telemetry-1 — [rewrite-dispatch] log 를 search_failure_logs 또는 별 telemetry 테이블 에 누적 (search_telemetry.py 패턴 재사용). 1주 관찰 metric 의 정량 분석 source.
PR-2Q-Alert-1 — Prometheus + ntfy alert rule (LLM 503 ≥ 10/hour / cache hit < 30% 7d window). monitoring stack 영역.
PR-2Q-Apply-Default-ON-1 — 1주 관찰 종료 후 default ON 전환.
PR-2Q-Cache-Prewarm — cache hit rate < 50% 관찰 시 nightly cron.
PR-2Q-Apply-Category-Analysis — Rerank-Fix 측정의 카테고리 회귀 (standards -0.28, exam -0.19) 분석. RRF fallback vs reranker 의 ranking 동작 차이 박제.

4.6 KiB Raw Blame History