scripts/README.md

운영 지원 스크립트

내부망 배포에서 지원하는 스크립트는 다음과 같습니다.

스크립트	역할
44_generate_oneline_desc.py	후보 한 줄 설명 생성
45_validate_eval_sets.py	dev/gold/no-match 평가 데이터 검증
46_build_dataset_manifest.py	버전별 데이터 매니페스트 재생성
47_eval_retrieval.py	exact menu ID 검색·서빙 경로 평가
48_prepare_version_data.py	버전별 SQLite를 검수 승계된 검색 데이터로 변환
49_build_version_indexes.py	버전별 BM25와 공용 Qdrant 인덱스 구축
50_import_version_review.py	승인된 키워드·한 줄 설명을 영속 override로 반영
51_generate_version_candidates.py	신규·메뉴명 변경 메뉴의 근거 기반 검색 후보 생성
52_update_version_release.py	DB 변환부터 인덱스 생성까지 반복 작업 일괄 실행
53_ablate_ranking.py	쿼리 확장·인기도·Q↔Q 설정의 순위 회귀 비교

00~`43`은 과거 POC 실험 및 마이그레이션 도구입니다. 운영 Docker 이미지에는 포함하지 않으며, 내부망 첫 배포 승인 전까지 실험 이력으로만 보존합니다.

표준 업데이트 순서:

# 승인된 내부 Azure LLM을 사용하는 자동 처리
.\.venv\Scripts\python.exe scripts\52_update_version_release.py

# 현업 검수 결과가 생긴 뒤
.\.venv\Scripts\python.exe scripts\50_import_version_review.py --input <reviewed.csv>
.\.venv\Scripts\python.exe scripts\48_prepare_version_data.py
.\.venv\Scripts\python.exe scripts\49_build_version_indexes.py
.\.venv\Scripts\python.exe scripts\47_eval_retrieval.py --app-version 1.5.5 --serving-path --no-hyde

52는 운영 버전 SQLite를 자동 발견하고 48 → 51 → 48 → 45 → 49 순서로 실행합니다. 51은 원천 메뉴명·경로·DB 키워드만 근거로 후보를 만들며, 결과는 auto_generated_unreviewed 상태로 남습니다. 동일한 원천 fingerprint의 메뉴는 다시 호출하지 않고 신규·변경분만 증분 생성합니다.

비 Azure LLM 백엔드는 기본 차단됩니다. 메뉴 메타데이터의 외부 전송이 승인된 경우에만 --allow-external-llm을 명시해야 합니다.

48이 만든 data/versions/review_queue.csv의 사본에서 검수하고, 승인 결과를 50으로 가져온 뒤 48과 49를 다시 실행하면 승인 데이터가 자동 후보보다 우선 적용됩니다.

컨테이너에서는 MENU_DB_DIR=/app/menu_db_ver를 사용합니다.