Spaces:

gbrabbit
/

lily_fast_api

Sleeping

App Files Files Community

lily_fast_api / docs /API_REFERENCE.md

gbrabbit

Fresh start for HF Spaces deployment

526927a about 1 year ago

preview code

Raw History Blame Contribute Delete

10.4 kB

# 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/) 

	# 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/)