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 토큰 인증

# 로그인
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"
}

보호된 엔드포인트 사용

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

🤖 AI 모델 관련

1. 모델 목록 조회

GET /models

응답 예시:

{
  "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. 텍스트 생성

POST /generate

요청 파라미터:

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

응답 예시:

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

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

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, ...]

응답 예시:

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

📄 문서 처리 (RAG)

1. 문서 업로드

POST /document/upload

요청 (multipart/form-data):

file: [PDF/DOC/DOCX/PPTX 파일]
user_id: "user123"

응답 예시:

{
  "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 쿼리

POST /rag/generate

요청 파라미터:

{
  "query": "인공지능의 미래에 대해 알려주세요",
  "user_id": "user123",
  "max_length": 300,
  "temperature": 0.7
}

응답 예시:

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

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

POST /rag/generate-hybrid

요청 (multipart/form-data):

query: "이 이미지와 관련된 문서 내용을 찾아주세요"
user_id: "user123"
image_files: [이미지 파일들]
max_length: 300
temperature: 0.7

💬 채팅 및 세션 관리

1. 사용자 생성

POST /user/create

요청 파라미터:

{
  "user_id": "user123",
  "username": "테스트사용자",
  "email": "test@example.com"
}

2. 채팅 세션 생성

POST /session/create

요청 파라미터:

{
  "user_id": "user123",
  "session_name": "AI 상담 세션"
}

3. 메시지 추가

POST /chat/message

요청 파라미터:

{
  "session_id": "session_123",
  "user_id": "user123",
  "message_type": "text",
  "content": "안녕하세요!"
}

4. 채팅 기록 조회

GET /chat/history/{session_id}

🔄 백그라운드 작업

1. 문서 처리 작업

POST /tasks/document/process

요청 파라미터:

{
  "file_path": "/uploads/document.pdf",
  "user_id": "user123"
}

응답 예시:

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

2. 작업 상태 확인

GET /tasks/{task_id}

응답 예시:

{
  "task_id": "task_123456",
  "status": "SUCCESS",
  "result": {
    "document_id": "doc_123456",
    "chunks": 45
  },
  "progress": 100
}

📊 모니터링

1. 성능 모니터링 시작

POST /monitoring/start

2. 성능 상태 조회

GET /monitoring/status

응답 예시:

{
  "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. 시스템 건강 상태

GET /monitoring/health

🔌 WebSocket

연결

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);
};

메시지 전송

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

🚨 오류 코드

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

📝 예제 코드

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 클라이언트

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);
    }
});

🔧 설정

환경 변수

# 서버 설정
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 문서
• Celery 문서
• Redis 문서
• LangChain 문서