docs/API_REFERENCE.md

# Lily LLM API 참조 문서

## 📋 개요

Lily LLM API는 다양한 언어 모델을 지원하는 RESTful API 서버입니다. 텍스트 생성, 멀티모달 처리, RAG(Retrieval-Augmented Generation) 기능을 제공합니다.

## 🔗 기본 정보

- **Base URL**: `http://localhost:8001`
- **API 문서**: `http://localhost:8001/docs`
- **ReDoc 문서**: `http://localhost:8001/redoc`

## 🔐 인증

### JWT 토큰 인증

```bash
# 로그인
curl -X POST "http://localhost:8001/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your_username&password=your_password"

# 응답
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer"
}
```

### 보호된 엔드포인트 사용

```bash
curl -X GET "http://localhost:8001/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## 🤖 AI 모델 관련

### 1. 모델 목록 조회

```http
GET /models
```

**응답 예시:**
```json
{
  "available_models": [
    {
      "model_id": "polyglot-ko-1.3b-chat",
      "display_name": "Polyglot Korean 1.3B Chat",
      "model_type": "text",
      "description": "한국어 특화 텍스트 생성 모델"
    },
    {
      "model_id": "kanana-1.5-v-3b-instruct",
      "display_name": "Kanana 1.5 v3B Instruct",
      "model_type": "multimodal",
      "description": "멀티모달 이미지+텍스트 처리 모델"
    }
  ],
  "current_model": "polyglot-ko-1.3b-chat"
}
```

### 2. 텍스트 생성

```http
POST /generate
```

**요청 파라미터:**
```json
{
  "prompt": "안녕하세요, AI에 대해 설명해주세요.",
  "model_id": "polyglot-ko-1.3b-chat",
  "max_length": 200,
  "temperature": 0.7,
  "top_p": 0.9,
  "do_sample": true
}
```

**응답 예시:**
```json
{
  "generated_text": "안녕하세요! AI(인공지능)는 인간의 학습능력과 추론능력을 인공적으로 구현한 컴퓨터 시스템입니다...",
  "model_name": "polyglot-ko-1.3b-chat",
  "processing_time": 2.34,
  "tokens_generated": 45
}
```

### 3. 멀티모달 생성 (이미지 + 텍스트)

```http
POST /generate-multimodal
```

**요청 (multipart/form-data):**
```
prompt: "이 이미지에 대해 설명해주세요"
model_id: "kanana-1.5-v-3b-instruct"
max_length: 200
temperature: 0.7
image_files: [파일1, 파일2, ...]
```

**응답 예시:**
```json
{
  "generated_text": "이 이미지는 아름다운 자연 풍경을 보여줍니다...",
  "model_name": "kanana-1.5-v-3b-instruct",
  "processing_time": 15.67,
  "images_processed": 2
}
```

## 📄 문서 처리 (RAG)

### 1. 문서 업로드

```http
POST /document/upload
```

**요청 (multipart/form-data):**
```
file: [PDF/DOC/DOCX/PPTX 파일]
user_id: "user123"
```

**응답 예시:**
```json
{
  "document_id": "doc_123456",
  "filename": "sample.pdf",
  "file_type": "pdf",
  "file_size": 1024000,
  "pages": 15,
  "chunks": 45,
  "upload_time": "2025-08-04T10:30:00Z"
}
```

### 2. RAG 쿼리

```http
POST /rag/generate
```

**요청 파라미터:**
```json
{
  "query": "인공지능의 미래에 대해 알려주세요",
  "user_id": "user123",
  "max_length": 300,
  "temperature": 0.7
}
```

**응답 예시:**
```json
{
  "response": "인공지능의 미래는 매우 밝습니다. 현재 문서에 따르면...",
  "sources": [
    {
      "document_id": "doc_123456",
      "page": 5,
      "chunk": "AI 기술의 발전 방향..."
    }
  ],
  "confidence": 0.85,
  "processing_time": 3.45
}
```

### 3. 하이브리드 RAG (이미지 + 문서)

```http
POST /rag/generate-hybrid
```

**요청 (multipart/form-data):**
```
query: "이 이미지와 관련된 문서 내용을 찾아주세요"
user_id: "user123"
image_files: [이미지 파일들]
max_length: 300
temperature: 0.7
```

## 💬 채팅 및 세션 관리

### 1. 사용자 생성

```http
POST /user/create
```

**요청 파라미터:**
```json
{
  "user_id": "user123",
  "username": "테스트사용자",
  "email": "test@example.com"
}
```

### 2. 채팅 세션 생성

```http
POST /session/create
```

**요청 파라미터:**
```json
{
  "user_id": "user123",
  "session_name": "AI 상담 세션"
}
```

### 3. 메시지 추가

```http
POST /chat/message
```

**요청 파라미터:**
```json
{
  "session_id": "session_123",
  "user_id": "user123",
  "message_type": "text",
  "content": "안녕하세요!"
}
```

### 4. 채팅 기록 조회

```http
GET /chat/history/{session_id}
```

## 🔄 백그라운드 작업

### 1. 문서 처리 작업

```http
POST /tasks/document/process
```

**요청 파라미터:**
```json
{
  "file_path": "/uploads/document.pdf",
  "user_id": "user123"
}
```

**응답 예시:**
```json
{
  "task_id": "task_123456",
  "status": "PENDING",
  "message": "문서 처리 작업이 시작되었습니다."
}
```

### 2. 작업 상태 확인

```http
GET /tasks/{task_id}
```

**응답 예시:**
```json
{
  "task_id": "task_123456",
  "status": "SUCCESS",
  "result": {
    "document_id": "doc_123456",
    "chunks": 45
  },
  "progress": 100
}
```

## 📊 모니터링

### 1. 성능 모니터링 시작

```http
POST /monitoring/start
```

### 2. 성능 상태 조회

```http
GET /monitoring/status
```

**응답 예시:**
```json
{
  "current_metrics": {
    "cpu_percent": 25.5,
    "memory_percent": 68.2,
    "memory_used_mb": 8192.0,
    "disk_usage_percent": 45.0
  },
  "performance_stats": {
    "avg_response_time": 1.23,
    "avg_inference_time": 2.45,
    "total_requests": 1250,
    "success_rate": 98.5
  },
  "system_health": {
    "status": "healthy",
    "recommendations": []
  }
}
```

### 3. 시스템 건강 상태

```http
GET /monitoring/health
```

## 🔌 WebSocket

### 연결

```javascript
const ws = new WebSocket('ws://localhost:8001/ws/user123');

ws.onopen = function() {
    console.log('WebSocket 연결됨');
};

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('메시지 수신:', data);
};
```

### 메시지 전송

```javascript
ws.send(JSON.stringify({
    type: 'chat',
    message: '안녕하세요!',
    session_id: 'session_123'
}));
```

## 🚨 오류 코드

| 코드 | 의미 | 해결 방법 |
|------|------|-----------|
| 400 | 잘못된 요청 | 요청 파라미터 확인 |
| 401 | 인증 실패 | 토큰 확인 |
| 403 | 권한 없음 | 권한 확인 |
| 404 | 리소스 없음 | URL 확인 |
| 422 | 검증 실패 | 요청 데이터 형식 확인 |
| 500 | 서버 오류 | 서버 로그 확인 |
| 503 | 서비스 불가 | 서비스 상태 확인 |

## 📝 예제 코드

### Python 클라이언트

```python
import requests
import json

class LilyLLMClient:
    def __init__(self, base_url="http://localhost:8001"):
        self.base_url = base_url
        self.token = None
    
    def login(self, username, password):
        response = requests.post(f"{self.base_url}/auth/login", 
                               data={"username": username, "password": password})
        if response.status_code == 200:
            self.token = response.json()["access_token"]
            return True
        return False
    
    def generate_text(self, prompt, model_id="polyglot-ko-1.3b-chat"):
        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
        data = {
            "prompt": prompt,
            "model_id": model_id,
            "max_length": 200,
            "temperature": 0.7
        }
        response = requests.post(f"{self.base_url}/generate", 
                               data=data, headers=headers)
        return response.json()
    
    def upload_document(self, file_path, user_id):
        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
        with open(file_path, 'rb') as f:
            files = {'file': f}
            data = {'user_id': user_id}
            response = requests.post(f"{self.base_url}/document/upload", 
                                   files=files, data=data, headers=headers)
        return response.json()

# 사용 예제
client = LilyLLMClient()
if client.login("username", "password"):
    result = client.generate_text("안녕하세요!")
    print(result["generated_text"])
```

### JavaScript 클라이언트

```javascript
class LilyLLMClient {
    constructor(baseUrl = 'http://localhost:8001') {
        this.baseUrl = baseUrl;
        this.token = null;
    }
    
    async login(username, password) {
        const response = await fetch(`${this.baseUrl}/auth/login`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
            },
            body: `username=${username}&password=${password}`
        });
        
        if (response.ok) {
            const data = await response.json();
            this.token = data.access_token;
            return true;
        }
        return false;
    }
    
    async generateText(prompt, modelId = 'polyglot-ko-1.3b-chat') {
        const headers = this.token ? 
            {'Authorization': `Bearer ${this.token}`} : {};
        
        const formData = new FormData();
        formData.append('prompt', prompt);
        formData.append('model_id', modelId);
        formData.append('max_length', '200');
        formData.append('temperature', '0.7');
        
        const response = await fetch(`${this.baseUrl}/generate`, {
            method: 'POST',
            headers,
            body: formData
        });
        
        return await response.json();
    }
}

// 사용 예제
const client = new LilyLLMClient();
client.login('username', 'password').then(async (success) => {
    if (success) {
        const result = await client.generateText('안녕하세요!');
        console.log(result.generated_text);
    }
});
```

## 🔧 설정

### 환경 변수

```bash
# 서버 설정
HOST=0.0.0.0
PORT=8001
LOG_LEVEL=INFO

# 데이터베이스
DATABASE_URL=sqlite:///app/data/lily_llm.db

# Redis
REDIS_URL=redis://localhost:6379

# Celery
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# 보안
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret-key
```

## 📚 추가 리소스

- [FastAPI 문서](https://fastapi.tiangolo.com/)
- [Celery 문서](https://docs.celeryproject.org/)
- [Redis 문서](https://redis.io/documentation)
- [LangChain 문서](https://python.langchain.com/)