Local AI fallback ship하기

이 마지막 lesson 모양

여기서 quest를 하나로 묶어서 진짜 물건을 하나 띄워. 작은 backend service인데, cloud provider를 골라서 user prompt에 답하고, cloud에 못 닿을 땐 조용히 Ollama로 넘어가. 앞의 모든 track에서 배운 패턴이 production 모양으로 돌아간다는 걸 보이는, 가장 작은 증거야.

Production check-list

Adapter 패턴. Cloud랑 Ollama 둘 다 stream() 구현.
Health check. 둘 다 빠른 timeout 가진 health_check().
Orchestrator. Cloud를 먼저 부르고, 실패하거나 health가 나쁘면 Ollama로 넘어가. Priority는 기본값이 아니라 인자야. adapters 트랙은 같은 클래스를 local-first로 만들거든. cloud-first를 뜻하는 서비스면 그렇게 말해 줘야 해.
Streaming. 어느 vessel이 답하든 frontend는 끊김 없는 SSE stream 하나만 봐.
Pin한 모델 tag. Ollama 쪽도 cloud 쪽도 버전을 못 박아둬.
Observability. 매 request마다 뭐가 답했는지 남겨. 아래 skeleton은 model tag를 기록해. chunk가 실어 오는 게 그거니까. vessel 키가 필요하면 orchestrator가 그걸 실어 보내게 해. 그리고 믿기 전에 그 로그를 한 번은 읽어봐. 이름 필드가 아예 없는 게 아니라 빈 값이면, 로그는 평생 빈칸만 성실하게 찍거든. 나중에 어떤 답이 유독 다르게 느껴질 때 이 로그가 없으면 아무것도 못 해.
Mini mode. Local 모델이 작으면 system prompt를 확 덜어내.
Warm-up. Startup task에서 keep_alive: -1로 local 모델을 미리 올려둬. 그래야 첫 fallback이 견딜 만한 속도로 나와. tag는 adapter에서 읽어야 데운 모델이랑 부르는 모델이 갈라지지 않아.

이게 동작할 때 만든 거

privacy도, 비용도, 장애도 아는 서비스야. Cloud가 죽어도 user는 답을 계속 받아. Cloud가 rate-limit을 걸어도 계속 받고. Cloud가 비싸지면 bulk batch job이 local로 흘러가. Orchestrator는 단순하고 adapter는 좁아. 그래서 잘 안 부러져.

EV v3 · 2026-09-18: 아래 skeleton이 자기 check-list랑 세 군데서 어긋나 있었어. 전부 발행일부터야. 3번은 “cloud를 먼저 부른다”고 약속해 놓고, 코드는 adapters 트랙의 AIOrchestrator를 그대로 가져다 썼어. 그 priority 리스트는 ollama로 시작해. 출시된 서비스가 local-first였던 거야. 레슨 전제랑 정반대로. 이제 priority를 명시해서 넘겨. 8번 warm-up은 qwen2.5:7b를 미리 올렸는데 orchestrator의 Ollama adapter는 qwen2.5:32b로 만들어져 있었어. 서비스가 부르지도 않는 모델을 데우고, 막으라고 있는 첫 cold fallback은 그대로 남겨둔 거지. 지금은 tag를 adapter에서 읽어. 6번 vessel 로그는 is None 가드 아래서 첫 chunk의 chunk.model을 붙잡았는데, StreamChunk.model의 기본값은 빈 문자열이고 그건 None이 아니야. 가드가 바로 만족돼서 모든 request가 vessel=만 찍었어. skeleton은 deprecated된 @app.on_event("startup")에서 lifespan context manager로도 옮겼어. FastAPI 0.140이 요구하는 쪽이야. 이제 적힌 그대로 돌리면 진짜 model tag가 찍혀. 같은 블록에서 리뷰가 두 개를 더 잡았어. warm-up이 keep_alive를 "-1" 문자열로 보내고 있었는데 ollama는 거기에 400으로 답해. 그러니까 엉뚱한 모델을 데우던 걸 고친 수정 자체가 값이 숫자 -1이 되기 전까진 아무 일도 안 하고 있었던 거야. 그리고 로그가 기록하는 chunk.model은 vessel 키가 아니라 model tag라서, 변수 이름도 model로 바꿔서 딴 걸 가리키는 척하지 않게 했어. orchestrator의 두 번째 vessel 이름도 여기선 codex야. fallback 레슨 산문이랑 맞췄어.

Code

End-to-end skeleton (FastAPI + orchestrator)·python

from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import json

# Cloud 먼저, local은 장애 대비 그물. adapters 트랙의 기본 priority는
# 반대 방향이니까, 여기서 어느 쪽인지 분명히 말해 줘야 해.
ORCHESTRATOR = AIOrchestrator(priority=["claude", "codex", "gemini", "ollama"])

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 첫 cold fallback이 30초 대기가 되지 않게 local fallback을 미리 올려둬.
    # tag를 다시 적지 말고 adapter에서 읽어. 자기 모델 이름을 따로 적어 둔
    # warm-up은 adapter가 바뀌는 순간 엉뚱한 모델을 데워.
    local = ORCHESTRATOR.vessels["ollama"]
    try:
        await local.client.post(
            f"{local.base_url}/api/generate",
            json={"model": local.model, "keep_alive": -1},   # the number, not "-1"
            timeout=120.0,
        )
    except Exception:
        pass  # local이 안 깔려 있어도 괜찮아
    yield

app = FastAPI(lifespan=lifespan)

@app.post("/chat/stream")
async def chat_stream(req: dict):
    """cloud→local fallback으로 user에게 답을 stream."""
    answered_by = {"model": None}

    async def gen():
        async for chunk in ORCHESTRATOR.stream(req["messages"]):
            # 실제로 보이는 첫 model tag를 기록해. `is None`만으로 막으면
            # 첫 chunk의 빈 문자열 기본값이 그대로 박혀서 영원히 빈 값만 찍혀.
            # 뭘 얻는지도 분명히 해 두자. vessel 키가 아니라 model tag야.
            # 키가 필요하면 orchestrator가 그걸 실어 보내게 해.
            if not answered_by["model"] and chunk.model:
                answered_by["model"] = chunk.model
            payload = {"content": chunk.content, "done": chunk.done}
            yield f"data: {json.dumps(payload)}\n\n"
        # 어느 vessel이 답했는지 로그 (ops용)
        print(f"[/chat/stream] model={answered_by['model']}")

    return StreamingResponse(gen(), media_type="text/event-stream")

# 실행: uvicorn main:app --host 0.0.0.0 --port 9000

Exercise

FastAPI 서비스 빌드. 실행. 4 시나리오 test: (1) cloud 닿음, (2) cloud firewall에서 차단, (3) cloud 닿는데 느림, (4) Ollama daemon 멈춤. 네 경우 다 사용자 눈에 보이는 동작이 매끄러운지 확인해. 각 실패 모드에서 '매끄럽다'가 정확히 뭔지 글로 적어봐. 그게 네 진짜 ops 계약이야.