---
id: adr-0008-local-first-llm-cloud-fallback
title: "ADR-0008 로컬 우선 LLM과 클라우드 폴백"
category: "Architecture_Decision"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["ADR local-first", "엔진 폴백 결정", "로컬 LLM 우선", "프로바이더 라우팅 결정"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.9
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["adr", "llm", "provider", "decision", "fallback", "connectai"]
raw_sources: ["ConnectAI/src/core/services.ts", "ConnectAI/src/features/providers/types.ts", "ConnectAI/src/features/providers/index.ts"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[ADR-0008 로컬 우선 LLM과 클라우드 폴백]]

## 🎯 한 줄 통찰 (One-line insight)
기본은 **로컬 엔진(LM Studio/Ollama)을 우선**하고 로컬끼리 폴백하며, 클라우드(OpenRouter/Anthropic/Gemini)는 **model id prefix 로 옵션 선택**하기로 결정했다 — 프라이버시·비용·오프라인을 기본값으로, 필요 시 클라우드 품질을 끌어쓰기 위해 [S1][S2].

## 🧠 핵심 개념 (Core concepts)
- **결정:** prefix 없으면 로컬, 있으면 클라우드 어댑터. 로컬은 LM Studio↔Ollama 자동 폴백.
- 구현은 [[LLM 프로바이더 추상화]] 참조.

## 📖 세부 내용 (Details · ADR)
### Problem
어떤 LLM 을 어떻게 선택/실패 처리할 것인가. 로컬은 무료·프라이버시·오프라인이지만 품질·가용성이 들쭉날쭉. 클라우드는 품질↑ 비용·프라이버시 우려.

### Context
제2뇌는 개인 지식을 다룸 → 프라이버시 중요. 로컬 엔진은 가끔 빈 응답/전송 오류. 사용자가 작업별로 품질을 올리고 싶을 때가 있음.

### Options Considered
1. **클라우드 전용** — 품질·간편, 그러나 비용·프라이버시·오프라인 불가.
2. **로컬 전용** — 프라이버시·무료, 그러나 실패 시 대안 없음.
3. **로컬 우선 + 로컬 폴백 + 클라우드 옵션(prefix)** — 기본 안전 + 선택적 품질.

### Chosen Solution
3번. `AIService.chat` 이 설정 엔진→다른 로컬 엔진 폴백(빈 응답=soft failure). 클라우드는 `parseModelPrefix` 로 라우팅, 어댑터가 SSE 정규화 [S1][S2].

### Why It Was Chosen
프라이버시·비용·오프라인을 기본으로 보장하면서, 로컬 불안정을 폴백으로 메우고, 필요 시 클라우드 품질을 prefix 하나로 선택.

### Benefits
프라이버시 기본, 가용성↑(폴백), 유연성(작업별 클라우드), 호출부 공급자 무관.

### Drawbacks
폴백이 지연을 더함, 로컬/클라우드 응답 형식 차이를 어댑터가 흡수해야 함, 클라우드 키 관리.

### Future Risks
클라우드 모델 id/형식 변경 시 어댑터 유지보수, 로컬 모델 품질이 작업을 못 받치면 사용자 불만.

### Alternative Approaches
품질이 절대 우선이면 클라우드 기본 + 로컬 폴백(역순). 또는 작업 난이도 자동 분류로 라우팅(쉬운 건 로컬, 어려운 건 클라우드).

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"좋은 클라우드 모델을 쓰면 되지" 라는 입장과 충돌 — 이 결정은 *프라이버시·비용·오프라인* 을 품질보다 우선한 가치 판단. 사용은 prefix 로 자유.

## 🛠️ 적용 사례 (Applied in summary)
`services.ts`(폴백), `providers/types.ts`+`index.ts`(prefix 라우팅) [S1][S2].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
- **관련 개념:** [[LLM 프로바이더 추상화]], [[API Client Pattern]], [[Tool Calling Pattern]]
- **참조 맥락:** 로컬 LLM 이 다중 추론 백엔드 전략(로컬/클라우드/폴백)을 설계할 때 참조.

## 📚 출처 (Sources)
- [S1] ConnectAI/src/core/services.ts — 로컬 엔진 폴백, soft failure
- [S2] ConnectAI/src/features/providers/types.ts, index.ts — prefix 라우팅, 어댑터 dispatch

## 📝 변경 이력 (Change history)
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
