콘텐츠로 이동

OpenAI 임베딩 형식

공식 문서

OpenAI Embeddings

📝 소개

입력 텍스트를 머신러닝 모델 및 알고리즘에서 쉽게 활용할 수 있는 벡터 표현으로 변환합니다. 관련 가이드는 Embeddings Guide를 참고하세요.

중요 참고 사항:

  • 일부 모델은 입력의 총 토큰 수에 제한이 있습니다.

  • 토큰 수 계산은 Python 예제 코드를 참고하세요.

  • 예: text-embedding-ada-002 모델은 1536차원 벡터를 출력합니다.

💡 요청 예시

텍스트 임베딩 생성 ✅

curl https://ssanai-workspace.atto-lab.cc/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-ada-002",
    "encoding_format": "float"
  }'

응답 예시:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        // ... (1536 floating point numbers for ada-002)
        -0.0028842222
      ],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

배치 임베딩 생성 ✅

curl https://ssanai-workspace.atto-lab.cc/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "input": ["The food was delicious", "The waiter was friendly"],
    "model": "text-embedding-ada-002",
    "encoding_format": "float"
  }'

응답 예시:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        // ... (1536 floating point numbers)
      ],
      "index": 0
    },
    {
      "object": "embedding",
      "embedding": [
        -0.008815289,
        // ... (1536 floating point numbers)  
      ],
      "index": 1
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

📮 요청

엔드포인트

POST /v1/embeddings

입력 텍스트를 표현하는 임베딩 벡터를 생성합니다.

인증 방법

요청 헤더에 다음 값을 포함하여 API 키 인증을 수행하세요:

Authorization: Bearer $API_KEY

$API_KEY는 발급받은 API 키입니다.

요청 본문 파라미터

input

  • 유형: String 또는 Array
  • 필수: Yes

임베딩할 입력 텍스트입니다. 문자열 또는 토큰 배열 형태로 전달할 수 있습니다. 한 번의 요청에서 여러 입력을 임베딩하려면 문자열 배열 또는 토큰 배열의 배열을 전달하세요. 입력은 모델의 최대 입력 토큰 수(예: text-embedding-ada-002는 8192 토큰)를 초과할 수 없고, 빈 문자열일 수 없으며, 모든 배열 차원은 2048 이하여야 합니다.

model

  • 유형: String
  • 필수: Yes

사용할 모델 ID입니다. 사용 가능한 모델은 List models API에서 확인할 수 있으며, 모델 설명은 모델 개요 문서를 참고하세요.

encoding_format

  • 유형: String
  • 필수: No
  • 기본값: float

임베딩 반환 형식입니다. float 또는 base64를 사용할 수 있습니다.

dimensions

  • 유형: Integer
  • 필수: No

생성되는 임베딩 출력 차원 수입니다. text-embedding-3 이상 모델에서만 지원됩니다.

user

  • 유형: String
  • 필수: No

최종 사용자를 나타내는 고유 식별자입니다. OpenAI의 오남용 모니터링 및 탐지에 도움이 됩니다. 자세히 보기.

📥 응답

성공 응답

임베딩 객체 목록을 반환합니다.

object

  • 유형: String
  • 설명: 객체 타입, 값은 "list"

data

  • 유형: Array
  • 설명: 임베딩 객체를 포함하는 배열
  • 속성:
  • object: 객체 타입, 값은 "embedding"
  • embedding: 임베딩 벡터(부동소수점 숫자 목록). 벡터 길이는 모델에 따라 다름
  • index: 목록 내 임베딩 인덱스

model

  • 유형: String
  • 설명: 사용된 모델 이름

usage

  • 유형: Object
  • 설명: 토큰 사용 통계
  • 속성:
  • prompt_tokens: 프롬프트에 사용된 토큰 수
  • total_tokens: 총 토큰 수

임베딩 객체

임베딩 엔드포인트가 반환하는 임베딩 벡터 객체입니다.

{
  "object": "embedding",
  "embedding": [
    0.0023064255,
    -0.009327292,
    // ... (1536 floating point numbers total for ada-002)
    -0.0028842222
  ],
  "index": 0
}

index

  • 유형: Integer
  • 설명: 목록 내 임베딩 인덱스

embedding

  • 유형: Array
  • 설명: 임베딩 벡터(부동소수점 숫자 목록). 벡터 길이는 모델에 따라 다르며, 자세한 내용은 Embeddings 가이드를 참고하세요.

object

  • 유형: String
  • 설명: 객체 타입, 항상 "embedding"

오류 응답

요청 처리 중 문제가 발생하면 API는 4XX-5XX 범위의 HTTP 상태 코드와 함께 오류 응답 객체를 반환합니다.

주요 오류 상태 코드

  • 401 Unauthorized: API 키가 유효하지 않거나 누락됨
  • 400 Bad Request: 빈 입력, 토큰 제한 초과 등 잘못된 요청 파라미터
  • 429 Too Many Requests: API 호출 한도 초과
  • 500 Internal Server Error: 서버 내부 오류

오류 응답 예시:

{
  "error": {
    "message": "The input exceeds the maximum length. Please reduce the length of your input.",
    "type": "invalid_request_error",
    "param": "input",
    "code": "context_length_exceeded"
  }
}