API 활용

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

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

토큰 계산기 API

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

슬라이딩 윈도우 API

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

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

슬라이딩 윈도우 작동 방식

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

슬라이딩 윈도우 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의 작업 과정은 다음과 같습니다.

요약 API

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

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

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

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

임베딩 API

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

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

임베딩 활용

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

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

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

긴 텍스트 처리

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

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

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를 호출할 수 있습니다.
• 생성된 테스트 앱 정보는 앱 신청 현황의 [테스트 앱] 탭에서 확인할 수 있습니다.

• 테스트 앱 발급에 대한 자세한 설명은 익스플로러 작업 관리에서 확인해 주십시오.