# 05. LLM Backend Guide

## 기본 정책

외부 API는 기본 비활성화한다. Local Agent는 OpenAI-compatible local endpoint를 우선 호출하도록 설계한다. SaaS Web은 사용자가 입력한 Local Agent `IP:Port`로 직접 연결하고, Flownco 서버는 사용자 입력 IP로 proxy 요청하지 않는다.

## LLM Provider Router 구조

```text
SaaS Web
  -> 사용자가 입력한 Local Agent IP:Port
  -> Local Agent FastAPI :8787
  -> LLM Provider Router
       |- DeepSeek API
       |    base_url: https://api.deepseek.com
       |    model: deepseek-v4-pro / deepseek-v4-flash
       |    status: MVP 기본 차단
       |
       |- HyperCLOVA X Local vLLM
       |    base_url: http://127.0.0.1:8001/v1
       |    model: naver-hyperclovax/HyperCLOVAX-SEED-Think-14B
       |
       |- HyperCLOVA X Vision Local vLLM
       |    base_url: http://127.0.0.1:8002/v1
       |    model: naver-hyperclovax/HyperCLOVAX-SEED-Vision-Instruct-3B
       |
       |- DeepSeek-R1-Distill Local
       |    base_url: http://127.0.0.1:11434/v1
       |    model: deepseek-r1:7b
       |    role: math_validation
       |
       |- Ollama / LM Studio / llama.cpp
            base_url: http://127.0.0.1:11434/v1
```

Local Agent `/health` 응답은 `providerRouter` 필드에 active provider, 각 provider의 allowed/blocked 상태, 역할별 `roleRouting`을 포함한다.

## 역할별 모델 사용 기준

| 역할 | Provider | Endpoint | 사용 범위 |
| --- | --- | --- | --- |
| 한글 시각 OCR | HyperCLOVA X SEED Vision | `http://127.0.0.1:8002/v1` | 시험지 이미지, 문제 crop, 인쇄 글자 후보 인식 |
| 한글 문맥 보정 | HyperCLOVA X SEED Think/Text | `http://127.0.0.1:8001/v1` | 깨진 한글 후보 보정, 문항 문맥 후보 생성 |
| 풀이 이미지 후보 인식 | HyperCLOVA X SEED Vision | `http://127.0.0.1:8002/v1` | 학생 풀이·문항 구조 후보 JSON 생성 |
| 수학적 검증 | DeepSeek-R1-Distill compatible local model | `http://127.0.0.1:11434/v1` | 풀이 단계의 수학적 검증 후보 생성 |

DeepSeek-R1-Distill은 최종 판정자가 아니다. 수학 검증 후보는 `math_validation_result`로 저장하고, 최종 확정은 시각 증거, OCR 근거, 교사 승인 흐름을 통과한 결과만 사용한다.

## 시험지 업로드 처리 흐름

프로젝트 생성 화면에서 시험지를 업로드하면 브라우저는 다음 순서로 동작한다.

1. Flownco SaaS API에 프로젝트, 업로드 파일, 페이지 정보를 저장한다.
2. 사용자가 설정한 `protocol://host:port`의 Local Agent `/scan/upload-and-recognize`로 같은 시험지 파일을 직접 전송한다.
3. Local Agent는 Provider Router 정책을 확인한 뒤 mock 또는 local model 결과를 반환한다.
4. 브라우저는 반환된 `recognitionResults`, `unreadableAreas`를 SaaS API에 저장해 사용자 상세 화면과 관리자 화면에서 조회하게 한다.

이 경로에서도 Flownco 서버의 사용자 입력 IP proxy는 금지된다.

## HyperCLOVA Vision 3B 예시

```text
modelBaseUrl=http://127.0.0.1:8002/v1
modelName=naver-hyperclovax/HyperCLOVAX-SEED-Vision-Instruct-3B
task=SOLUTION_RECOGNITION
```

## HyperCLOVA Text 1.5B 예시

```text
modelBaseUrl=http://127.0.0.1:8001/v1
modelName=naver-hyperclovax/HyperCLOVAX-SEED-Text-Instruct-1.5B
task=ANNOTATION_PHRASE
```

## DeepSeek-R1-Distill local 예시

```text
modelBaseUrl=http://127.0.0.1:11434/v1
modelName=deepseek-r1:7b
task=MATH_VALIDATION
```

## Ollama/LM Studio 테스트

Ollama 또는 LM Studio가 OpenAI-compatible `/v1/chat/completions`를 제공하면 Local Agent의 `model_base_url`에 입력해 mock을 local inference로 교체할 수 있다.

```text
providerKey=ollama-compatible
modelBaseUrl=http://127.0.0.1:11434/v1
modelName=local-openai-compatible-model
```

## 금지사항

- MVP 기본 모드에서 DeepSeek API 호출 금지
- OpenAI API 호출 금지
- Anthropic API 호출 금지
- 외부 CLOVA Studio API 호출 금지
- 원본 시험지 이미지와 OCR 텍스트 외부 전송 금지