LLM RAG Local — 로컬 RAG 운영 시스템

로컬 LLM(Ollama) + ChromaDB 기반의 프로젝트 물류 Copilot.
Cursor IDE에서 DRY_RUN → 승인 → APPLY 계약으로 안전하게 운영한다.

---

빠른 시작 (Quick Start)

1) 의존 패키지 설치 (승인 필요)

pip install -r tools/requirements.txt

2) Ollama 모델 준비 (기본값 기준)

실제 사용 모델/URL의 SSOT는 tools/config.py + 환경 변수다.

ollama pull qwen2.5:7b-instruct
ollama pull nomic-embed-text

Gemma 4 파일럿(선택): 게이트 모델은 Ollama 0.20 이상이 필요하다(구버전은 manifest 412). 예시:

ollama pull gemma4:e4b-it-q4_K_M
python tools/bench/ollama_bench_one.py
python tools/poc/schema_extract.py --dry-run tests/fixtures/pilot_invoice_sample.txt

파일럿 전용 모델 태그는 환경 변수 PILOT_OLLAMA_MODEL로 지정한다(기본 LLM_MODEL은 바꾸지 않는다).

BL PoC / RAG 모델 A-B(선택, plan-doc-2026-04-06-gemma-next-epics-full.md):

python tools/poc/bl_schema_extract.py --dry-run tests/fixtures/pilot_bl_sample.txt
python tools/bench/rag_model_compare.py --dry-run
# 실측: Chroma 인덱스 + Ollama. B 모델 필수 (--model-b 또는 PILOT_OLLAMA_MODEL)
python tools/bench/rag_model_compare.py --model-b gemma4:e4b-it-q4_K_M
# 질문 여러 개일 때 페어 단위 병렬: --jobs 4 (질문마다 A→B 순서는 유지)

• A측은 --model-a 또는 환경 변수 AB_MODEL_A; 비우면 호스트의 LLM_MODEL(미설정 시 config 기본)을 쓴다.
• ask.py를 두 번 호출해 out/bench/rag_ab_report.json에 지연·exit·evidence 요약을 남긴다(저장소에는 .gitignore).

3) 데이터 투입 (SSOT 경로)

ssot/pdf/    ← PDF (.pdf)
ssot/xlsx/   ← Excel (.xlsx)
ssot/facts/  ← Facts (.md, .json)

4) 인덱싱 (DRY_RUN → 승인 → APPLY)

python tools/rag.py index               # DRY_RUN (기본)
python tools/rag.py index --apply       # 실제 인덱싱(승인 후)

5) 질의

python tools/rag.py ask "BL번호 알려줘"

tools/ask.py와 rag.py ask의 표준 출력은 한 줄 JSON이다. answer, evidence_count, route_used, evidence, timing_ms(retrieve·generate ms), llm_model, embed_model를 포함하며, 증거가 없을 때는 error_code(예: E007_NO_EVIDENCE)가 설정된다. rag.py ask는 동일 JSON을 out/rag/에 저장하고 qa_log에 요약을 남긴다.

---

핵심 계약 (AGENTS.md 요약)

계약	내용
DRY_RUN 기본	--apply 없으면 실제 쓰기 없음
ZERO_STOP	Evidence 0건 → ExitCode=2, 답변 금지
append-only 로그	out/logs/ops_log.jsonl, out/logs/qa_log.jsonl
localhost 전용	기본 http://localhost:11434 (외부 네트워크 호출 금지)

---

SSOT (Config)

• tools/config.py 가 경로/기본값의 단일 근거다.

SSOT 경로 (확정)

• 입력:
  • ssot/pdf
  • ssot/xlsx
  • ssot/facts
• 출력:
  • VectorDB: out/chroma
  • Q&A 결과: out/rag
  • 운영 로그: out/logs/ops_log.jsonl
  • Q&A 로그: out/logs/qa_log.jsonl

---

환경 변수 (기본값 = config.py)

변수	기본값	설명
OLLAMA_URL	http://localhost:11434	Ollama 주소
LLM_MODEL	tools/config.py 참조	생성 모델(RAG ask 등)
EMBED_MODEL	tools/config.py 참조	임베딩 모델
PILOT_OLLAMA_MODEL	(미설정 시 스크립트 기본값)	파일럿 벤치/PoC 전용 태그
RAG_CHROMA_DIR	(미설정)	테스트·격리용 Chroma 디렉터리 덮어쓰기(일반 운영에서는 비움)

---

전체 명령어 (확정: help 기준)

python tools/rag.py status
python tools/rag.py index
python tools/rag.py ask
python tools/rag.py replay
python tools/rag.py export

테스트: python -m pytest tests -q (회귀 시나리오·스모크 포함). Ollama 통합만 보려면 pytest -m ollama.

의존성: GitHub에서 Dependabot이 tools/requirements.txt를 주간으로 스캔한다(.github/dependabot.yml).