Chat Completions

현재 지원되는 모델:
  • HCX-GOV-Think: 추론형(Reasoning) 모델
    • 컨텍스트 길이: 128,000 tokens
    • 복잡한 문제 해결, 논리적 추론, 단계별 설명에 적합
  • HCX-DASH-002: 경량화 모델
    • 컨텍스트 길이: 32,000 tokens
    • 간단한 질의응답, 빠른 응답이 필요한 경우에 적합
  • LLM42 (Gemma 3 12B): 멀티모달 모델
    • 컨텍스트 길이: 128,000 tokens
    • 이미지 분석, 차트 해석, 문서 OCR, 시각적 질의응답에 적합
모델별 특징과 사용 방법은 Chat Completions 문서를 참고하세요.
메시지 배열에 이전 대화를 포함하면 됩니다:
messages = [
    {"role": "system", "content": "당신은 도움이 되는 AI 어시스턴트입니다."},
    {"role": "user", "content": "Python이 뭐야?"},
    {"role": "assistant", "content": "Python은 프로그래밍 언어입니다."},
    {"role": "user", "content": "그럼 어디에 사용돼?"}  # 이전 맥락 유지
]
자세한 예제는 Chat 애플리케이션 Cookbook을 참고하세요.
네, stream: true 옵션을 사용하면 실시간으로 응답을 받을 수 있습니다:
response = requests.post(
    url,
    headers=headers,
    json={
        "model": "clova-x",
        "messages": messages,
        "stream": True  # 스트리밍 활성화
    },
    stream=True
)

for line in response.iter_lines():
    # 실시간으로 처리
    print(line)
사용자 경험 향상을 위해 스트리밍을 권장합니다.
응답의 창의성과 일관성을 조절하는 매개변수입니다:Temperature (0.0 ~ 1.0):
  • 0.0-0.3: 일관되고 예측 가능한 응답
    • 사실 기반 질문, 데이터 분석, 코드 생성에 적합
  • 0.4-0.7: 균형잡힌 응답 (권장, 기본값 0.5)
    • 일반적인 대화, 설명, 요약에 적합
  • 0.8-1.0: 창의적이고 다양한 응답
    • 브레인스토밍, 창작 글쓰기, 아이디어 생성에 적합
Top-p (0.0 ~ 1.0):
  • 0.1-0.5: 가장 확률 높은 단어만 선택 (보수적)
  • 0.6-0.9: 적절한 다양성 유지 (권장, 기본값 0.9)
  • 0.95-1.0: 다양한 단어 선택 가능 (창의적)
Temperature와 Top P를 동시에 높게 설정하면 응답이 불안정해질 수 있습니다. 일반적으로 둘 중 하나만 조정하는 것을 권장합니다.
모델별 컨텍스트 길이:
  • HCX-GOV-Think: 128,000 tokens
  • HCX-DASH-002: 32,000 tokens
  • LLM42: 128,000 tokens
max_tokens 파라미터로 출력 길이 제한 가능:
  • 짧은 답변 (요약, 분류): 256-512 tokens
  • 일반 대화: 1024-2048 tokens
  • 긴 문서 생성: 2048-4096 tokens (기본값)
토큰 계산 팁:
  • 한글: 약 1자 = 1~2 토큰
  • 영문: 약 1단어 = 1~2 토큰
role: "system" 메시지로 AI의 행동을 정의합니다:
messages = [
    {
        "role": "system",
        "content": "당신은 Python 프로그래밍 전문가입니다. "
                  "항상 코드 예제와 함께 설명하세요."
    },
    {
        "role": "user",
        "content": "리스트 컴프리헨션을 설명해주세요."
    }
]
효과적인 시스템 프롬프트 작성법:
  • 명확한 역할 정의
  • 구체적인 행동 지침
  • 응답 형식 지정
  • 제약 사항 명시

RAG42

RAG42는 Retrieval-Augmented Generation을 위한 완전한 문서 관리 및 검색 시스템입니다.주요 기능:
  • 컬렉션 관리
  • 문서 업로드 및 자동 청킹
  • 벡터 검색
  • 하이브리드 검색 (키워드 + 의미)
자세한 내용은 RAG 시스템 구축 Cookbook을 참고하세요.
RAG42가 지원하는 파일 형식:
  • 문서: PDF, DOCX, HWP, HWPX, TXT, MD
  • 스프레드시트: XLSX, CSV
  • 프레젠테이션: PPTX
  • 기타: HTML
파일은 자동으로 텍스트로 변환되고 청크로 분할됩니다.
네, 문서를 업로드하면 자동으로 처리됩니다:
  1. 파싱: 텍스트 추출
  2. 청킹: 의미 단위로 분할
  3. 임베딩: 벡터 생성
  4. 인덱싱: 검색 가능하게 저장
청킹 전략을 커스터마이즈하려면 문서 처리 파이프라인 Cookbook을 참고하세요.
다음 방법들을 시도해보세요:
  1. 하이브리드 검색 사용
    • 키워드 + 의미 검색 결합
    • search_type: "hybrid" 옵션
  2. 재순위(Rerank) 적용
    • 검색 결과를 재정렬
    • 더 관련성 높은 문서 우선
  3. 적절한 청크 크기
    • 너무 크면: 관련 없는 정보 포함
    • 너무 작으면: 컨텍스트 부족
    • 권장: 512~1024 토큰
  4. 메타데이터 활용
    • 문서에 태그, 카테고리 추가
    • 필터링으로 검색 범위 좁히기
시범 서비스 기간 동안 기본 제한이 적용됩니다.더 많은 컬렉션이 필요한 경우 문의해주세요.컬렉션 구성 권장사항:
  • 주제별로 분리
  • 문서 타입별로 분리
  • 권한 관리를 위해 분리
네, RAG42 API를 통해 가능합니다:
  • 문서 수정: PATCH /rag42/documents/
  • 문서 삭제: DELETE /rag42/documents/
  • 청크 수정: PATCH /rag42/chunks/
  • 청크 삭제: DELETE /rag42/chunks/
자세한 API 명세는 RAG42 API 문서를 참고하세요.

Tools

개인정보를 자동으로 감지하고 마스킹합니다:감지 가능한 정보:
  • 이메일 주소
  • 전화번호
  • 주민등록번호
  • 신용카드 번호
  • 주소
  • 이름
response = requests.post(
    f"{base_url}/tools/pii-mask",
    headers=headers,
    json={
        "text": "제 이메일은 user@example.com입니다.",
        "mask_types": ["email"]
    }
)
# 결과: "제 이메일은 [EMAIL]입니다."
자세한 내용은 PII 마스킹 문서를 참고하세요.
텍스트를 숫자 벡터로 변환하는 기술입니다.용도:
  • 의미 기반 검색
  • 텍스트 유사도 계산
  • 문서 클러스터링
  • 추천 시스템
response = requests.post(
    f"{base_url}/tools/embeddings",
    headers=headers,
    json={
        "texts": ["안녕하세요", "Hello"],
        "model": "clova-embedding"
    }
)
# 각 텍스트가 벡터로 변환됨
다양한 형식의 문서에서 텍스트를 추출할 때 사용합니다:사용 사례:
  • PDF 보고서에서 텍스트 추출
  • Word 문서 내용 파싱
  • 스캔된 이미지에서 OCR
  • 구조화된 데이터 추출
두 가지 파서 제공:
  • RAG42 파서: RAG 시스템용 최적화
  • Lomin 파서: 고급 레이아웃 분석
자세한 내용은 문서 파서 문서를 참고하세요.
고품질 음성 처리를 제공합니다:STT (Speech-to-Text):
  • 다양한 음성 환경 지원
  • 한국어/영어 지원
  • 타임스탬프 제공
TTS (Text-to-Speech):
  • 자연스러운 음성 합성
  • 다양한 보이스 옵션
  • 속도/음높이 조절 가능
예제는 음성 처리 Cookbook을 참고하세요.

성능 및 최적화

다음 방법들을 시도해보세요:
  1. 스트리밍 사용
    • 첫 토큰을 빠르게 받음
    • 사용자 체감 속도 향상
  2. 적절한 max_tokens 설정
    • 필요 이상으로 크게 설정하지 않기
  3. 병렬 처리
    • 독립적인 요청은 동시 실행
  4. 캐싱
    • 자주 사용되는 응답 캐싱
    • 임베딩 결과 캐싱
  5. 배치 처리
    • 여러 요청을 묶어서 처리
효율적인 API 사용 방법:
  1. 적절한 모델 선택
    • 작업에 맞는 최소 모델 사용
  2. 토큰 사용 최적화
    • 불필요한 컨텍스트 제거
    • 간결한 프롬프트 작성
  3. 캐싱 활용
    • 반복 요청 줄이기
  4. 에러 처리
    • 재시도 전에 원인 파악
    • 무한 재시도 방지
Rate Limit 대응 방법:
  1. 지수 백오프 구현
import time

for attempt in range(max_retries):
    try:
        response = make_request()
        break
    except RateLimitError:
        wait_time = 2 ** attempt
        time.sleep(wait_time)
  1. 요청 속도 조절
    • 큐 시스템 사용
    • 배치 크기 조정
  2. 제한 확인
    • 응답 헤더에서 제한 정보 확인
    • X-RateLimit-Remaining 헤더
자세한 내용은 에러 처리 문서를 참고하세요.

관련 문서