# 사용자 가이드 개선 TODO

이 문서는 사용자 가이드에서 처음 읽는 사람이 이해하기 어려울 수 있는 부분을 식별하고 개선이 필요한 영역을 나열합니다.

---

## 챕터 1: 시작하기

### 1.1 소개 및 개요
- [ ] **시각적 아키텍처 다이어그램 추가** - "세 가지 핵심 요소"를 텍스트로 설명하지만, YAML 파일, 컴포넌트, 실행 환경이 어떻게 상호작용하는지 시각적으로 표현하는 자료가 부족함
- [ ] **"docker-compose에서 영감" 부분 명확히** - docker-compose에 익숙하지 않은 사용자를 위해 구체적인 유사점/차이점을 더 명확하게 설명
- [ ] **비교 표 추가** - model-compose vs 다른 오케스트레이션 도구 비교표를 제공하여 포지셔닝 이해 돕기

### 1.3 첫 번째 워크플로우 실행
- [ ] **처음 사용 전 변수 바인딩 명확히** - `${env.OPENAI_API_KEY}`와 `${input.prompt}`가 `${}` 구문에 대한 사전 설명 없이 사용됨
- [ ] **첫 실행 시 문제 해결 추가** - 첫 실행에서 발생하는 일반적인 오류(API 키 누락, 포트 충돌 등) 포함
- [ ] **출력 구조 설명** - 예제에서 `response: ${response.choices[0].message.content}`를 보여주지만 응답 구조를 어떻게 알 수 있는지 설명하지 않음

### 1.4 기본 개념
- [ ] **워크플로우 실행 흐름 다이어그램 추가** - input → component → output이 어떻게 작동하는지 단계별로 표시

---

## 챕터 2: 핵심 개념

### 2.2 Controller
- [ ] **HTTP vs MCP 사용 시기 명확히** - 의사결정 트리 또는 비교 표 추가
- [ ] **실제 curl 명령이 포함된 엔드포인트 예제 추가** - 완전한 요청/응답 예제 표시

### 2.3 Components
- [ ] **단일 vs 다중 액션 결정 플로우차트 추가** - 사용자가 각 접근 방식을 언제 선택해야 하는지?
- [ ] **component vs action vs job 관계 설명** - 이 세 개념이 비슷해 보이지만 서로 다른 목적을 가짐
- [ ] **`${response}` vs `${output}` vs `${result}` 명확히** - 각 변수 소스를 언제 사용하는지

### 2.6 데이터 흐름 및 변수 바인딩
- [ ] **시각적 데이터 흐름 다이어그램 추가** - `${input}` → `${response}` → `${output}` → `${jobs.*.output}` 흐름 표시
- [ ] **Base64 인코딩 타이밍 설명** - 워크플로우 중 `as base64`가 언제 적용되는지?
- [ ] **미디어 타입 변환 명확히** - `${output as audio/mp3;base64}` 디코딩이 어떻게 작동하는지?

---

## 챕터 3: CLI 사용법

### 3.2 up 명령
- [ ] **"detached mode" 더 잘 설명** - 백그라운드 실행 외에 동작의 차이점은?
- [ ] **프로세스 모니터링 예제 추가** - detached 모드에서 서비스가 실행 중인지 확인하는 방법?

### 3.4 start 명령
- [ ] **"이미 구성된 서비스" 명확히** - 이 구성을 생성하는 것은 무엇인가? `up` vs `start`는 언제 적용되는가?
- [ ] **상태 다이어그램 추가** - 서비스 라이프사이클 표시 (stopped → configured → started)

---

## 챕터 4: 컴포넌트 구성

### 4.1 컴포넌트 타입
- [ ] **의사결정 트리 추가** - 사용자가 자신의 유스케이스에 적합한 컴포넌트 타입을 선택하도록 돕기
- [ ] **컴포넌트 타입 감지 설명** - 시스템이 어떤 드라이버를 사용할지 어떻게 아는가?

### 4.3 입/출력 매핑
- [ ] **배열 인덱싱 명확히** - `${response.data[0].id}`가 어떻게 작동하는가? 배열이 비어있으면?
- [ ] **객체 배열 변환 설명** - `${response.users as object[]/id,name}` 구문에 더 많은 설명 필요
- [ ] **오류 처리 예제 추가** - 매핑된 경로가 존재하지 않을 때 어떻게 되는가?

---

## 챕터 5: 워크플로우 작성

### 5.4 Job 타입
- [ ] **job 타입 결정 플로우차트 추가** - action vs if vs switch vs delay를 언제 사용하는가
- [ ] **random-router 가중치 계산 설명** - 가중치가 확률로 어떻게 변환되는가?
- [ ] **if vs switch 사용 명확히** - 언제 하나를 선택하는가?

### 5.5 조건부 실행
- [ ] **더 많은 연산자 예제 추가** - 모든 연산자 (eq, neq, gt, gte, lt, lte, in, not-in, starts-with, ends-with, match)를 예제와 함께 표시
- [ ] **다중 조건 평가 설명** - `if` job의 여러 조건이 어떻게 처리되는가?

### 5.6 스트리밍 모드
- [ ] **스트리밍 감지 명확히** - 시스템이 스트리밍을 사용해야 하는지 어떻게 아는가?
- [ ] **`${response[]}` vs `${response}` 설명** - `[]` 구문이 설명 없이 갑자기 나타남
- [ ] **클라이언트 측 스트리밍 예제 추가** - 챕터 11 참조는 읽기 흐름을 끊음

### 5.7 오류 처리
- [ ] **완전한 오류 처리 예제 추가** - retry + fallback + 오류 로깅을 함께 표시
- [ ] **`on_error: continue` 설명** - 이것이 설정되면 워크플로우에 어떤 일이 발생하는가?
- [ ] **오류 객체 구조 명확히** - `${jobs.*.error}`에서 사용 가능한 필드는?

---

## 챕터 6: Controller 구성

### 6.1 HTTP 서버
- [ ] **태스크 큐 동작 명확히** - `wait_for_completion: false`와 태스크 폴링이 어떻게 작동하는가?
- [ ] **태스크 캐싱 기간 설명** - "1시간 동안" 캐시된 태스크 - 그 후에는?
- [ ] **동기 vs 비동기 결정 가이드 추가** - 각 실행 모드를 언제 사용하는가?

### 6.2 MCP 서버
- [ ] **Streamable HTTP 프로토콜 더 잘 설명** - HTTP+SSE와의 주요 차이점은?
- [ ] **MCP 워크플로우 예제 추가** - Claude Desktop 통합과 함께 완전한 예제 표시
- [ ] **양방향 통신 명확히** - 서버가 무엇을 시작할 수 있는가?

### 6.3 동시성 제어
- [ ] **controller vs component 동시성 설명** - 두 제한이 어떻게 상호작용하는가?
- [ ] **동시성 튜닝 가이드 추가** - 적절한 값을 어떻게 결정하는가?
- [ ] **큐 동작 명확히** - 큐 순서는? FIFO? 우선순위?

---

## 챕터 7: Web UI 구성

### 7.1 Web UI 개요
- [ ] **포트 분리 요구 사항 설명** - Web UI가 다른 포트에서 실행되어야 하는 이유는?
- [ ] **Web UI → Controller 통신 명확히** - Web UI가 controller API를 어떻게 호출하는가?

### 7.2 Gradio 드라이버
- [ ] **UI 컴포넌트 매핑 테이블 추가** - 모든 input/output 타입을 Gradio 컴포넌트로 매핑 표시
- [ ] **Gradio에서 스트리밍 설명** - `sse-text` vs `sse-json`이 어떻게 다르게 렌더링되는가?

---

## 챕터 8: 로컬 AI 모델 작업

### 8.1 로컬 모델 개요
- [ ] **드라이버 선택 가이드 추가** - huggingface vs unsloth vs vllm vs llamacpp를 언제 사용하는가?
- [ ] **형식 호환성 설명** - 어떤 형식이 어떤 드라이버와 작동하는가?
- [ ] **하드웨어 요구 사항 테이블 추가** - 다양한 모델에 대한 GPU 메모리, CPU, 디스크 공간

### 8.2 모델 설치 및 설정
- [ ] **경로 인식 규칙 명확히** - 자동 감지 로직에 더 명확한 예제 필요
- [ ] **revision vs filename 설명** - 각 옵션을 언제 사용하는가?
- [ ] **캐시 관리 섹션 추가** - 캐시 지우기, 캐시 위치 변경 등

### 8.3 지원되는 태스크 타입
- [ ] **태스크 선택 가이드 추가** - 사용자가 올바른 태스크 타입을 선택하도록 돕기
- [ ] **architecture 필드 설명** - 필수인 경우 vs 선택인 경우?
- [ ] **각 태스크에 대한 입/출력 명확히** - 모든 태스크 타입에 대한 완전한 스키마

### 8.4 모델 구성
- [ ] **정밀도 선택 가이드 추가** - float32 vs float16 vs bfloat16에 대한 의사결정 트리
- [ ] **양자화 영향 설명** - 메모리 절약 vs 품질 트레이드오프 테이블
- [ ] **device_mode: auto 명확히** - GPU 분산이 어떻게 작동하는가?

### 8.6 모델 서빙 프레임워크
- [ ] **컴포넌트 타입 혼동 명확히** - vLLM에 `model` 대신 `http-server`를 사용하는 이유는?
- [ ] **`manage.install` vs `manage.start` 설명** - 각각 언제 실행되는가?
- [ ] **구체적인 예제로 프레임워크 비교 추가** - 다양한 프레임워크에서 동일한 모델 표시

---

## 챕터 9: 모델 학습

**참고**: 챕터 9를 파일에서 찾을 수 없습니다. 이 섹션은:
- [ ] **완전히 누락됨** - 학습 문서 생성 필요
- [ ] **또는 다른 곳에 위치** - 파일 구조 확인

---

## 챕터 10: 외부 서비스 통합

### 10.1 OpenAI API
- [ ] **스트리밍 채팅 예제 추가** - 완전한 스트리밍 구성 표시
- [ ] **응답 구조 변형 설명** - 다른 모델은 다른 응답 형식을 가질 수 있음

### 10.5 Stability AI
- [ ] **aspect_ratio 형식 명확히** - 각 비율의 시각적 표현 표시

### 10.6 Replicate
- [ ] **비동기 폴링 패턴 설명** - 예제는 prediction_id를 보여주지만 폴링 워크플로우는 없음
- [ ] **완전한 비동기 워크플로우 예제 추가** - 요청 → 폴링 → 결과 패턴 표시

### 10.8 모범 사례
- [ ] **속도 제한 구현 추가** - `rate_limit` 필드가 사전 문서 없이 나타남
- [ ] **캐시 구현 설명** - `cache.enabled`가 어떻게 작동하는가?

---

## 챕터 11: 스트리밍 모드

### 11.1 스트리밍 개요
- [ ] **프로토콜 다이어그램 추가** - SSE 메시지 형식을 시각적으로 표시
- [ ] **청크 vs 완전한 응답 명확히** - 스트리밍 vs 비스트리밍을 언제 사용하는가

### 11.2 컴포넌트별 스트리밍
- [ ] **`${result[]}` vs `${response[]}` 설명** - 다양한 컴포넌트에서 각각 언제 사용하는가
- [ ] **batch_size 제약 명확히** - 스트리밍 중 batch_size가 1이어야 하는 이유는?
- [ ] **stream_format 감지 추가** - HTTP 컴포넌트에서 자동 감지가 어떻게 작동하는가?

### 11.3 워크플로우에서 스트리밍 사용
- [ ] **"마지막 job만 스트리밍 가능" 명확히** - 이 제약을 보여주는 다이어그램 추가
- [ ] **여러 단계 스트리밍 제한 설명** - 중간 job이 스트리밍할 수 없는 이유는?

### 11.4 스트리밍 응답 처리
- [ ] **스트리밍에 대한 오류 처리 추가** - 스트림이 중단되면 어떻게 되는가?
- [ ] **SSE 파싱 세부 사항 설명** - 모든 필드가 포함된 완전한 이벤트 형식 표시

---

## 챕터 12: 변수 바인딩

### 12.1 기본 구문
- [ ] **완전한 구문 railroad 다이어그램 추가** - 가능한 모든 구문 조합 표시
- [ ] **평가 순서 설명** - 변환이 언제 적용되는가?

### 12.2 키 참조
- [ ] **`${result[0]}` 사용 명확히** - 특정 인덱스 vs `${result[]}`를 언제/왜 사용하는가?
- [ ] **컨텍스트 변수 설명** - `${context}`에서 사용 가능한 필드는?

### 12.3 타입 변환
- [ ] **변환 실패 처리 추가** - 변환이 실패하면 어떻게 되는가?
- [ ] **객체 배열 변환 설명** - 중첩된 경로가 있는 더 복잡한 예제 표시
- [ ] **미디어 타입 감지 명확히** - `as image`가 형식을 어떻게 감지하는가?

### 12.5 기본값
- [ ] **우선순위 규칙 추가** - 중첩된 기본값에서 어떻게 되는가?
- [ ] **리터럴 타입 추론 설명** - 기본값 타입이 어떻게 결정되는가?

### 12.6 주석
- [ ] **완전한 MCP 예제 표시** - 주석 및 MCP 클라이언트 사용이 포함된 전체 워크플로우
- [ ] **MCP 외부에서 주석 사용 설명** - 주석이 다른 곳에서 사용되는가?

### 12.7 UI 타입 힌트
- [ ] **모든 UI 힌트 타입 추가** - 예제가 포함된 완전한 목록
- [ ] **힌트 vs 자동 감지 설명** - 힌트가 필수인 경우 vs 선택인 경우?

---

## 챕터 13: 시스템 통합

### 13.1 Listeners
- [ ] **완전한 콜백 라이프사이클 다이어그램 추가** - 요청 → 대기 → 콜백 → 결과 흐름 표시
- [ ] **태스크 식별 설명** - `identify_by` 매칭이 어떻게 작동하는가?
- [ ] **대량 처리 명확히** - 여러 항목이 있는 완전한 예제 표시

### 13.1.7 Listeners 작동 방식
- [ ] **`${context.run_id}` 생성 설명** - run_id가 어떻게/언제 생성되는가?
- [ ] **listener 타임아웃 명확히** - 기본값은? 구성 방법은?

### 13.2 Gateways
- [ ] **gateway 선택 가이드 추가** - ngrok vs cloudflare vs SSH를 언제 사용하는가?
- [ ] **`${gateway:port.public_url}` 구문 설명** - 사용 가능한 모든 gateway 변수 표시
- [ ] **포트 지정 명확히** - gateway가 포트를 알아야 하는 이유는?

### 13.3 Listeners와 Gateways 함께 사용
- [ ] **문제 해결 섹션 추가** - 외부 웹훅의 일반적인 문제
- [ ] **프로덕션 마이그레이션 설명** - gateway에서 공개 URL로 이동하는 방법은?

---

## 챕터 14: 배포

### 14.1 로컬 실행
- [ ] **중지 메커니즘 설명** - `.stop` 파일 감지가 어떻게 작동하는가?
- [ ] **환경 변수 우선순위 명확히** - 완전한 우선순위 테이블

### 14.2 Docker 런타임
- [ ] **완전한 Docker 옵션 참조 추가** - 모든 사용 가능한 필드를 한 곳에
- [ ] **자동 빌드 프로세스 설명** - 어떤 파일이 복사되는가? 디렉토리 구조는?
- [ ] **runtime: docker (문자열) 확장 명확히** - 완전히 확장된 YAML 표시

### 14.3 Docker 컨테이너 빌드
- [ ] **기본 Dockerfile 생성 설명** - 언제/어떻게 생성되는가?
- [ ] **사용자 정의 Dockerfile 가이드 추가** - 프로젝트별 이미지 생성 모범 사례
- [ ] **빌드 컨텍스트 명확히** - 어떤 파일이 포함/제외되는가?

### 14.4 프로덕션 환경 고려 사항
- [ ] **프로덕션 배포 체크리스트 추가** - 프로덕션 설정의 완전한 목록
- [ ] **healthcheck 구성 설명** - 예제가 포함된 모든 사용 가능한 옵션

### 14.5 모니터링 및 로깅
- [ ] **완전한 로깅 전략 가이드 추가** - 개발 vs 스테이징 vs 프로덕션
- [ ] **메트릭 수집 설명** - Prometheus/Grafana와 통합하는 방법

---

## 챕터 15: 실용적인 예제

### 15.1 챗봇 구축
- [ ] **대화 기록 예제 추가** - 채팅 컨텍스트를 유지하는 방법은?
- [ ] **메시지 형식 차이 설명** - 지원되는 모든 role 타입 표시

### 15.4 RAG 시스템
- [ ] **문서 수집 워크플로우 추가** - vector DB를 채우는 방법은?
- [ ] **컬렉션 관리 설명** - 컬렉션 생성, 업데이트, 삭제
- [ ] **임베딩 차원 설명 추가** - 호환성을 보장하는 방법은?

### 15.5 Slack 봇
- [ ] **자동 응답 예제 완성** - listener 콜백 구성이 불완전함
- [ ] **Slack 앱 설정 가이드 추가** - 단계별 지침

---

## 챕터 16: 문제 해결

### 16.1 FAQ
- [ ] **버전 호환성 매트릭스 추가** - Python 버전, 패키지 버전, OS 지원
- [ ] **알려진 문제 섹션 포함** - 현재 제한 사항 및 해결 방법

### 16.2 일반적인 오류
- [ ] **오류 코드 참조 추가** - 시스템이 오류 코드를 사용하는 경우 모두 나열
- [ ] **스택 트레이스 해석 포함** - model-compose 오류를 읽는 방법

### 16.3 디버깅 팁
- [ ] **성능 프로파일링 가이드 추가** - 병목 현상을 식별하는 방법
- [ ] **메모리 누수 감지 포함** - 도구 및 기법

---

## 챕터 17: 부록

### 17.1 완전한 구성 파일 스키마
- [ ] **JSON 스키마 내보내기 추가** - 유효성 검사를 위한 기계 판독 가능한 스키마 제공
- [ ] **모든 스키마 섹션에 대한 예제 포함** - 참조용 완전한 예제
- [ ] **스키마 유효성 검사 도구 추가** - 실행 전 YAML을 유효성 검사하는 방법

---

## 범주 간 개선 사항

### 일반적인 문서 문제

1. **용어 일관성**
   - [ ] 용어 사전 생성 (component, action, job, workflow 등)
   - [ ] 모든 챕터에서 일관된 사용 보장
   - [ ] 처음 사용 시 용어 정의 추가

2. **탐색 개선**
   - [ ] 각 챕터에 "전제 조건" 섹션 추가
   - [ ] "관련 섹션" 링크 포함
   - [ ] 일반적인 패턴에 대한 빠른 참조 카드 추가

3. **예제 향상**
   - [ ] 완전히 작동하는 예제가 포함된 "직접 해보기" 섹션 추가
   - [ ] 모든 예제에 대한 예상 출력 포함
   - [ ] 예제 변형 추가 (성공 사례, 오류 사례, 엣지 케이스)

4. **시각적 보조 자료**
   - [ ] 복잡한 흐름에 대한 아키텍처 다이어그램 추가
   - [ ] 비동기 작업에 대한 시퀀스 다이어그램 포함
   - [ ] 구성 선택을 위한 의사결정 트리 생성
   - [ ] 문제 해결을 위한 플로우차트 추가

5. **초보자 친화적 추가 사항**
   - [ ] "일반적인 함정" 섹션 추가
   - [ ] 일반적인 유스케이스에 대한 "빠른 시작" 템플릿 포함
   - [ ] "처음부터" 튜토리얼 생성
   - [ ] 비디오 튜토리얼 링크 추가 (사용 가능한 경우)

6. **고급 주제**
   - [ ] 성능 튜닝 가이드 추가
   - [ ] 보안 모범 사례 포함
   - [ ] 스케일링 가이드 생성 (수평/수직)
   - [ ] 사용자 정의 컴포넌트 개발 가이드 추가

7. **누락된 챕터/섹션**
   - [ ] 챕터 9 (모델 학습)이 누락된 것으로 보임
   - [ ] 이미지 처리 가이드가 나열되어 있지만 상세하지 않음
   - [ ] API 참조 문서가 확장 필요할 수 있음

---

## 우선순위 레벨

### 높은 우선순위 (신규 사용자에게 차단 요소)
- 변수 바인딩 설명 (설명 전에 사용됨)
- Component vs Job vs Action 관계
- 스트리밍 구문 (`${}` vs `${}[]`)
- 오류 처리 패턴
- 기본 문제 해결 가이드

### 중간 우선순위 (이해도 향상)
- 아키텍처 다이어그램
- 각 기능에 대한 완전한 예제
- 구성을 위한 의사결정 트리
- FAQ 확장

### 낮은 우선순위 (있으면 좋음)
- 고급 튜닝 가이드
- 비디오 튜토리얼
- JSON 스키마 내보내기
- IDE 통합 가이드

---

## 참고 사항

- 많은 예제가 설명되기 전에 기능을 사용함 (특히 변수 바인딩)
- "SSE", "MCP", "LoRA"와 같은 기술 개념에는 용어 사전 항목이 필요함
- controller, component, workflow, job 간의 관계가 더 명확할 수 있음
- 더 많은 시각적 다이어그램이 복잡한 흐름 이해에 크게 도움이 될 것임
- 오류 메시지 및 디버깅 지침이 확장 필요
