API 임베딩 및 순위 재지정 개요

API 키 관리

MongoDB Atlas 사용하여 Embedding 및 Reranking API 에 대한 API 키를 관리 . 여기에는 조직 및 프로젝트 전반에서 모델 API 키 생성 및 관리, 사용량 모니터링 , 속도 제한 구성이 포함됩니다.

자세한 학습 은 ManageVoyage AI Model API Keys(Voyage AI 모델 API 키 관리)를 참조하세요.

인증

Embedding and Reranking API 에 대한 모든 요청에는 베어러 토큰 형식을 사용하는 모델 API 키와 함께 Authorization 헤더가 포함되어야 합니다.

Authorization: Bearer VOYAGE_API_KEY

클라이언트 SDK를 사용하는 경우 클라이언트 구성할 때 API 키를 설정하다 SDK가 모든 요청 에 대해 사용자를 대신하여 헤더를 전송합니다. API 와 직접 통합하는 경우 이 헤더를 직접 보내야 합니다.

엔드포인트

모델 API 키의 범위에 따라 요청을 보내는 엔드포인트가 결정됩니다. 지역으로 범위가 지정된 키는 해당 지역의 엔드포인트에 대해서만 작동하며, 범위가 지정되지 않은 키는 범위가 지정되지 않은 엔드포인트에 대해 작동합니다.

범위가 지정된 엔드포인트는 <geography>.ai.mongodb.com 패턴 따르며, 여기서 <geography> 은 요청 과 함께 전송하는 모델 API 키의 geography 값입니다.

범위가 지정된 키를 범위와 일치하지 않는 엔드포인트에 보내면 요청 이 실패합니다. Atlas 키와 일치하는 엔드포인트로 요청 다시 라우팅하지 않습니다.

범위가 지정된 엔드포인트는 다음과 같은 점에서 범위가 지정되지 않은 엔드포인트와 다릅니다.

• Atlas 범위가 지정된 엔드포인트로 전송하는 토큰에 10% 업리프트를 청구합니다.

• 범위가 지정된 엔드포인트에는 유료 사용 계층 이 필요하며 사용 계층 에서 1 시작합니다. 범위가 지정된 엔드포인트로 더 높은 사용량 계층 사용하려면 계정 팀 문의 . 사용 티어에 대해 자세히 학습 사용 티어를 참조하세요.

• 범위가 지정된 엔드포인트에는 자체 속도 제한이 있으며, 이는 범위가 지정되지 않은 엔드포인트보다 낮습니다. 자세한 학습 은 지리적 속도 제한을 참조하세요.

• 범위가 지정된 엔드포인트는 모든 모델을 제공 하지 않습니다. 특정 모델을 제공 엔드포인트를 확인하려면 모델 사용 중단, 수명 주기 상태 및 지원에 있는 모델 표의 지원되는 엔드포인트 열을 참조하세요.

지리란 무엇이며 언제 사용해야 하는지 학습 지리 for Voyage AI 추론을 참조하세요.

JSON

모든 엔터티는 JSON 으로 표시됩니다. 다음 규칙과 관례가 적용됩니다.

콘텐츠 유형 요청 헤더

게시 요청 사용하여 서버 에 JSON 보낼 때 Content-Type: application/json 헤더를 지정합니다. 클라이언트 SDK는 이를 자동으로 처리하다 .

유효하지 않은 요청

잘못된 JSON, 잘못된 데이터 유형 또는 제약 조건 위반(예: 토큰 제한 또는 배치 크기 초과)을 사용하여 요청 생성하려고 하면 서버 400 상태 코드와 문제를 설명하는 오류 메시지로 응답합니다.

숫자가 포함된 필드의 필드 이름

숫자 값이 포함된 필드에는 사용 중인 단위를 명확하게 하기 위해 이름이 지정됩니다. 예시 를 들어 토큰 수는 측정 단위를 명확히 하기 위해 total_tokens 및 output_dimension 같은 필드에 지정됩니다.

요금 한도 및 사용 계층

Embedding and Reranking API 공정한 사용과 최적의 성능을 보장하기 위해 속도 제한을 구현합니다. 속도 제한은 API 키별로 적용되며 2차원으로 측정됩니다. 사용 계층을 올라갈수록 요금 한도가 증가합니다.

• TPM(Tokens Per Minute): 분당 처리되는 최대 토큰 수

• RPM (Requests Per Minute): 분당 최대 API 요청 수

속도 제한을 초과하면 API 429 (Rate Limit Exceeded) HTTP 상태 코드를 반환합니다.

사용 계층에 대해 자세히 학습하려면 사용 계층을 참조하세요.

조직 에 대한 사용자 지정 속도 제한을 설정하다 하려면 Atlas UI 사용합니다. 자세한 학습 은 요금 제한 관리를 참조하세요.

요청하기

다음 예시 cURL 를 사용하여 임베딩 서비스에 요청 하는 방법을 보여 줍니다. 또한 모든 프로그래밍 언어 로 작성된 HTTP 클라이언트 사용하여 API 에 액세스 할 수 있습니다.

추가 사용 예시는 다음 리소스를 참조하세요.

• HTTP 요청 및 클라이언트 SDK 예시를 위한 Voyage AI 모델에 액세스

• 모델 별 사용을 위한 모델 페이지입니다.

• 모든 API엔드포인트에 대한 자세한 내용은 API 사양을 참조하세요.

curl \
  --request POST 'https://ai.mongodb.com/v1/embeddings' \
  --header "Authorization: Bearer $VOYAGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "input": [
      "MongoDB is redefining what a database is in the AI era.",
      "Voyage AI embedding and reranking models are state-of-the-art."
    ],
    "model": "voyage-4-large"
  }'

오류

API 에서 반환되는 오류에 대해 자세히 학습하려면 API 사양을 참조하세요.

모범 사례

API 사용할 때 다음 권장사항 고려하세요.

python -c "import voyageai; print(voyageai.__version__)"