---
template: plan
version: 1.3
feature: phase17-multimodal
date: 2026-06-02
author: sal
project: youlbot
status: Draft
---

# phase17-multimodal Planning Document

> **Summary**: analyze_image 도구 방식으로 이미지 이해 기능을 추가한다.
> Qwen3-8B가 대화를 유지하고, 이미지 첨부 시 Qwen2.5-VL-7B를 도구로 호출해 설명을 얻은 뒤 답변한다.
>
> **Project**: youlbot
> **Author**: sal
> **Date**: 2026-06-02
> **Status**: Draft

---

## Executive Summary

| Perspective | Content |
|-------------|---------|
| **Problem** | 이유식 사진·금융 서류 등 이미지를 텍스트로만 처리하는 현재 한계 |
| **Solution** | Qwen2.5-VL-7B를 `analyze_image` LangChain 도구로 래핑, Qwen3-8B가 필요 시 자동 호출 |
| **Function/UX Effect** | 채팅창에 이미지 첨부 → 자동 분석 → 육아·금융 상담으로 자연스럽게 연결 |
| **Core Value** | 텍스트 추론 품질(Qwen3-8B)을 유지하면서 이미지 이해 기능 추가 |

---

## Context Anchor

| Key | Value |
|-----|-------|
| **WHY** | 손이 자유롭지 않은 육아 상황에서 사진 한 장으로 재료 분석·서류 해석이 가능해야 함 |
| **WHO** | 아록(주 사용자) — 이유식 사진, 건강보험 서류, 접종 기록지 등 촬영 후 질문 |
| **RISK** | 16GB 메모리에서 두 모델 동시 로드 시 OOM 가능 → Vision 모델 lazy load로 완화 |
| **SUCCESS** | 이미지 첨부 → analyze_image 도구 자동 호출 → 설명이 대화 히스토리에 남아 후속 질문 가능 |
| **SCOPE** | 이미지 분석 + 채팅 연동. 동영상·실시간 캡처는 제외 |

---

## 1. Overview

### 1.1 Purpose
사진을 첨부하면 `analyze_image` 도구가 Qwen2.5-VL-7B를 호출해 이미지 설명을 생성하고,
Qwen3-8B가 그 설명을 컨텍스트로 삼아 육아·금융 상담 답변을 제공한다.

### 1.2 모델 분담

| 모델 | 역할 | 메모리 |
|------|------|--------|
| Qwen3-8B-4bit | 대화·추론·도구 결정 (항상 로드) | ~5GB |
| Qwen2.5-VL-7B-Instruct-4bit | 이미지 분석 (lazy load) | ~5GB |
| 합계 | — | ~10GB / 16GB 사용 가능 |

---

## 2. Scope

### 2.1 In Scope
- `mlx-vlm` 패키지로 Vision 모델 로드 및 추론
- `analyze_image(image_path, prompt)` LangChain 도구 구현
- AgentService: 요청에 이미지 있을 때 도구 동적 주입
- API(`/chat`): 이미지 파일 업로드 지원 (multipart form)
- WebUI: 채팅 입력창에 이미지 첨부 버튼 추가
- Telegram: 사진 메시지 수신 → 이미지 다운로드 → API 전달

### 2.2 Out of Scope
- 동영상 분석
- 이미지 생성(text-to-image)
- 실시간 카메라 입력

---

## 3. Architecture — C방식 (analyze_image 도구)

```
사용자
  │  텍스트 + 이미지(선택)
  ▼
API /chat  (multipart form)
  │  image → /tmp/youlbot_img_xxx.jpg 저장
  │  image_path → AgentService.stream_response(message, image_path=...)
  ▼
AgentService
  │  image_path 있을 때: analyze_image 도구를 tools 목록에 동적 추가
  │  image_path를 도구 클로저로 바인딩
  ▼
LangGraph ReAct
  │  Qwen3-8B가 이미지 관련 질문 감지 → analyze_image() 자동 호출
  ▼
analyze_image 도구
  │  mlx_vision_model.analyze(image_path, prompt)
  ▼
MlxVisionModel (Qwen2.5-VL-7B, lazy load)
  │  이미지 설명 텍스트 반환
  ▼
LangGraph
  │  설명이 ToolMessage로 대화 히스토리에 저장
  ▼
Qwen3-8B  →  최종 답변 생성
```

**핵심 특성:**
- Vision 모델은 처음 analyze_image 호출 시 로드 (이후 캐시)
- 이미지 설명이 대화 히스토리에 남아 후속 질문("그 재료로 이유식 만들어줘") 가능
- 이미지 없는 메시지는 기존과 완전히 동일하게 동작

---

## 4. 변경 파일 목록

### 신규 생성
| 파일 | 설명 |
|------|------|
| `services/model/mlx_vision_model.py` | MlxVisionModel 클래스 (mlx-vlm 래퍼, lazy load) |

### 수정
| 파일 | 변경 내용 |
|------|----------|
| `config.py` | `vision_enabled: bool`, `vision_model_id: str` 추가 |
| `container.py` | `vision_model` Singleton 프로바이더 추가 |
| `services/agent/tools.py` | `make_vision_tool(vision_model, image_path)` 추가 |
| `services/agent/agent_service.py` | `stream_response(image_path=None)` 파라미터 추가, 도구 동적 주입 |
| `api.py` | `/chat` → multipart form으로 변경, 이미지 temp 저장 |
| `youlbot-webui/api_client.py` | `chat(image_path=None)` 파라미터 추가, multipart 전송 |
| `youlbot-webui/app.py` | 채팅 입력 영역에 이미지 업로드 컴포넌트 추가 |

---

## 5. 주요 구현 세부사항

### 5.1 MlxVisionModel
```python
class MlxVisionModel:
    def __init__(self, model_id: str): ...
    
    def analyze(self, image_path: str, prompt: str = "이 이미지를 한국어로 자세히 설명해줘.") -> str:
        # 첫 호출 시 lazy load
        # mlx_vlm.generate() 호출
        # 한국어 설명 반환
```

### 5.2 make_vision_tool
```python
def make_vision_tool(vision_model, image_path: str):
    @tool
    def analyze_image(prompt: str = "이 이미지를 설명해줘") -> str:
        """현재 첨부된 이미지를 분석한다."""
        return vision_model.analyze(image_path, prompt)
    return analyze_image
```

### 5.3 API /chat 변경
- JSON Body → `multipart/form-data`
- 필드: `message`, `user_id`, `show_thinking`, `image` (optional file)
- 이미지를 `/tmp/youlbot_img_{uuid}.{ext}`에 저장 후 agent에 전달
- 응답 완료 후 temp 파일 삭제

### 5.4 WebUI 변경
- `gr.Image(type="filepath", ...)` 컴포넌트 채팅 입력 영역에 추가
- 이미지 첨부 시 api_client.chat()에 image_path 전달
- 전송 후 이미지 초기화

---

## 6. 환경 설정

```env
# .env 추가
VISION_ENABLED=true
VISION_MODEL_ID=mlx-community/Qwen2.5-VL-7B-Instruct-4bit
```

```bash
# 패키지 설치
pip install mlx-vlm
```

---

## 7. 위험 요소 및 대응

| 위험 | 대응 |
|------|------|
| 16GB에서 두 모델 동시 OOM | Vision 모델 lazy load + 미사용 시 unload 옵션 제공 |
| mlx-vlm API 변경 가능성 | MlxVisionModel로 캡슐화해 교체 용이하게 |
| Telegram 이미지 전달 복잡성 | Phase 17-B로 분리, 우선 WebUI만 구현 |
| 이미지 temp 파일 누적 | 응답 완료 후 즉시 삭제 |

---

## 8. 성공 기준

- [ ] 이미지 첨부 시 `analyze_image` 도구가 자동 호출되어 설명 생성
- [ ] "이 사진에서 뭐가 보여?" 후속 질문이 히스토리 기반으로 동작
- [ ] 이미지 없는 일반 질문은 기존과 동일하게 Qwen3-8B로 처리
- [ ] 16GB 환경에서 OOM 없이 동작