API 활용
    • PDF

    API 활용

    • PDF

    기사 요약

    Classic/VPC 환경에서 이용 가능합니다.

    익스플로러 메뉴에서 제공하는 API에 대해 설명합니다. 각 API의 [시작하기] 버튼을 클릭하면 각 API의 세부 정보를 확인할 수 있습니다.

    토큰 계산기 API

    토큰 계산기 API는 입력한 문장의 토큰 수를 계산할 수 있습니다. 토큰 계산기를 활용하여 최적의 토큰 수를 찾거나 효율적인 프롬프트를 만들 수 있습니다.
    토큰 계산기(HCX)는 HyperCLOVA X 모델에서 입력한 문장의 토큰 수를 계산하는 API입니다.
    토큰 계산기(임베딩 v2)는 임베딩 v2 API의 bge-m3 모델에서 입력한 문장의 토큰 수를 계산하는 API입니다.

    슬라이딩 윈도우 API

    슬라이딩 윈도우 API는 챗 모드에서 프롬프트 및 결괏값을 HyperCLOVA X 언어 모델이 처리 가능한 최대 토큰 수 이내로 조절하여 대화가 끊기지 않고 진행되도록 도와줍니다.

    챗 모드에서는 사용자와 어시스턴트의 대화가 HyperCLOVA X 언어 모델이 처리 가능한 최대 토큰 수를 초과할 경우, 더 이상 새로운 대화를 생성하지 못하도록 설정되어 있습니다. 슬라이딩 윈도우 API는 사용자와 어시스턴트의 대화 내역 중 가장 오래된 대화 턴을 삭제하여 대화가 더 이상 생성되지 않는 상황을 방지할 수 있습니다. 대화 삭제 시 시스템 지시문의 다음 대화, 즉 가장 먼저 입력된 대화 턴부터 차례대로 삭제합니다.

    참고
    • 슬라이딩 윈도우 API는 챗 모드에 해당하는 모델(Chat Completions API)에 대해서만 작동합니다.
    • 슬라이딩 윈도우 API의 결괏값이 그대로 Chat Completions API에 입력되도록 순서를 설정해야 합니다.
    • modelName, maxTokens 등의 기타 설정 값은 함께 사용하는 Chat Completions API 설정값과 동일하게 설정해야 합니다.
    주의
    • 사용자 및 어시스턴트 간의 대화 내역을 대화 턴 단위로 앞에서부터 순차적으로 삭제하기 때문에 새로 생성되는 대화 내용이 이전 대화 내용을 반영하지 못할 수 있습니다.
    • 특히 결괏값의 최대 생성 토큰 수(API의 maxTokens 값)가 크게 설정된 경우, 이에 비례하여 대화 내역이 삭제되므로 새롭게 생성되는 대화 내용이 이전 대화 내역을 충분히 반영하지 못할 수 있습니다.

    슬라이딩 윈도우 작동 방식

    챗 모드에서 입력된 대화 내역의 총 토큰 수(A)와 새롭게 생성될 대화의 최대 생성 토큰 수(B=maxTokens)의 합이 모델의 처리 가능한 최대 토큰 수(X)보다 크면 (즉, A+B>X), Chat Completions API는 더 이상 대화를 생성하지 않습니다. 이 문제를 해결하기 위해 슬라이딩 윈도우 API는 초과된 토큰 수(A+B−X)만큼 기존 대화 중 오래된 대화 턴부터 삭제합니다. 대화 턴에서 일부만 삭제되지 않도록 대화 턴 단위로 삭제합니다(초과 토큰 수 이상의 최소 대화 턴 삭제).
    예를 들어 아래 그림에서와 같이 초과된 토큰 수가 200 토큰일 때, 슬라이딩 윈도우 API를 적용하면 기존 대화 내역 중 가장 오래된 두 개의 대화 턴(100, 200 토큰)을 삭제합니다. 초과된 토큰 수가 100 토큰 이하인 경우에는 기존 대화 내역 중 가장 오래된 한 개의 대화 턴만 삭제됩니다. 즉, 사용자와 어시스턴트 간의 대화 쌍이 아닌 개별 대화 턴이 삭제됩니다.
    clovastudio-explorer_slidingwindow_ko.png

    슬라이딩 윈도우 API 작업 과정

    슬라이딩 윈도우 API를 적용하면 전체 대화 내용의 토큰 수를 별도로 조절할 필요 없이 Chat Completions API를 연속적으로 사용할 수 있습니다.

    슬라이딩 윈도우 API 작업 과정은 다음과 같습니다.

    1. Chat Completions API를 사용하기 전에 슬라이딩 윈도우 API를 먼저 호출하여 입력하고자 하는 프롬프트(대화 내용; body > messages)를 요청에 입력해 주십시오.
    2. 슬라이딩 윈도우 API의 응답 내 결괏값(result > messages)을 그대로 Chat Completions API 요청에 입력해 주십시오.
    3. 모델명 및 최대 토큰 수는 Chat Completion API와 슬라이딩 윈도우 API에 동일하게 입력해 주십시오.

    문단 나누기 API

    문단 나누기 API는 문장 간 유사도를 계산하여 주제 단위로 단락을 구분할 수 있습니다. 한 문단 안에 들어갈 수 있는 토큰 수를 지정할 수 있고, 문단에 빈 줄이 없거나 구분이 명확하지 않은 경우에도 맥락을 파악하여 문단을 나눌 수 있습니다. 문단을 나눌 개수는 'SegCount' 설정 값으로 조절할 수 있습니다. 자동으로 문단 나누기를 원할 경우에는 SegCount 값을 -1로 설정해 주십시오. 값이 0 이상인 경우에는 사용자가 입력한 값만큼 문단 나누기를 수행합니다.

    문단 나누기 API의 작업 과정은 다음과 같습니다.

    clovastudio-explorer03_segment_ko

    요약 API

    요약 API는 주어진 문장을 문단으로 구분한 후, 각 문단을 요약할 수 있는 API입니다.

    요약 API는 긴 문서를 맥락에 맞게 문단으로 구분하고 각 문단을 요약할 수 있습니다. 중요한 정보를 유지하면서도 불필요한 부분을 제거하여 텍스트의 길이를 줄일 수 있습니다. 문단 나누기의 segMaxSize와 segMinSize를 이용하면 한 단락 안에 포함할 글자 수를 제한하여 요약문 분량도 조절할 수 있습니다.

    clovastudio-explorer03_summarize_ko

    요약 API는 다음과 같이 활용할 수 있습니다.

    1. 장문의 회의록을 요약할 수 있고, 회의록의 내용을 파악하여 핵심 요약 결과를 생성할 수 있습니다.
    2. 장문의 이메일에서 중요한 내용을 추려서 쉽게 파악할 수 있습니다.
    3. 보고서나 스크립트를 간략하게 요약할 수 있습니다. 맥락에 맞게 문단을 구분하여 요약하기 때문에 목차를 쉽게 생성할 수 있습니다.
    참고

    웹에 공개된 글인 경우에는 요약의 성능이 떨어질 수 있습니다.

    임베딩 API

    입력 텍스트를 숫자 형태의 벡터 값으로 변환할 수 있습니다. 사용자의 작업과 목적에 따라 세가지 모델 중 원하는 방식을 선택할 수 있습니다. 각 모델은 동일한 문장 쌍에 대해 서로 다른 유사도 결과를 반환합니다.

    도구명모델명최대 토큰 수벡터 차원권장 거리 지표 distance metric)비고
    임베딩v2bge-m38,192 토큰1024Cosine Similarity (코사인 유사도)오픈 소스 모델*

    임베딩 API의 모델별 특징은 다음과 같습니다.
    clovastudio-explorer_embedding01_ko.png

    참고

    임베딩 v2의 출력을 오픈소스로 제공되는 bge-m3 모델 출력과 동일하게 얻기 위해서는 아래 사항을 고려해주십시오.

    • 임베딩 v2는 bge-m3 모델의 총 3가지 방식 (sparse, dense, multi-dense/colbert) 출력 중 dense 에 해당하는 값을 반환합니다.
    • 임베딩 v2는 FP16 및 정규화(normalization) 적용이 되어있지 않습니다.

    임베딩 활용

    임베딩 API는 다음과 같은 작업에 활용할 수 있습니다.

    • 문장 간의 벡터 유사도를 계산하여 검색 기능을 개선할 수 있습니다. 예를 들어, 사용자가 입력한 검색어와 문서의 벡터 유사도를 측정하여 가장 관련성이 높은 문서를 반환할 수 있습니다.
    • 두 문장 간의 유사도를 계산해 관련 문서의 유사성을 판단하거나 문장 간의 의미적 유사성을 비교할 수 있습니다.
    • 비슷한 특성을 가진 문서를 클러스터로 그룹화할 수 있습니다.
    • 문서를 분류할 수 있습니다. 벡터화된 텍스트 데이터를 학습된 모델에 사용하여 텍스트의 주제나 감성에 따라 분류하는 등 다양한 분류 작업에 활용할 수 있습니다.

    일반적인 임베딩의 작업 과정은 데이터 준비, 임베딩 수행, 벡터 결과물 저장, API 개발 및 결과물 호출로 구성됩니다. 이 과정을 통해 임베딩된 결과물을 저장하고 데이터베이스에 활용할 수 있습니다.

    임베딩 작업 과정
    1. 임베딩할 파일을 Text로 변환합니다.
    2. 텍스트 유형과 목적에 따라 문단 나누기 또는 요약 API 이용하여 Text를 적절하게 나눕니다.
    3. 적합한 임베딩 모델을 선택 후, Text를 벡터로 변환하여 임베딩 작업을 수행합니다.
    4. 임베딩된 결과물과 원본 Text를 벡터 DB에 함께 저장합니다.
    5. 사용자 입력 쿼리를 벡터 변환하여 API화 → DB에 저장된 벡터와의 유사도를 비교하여 일치하는 벡터를 찾아 매핑된 원본 텍스트를 호출하여 최종 결과를 생성합니다.
    6. API 결과를 prompt에 넣어 사용자가 원하는 적절한 형식의 응답으로 만들어 최종 결과물을 출력하기 위해 Chat Completions API를 사용하실 수 있습니다.

    clovastudio-explorer_embedding2_ko.png

    긴 텍스트 처리

    임베딩 API가 한 번에 처리 가능한 최대 텍스트 길이는 8,192 토큰(v2, bge-m3)입니다. 텍스트 토큰 수 제한으로 임베딩이 어려운 경우, 긴 텍스트를 적절하게 나누기 위해 청크 방식을 사용하는 것을 권장합니다. 텍스트를 나눌 때에는 올바른 정보를 추출하기 위해 텍스트를 의미 단위로 적절하게 구분하는 것이 중요합니다. 청크는 텍스트를 작은 조각으로 나누는 작업으로 기본 텍스트 분할, 문단 나누기, 요약이 있습니다.

    청크 방식의 종류와 각 방식의 장단점은 다음과 같습니다.

    방식설명장점단점
    기본 텍스트 분할텍스트를 일정한 길이의 단위로 나누는 방식텍스트를 세세하게 나누어 질의에 대한 정답을 추출하기 용이함텍스트를 의미 단위가 아닌 길이 단위로 자르기 때문에 텍스트의 처음과 끝 처리가 미흡하고 전체 텍스트의 의미 파악이 어려움
    문단 나누기텍스트를 문맥에 맞게 의미 있는 문단으로 분리텍스트가 의미 있는 단위로 묶여 임베딩 성능을 높일 수 있음긴 문단의 경우, 질의에 대한 정답이 있는 영역을 특정하기 어려움
    요약주요 내용에 초점을 두고 긴 텍스트를 짧게 요약문단 나누기보다 더 긴 맥락의 텍스트를 요약할 수 있어 문서 단위로 임베딩하기에 용이함긴 문단의 경우, 질의에 대한 정답이 있는 영역을 특정하기 어려움
    참고

    CLOVA Studio에서는 토큰 계산기(임베딩 v2) API, 문단 나누기 API와 요약 API를 제공합니다. 자세한 정보는 토큰 계산기 API, 문단 나누기 API요약 API를 참고해 주십시오.

    bge-m3 모델 인용 정보는 다음과 같습니다.

    @misc{bge-m3,
        title={BGE M3-Embedding: Multi-Lingual, Multi-Functionality, Multi-Granularity Text Embeddings Through Self-Knowledge Distillation},
        author={Jianlv Chen and Shitao Xiao and Peitian Zhang and Kun Luo and Defu Lian and Zheng Liu},
        year={2024},
        eprint={2402.03216},
        archivePrefix={arXiv},
        primaryClass={cs.CL}
    }
    

    테스트 앱 생성

    CLOVA Studio에서 제공하는 서비스를 연동하기 위한 API 가이드와 앱 생성 도구를 제공합니다. 테스트 앱을 생성한 후, curl과 python 코드를 활용하여 익스플로러에서 제공하는 API를 호출할 수 있습니다.

    • [테스트 앱 생성] 버튼을 클릭한 후 curl과 python 코드를 활용하여 API를 호출할 수 있습니다.
    • 생성된 테스트 앱 정보는 앱 신청 현황[테스트 앱] 탭에서 확인할 수 있습니다.

    summarization_app-request_ko


    이 문서가 도움이 되었습니까?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.