AI 에이전트의 경우: 문서 인덱스는 https://www.mongodb.com/ko-kr/docs/llms.txt에서 사용할 수 있으며, 모든 페이지의 마크다운 버전은 어떤 URL 경로에 .md를 추가하여 사용할 수 있습니다.
Docs Menu

Voyage AI 모델에 액세스

MongoDB Atlas 통해 제공되는 임베딩 및 리랭킹 API 사용하여 Voyage AI 모델에 액세스 할 수 있습니다. 다음 방법을 사용하여 API 에 액세스 .

이 페이지에는 API 액세스 방법이 요약되어 있습니다. 요금 제한 및 사용 계층을 포함하여 API 에 대한 자세한 내용은 API 참조를 참조하세요.

Embedding and Reranking API API 키를 사용하여 사용량을 모니터 하고 권한을 관리 . 모델 API 키를 생성하고 관리 하려면 MongoDB Atlas UI 사용합니다. 지침은 Voyage AI 모델 API 키 관리를 참조하세요.

다음 예제는 REST API 통해 임베딩 서비스를 호출하는 방법을 보여줍니다. API 모든 프로그래밍 언어 의 cURL 및 HTTP 요청을 지원합니다.

인증은 모델 API 키를 통해 처리되며, 이 키를 모든 API 요청의 권한 부여 헤더에 베어러 토큰으로 포함해야 합니다.

자세한 학습 은 전체 API 사양을 참조하세요.

참고

공개 미리보기

유럽 지리 및 해당 엔드포인트인 eu.ai.mongodb.com는 공개 미리 보기 기능 으로 사용할 수 있습니다. 기능 및 해당 설명서는 미리 보기 기간에 언제든지 변경될 수 있습니다.

모델 API 키 범위가 지리로 지정된 경우 ai.mongodb.com 대신 해당 지리의 엔드포인트로 요청을 보냅니다. 요청 본문, 헤더 및 응답 형식은 변경되지 않습니다. 호스팅하다 만 변경됩니다.

엔드포인트
지리

ai.mongodb.com

범위 없음. Atlas 모든 지리적 위치에서 요청 제공 할 수 있습니다.

eu.ai.mongodb.com

유럽

us.ai.mongodb.com

미국

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

앞의 예제 중 하나를 적용하려면 요청 URL 에서 호스팅하다 바꿉니다. 예시 를 들어 유럽으로 범위가 지정된 키는 다음 URL 사용하여 임베딩을 생성합니다.

https://eu.ai.mongodb.com/v1/embeddings

범위가 지정된 키는 일치하는 엔드포인트에 대해서만 작동합니다. 유럽 범위 키를 us.ai.mongodb.com 또는 ai.mongodb.com로 보내지 못합니다.

지리란 무엇이며 키 범위를 지정해야 하는 경우에 대해 학습 지리 forVoyage AI 추론을 참조하세요.

pip을(를) 사용하여 공식 Python 패키지 설치하려면 다음을 수행합니다.

pip install --upgrade voyageai

--upgrade 또는 -U 옵션을 사용하여 최신 버전의 패키지 설치합니다. 이를 통해 최신 기능 및 버그 수정에 액세스 할 수 있습니다. 모델별 매개변수는 각 모델 페이지의 사용 예시를 참조하세요.

중요

Python 클라이언트 라이브러리의 버전 0.3.7 이상을 사용해야 합니다. 이 버전에는 Embedding 및 Reranking API 에 대한 지원 추가됩니다.

voyageai.Client 클래스는 Voyage의 API 호출하기 위한 동기 인터페이스를 제공합니다. 클라이언트 객체 생성하고 이를 사용하여 Voyage AI 모델에 액세스 .

예시

다음 예시 사용자 지정 설정으로 클라이언트 초기화하고 임베딩을 생성하는 방법을 보여줍니다.

import voyageai
# Initialize the client with custom settings
vo = voyageai.Client(
api_key="<model-api-key>", # Or use VOYAGE_API_KEY environment variable
max_retries=3, # Retry up to 3 times on rate limit errors
timeout=30 # Timeout after 30 seconds
)
# Generate embeddings
result = vo.embed(
texts=["MongoDB is redefining what a database is in the AI era."],
model="voyage-4-large"
)
print(f"Embedding dimension: {len(result.embeddings[0])}")
print(f"Total tokens used: {result.total_tokens}")

다음 표에서는 클라이언트 초기화할 때 전달할 수 있는 매개변수에 대해 설명합니다.

Parameter
유형
필수 사항
설명

api_key

문자열

No

모델 API 키입니다. 기본값은 없음입니다.

없음인 경우 클라이언트 다음 순서로 API 키를 검색합니다.

  • voyageai.api_key_path, 키가 포함된 파일 의 경로

  • 키가 포함된 파일 의 경로로 설정하다 수 있는 환경 변수 VOYAGE_API_KEY_PATH

  • voyageai.api_key키를 저장 데 사용할 수 있는 voyageai 모듈의 속성입니다.

  • 환경 변수 VOYAGE_API_KEY

참고: Python 클라이언트 는 API 키 형식에 따라 요청을 올바른 API 엔드포인트로 자동 라우팅합니다.

  • MongoDB Atlas 에서 생성된 모델 API 키ai.mongodb.com 엔드포인트로 라우팅됩니다.

  • 지리적으로 범위가 지정된 모델 API 키는 eu.ai.mongodb.com 와 같이 해당 지리적 엔드포인트로 경로를 지정합니다.

  • Voyage 플랫폼에서 생성된 API 키는 api.voyageai.com 엔드포인트로 라우팅됩니다.

클라이언트 만들 때 base_url 매개 변수를 설정하여 이 동작을 재정의할 수 있습니다.

max_retries

Integer

No

속도 제한 오류 또는 일시적으로 서버 사용할 수 없는 경우 각 API 요청 에 대한 최대 재시도 횟수입니다. 기본값은 0입니다.

클라이언트 대기 후 재시도 전략을 사용하여 이러한 오류를 처리하다 하고 최대 재시도 제한에 도달하면 예외를 발생시킵니다. 기본값 으로 클라이언트 재시도하지 않습니다.

timeout

Integer

No

요청 중단하기 전에 API 의 응답을 기다리는 최대 시간(초)입니다. 기본값은 없음입니다.

지정된 시간 초과를 초과하면 요청 종료되고 시간 초과 예외가 발생합니다. 기본값 으로 시간 초과 제약 조건이 적용되지 않습니다.

base_url

문자열

No

API 요청에 대한 사용자 지정 기본 URL . 기본값 으로 클라이언트 제공된 API 키를 기반으로 올바른 엔드포인트를 자동으로 감지합니다.

npm을(를) 사용하여 공식 TypeScript 패키지 설치하려면 다음을 수행합니다.

npm install voyageai

VoyageAIClient 클래스는 TypeScript 및 JavaScript 애플리케이션에서 Voyage의 API 호출하기 위한 비동기 인터페이스를 제공합니다. 클라이언트 객체 생성하고 이를 사용하여 Voyage AI 모델에 액세스 .

Python 클라이언트 와 달리 TypeScript 클라이언트 기본값 으로 요청을 Voyage 플랫폼 엔드포인트()로 보냅니다.https://api.voyageai.com/v1 모델 API 키와 함께 Embedding 및 Reranking API 사용하려면 environment https://ai.mongodb.com/v1 클라이언트 생성할 때 옵션을 로 설정하다 .

예시

다음 예시 Embedding 및 Reranking API 에 대한 클라이언트 초기화하고 임베딩을 생성하는 방법을 보여 줍니다.

import { VoyageAIClient } from "voyageai";
// Initialize the client for the Embedding and Reranking API
const client = new VoyageAIClient({
apiKey: process.env.VOYAGE_API_KEY, // Model API key
environment: "https://ai.mongodb.com/v1",
maxRetries: 3, // Retry up to 3 times
timeoutInSeconds: 30 // Time out after 30 seconds
});
// Generate embeddings
const result = await client.embed({
input: ["MongoDB is redefining what a database is in the AI era."],
model: "voyage-4-large"
});
console.log(`Embedding dimension: ${result.data[0].embedding.length}`);
console.log(`Total tokens used: ${result.usage.totalTokens}`);

다음 표에서는 클라이언트 초기화할 때 전달할 수 있는 옵션에 대해 설명합니다.

옵션
유형
필수 사항
설명

apiKey

문자열

모델 API 키입니다. 이 옵션을 설정하다 하지 않으면 클라이언트 는 VOYAGE_API_KEY 환경 변수를 사용합니다.

environment

문자열

No

API 요청의 기본 URL . 기본값은 Voyage 플랫폼 엔드포인트인 https://api.voyageai.com/v1입니다. Embedding and Reranking API 사용하려면 이 옵션을 https://ai.mongodb.com/v1 로 설정합니다.

maxRetries

번호

No

속도 제한 오류 또는 일시적으로 서버 사용할 수 없는 경우 각 API 요청 에 대한 최대 재시도 횟수입니다. 기본값은 2입니다.

클라이언트 대기 후 재시도 전략을 사용하여 이러한 오류를 처리하다 하고 최대 재시도 제한에 도달하면 예외를 발생시킵니다.

timeoutInSeconds

번호

No

요청 중단하기 전에 API 의 응답을 기다리는 최대 시간(초)입니다. 기본값은 60입니다.

요청 이 지정된 제한 시간을 초과하면 클라이언트 요청 종료하고 제한 시간 예외를 발생시킵니다.

headers

객체

No

모든 API 요청 과 함께 보낼 추가 HTTP headers .

embed클라이언트 외에도,rerank multimodalEmbedcontextualizedEmbed 메서드를 제공합니다. 모델별 매개변수는 각 모델 페이지의 사용 예시를 참조하세요.