​
연결 및 네트워크

네트워크 연결 문제일 수 있습니다.해결 방법:
  1. 네트워크 연결 확인
ping api.clovastudio.go.kr
  1. 방화벽 설정 확인
    • 아웃바운드 HTTPS (443 포트) 허용
    • 프록시 설정 확인
  2. 타임아웃 값 증가 
response = requests.post(
    url,
    headers=headers,
    json=data,
    timeout=60  # 60초로 증가
)
  1. VPN 확인
    • VPN 사용 시 연결 안정성 확인
SSL/TLS 관련 문제입니다.해결 방법:
  1. 시스템 인증서 업데이트
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install ca-certificates

# macOS
brew install openssl
  1. Python certifi 업데이트
pip install --upgrade certifi
  1. 임시 해결 (개발 환경만)
import requests
response = requests.post(url, verify=False)  # 권장하지 않음
프로덕션 환경에서는 verify=False 사용을 금합니다.
도메인 이름을 IP로 변환하지 못하는 문제입니다.해결 방법:
  1. DNS 설정 확인
nslookup api.clovastudio.go.kr
  1. DNS 서버 변경
    • Google DNS (8.8.8.8, 8.8.4.4)
    • Cloudflare DNS (1.1.1.1)
  2. 호스트 파일 확인
    • /etc/hosts (Linux/Mac)
    • C:\Windows\System32\drivers\etc\hosts (Windows)

​
API 에러

요청 형식이 잘못되었습니다.확인 사항:
  1. JSON 형식 확인
import json

# 올바른 JSON인지 확인
try:
    json.dumps(data)
except Exception as e:
    print(f"Invalid JSON: {e}")
  1. 필수 필드 확인
    • model 필드가 있나요?
    • messages 배열이 올바른가요?
  2. 데이터 타입 확인
    • 숫자는 숫자로, 문자열은 문자열로
    • temperature는 float (0.0 ~ 2.0)
  3. 에러 메시지 확인 
if response.status_code == 400:
    print(response.json())  # 상세한 에러 정보
엔드포인트 경로가 잘못되었습니다.해결 방법:
  1. URL 확인
# 올바른 형식
url = "https://api.clovastudio.go.kr/v1/chat/completions"

# 잘못된 예시
# url = "https://api.clovastudio.go.kr/chat/completions"  # /v1 빠짐
# url = "https://api.clovastudio.go.kr/v1/chats"  # 잘못된 경로
  1. API 버전 확인
    • 현재 버전: /v1
  2. 문서 참조
Rate Limit를 초과했습니다.해결 방법:
  1. 지수 백오프 구현
import time

def make_request_with_retry(url, headers, data, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 429:
            wait_time = (2 ** attempt) + random.random()
            print(f"Rate limited. Waiting {wait_time:.2f} seconds...")
            time.sleep(wait_time)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")
  1. Rate Limit 헤더 확인
print(response.headers.get('X-RateLimit-Limit'))
print(response.headers.get('X-RateLimit-Remaining'))
print(response.headers.get('X-RateLimit-Reset'))
  1. 요청 속도 조절
    • 배치 크기 줄이기
    • 요청 간 딜레이 추가
    • 큐 시스템 사용
서버 측 오류입니다.대응 방법:
  1. 재시도
    • 일시적 오류일 수 있음
    • 몇 초 후 다시 시도
  2. 요청 내용 확인
    • 너무 긴 입력은 아닌가요?
    • 특수 문자가 문제를 일으키지 않나요?
  3. 상태 페이지 확인
    • 서비스 장애 여부 확인
  4. 이슈 보고
    • 지속적으로 발생하면 이슈 등록
    • 재현 가능한 요청 예시 포함
서비스가 일시적으로 사용 불가능합니다.대응 방법:
  1. 잠시 대기
    • 서버 점검 중일 수 있음
    • 5-10분 후 재시도
  2. 서비스 공지 확인
    • 예정된 점검인지 확인
  3. 대체 로직 구현 
try:
    response = api_call()
except ServiceUnavailableError:
    # 캐시된 응답 사용 또는
    # 사용자에게 안내 메시지
    return cached_response

​
응답 관련

응답 속도를 개선하는 방법:
  1. 스트리밍 사용
response = requests.post(
    url,
    headers=headers,
    json={
        "model": "clova-x",
        "messages": messages,
        "stream": True  # 스트리밍 활성화
    },
    stream=True
)
  1. max_tokens 줄이기
data = {
    "model": "clova-x",
    "messages": messages,
    "max_tokens": 500  # 필요한 만큼만
}
  1. 컨텍스트 최소화
    • 불필요한 대화 히스토리 제거
    • 짧고 명확한 프롬프트 사용
응답이 중간에 끊기는 경우:원인:
  • max_tokens 제한 도달
  • 모델의 최대 길이 초과
해결 방법:
  1. max_tokens 증가
data = {
    "model": "clova-x",
    "messages": messages,
    "max_tokens": 2000  # 증가
}
  1. finish_reason 확인
result = response.json()
finish_reason = result['choices'][0]['finish_reason']

if finish_reason == 'length':
    print("토큰 제한으로 인해 잘림")
elif finish_reason == 'stop':
    print("정상 종료")
  1. 분할 요청
    • 긴 작업은 여러 단계로 나누기
예상과 다른 응답이 나오는 경우:원인 및 해결:
  1. 프롬프트 개선
    • 더 명확하고 구체적으로 작성
    • 예시 포함
    • 출력 형식 명시
  2. temperature 조정 
# 일관된 응답 필요
data = {"temperature": 0.2}

# 창의적인 응답 필요
data = {"temperature": 0.9}
  1. 시스템 프롬프트 사용
messages = [
    {
        "role": "system",
        "content": "당신은 정확한 정보만 제공하는 전문가입니다."
    },
    {"role": "user", "content": "..."}
]
응답을 JSON으로 파싱할 수 없는 경우:해결 방법:
  1. 응답 내용 확인
print(response.text)  # 원본 텍스트 확인
print(response.headers)  # Content-Type 확인
  1. 에러 처리 추가
try:
    data = response.json()
except json.JSONDecodeError as e:
    print(f"JSON 파싱 실패: {e}")
    print(f"응답 내용: {response.text}")
  1. 스트리밍 응답 처리
for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data_str = line[6:]
            if data_str != '[DONE]':
                data = json.loads(data_str)

​
파일 및 데이터

RAG42 문서 업로드 문제:확인 사항:
  1. 파일 형식
    • 지원되는 형식인가요? (PDF, DOCX, TXT 등)
    • 파일이 손상되지 않았나요?
  2. 파일 크기
    • 너무 크지 않나요?
    • 최대 크기: 확인 필요 (문의)
  3. 인코딩
    • 텍스트 파일은 UTF-8 인코딩 권장
  4. 올바른 요청 형식 
with open('document.pdf', 'rb') as f:
    files = {'file': f}
    data = {'collection_id': collection_id}
    
    response = requests.post(
        url,
        headers={"Authorization": f"Bearer {api_key}"},
        files=files,
        data=data
    )
RAG42 검색 품질 개선:
  1. 하이브리드 검색 사용
data = {
    "collection_id": collection_id,
    "query": query,
    "search_type": "hybrid",
    "alpha": 0.5
}
  1. 재순위 적용
# 1. 검색
search_results = search_documents(query, top_k=20)

# 2. 재순위
reranked = rerank_documents(query, search_results, top_k=5)
  1. 쿼리 개선
    • 더 구체적으로 작성
    • 키워드 포함
    • 질문 형태로 작성
  2. 메타데이터 필터링 
data = {
    "collection_id": collection_id,
    "query": query,
    "filter": {
        "category": "정책",
        "date": {"gte": "2024-01-01"}
    }
}
문자 인코딩 문제:해결 방법:
  1. UTF-8 사용
with open('file.txt', 'r', encoding='utf-8') as f:
    content = f.read()
  1. 인코딩 자동 감지
import chardet

with open('file.txt', 'rb') as f:
    raw_data = f.read()
    result = chardet.detect(raw_data)
    encoding = result['encoding']

with open('file.txt', 'r', encoding=encoding) as f:
    content = f.read()
  1. 에러 무시 (비권장)
with open('file.txt', 'r', encoding='utf-8', errors='ignore') as f:
    content = f.read()

​
개발 환경

패키지 설치 문제:
  1. pip 업그레이드
pip install --upgrade pip
  1. 가상 환경 사용
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate  # Windows
  1. 의존성 설치
pip install requests python-dotenv
환경 변수 문제:
  1. .env 파일 확인
# .env
CLOVA_API_KEY=your_api_key_here
  1. python-dotenv 사용
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("CLOVA_API_KEY")

if not api_key:
    raise ValueError("API key not found")
  1. 경로 확인
    • .env 파일이 실행 디렉토리에 있나요?
    • 절대 경로 지정: load_dotenv("/path/to/.env")
브라우저에서 직접 호출 시 CORS 문제:해결 방법:
  1. 백엔드에서 호출 (권장)
프론트엔드 → 백엔드 → Clova Studio API
  1. 프록시 서버 사용
    • 개발 환경에서만
    • webpack devServer proxy 설정
브라우저에서 직접 API 키를 사용하지 마세요! 보안 위험이 있습니다.

​
관련 문서

에러 처리

에러 코드 및 처리 방법

API Reference

API 상세 문서

Cookbook

실전 예제 코드