임베딩 API 사용법 임베딩 API는 문자열을 부동소수점 벡터로 바꿔 관련성을 거리로 측정합니다. 거리가 짧으면 주가깝고 길면 주멀다고 해석합니다. 검색과 RAG 파이프라인을 붙이기 전에 모델 이름과 입력 한도, 인증 헤더를 함께 익혀 두는 것이 안전합니다.
OpenAI embeddings 호출은 POST https://api.openai.com/v1/embeddings로 보냅니다. 인증은 Authorization 헤더에 Bearer와 API 키 또는 액세스 토큰을 넣습니다. 필수 값은 model과 input이며 한도와 차원을 지키면 오류를 줄일 수 있습니다. 워크로드 토큰도 같은 Bearer 헤더로 전달합니다.
임베딩 API란 무엇인가요
텍스트 임베딩은 문장을 부동소수점 벡터로 바꿔 비슷한 뜻을 가까운 좌표에 놓습니다. OpenAI는 작은 거리를 높은 관련성으로 보고 큰 거리를 낮은 관련성으로 설명합니다. 벡터 한 줄이 곧 그 문장의 위치가 되므로 검색은 좌표 비교로 줄어듭니다.
이 값이 있어야 코사인 유사도로 문서를 고를 수 있습니다. RAG 파이프라인은 고른 조각을 프롬프트에 붙여 답을 만들므로 임베딩이 검색 품질에 바로 이어집니다. 질문과 문서는 같은 모델로 바꿔야 거리 비교가 맞습니다.
긴 글은 문단 단위로 나눈 뒤 각각 벡터로 바꿉니다. 빈 제목이나 빈 본문은 요청에 넣지 마십시오. 모델이 바뀌면 점수 범위도 달라지므로 인덱스와 질의는 항상 한 모델로 맞춥니다.
요청·응답 구조와 주요 파라미터
(출처: 모두의AI)
호출은 POST 한 번이며 본문에는 model과 input이 들어갑니다. input은 문자열 하나이거나 문자열 또는 토큰 배열이며 빈 문자열은 보낼 수 없습니다. 배열로 보낼 때도 항목마다 내용이 있어야 하며 공백만 있는 값은 받아 주지 않습니다.
응답은 object 값이 list인 JSON입니다. data 배열의 embedding과 model, usage의 prompt_tokens와 total_tokens가 함께 돌아옵니다. 인덱스를 저장할 때는 이 벡터와 모델 이름을 한 세트로 보관하면 나중에 질의 임베딩과 맞춰 쓰기 쉽습니다.
여러 문장을 한 요청에 넣으면 응답 data의 index로 입력 순서와 벡터를 짝지으십시오. 사용량 집계는 usage 필드의 total_tokens로 확인하면 청구 단위를 따라가기 쉽습니다.
| 항목 | 규정 |
|---|---|
| 엔드포인트 | POST /v1/embeddings |
| 필수 값 | model, input |
| 항목 토큰 | 8192 |
| 요청 합산 토큰 | 300,000 |
| 배열 길이 | 2048개 이하 |
| 3-small 기본 차원 | 1536 |
| 3-large 기본 차원 | 3072 |
모델·차원·입력 길이 선택
text-embedding-3-small의 기본 길이는 1536이고 text-embedding-3-large는 3072입니다. dimensions는 text-embedding-3 이후 모델만 받으며 길이를 줄일 때 씁니다. encoding_format은 float 또는 base64 중에서 고르십시오.
항목당 한도는 8192 토큰이고 요청 합산은 300,000 토큰입니다. 배열은 2048개 이하로 자르고 긴 문서는 미리 나눠 보내는 편이 안전합니다. 한도를 넘기면 응답 벡터가 비는 것이 아니라 요청 자체가 실패합니다.
차원을 줄이면 저장 용량은 낮아지지만 가까운 문서와 먼 문서를 가르는 힘이 약해질 수 있습니다. 서비스에 쓰는 길이를 정한 뒤에는 질의와 문서에 같은 값을 유지하십시오.
언어별 호출 예제와 인증 설정
인증 헤더는 Authorization 뒤에 Bearer와 API 키 또는 액세스 토큰을 붙입니다. curl은 -H로 헤더를 넣고 JSON 본문에 model과 input을 담아 POST합니다. 키를 소스에 직접 쓰지 말고 환경 변수로 읽으면 유출 위험을 낮출 수 있습니다.
Python은 openai 패키지의 embeddings 생성 함수에 같은 인자를 넘깁니다. Node 환경도 공식 SDK의 embeddings 메서드에 model과 input을 넣으면 동일한 JSON 응답을 받습니다. 로컬 시험과 서버 배포에서 키 이름을 같게 두면 설정 실수를 줄일 수 있습니다.
헤더 이름이 틀리거나 Bearer 접두가 빠지면 인증 단계에서 막힙니다. 본문 Content-Type은 application/json으로 맞추십시오.
오류 코드와 재시도 처리
한도를 넘기거나 빈 문자열을 넣으면 요청을 받아 주지 않습니다. 429나 5xx가 나오면 잠시 기다렸다가 같은 본문으로 다시 보내는 재시도가 필요합니다. 즉시 재시도만 반복하면 한도 창이 더 막힐 수 있으니 간격을 늘리는 편이 낫습니다.
입력 배열을 쪼개 요청당 합산 토큰을 300,000 아래로 맞추면 반복 실패를 줄일 수 있습니다. 항목이 8192 토큰을 넘으면 문장을 자른 뒤 각각 임베딩하고 검색 단위도 그 조각에 맞춥니다. 실패 본문을 로그에 남기면 빈 값과 과다 토큰을 빨리 가려낼 수 있습니다.
401은 키와 권한을 다시 확인하고 400은 input 형식을 점검하십시오. 재시도 횟수를 정해 두면 장애가 검색 전체에 퍼지는 시간을 줄일 수 있습니다.
검색·유사도·RAG에 적용하는 방법
문서와 질문을 같은 모델로 임베딩한 뒤 코사인 유사도로 가까운 조각을 고릅니다. 고른 조각을 프롬프트에 붙여 답하게 하는 흐름이 RAG 파이프라인입니다. 벡터 검색 인덱스에 넣을 때도 차원 수와 모델 이름을 함께 기록해야 질의 벡터를 같은 공간에 맞출 수 있습니다.
유사도 임계값을 정해 너무 먼 조각은 프롬프트에 넣지 않으면 헛답이 줄어듭니다. 청크 길이는 항목당 8192 토큰 한도 안에서 문단 단위로 자르는 것이 관리에 유리합니다. 재임베딩 없이 모델만 바꾸면 거리가 어긋나므로 인덱스 전체를 다시 만들어야 합니다.
상위 k개만 가져와 컨텍스트 길이를 맞추면 생성 모델 한도도 지키기 쉽습니다. 동일 문서를 중복으로 넣지 않도록 조각 식별자를 저장해 두십시오. 질문 임베딩도 문서와 같은 dimensions 값을 써야 코사인 계산이 맞습니다.
임베딩 API 사용 정리
호출 주소와 Bearer 인증, model과 input 필수 값, 토큰과 배열 한도를 먼저 고정하십시오. 차원은 3-small 1536, 3-large 3072를 기준으로 두고 필요하면 dimensions로 줄입니다. encoding_format은 float 또는 base64 중 저장 형식에 맞게 고르십시오.
검색과 RAG는 같은 모델의 벡터와 코사인 유사도로 연결합니다. 오류가 나면 빈 입력과 합산 토큰부터 확인하고 429에는 간격을 둔 재시도를 적용하십시오. 모델 이름을 인덱스 메타데이터에 남기면 나중에 질의 경로를 같은 설정으로 맞출 수 있습니다.
운영 중에는 입력 길이 분포와 실패 비율을 주기적으로 보면 한도 초과를 일찍 발견할 수 있습니다. 키 순환 뒤에도 헤더 형식을 그대로 유지하면 인증 오류를 줄일 수 있습니다.
