Chatbot API

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

주요 기능

기능	설명
다중 AI 제공자	OpenAI, Anthropic, Gemini API 통합
자동 Fallback	크레딧 소진 시 자동으로 다른 제공자로 전환
대화 모드	Stateless(단일 응답) / Stateful(히스토리 유지)
제공자 선택	force_provider 옵션으로 특정 제공자 지정
API 문서	Swagger UI / ReDoc 자동 생성
Docker	컨테이너화된 배포 환경 지원

빠른 시작

요구사항: Python 3.8+, uv, AI API 키 1개 이상

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

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

# 환경 변수 설정 후 서버 실행
cp .env.template .env && vi .env  # API 키 입력
uv run uvicorn src.chatbot_api.main:app --reload

접속 URL

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

자세한 가이드: docs/QUICK_START.md

설치

# uv (권장)
uv sync           # 프로덕션
uv sync --dev     # 개발 의존성 포함

# pip
python -m venv venv && source venv/bin/activate
pip install -e .

환경 설정

.env 파일에 다음 환경변수를 설정합니다:

# 필수 (최소 1개)
GEMINI_API_KEY=your_key

# Fallback용 (선택)
OPENAI_API_KEY=your_key
ANTHROPIC_API_KEY=your_key

# 디버깅용 (선택)
LANGCHAIN_API_KEY=your_key
LANGCHAIN_TRACING_V2=true

API 키 발급: Gemini | OpenAI | Anthropic

사용 방법

API 엔드포인트

메서드	경로	설명
GET	/	API 기본 정보
GET	/health	서비스 상태 확인
POST	/api/v1/chat/stateless	상태 비저장 대화 (히스토리 없음)
POST	/api/v1/chat/stateful	상태 저장 대화 (히스토리 유지)

요청 예시

# Stateless - 단일 응답
curl -X POST "http://localhost:8000/api/v1/chat/stateless" \
  -H "Content-Type: application/json" \
  -d '{"message": "안녕하세요"}'

# Stateful - 대화 유지
curl -X POST "http://localhost:8000/api/v1/chat/stateful" \
  -H "Content-Type: application/json" \
  -d '{"message": "안녕하세요", "conversationId": "conv-123"}'

# 특정 제공자 지정 (gemini | openai | anthropic)
curl -X POST "http://localhost:8000/api/v1/chat/stateless" \
  -H "Content-Type: application/json" \
  -d '{"message": "안녕하세요", "force_provider": "anthropic"}'

응답 형식

{
  "success": true,
  "data": {
    "message": "안녕하세요! 어떻게 도와드릴까요?",
    "conversationId": "conv_abc123",
    "messageId": "msg_xyz789"
  },
  "metadata": {
    "provider": "gemini",
    "model": "gemma-3-27b-it",
    "processingTimeMs": 1250,
    "tokenUsage": 73
  },
  "requestId": "req_12345",
  "timestamp": "2025-12-12T10:30:45Z"
}

Python 클라이언트 예제

import requests

def chat(message: str, conversation_id: str = None, provider: str = None):
    url = "http://localhost:8000/api/v1/chat/stateful"
    payload = {"message": message}
    if conversation_id:
        payload["conversationId"] = conversation_id
    if provider:
        payload["force_provider"] = provider
    return requests.post(url, json=payload).json()

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

프로젝트 구조

src/chatbot_api/
├── main.py              # FastAPI 진입점
├── config.py            # 환경 변수 설정
├── api/v1/endpoints/    # API 엔드포인트 (chat.py, health.py)
├── schemas/             # Pydantic 모델
└── services/            # 비즈니스 로직 (chatbot.py, chat.py)

전체 구조 보기

eul-chatbot-api/
├── .github/              # GitHub Actions
├── docker/               # Dockerfile, docker-compose.yml
├── docs/                 # 문서
├── src/chatbot_api/      # 소스 코드
├── tests/                # 테스트
├── pyproject.toml        # 의존성 설정
└── uv.lock               # 락 파일

개발

# 코드 품질
black . && ruff check --fix .    # 포맷팅
mypy src/                         # 타입 체크
ruff check .                      # 린트

# 테스트
pytest                                              # 전체 실행
pytest --cov=src/chatbot_api --cov-report=html     # 커버리지

# 서버 실행
uv run uvicorn src.chatbot_api.main:app --reload              # 개발
uv run uvicorn src.chatbot_api.main:app --host 0.0.0.0        # 프로덕션

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       # 중지

기여하기

1. Fork → 2. 브랜치 생성 (feature/기능명) → 3. 커밋 → 4. Push → 5. PR 생성

코드 스타일: Black (포맷팅) + Ruff (린트) + Type Hints

라이선스

MIT License

---

사용 기술: FastAPI · LangChain · uv

문의: GitHub Issues