fix: reasoning OFF for OpenRouter reasoning models (Kimi K2.5 / Claude judge)

[TaskerJang]

배경

PR #53 의 첫 80 QA 측정 결과를 분석한 결과, doc-graph-agent 도 doc-summary-agent (PR #133) 와 동일한 reasoning model 빈 응답 문제 의 영향을 받았음이 확인됨.

증거

시스템	LLM	Faithfulness	비고
doc-summary	deepseek-v3.2	87.5% (n=57)	정상
doc-summary	Kimi K2.5	13.8% (n=80)	reasoning 무력화 → 빈 응답 누적
doc-graph	deepseek-v3.2	80%+ 추정	정상
doc-graph	Kimi K2.5	42.5~45% (n=80)	절반으로 떨어짐

doc-graph 가 doc-summary 만큼 완전히 무너지지 않은 이유는 LLM 호출 횟수 차이:

• doc-summary: Map-Reduce 패턴 → 80 QA × ~20 청크 × 3단계 ≈ 5,000 호출 (누적 영향 큼)
• doc-graph: 단일 retrieval → 80 QA × 1단계 ≈ 80 호출 (영향 적음)

다만 영향 자체는 똑같이 받음 → Faithfulness 가 deepseek 측정 대비 절반.

원인

OpenRouter 공식 문서 (https://openrouter.ai/docs/guides/best-practices/reasoning-tokens) 박힌 내용:

Reasoning tokens are considered output tokens and charged accordingly.

Kimi K2.5 / DeepSeek V3.2 등 reasoning 모델은 thinking tokens 가 max_tokens 를 소진한 뒤 실제 출력 (content) 은 빈 문자열로 반환되는 케이스가 발생.

이전 코드 박힌 reasoning: {"enabled": False} 만으로는 일부 모델 (특히 Kimi K2.5) 에서 무시 됨.

패치

공식 문서 박힌 정답 패턴:

"reasoning": {
    "max_tokens": 1,    # ← 공식 권장값 (모든 모델 호환)
    "enabled": False,   # ← Anthropic 일부 모델
    "exclude": True,    # ← reasoning 응답 전달 X
}

3중 안전을 모든 LLM 호출 지점에 박음:

변경 파일

1. agent/llm_client.py — retrieval 답변 생성 LLM

   • LLMConfig.is_openrouter 프로퍼티 박아 자동 감지
   • OpenRouter 경유 시만 extra_body 박기 (Kimi 직결 / OpenAI 직결 영향 0)
   • 빈 응답 진단 + reasoning_content / reasoning 필드 fallback

2. eval/metrics/faithfulness_judge.py — Faithfulness / Numerical Faithfulness judge

   • _use_openrouter_extras 플래그 박음
   • _REASONING_OFF_BODY 3중 안전
   • TIMEOUT 30 → 60s
   • reasoning + reasoning_content 두 필드 모두 fallback

3. eval/metrics/answer_correctness.py — Answer Correctness judge

   • faithfulness_judge._REASONING_OFF_BODY 재사용
   • 동일한 reasoning OFF 패턴

호환성

환경	영향
prod / W4 정성 검증 (KIMI_* 직결)	❌ 영향 0 — is_openrouter False 박혀서 extra_body 미적용
OpenAI 직결 (configure_llm 미호출)	❌ 영향 0
OpenRouter 경유 측정	✅ reasoning OFF 자동 적용

예상 효과

• doc-graph Kimi 재측정 시 Faithfulness 42-45% → 70-85% 박힐 거 예상
• doc-summary Kimi 측정 박힌 deepseek 87.5% 와 비교 가능한 수치 박힐 거
• 비용 절감: reasoning tokens 안 박혀서 약 1/3

재측정 명령어

cd C:\Users\taske\doc-graph-agent && git fetch origin && git checkout feat/disable-reasoning && uv run python scripts/run_qa_eval.py --llm-model "moonshotai/kimi-k2.5" --llm-base-url "https://openrouter.ai/api/v1" --llm-api-key-env "OPENROUTER_API_KEY" --judge-model "anthropic/claude-haiku-4.5" --judge-base-url "https://openrouter.ai/api/v1" --judge-api-key-env "OPENROUTER_API_KEY" --qa-set both --tag kimi_no_reasoning_80qa

---

🤖 Generated with Claude (자고 일어나면 결과 박혀있을 거 예상)

Refs #127, PR #53, doc-summary PR #133