🤖 Chatbot API

FastAPI 기반의 지능형 챗봇 API 서비스로, 여러 AI 제공자(OpenAI, Anthropic, Gemini)를 통합 지원하며 자동 fallback 기능을 제공합니다.

✨ 주요 기능

🔄 다중 AI 제공자 지원: OpenAI, Anthropic, Gemini API 통합
🛡️ 자동 Fallback: OpenAI 크레딧 소진 시 자동으로 다른 제공자로 전환
💬 상태 저장/비저장 대화: 단일 응답 및 대화 히스토리 유지 모드 지원
🎯 제공자 선택: force_provider 옵션으로 특정 AI 제공자 강제 사용
📊 자동 API 문서: Swagger UI 및 ReDoc을 통한 인터랙티브 문서
⚡ 빠른 의존성 관리: uv를 활용한 초고속 패키지 관리
🐳 Docker 지원: 컨테이너화된 배포 환경
🔒 안전한 설정 관리: 환경 변수 기반 설정

🚀 빠른 시작

더 자세한 빠른 시작 가이드는 docs/QUICK_START.md를 참고하세요.

필수 요구사항

Python 3.8 이상
uv (Python 패키지 관리자)
최소 하나 이상의 AI API 키 (Gemini, OpenAI, 또는 Anthropic)

설치 및 실행

# 1. 저장소 클론
git clone https://github.com/eul-lab/eul-chatbot-api.git
cd eul-chatbot-api

# 2. uv 설치 (없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 환경 변수 설정
cp .env.template .env
# .env 파일을 열어 API 키를 입력하세요

# 4. 의존성 설치 및 서버 실행
uv run uvicorn src.chatbot_api.main:app --reload

서버가 실행되면 다음 주소에서 접속할 수 있습니다:

📦 설치

uv 사용 (권장)

# uv를 사용한 의존성 설치
uv sync

# 개발 의존성 포함 설치
uv sync --dev

pip 사용

# 가상환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -e .

⚙️ 환경 설정

프로젝트 루트에 .env 파일을 생성하고 다음 환경변수를 설정합니다:

# 필수: 최소 하나 이상의 AI API 키가 필요합니다
GEMINI_API_KEY=your_gemini_api_key_here

# 선택사항: Fallback용 추가 제공자
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 선택사항: LangChain 추적 (디버깅용)
LANGCHAIN_API_KEY=your_langchain_api_key_here
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=chatbot-api

# 선택사항: 개발 설정
DEBUG=True
PORT=8000
HOST=0.0.0.0

API 키 발급 방법

Gemini API: Google AI Studio
OpenAI API: OpenAI Platform
Anthropic API: Anthropic Console

💻 사용 방법

1. 상태 비저장 대화 (Stateless)

단일 메시지-응답 방식으로, 이전 대화 내역을 기억하지 않습니다.

curl -X POST "http://localhost:8000/api/v1/chat/stateless" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "안녕하세요, 인공지능에 대해 설명해주세요."
  }'

2. 상태 저장 대화 (Stateful)

conversationId를 사용하여 대화 히스토리를 유지합니다.

# 첫 번째 메시지
curl -X POST "http://localhost:8000/api/v1/chat/stateful" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "파이썬으로 Hello World를 출력하는 방법을 알려줘",
    "conversationId": "conversation-123"
  }'

# 두 번째 메시지 (이전 대화를 기억)
curl -X POST "http://localhost:8000/api/v1/chat/stateful" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "그럼 자바스크립트로는?",
    "conversationId": "conversation-123"
  }'

3. 특정 AI 제공자 사용

force_provider 옵션으로 특정 AI 제공자를 강제로 사용할 수 있습니다.

# Anthropic Claude 사용
curl -X POST "http://localhost:8000/api/v1/chat/stateless" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "안녕하세요",
    "force_provider": "anthropic"
  }'

# OpenAI GPT 사용
curl -X POST "http://localhost:8000/api/v1/chat/stateless" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "안녕하세요",
    "force_provider": "openai"
  }'

# Gemini 사용
curl -X POST "http://localhost:8000/api/v1/chat/stateless" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "안녕하세요",
    "force_provider": "gemini"
  }'

응답 형식

{
  "success": true,
  "data": {
    "message": "안녕하세요! 어떻게 도와드릴까요?",
    "conversationId": "conv_abc123def456",
    "messageId": "msg_xyz789"
  },
  "metadata": {
    "provider": "openai",
    "model": "gpt-3.5-turbo",
    "processingTimeMs": 1250,
    "tokenUsage": 73
  },
  "requestId": "req_unique_id_12345",
  "timestamp": "2025-12-12T10:30:45Z"
}

Python 클라이언트 예제

import requests

API_BASE_URL = "http://localhost:8000"

def chat(message: str, conversation_id: str = None, provider: str = None):
    """챗봇 API 호출"""
    url = f"{API_BASE_URL}/api/v1/chat/stateful"
    payload = {"message": message}
    
    if conversation_id:
        payload["conversationId"] = conversation_id
    if provider:
        payload["force_provider"] = provider
    
    response = requests.post(url, json=payload)
    return response.json()

# 사용 예시
result = chat("파이썬의 장점은 무엇인가요?", conversation_id="my-conv-001")
print(result["data"]["message"])

📚 API 문서

엔드포인트

메서드	경로	설명
GET	`/`	API 기본 정보
GET	`/health`	서비스 상태 확인
POST	`/api/v1/chat/stateless`	상태 비저장 대화
POST	`/api/v1/chat/stateful`	상태 저장 대화

상세 문서

서버 실행 후 다음 URL에서 인터랙티브 API 문서를 확인할 수 있습니다:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

🗂️ 프로젝트 구조

eul-chatbot-api/
├── .github/                    # GitHub Actions 워크플로우
├── docker/                     # Docker 설정 파일
│   ├── Dockerfile
│   └── docker-compose.yml
├── docs/                       # 문서
│   └── QUICK_START.md
├── src/
│   └── chatbot_api/
│       ├── main.py            # FastAPI 애플리케이션 진입점
│       ├── config.py          # 환경 변수 및 설정
│       ├── api/               # API 레이어
│       │   └── v1/
│       │       └── endpoints/ # API 엔드포인트
│       │           ├── chat.py
│       │           └── health.py
│       ├── models/            # Pydantic 데이터 모델
│       │   ├── request.py
│       │   └── response.py
│       └── services/          # 비즈니스 로직
│           ├── chatbot_service.py
│           └── llm_provider.py
├── tests/                     # 테스트 파일
├── .cursorrules              # Cursor IDE 설정
├── .env.template             # 환경 변수 템플릿
├── .gitignore
├── LICENSE                   # MIT 라이선스
├── NOTICE                    # 저작권 고지
├── README.md
├── pyproject.toml            # 프로젝트 설정 및 의존성
└── uv.lock                   # 의존성 락 파일

🛠️ 개발

개발 환경 설정

# 개발 의존성 포함 설치
uv sync --dev

# 사전 커밋 훅 설치 (있는 경우)
pre-commit install

코드 품질

# 코드 포맷팅
black .
ruff check --fix .

# 타입 체크
mypy src/

# 린트 검사
ruff check .

테스트

# 모든 테스트 실행
pytest

# 커버리지와 함께 실행
pytest --cov=src/chatbot_api --cov-report=html

# 특정 테스트 파일 실행
pytest tests/test_chatbot_service.py

로컬 서버 실행

# 개발 모드 (자동 재시작)
uv run uvicorn src.chatbot_api.main:app --reload

# 프로덕션 모드
uv run uvicorn src.chatbot_api.main:app --host 0.0.0.0 --port 8000

🐳 Docker

Docker로 실행

# Docker 이미지 빌드
docker build -t eul-chatbot-api -f docker/Dockerfile .

# 컨테이너 실행
docker run -p 8000:8000 --env-file .env eul-chatbot-api

Docker Compose 사용

# 서비스 시작
docker-compose -f docker/docker-compose.yml up -d

# 로그 확인
docker-compose -f docker/docker-compose.yml logs -f

# 서비스 중지
docker-compose -f docker/docker-compose.yml down

🤝 기여하기

기여를 환영합니다! 다음 절차를 따라주세요:

이 저장소를 Fork합니다
Feature 브랜치를 생성합니다 (git checkout -b feature/AmazingFeature)
변경사항을 커밋합니다 (git commit -m 'Add some AmazingFeature')
브랜치에 Push합니다 (git push origin feature/AmazingFeature)
Pull Request를 생성합니다

코드 스타일

이 프로젝트는 다음 코드 스타일 가이드를 따릅니다:

Black: 코드 포맷팅
Ruff: 린팅 및 코드 품질
Type Hints: 모든 함수에 타입 힌트 사용

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 글

이 프로젝트는 다음 오픈소스 프로젝트들을 사용합니다:

📞 문의

문제가 발생하거나 제안사항이 있으시면 GitHub Issues를 통해 알려주세요.

Made with ❤️ by EUL Lab

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
.github		.github
docker		docker
docs		docs
src/chatbot_api		src/chatbot_api
.cursorrules		.cursorrules
.env.template		.env.template
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

eul-lab/eul-chatbot-api

Folders and files

Latest commit

History

Repository files navigation