505 lines
13 KiB
Markdown
505 lines
13 KiB
Markdown
# 엔큐톡 (ncuetalk) - 다목적 AI 채팅 플랫폼
|
|
|
|
엔큐톡은 다양한 AI 도구들을 통합한 웹 기반 채팅 플랫폼입니다. ChatGPT, 문서 분석, 번역, 연구 질의응답 등 여러 AI 서비스를 하나의 통합 인터페이스에서 제공합니다.
|
|
|
|
## 📋 목차
|
|
|
|
- [주요 기능](#주요-기능)
|
|
- [프로젝트 구조](#프로젝트-구조)
|
|
- [설치 및 실행](#설치-및-실행)
|
|
- [도구별 상세 가이드](#도구별-상세-가이드)
|
|
- [API 문서](#api-문서)
|
|
- [개발 가이드](#개발-가이드)
|
|
|
|
## 🚀 주요 기능
|
|
|
|
### 🔧 통합 AI 도구 플랫폼
|
|
- **6개의 전문 AI 도구** 통합 제공
|
|
- **통일된 채팅 인터페이스**로 일관된 사용자 경험
|
|
- **세션 관리** 및 **대화 기록** 저장
|
|
- **파일 업로드 및 처리** 기능
|
|
|
|
### 🎯 지원 도구 목록
|
|
|
|
| 도구 | 기능 | 특징 |
|
|
|------|------|--------------------------|
|
|
| **ChatGPT** | OpenAI 모델 대화 | GPT-5 등 다중 모델 지원 |
|
|
| **GxP 챗봇** | GxP 문서 질의응답 | 벡터 DB 기반 문서 검색 |
|
|
| **개발챗봇** | PDF 문서 분석 | PDF 업로드, 벡터 검색, 지식베이스 모드 |
|
|
| **문서번역** | 한영 번역 서비스 | Word 문서 + 실시간 텍스트 번역 |
|
|
| **연구QA** | 연구 질의응답 | 외부 연구 플랫폼 연동 |
|
|
| **Text2SQL** | LIMS 데이터 조회 | 자연어를 SQL로 변환 |
|
|
|
|
## 📁 프로젝트 구조
|
|
|
|
```
|
|
ncuetalk/
|
|
├── README.md # 프로젝트 문서
|
|
├── requirements.txt # Python 의존성
|
|
├── index.html # 메인 웹 페이지
|
|
├── main.js # 프론트엔드 로직
|
|
├── style.css # 스타일시트
|
|
├──
|
|
├── backend/ # 백엔드 서버
|
|
│ ├── app.py # FastAPI 메인 앱
|
|
│ └── engines/ # AI 도구 엔진들
|
|
│ ├── __init__.py # 엔진 레지스트리
|
|
│ ├── chatgpt_tool/ # ChatGPT 도구
|
|
│ ├── chatbot_gxp/ # GxP 챗봇
|
|
│ ├── dev_chatbot/ # 개발챗봇
|
|
│ ├── doc_translation/ # 문서번역
|
|
│ ├── research_qa/ # 연구QA
|
|
│ └── lims_text2sql/ # Text2SQL
|
|
│
|
|
├── frontend/ # 프론트엔드 리소스
|
|
│ ├── dev_chatbot/ # 개발챗봇 UI 컴포넌트
|
|
│ ├── lims_text2sql/ # Text2SQL UI
|
|
│ └── research_qa/ # 연구QA UI
|
|
│
|
|
├── uploads/ # 업로드된 파일들
|
|
├── chroma_db/ # 벡터 데이터베이스
|
|
├── logs/ # 시스템 로그
|
|
└── scripts/ # 유틸리티 스크립트
|
|
```
|
|
|
|
## 🛠 설치 및 실행
|
|
|
|
### 전제 조건
|
|
- Python 3.8+
|
|
- Node.js (선택사항, 프론트엔드 개발 시)
|
|
- OpenAI API 키
|
|
|
|
### 1. 환경 설정
|
|
|
|
```bash
|
|
# 저장소 클론
|
|
git clone <repository-url>
|
|
cd ncuetalk
|
|
|
|
# 가상환경 생성 및 활성화
|
|
python -m venv venv
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
|
|
# 의존성 설치
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. 환경 변수 설정
|
|
|
|
프로젝트 루트에 `.env` 파일 생성:
|
|
|
|
```env
|
|
# OpenAI API 설정
|
|
OPENAI_API_KEY=your_openai_api_key_here
|
|
|
|
# Ollama 모델 설정 (자체모델 사용 시)
|
|
OLLAMA_MODEL=gpt-oss:latest
|
|
LLM_PROVIDER=ollama
|
|
|
|
# 기타 설정
|
|
UPLOAD_MAX_SIZE=50MB
|
|
```
|
|
|
|
### 3. 서버 실행
|
|
|
|
```bash
|
|
# 백엔드 서버 시작
|
|
cd backend
|
|
python -m uvicorn app:app --host 0.0.0.0 --port 8010 --reload
|
|
|
|
# 프론트엔드 서버 시작 (별도 터미널)
|
|
cd ..
|
|
python -m http.server 3000
|
|
```
|
|
|
|
### 4. 웹 브라우저에서 접속
|
|
|
|
- 프론트엔드: http://localhost:3000
|
|
- 백엔드 API: http://localhost:8010
|
|
- API 문서: http://localhost:8010/docs
|
|
|
|
## 🎯 도구별 상세 가이드
|
|
|
|
### 1. ChatGPT 💬
|
|
|
|
**기능**: OpenAI의 ChatGPT 모델과 직접 대화
|
|
|
|
**지원 모델**:
|
|
- `auto`: 자동 선택 (기본값)
|
|
- `gpt-5`: GPT-5 모델
|
|
|
|
**사용법**:
|
|
1. 도구 목록에서 "ChatGPT" 선택
|
|
2. 모델 선택 드롭다운에서 원하는 모델 선택
|
|
3. 채팅창에 질문 입력 후 엔터
|
|
|
|
### 2. GxP 챗봇 📋
|
|
|
|
**기능**: GxP(Good Practice) 문서에 대한 전문적인 질의응답
|
|
|
|
**특징**:
|
|
- Adobe PDF Services API 기반 고품질 텍스트 추출
|
|
- ChromaDB 벡터 데이터베이스를 활용한 의미 검색
|
|
- AI Agent 기반 도구 선택 자동화
|
|
|
|
**사용법**:
|
|
1. "GxP 챗봇" 선택
|
|
2. GxP 관련 질문 입력 (예: "mapping test가 무엇인지?")
|
|
3. 벡터 검색을 통해 관련 문서에서 답변 생성
|
|
|
|
### 3. 개발챗봇 🛠
|
|
|
|
**기능**: PDF 문서 업로드 및 분석을 통한 질의응답
|
|
|
|
**주요 기능**:
|
|
- PDF 파일 업로드 및 벡터화
|
|
- 문서 기반 질의응답
|
|
- 출처 페이지 번호 제공
|
|
- 지식베이스 전용 모드 지원
|
|
|
|
**사용법**:
|
|
1. "개발챗봇" 선택
|
|
2. 좌측 파일 리스트에서 "+" 버튼으로 PDF 업로드
|
|
3. 모델 선택: "자체모델" (Ollama 기반)
|
|
4. 지식모드 선택: "지식베이스" (업로드된 문서만 참조)
|
|
5. 업로드한 문서에 대해 질문
|
|
|
|
**파일 관리**:
|
|
- 지원 형식: PDF 파일만
|
|
- 최대 파일 크기: 환경 설정에 따름
|
|
- 파일 삭제: 각 파일 옆 "✕" 버튼
|
|
|
|
### 4. 문서번역 🌐
|
|
|
|
**기능**: 한국어를 영어로 번역 (Word 문서 + 실시간 텍스트)
|
|
|
|
**지원 기능**:
|
|
- **Word 문서 번역**: .doc/.docx 파일 업로드 후 일괄 번역
|
|
- **실시간 텍스트 번역**: 채팅창에 입력한 텍스트 즉시 번역
|
|
- **이중언어 문서 생성**: 원본과 번역문이 함께 포함된 결과 파일
|
|
|
|
**모델 선택**:
|
|
- **자체모델**: Ollama 기반 gpt-oss:latest (빠른 처리)
|
|
- **외부모델**: OpenAI GPT-5 (고품질 번역)
|
|
|
|
**사용법**:
|
|
|
|
**📄 Word 문서 번역**:
|
|
1. "문서번역" 선택
|
|
2. 좌측 파일 리스트에서 "+" 버튼
|
|
3. .doc 또는 .docx 파일 선택
|
|
4. 자동으로 번역 처리 시작
|
|
5. 완료 후 "[원본다운]", "[결과다운]" 버튼으로 파일 다운로드
|
|
|
|
**💬 실시간 텍스트 번역**:
|
|
1. "문서번역" 선택
|
|
2. 모델 선택 (자체모델/외부모델)
|
|
3. 채팅창에 번역할 한국어 텍스트 입력
|
|
4. 즉시 영어 번역 결과 확인
|
|
|
|
**예시**:
|
|
```
|
|
입력: "안녕하세요. 오늘 날씨가 좋네요."
|
|
출력: "Hello. The weather is nice today."
|
|
```
|
|
|
|
### 5. 연구QA 📚
|
|
|
|
**기능**: 연구 관련 질의응답 (외부 플랫폼 연동)
|
|
|
|
**특징**:
|
|
- 외부 연구 플랫폼과 iframe 연동
|
|
- 연구 방법론, 데이터 분석, 논문 작성 지원
|
|
|
|
**사용법**:
|
|
1. "연구QA 챗봇" 선택
|
|
2. 자동으로 외부 연구 플랫폼 로드
|
|
3. 연동된 플랫폼에서 직접 질의응답
|
|
|
|
### 6. Text2SQL (LIMS) 🗃
|
|
|
|
**기능**: 자연어를 SQL 쿼리로 변환하여 LIMS 데이터 조회
|
|
|
|
**특징**:
|
|
- 자연어 질의를 SQL로 자동 변환
|
|
- LIMS 데이터베이스 전용 최적화
|
|
|
|
**사용법**:
|
|
1. "Text2SQL (LIMS)" 선택
|
|
2. 자동으로 외부 LIMS 플랫폼 로드
|
|
3. 자연어로 데이터 조회 요청
|
|
|
|
## 📚 API 문서
|
|
|
|
### 🔗 공통 엔드포인트
|
|
|
|
#### GET `/`
|
|
- **설명**: 서버 상태 확인
|
|
- **응답**: `{"message": "엔큐톡 AI 채팅 서버가 실행 중입니다."}`
|
|
|
|
#### GET `/tools`
|
|
- **설명**: 사용 가능한 도구 목록 조회
|
|
- **응답**:
|
|
```json
|
|
[
|
|
{
|
|
"id": "chatgpt",
|
|
"name": "ChatGPT",
|
|
"description": "OpenAI ChatGPT 모델과 대화할 수 있는 도구입니다."
|
|
}
|
|
]
|
|
```
|
|
|
|
#### POST `/chat`
|
|
- **설명**: 통합 채팅 엔드포인트 (모든 도구 지원)
|
|
- **Content-Type**: `multipart/form-data`
|
|
- **Parameters**:
|
|
- `message` (string, required): 사용자 메시지
|
|
- `tool_id` (string, required): 도구 ID
|
|
- `session_id` (string, optional): 세션 ID
|
|
- `model` (string, optional): 모델명 (기본값: "exone3.5")
|
|
- `knowledge_mode` (string, optional): 지식 모드 ("hybrid", "kb_only")
|
|
- `image` (file[], optional): 이미지 파일들
|
|
- **응답**:
|
|
```json
|
|
{
|
|
"response": "AI 응답 텍스트",
|
|
"status": "success",
|
|
"session_id": "생성된_세션_ID",
|
|
"tool_name": "도구명"
|
|
}
|
|
```
|
|
|
|
### 🛠 개발챗봇 API
|
|
|
|
**Base Path**: `/`
|
|
|
|
#### POST `/upload_pdf`
|
|
- **설명**: PDF 파일 업로드 및 벡터화
|
|
- **Content-Type**: `multipart/form-data`
|
|
- **Parameters**:
|
|
- `files` (file[], required): PDF 파일들
|
|
- **응답**:
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"files": ["파일명1.pdf", "파일명2.pdf"]
|
|
}
|
|
```
|
|
|
|
#### GET `/files`
|
|
- **설명**: 업로드된 PDF 파일 목록 조회
|
|
- **응답**:
|
|
```json
|
|
{
|
|
"files": ["파일명1.pdf", "파일명2.pdf"]
|
|
}
|
|
```
|
|
|
|
#### GET `/file_content`
|
|
- **설명**: PDF 파일 내용 조회
|
|
- **Parameters**:
|
|
- `filename` (string, required): 파일명
|
|
- **응답**: PDF 내용을 JSON 형태로 반환
|
|
|
|
#### DELETE `/delete_pdf/{filename}`
|
|
- **설명**: PDF 파일 삭제
|
|
- **Parameters**:
|
|
- `filename` (string, required): 삭제할 파일명
|
|
|
|
#### GET `/pdf`
|
|
- **설명**: PDF 파일 뷰어 제공
|
|
- **Parameters**:
|
|
- `filename` (string, required): 파일명
|
|
|
|
### 🌐 문서번역 API
|
|
|
|
**Base Path**: `/doc_translation`
|
|
|
|
#### POST `/upload_doc`
|
|
- **설명**: Word 문서 업로드 및 번역
|
|
- **Content-Type**: `multipart/form-data`
|
|
- **Parameters**:
|
|
- `files` (file[], required): Word 파일들 (.doc, .docx)
|
|
- **응답**:
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"files": [
|
|
{
|
|
"original_filename": "원본파일명.docx",
|
|
"result_filename": "결과파일명.docx",
|
|
"status": "success"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### GET `/files`
|
|
- **설명**: 번역 파일 목록 조회
|
|
- **응답**:
|
|
```json
|
|
[
|
|
{
|
|
"filename": "원본파일명.docx",
|
|
"result_filename": "결과파일명.docx",
|
|
"has_result": true
|
|
}
|
|
]
|
|
```
|
|
|
|
#### GET `/download/{filename}`
|
|
- **설명**: 파일 다운로드
|
|
- **Parameters**:
|
|
- `filename` (string, required): 다운로드할 파일명
|
|
|
|
#### DELETE `/delete/{original_filename}`
|
|
- **설명**: 번역 파일 삭제 (원본+결과 모두)
|
|
- **Parameters**:
|
|
- `original_filename` (string, required): 원본 파일명
|
|
|
|
### 📋 GxP 챗봇 API
|
|
|
|
**Base Path**: `/gxp`
|
|
|
|
#### POST `/chat`
|
|
- **설명**: GxP 챗봇 대화
|
|
- **Parameters**:
|
|
- `query` (string, required): 질의 내용
|
|
- `session_id` (string, required): 세션 ID
|
|
|
|
#### POST `/ai-agent-chat`
|
|
- **설명**: AI Agent 기반 GxP 챗봇 대화
|
|
- **Parameters**:
|
|
- `query` (string, required): 질의 내용
|
|
- `session_id` (string, required): 세션 ID
|
|
|
|
#### GET `/active-sessions`
|
|
- **설명**: 활성 세션 목록 조회
|
|
|
|
#### GET `/serve-gxp-pdf/{filename}`
|
|
- **설명**: GxP PDF 파일 제공
|
|
|
|
#### GET `/search-vector-db`
|
|
- **설명**: 벡터 DB 검색
|
|
- **Parameters**:
|
|
- `query` (string, required): 검색 쿼리
|
|
- `plant` (string, optional): 공장명 필터
|
|
- `filename` (string, optional): 파일명 필터
|
|
- `collection_name` (string, optional): 컬렉션명 필터
|
|
|
|
#### GET `/collections`
|
|
- **설명**: ChromaDB 컬렉션 목록 조회
|
|
|
|
#### GET `/collections/{collection_name}`
|
|
- **설명**: 특정 컬렉션 정보 조회
|
|
|
|
### 💬 ChatGPT API
|
|
|
|
**Base Path**: `/chatgpt`
|
|
|
|
#### POST `/chat`
|
|
- **설명**: ChatGPT 전용 대화 엔드포인트
|
|
- **Parameters**:
|
|
- `message` (string, required): 메시지
|
|
- `model` (string, optional): 모델명 ("auto", "gpt-5", etc.)
|
|
- `session_id` (string, optional): 세션 ID
|
|
|
|
## 🔧 개발 가이드
|
|
|
|
### 새로운 도구 추가하기
|
|
|
|
1. **엔진 디렉토리 생성**:
|
|
```bash
|
|
mkdir backend/engines/new_tool
|
|
```
|
|
|
|
2. **`__init__.py` 작성**:
|
|
```python
|
|
TOOL_ID = "new_tool"
|
|
|
|
TOOL_INFO = {
|
|
"name": "새 도구",
|
|
"description": "새 도구 설명",
|
|
"system_prompt": "시스템 프롬프트"
|
|
}
|
|
|
|
# 필요한 함수들 구현
|
|
def prepare_context(question: str, **kwargs) -> str:
|
|
# 컨텍스트 준비 로직
|
|
return "준비된 컨텍스트"
|
|
|
|
# FastAPI router (선택사항)
|
|
from fastapi import APIRouter
|
|
router = APIRouter()
|
|
|
|
@router.get("/new-endpoint")
|
|
async def new_endpoint():
|
|
return {"message": "새 엔드포인트"}
|
|
```
|
|
|
|
3. **백엔드 등록**:
|
|
```python
|
|
# backend/app.py에 추가
|
|
from engines.new_tool import router as new_tool_router
|
|
app.include_router(new_tool_router, prefix="/new_tool")
|
|
```
|
|
|
|
4. **프론트엔드 통합**:
|
|
```javascript
|
|
// main.js에 도구별 로직 추가
|
|
} else if (toolId === 'new_tool') {
|
|
// 새 도구 전용 UI 로직
|
|
}
|
|
```
|
|
|
|
### 환경 변수 설정
|
|
|
|
`.env` 파일에서 다음 변수들을 설정할 수 있습니다:
|
|
|
|
```env
|
|
# 필수 설정
|
|
OPENAI_API_KEY=your_api_key
|
|
|
|
# 선택적 설정
|
|
OLLAMA_MODEL=gpt-oss:latest
|
|
LLM_PROVIDER=ollama
|
|
UPLOAD_MAX_SIZE=50MB
|
|
VECTOR_DB_PATH=./chroma_db
|
|
LOG_LEVEL=INFO
|
|
```
|
|
|
|
### 로깅
|
|
|
|
시스템 로그는 `logs/chat.log`에 저장됩니다:
|
|
- 채팅 요청/응답 로그
|
|
- 오류 로그
|
|
- 파일 업로드/삭제 로그
|
|
|
|
### 데이터베이스
|
|
|
|
- **벡터 DB**: ChromaDB (`chroma_db/` 디렉토리)
|
|
- **파일 저장**: `uploads/` 디렉토리
|
|
- **세션 데이터**: 메모리 저장 (서버 재시작 시 초기화)
|
|
|
|
## 🤝 기여하기
|
|
|
|
1. Fork 저장소
|
|
2. Feature 브랜치 생성 (`git checkout -b feature/AmazingFeature`)
|
|
3. 변경사항 커밋 (`git commit -m 'Add some AmazingFeature'`)
|
|
4. 브랜치에 Push (`git push origin feature/AmazingFeature`)
|
|
5. Pull Request 생성
|
|
|
|
## 📄 라이선스
|
|
|
|
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
|
|
|
|
## 📞 지원
|
|
|
|
문제가 발생하거나 질문이 있으시면:
|
|
- GitHub Issues 생성
|
|
- 개발팀 연락
|
|
|
|
---
|
|
|
|
**엔큐톡**과 함께 더 스마트한 AI 경험을 만들어보세요! 🚀 |