로컬 LLM

지도 위치 : 4일차 · ⑤애플리케이션 층 전체 — 부품을 한 앱으로 | 이전: 31차시 로컬 LLM 업무형 앱 구현 | 다음: 33차시 프로젝트 요구사항 분석 키워드 : LLM API, Streaming, Prompt, Structured Output, Function Calling 통합

이 차시를 다 읽으면

1. 4일차의 기능들이 다섯 층 중 ⑤의 어디에 , 헥사고날의 어느 칸에 놓이는지 지도로 말할 수 있다.
2. 문의봇 통합 구조도를 인바운드 · 유스케이스 · 아웃바운드 로 그릴 수 있다.
3. 통합을 루프 엔지니어링 으로 볼 때 "완료"를 누가 판정하는지 말할 수 있다.
4. 설정을 어디에 둘지 정하고, 프롬프트 · 응답 로그의 개인정보 마스킹 이 왜 필요한지 설명할 수 있다.
5. 통합 시나리오 테스트 목록 (정상 · 긴 메일 · 형식 실패 · 도구 실패 · LLM 서버 다운 · 동시 10명)을 만들고 결과를 검수할 수 있다.

---

0. 이 차시의 판별 축

앞에서 이어집니다 — 25차시 6절에서 "이 뼈대에 26~30차시가 기능을 붙이지만 유스케이스와 어댑터만 늘어나고 폴더 구조는 그대로 이며 32차시에서 전체를 다시 그린다"고 했습니다. 그리고 README 7장의 문장 3 — "표준 API(포트)로 층을 나누면 엔진(어댑터)을 갈아 끼울 수 있다" — 를 이 차시에서 엔진 밖으로까지 넓혀 회수합니다.

---

1. 4일차 전체 지도

⑤ 애플리케이션   ├ 연결        LLM 클라이언트 (25)
                 ├ 받는 방식   스트리밍 · SSE (26)
                 ├ 기억        대화 기록 · 토큰 예산 (27)
                 ├ 지시        프롬프트 파일 · 평가 루프 (28)
                 ├ 출력 모양   구조화 출력 · Pydantic 검증 (29)
                 ├ 행동        도구 호출 · 권한 · HITL (30)
                 └ 업무        분류 · 추출 · 요약 · 초안 (31)
④ API           OpenAI 호환 /v1/chat/completions (20)
③ 추론 엔진      vLLM (운영) / Ollama (개발)
② 모델 파일      Qwen3-8B (양자화 선택은 2일차)
① 하드웨어       RTX 4090 24GB

⭐ 일곱 줄 중 새 폴더를 만든 줄이 없습니다. 모두 25차시의 트리 안에 들어갔습니다.

---

2. ⭐ 통합 구조도 — 헥사고날 배치

   인바운드 어댑터                애플리케이션 코어                      아웃바운드 어댑터
┌────────────────────────┐  ┌──────────────────────────────────┐  ┌──────────────────────────┐
│ FastAPI 라우터          │  │ use_cases/                        │  │ OpenAICompatAdapter       │─▶ vLLM / Ollama
│  POST /inquiries/{id}/  │─▶│  ProcessInquiry                   │─▶│   (LLMPort)               │
│    analyze      (JSON)  │  │    분류 · 추출 · 요약              │  │ OrderApiAdapter           │─▶ 주문 시스템
│  POST /inquiries/{id}/  │  │  DraftReply                       │  │   (OrderPort)             │
│    draft/stream (SSE)   │  │    대화 조립 · 도구 루프 · 초안     │  │ RedisConversationStore    │─▶ Redis
│ schemas/ (문지기)        │  │ ports/output/ (세 개의 포트)       │  │   (ConversationStorePort) │
│ 인증 · 인가              │  │ prompts/*.md                      │  │                           │
└────────────────────────┘  └──────────────────────────────────┘  └──────────────────────────┘

⭐ README 7장의 문장 3은 엔진 이야기였습니다. 이제 주문 시스템 · 저장소 · 화면 까지 같은 원리로 갈아 끼웁니다. 헥사고날 배치는 좌우 대칭 입니다(25차시 2.1의 인바운드 · 아웃바운드) — 왼쪽(들어오는 쪽)과 오른쪽(나가는 쪽)이 같은 방식으로 교체됩니다.

⚠️ 안쪽 코드(app/)에서 바깥 기술로 바로 가는 길 이 있으면 그 자리에 포트(문)를 세워야 합니다. 이 노트에서는 이 점검 원칙을 Port Gate 라고 부릅니다. 지켜졌는지는 한 줄로 검사합니다. grep -rnE "fastapi|openai|redis|httpx" app/ 결과가 비어 있어야 합니다.

2.1 요청 한 건이 지나는 길

상담원 클릭
 └ [인바운드] 인증 · 인가 → 스키마 검증(본문 길이 상한)
 └ ProcessInquiry  분류+추출 (LLM, JSON 스키마, t=0) → Pydantic 검증 → 원문 대조 → 요약
 └ DraftReply      대화 기록 조립(예산) → LLM(tools) → get_order(권한 확인) → LLM → 초안 스트리밍
 └ [규칙]          금지 표현 · 다른 고객 정보 검사
 └ 상담원 화면     수정 → 발송 버튼 (사람)

---

3. 통합 = 루프 엔지니어링

부품이 하나씩 통과해도 합치면 깨지는 곳 이 있습니다.

그래서 "완료"를 사람의 느낌이나 AI의 "다 됐습니다"가 아니라 정해진 검사들이 판정하게 합니다.

루프 엔지니어링 — [개발 진행 방식]인데, [ "변경 → 검사 → 고침"을 반복하되, 끝났는지를 AI의 "완료했습니다" 선언이 아니라 테스트 · 평가 · 벤치마크 같은 정해진 검사가 판정하게 한다 ]는 점에서 한 번 만들고 눈으로 확인하는 방식과 구별된다. 코드를 AI에게 맡기는 이 과정에서는 특히 중요합니다.

코드 · 프롬프트 변경 ─▶ 단위 테스트 (FakeLLM, 수 초) ─▶ 평가셋 (실제 LLM, 31차시) ─▶ 통합 시나리오 (5절)
                   ─▶ 성능 측정 (22차시) ─▶ 전부 통과해야 배포

💡 CI(지속적 통합) 는 코드가 바뀔 때마다 이 검사들을 자동으로 돌리는 장치입니다. 이 줄을 CI에 올리면 사람이 잊어도 검사가 매번 돕니다. 평가셋과 통합 시나리오는 GPU가 필요하므로, GPU가 있는 서버에서 도는 별도 단계로 둡니다.

---

4. 설정과 로그

4.1 설정은 어디에

4.2 ⚠️ 로그 — 로컬 LLM을 고른 이유가 로그에서 무너진다

디버깅하려면 프롬프트와 응답을 봐야 합니다. 그런데 그 안에는 고객 이름 · 연락처 · 주소 · 주문번호 가 그대로 있습니다. 1차시에서 로컬을 고른 첫째 이유 — 데이터가 밖으로 나가지 않는다 — 가 있었는데, 이 로그를 외부 로그 수집 서비스로 보내면 LLM은 로컬인데 데이터는 밖으로 나갑니다.

PATTERNS = [(re.compile(r"01[016789]-?\d{3,4}-?\d{4}"), "<PHONE>"),
            (re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+"), "<EMAIL>"),
            (re.compile(r"\d{8}-\d{3}"), "<ORDER>")]

def mask(text: str, known_names: list[str]) -> str:
    for pat, tag in PATTERNS:
        text = pat.sub(tag, text)
    for name in known_names:                    # 29차시 추출 결과로 알게 된 고객명
        text = text.replace(name, "<NAME>")
    return text

🔍 읽는 포인트

• 전화번호 · 이메일 · 주문번호는 모양이 정해져 있어 정규식으로 잡힙니다.
• ⭐ 이름 · 주소는 정규식으로 잘 안 잡힙니다. 그래서 29차시에서 추출한 고객명 을 그 요청의 로그에서 지웁니다. 구조화 출력이 마스킹의 재료가 됩니다.
• ⚠️ 마스킹은 줄여 줄 뿐 완벽하지 않습니다. 원문 로그는 기본으로 끄고, 디버깅할 때만 짧게 켭니다.

⚠️ 앱 로그만이 아닙니다. vLLM · Ollama 서버 자체도 설정에 따라 요청 내용을 로그에 남길 수 있습니다. 관련 옵션 이름은 버전에 따라 바뀌어 왔으니 공식 문서와 실제 로그 파일로 확인 합니다.

---

5. 통합 시나리오 테스트

🔍 읽는 포인트

• 3번은 진짜 LLM으로는 재현이 어렵습니다(스키마 강제를 켜면 거의 안 깨지므로). 가짜 어댑터로 고장을 일부러 넣습니다 — 포트가 있어서 가능한 일입니다(25차시 2.4).
• 6번의 목표는 숫자로 미리 정해 둡니다. 예: "동시 10명에서 TTFT p95 < 1초" (예시 목표, 실측 아님). 숫자는 33차시 요구사항에서 정합니다.

---

6. 4일차 정리 → 5일차 예고

6.1 4일차를 세 문장으로

6.2 5일차에서 다시 만나는 곳

---

7. 실습 — 맡기고 검수하기

지시

25~31차시에서 만든 문의봇을 하나의 앱으로 통합하고 통합 시나리오 8개를 돌려줘.
- 구조: 노트 2절의 헥사고날 배치를 지킬 것. app/ 아래에서 fastapi·openai·redis·httpx import 금지
- 포트 세 개(LLMPort, OrderPort, ConversationStorePort)와 각 어댑터, 테스트용 가짜 어댑터
- 로그: 요청 ID, 프롬프트 version, 토큰 수, TTFT, finish_reason, 도구 결과는 항상 / 원문·응답은 mask() 후에만
- 시나리오 1~8은 노트 5절 표 그대로. 3번은 가짜 LLM 어댑터로 깨진 JSON 주입. 6번은 asyncio로 계정 10개 동시 실행
맥락: vLLM(또는 Ollama), FastAPI, openai 라이브러리 공식 문서 기준. 추측하지 말고 실행 출력 원문을 붙여.
보고 형식: [# | 시나리오 | 기대 결과 | 실제 결과 | 통과 여부 | 증거 위치(로그 줄·파일)] 표

받을 증거

• tree와 grep -rnE "fastapi|openai|redis|httpx" app/ 출력 ( 비어 있어야 함 )
• 시나리오 8개의 결과 표와 각각의 로그 · 응답 원문
• 마스킹 전후 로그 한 줄씩 (테스트용 가명 데이터로)
• 6번의 TTFT 중앙값 · p95 측정 출력 원문

내가 직접 볼 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 32차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"4일차 기능들의 헥사고날 배치", "합치면 깨지는 이음새", "로그 마스킹이 로컬 LLM을 고른 이유와 연결되는 지점", "통합 시나리오 8개"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.