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

API 키 관리

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

자세한 학습은 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부터 시작합니다. 범위가 지정된 엔드포인트에서 더 높은 사용 계층을 사용하려면 계정 팀에 문의하세요. 사용 계층에 대해 자세히 학습하려면 사용 계층을 참조하세요.

• 스코프 엔드포인트에는 고유의 레이트 제한이 있으며, 이는 비스코프 엔드포인트의 레이트 제한보다 낮습니다. 더 자세히 알아보려면 지리 제한 속도를 참조하세요.

• 범위가 지정된 엔드포인트는 모든 모델을 제공하지 않습니다. 특정 모델을 제공하는 엔드포인트를 확인하려면 Model Deprecations, Lifecycle States, and Support의 모델 테이블에 있는 지원되는 엔드포인트 열을 참조하세요.

Geography가 무엇인지 그리고 언제 사용해야 하는지 학습하려면 Voyage AI Inference용 Geography를 참조하세요.

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"
  }'

오류

To learn more about errors returned by the API, see the API specification.

모범 사례

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

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