본문으로 건너뛰기

Embeddings

검색과 유사도 계산을 위한 텍스트 벡터 변환

스트리밍을 지원하지 않는 단일 및 다중 입력 요청의 형식, 벡터 응답, 입력 한도와 차원 지정 조건을 설명합니다.

페이지 목차
POST
https://gw.letsur.ai/v1/embeddings
인증Authorization: Bearer <API_KEY>

지원 범위

이 엔드포인트는 텍스트를 임베딩 벡터로 변환합니다. 요청에는 에셋의 임베딩 모델 코드를 사용합니다. 결과를 응답으로 즉시 반환하는 동기 호출이며, 스트리밍은 지원하지 않습니다. 다른 API 형식과의 차이는 API 형식 선택에 있습니다.

요청 필드

기본값 칸의 -는 기본값이 명시되지 않았다는 뜻입니다.

필드타입요구 여부기본값설명
modelstring필수-에셋에 표시된 임베딩 모델 코드
inputstring | array필수-단일 문자열 또는 입력 배열
encoding_formatstring선택floatfloat 또는 base64
dimensionsinteger선택모델별출력 차원 (모델이 지원할 때만)

위 표의 선택 파라미터는 지원 여부와 허용 값이 모델마다 다릅니다. 지원 여부는 에셋 화면의 표시값에서 확인합니다.

입력 제약

입력 토큰 한도, 입력 배열의 최대 항목 수와 한 요청의 총 토큰 한도는 모델마다 다릅니다. 한도는 에셋 화면의 표시값에서 확인합니다. 필요한 한도가 표시되지 않았거나 뜻이 불분명하면 그 페이지에 안내된 문의 방법을 따르세요.

요청이 한도 초과로 거절되면 HTTP 상태와 응답의 type, detail을 확인하고 입력 길이나 배열 크기를 조정합니다. 한도를 초과했을 때 항상 같은 오류 코드가 반환된다고 가정하지 않습니다.

dimensions

차원은 임베딩 벡터를 이루는 숫자의 개수입니다. dimensions를 지원하는 모델에서는 이 필드로 개수를 낮춰 저장 공간과 검색 계산량을 줄일 수 있습니다. dimensions는 선택한 모델의 지원 여부와 허용 값을 확인한 경우에만 지정합니다.

client.embeddings.create( model="<MODEL_CODE>", input="안녕", dimensions=512, # 선택한 모델에서 지원을 확인한 값으로 변경 )

지원 여부를 확인하지 못했다면 dimensions를 생략합니다. 값을 지정했다면 응답 벡터의 차원이 의도한 값인지 확인하세요. 요청이 거절되면 응답 상세에 따라 필드를 수정합니다. 지원하지 않는 값이 자동으로 무시된다고 가정하지 않습니다.

응답 (200)

임베딩 호출은 동기 호출이므로 결과가 이 응답으로 즉시 반환됩니다. 입력 한도는 입력 제약에서 확인합니다.

아래 벡터는 구조를 보여 주기 위해 두 값만 남긴 예시입니다. 실제 벡터의 길이는 모델과 dimensions 설정에 따라 달라집니다.

{ "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [0.001, -0.024] } ], "model": "<MODEL_CODE>", "usage": { "prompt_tokens": 5, "total_tokens": 5 }, "estimated_cost": { "amount": "0.00000010", "currency": "unit", "disclaimer": "Estimated based on published pricing. Actual charges may differ." } }
필드설명
data[].embeddingfloat 배열입니다 (encoding_format이 base64면 base64 문자열). 순서는 input 배열 순서를 따릅니다
usage.prompt_tokens입력 토큰 수입니다 (출력 토큰 없음)
estimated_cost응답 최상위의 호출별 비용 객체입니다. 의미와 null 처리 기준은 요청별 비용을 따릅니다

요청과 응답 예시

아래 예제는 실행 환경의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행 방법은 첫 API 호출에 있습니다.

SDK 예제에서는 자동 재시도를 끕니다. timeout이나 응답 유실 뒤의 재전송 여부는 오류와 복구의 기준에 따라 판단합니다.

cURL
curl https://gw.letsur.ai/v1/embeddings \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_CODE>", "input": "안녕" }'

여러 입력을 한 요청으로 보내기

input에 배열을 지정하면 여러 문장의 임베딩 벡터를 한 요청으로 받을 수 있습니다.

response = client.embeddings.create( model="<MODEL_CODE>", input=["문장 1", "문장 2", "문장 3"], ) vectors = [item.embedding for item in response.data] # vectors[0]은 "문장 1"의 임베딩, vectors[1]은 "문장 2", ...

이 예제는 여러 입력을 배열로 지정해 한 번의 동기 요청으로 보냅니다. JSONL 파일을 업로드하고 작업 ID로 조회하는 별도의 비동기 Batch 처리와 구분하세요. 실제 비용은 입력 사용량과 현재 모델 단가를 기준으로 확인합니다.

오류와 복구

응답을 받지 못한 요청을 다시 보내면 추가 비용이 생길 수 있습니다

timeout이나 응답 유실 뒤 같은 요청을 다시 보내면 별도 호출로 처리됩니다. 다시 보내기 전에 동기 호출의 재시도와 비용 확인에 따라 원래 호출과 새 호출을 구분하세요. 배열 입력도 한 번의 동기 호출이므로 Batch의 중복 방지 방식이 적용되지 않습니다.

이 엔드포인트에서 주로 확인할 오류와 대응은 다음과 같습니다. 인증과 월 사용 한도 같은 공통 오류는 오류 코드와 한도에서 확인합니다.

오류의미와 대응
model_not_found (404)에셋 목록에 없는 모델입니다. 대응: 에셋에서 모델 코드와 Embeddings 지원 여부를 다시 확인합니다.
context_length_exceeded (400)입력이 모델의 토큰 한도를 초과했습니다. 대응: 입력을 더 짧은 단위로 나누고 한 요청에 보내는 입력의 총량을 확인합니다.
invalid_parameter (400)요청 파라미터가 거절됐습니다. 대응: 응답의 detail과 모델의 지원 조건을 확인해 필드나 값을 수정합니다.