feat(ai): LLM 티어별(Pro/Flash) 엔드포인트 오버라이드 + 모델 비교 벤치 스크립트

[i3months]

작업 내용

• LLM_PRO_BASE_URL / LLM_PRO_API_KEY / LLM_FLASH_BASE_URL / LLM_FLASH_API_KEY 추가. 체인 11곳의 ChatOpenAI 생성을 settings.llm_base_url_for(tier) / llm_api_key_for(tier) 로 일원화
• 오버라이드한 티어는 공용 LLM_API_KEY(학교 게이트웨이 키)를 물려받지 않음 — 다른 서버로 키 유출 방지
• ai/scripts/llm_bench.py: 운영 프롬프트·파서(질문 풀 생성, 스트리밍 꼬리질문) 그대로 후보 모델 비교
• compose / .env.example / docs/environment.md 반영

변경 이유 / 배경

로컬 LLM(Ollama) 도입 검토. 꼬리질문(Flash)만 로컬로 돌리고 질문 풀·피드백·PDF 비전(Pro)은 게이트웨이에 두는 식의 부분 전환을 설정만으로 가능하게 한다. 기본값은 비어 있어 운영 동작 변화 없음.

벤치 결과 요약 (ana-server, GTX 1660 Ti 6GB, Ollama num_ctx 8192, 워밍 후)

모델	꼬리질문 중간값	질문 풀 3개 중간값	GPU 적재
gemini-3.5-flash-lite (게이트웨이)	2.5s	3.2s	-
gemini-3.1-pro-preview (게이트웨이)	-	22s	-
qwen3:4b-instruct	2.0s	19s	100% GPU
qwen2.5:7b	4.4s	34s	8% CPU 넘침
exaone3.5:7.8b	14.5s	39s	19% CPU 넘침

모든 모델이 JSON/태그 출력 형식은 지켰다(파싱 성공 100%). 품질은 Gemini 우위 — 로컬 모델은 질문 반복·저가치 질문(키 형식/길이)·용어 오역("topic"→"테마")·복합질문 경향.

로컬 전환 시 주의

• Ollama 기본 num_ctx 4096 은 질문 풀 프롬프트(샘플만으로 3,113 토큰)에 부족 → 조용히 잘림. PARAMETER num_ctx 8192 파생 모델 필요
• 캐시 없는 첫 프리필 ~7초 → LLM_FLASH_TIMEOUT_SEC=10 에 근접. Ollama 기본 keep_alive 5분 후 언로드되면 로드 +4초
• Flash 티어는 꼬리질문뿐 아니라 피드백의 자기소개·인성 평가·답변 코칭(동시 5)에도 쓰인다 — 단일 GPU 직렬 처리라 피드백 생성이 크게 느려짐
• Pro 티어를 로컬 텍스트 모델로 돌리면 pdf_vision(스캔 PDF 판독)이 깨짐

테스트

• 단위 테스트 추가 (test_llm_endpoint_settings.py 5건), 전체 399 passed
• flake8 / black 통과
• 운영 서버에서 벤치 스크립트로 실제 체인 호출 확인

영향 범위

• DB 마이그레이션: 없음
• API contract 변경: 없음
• 환경변수 추가/변경: 있음 (위 4개, 모두 선택 · 기본 빈 값)

리뷰어 체크포인트

• Settings.llm_api_key_for 의 키 비상속 규칙

🤖 Generated with Claude Code