Configure `mongot` for MongoDB Vector Search Automated Embedding

중요

자동 임베딩은 자체 관리형 mongot의 미리보기에 있습니다. 기능 및 해당 설명서는 미리보기 기간 동안 언제든지 변경될 수 있습니다. 자세한 내용은 미리보기 기능을 참조하세요.

이 튜토리얼에서는 자체 관리형 mongot 배포에서 자동 임베딩을 구성하는 방법을 설명합니다. 자동 임베딩을 사용하면 mongot 은 인덱스 시점에 텍스트 데이터에 대한 벡터 임베딩을 생성하고 쿼리 시점에 쿼리 텍스트에 대한 벡터 임베딩을 생성합니다. 애플리케이션에서 별도의 임베딩 파이프라인을 유지할 필요가 없습니다.

This tutorial is for developers who are building semantic search or RAG features and want mongot to manage embeddings. For MongoDB Controllers for Kubernetes Operator deployments, see Automated Embedding.

자동화된 임베딩의 기능

자동 임베딩이 없으면 애플리케이션이 수행해야 할 작업은 다음과 같습니다.

삽입 또는 업데이트하는 각 문서에 대한 임베딩을 생성합니다.
컬렉션의 문서와 함께 임베딩을 저장합니다.
동일한 모델을 사용하여 쿼리 시점에 모든 쿼리에 대한 임베딩을 생성합니다.
쿼리 임베딩을 $vectorSearch에 제출합니다.

자동 임베딩을 사용하면 mongot 이 1, 2, 3 단계를 처리합니다. 애플리케이션:

텍스트 필드에 autoEmbed 필드 유형을 사용하여 MongoDB 벡터 검색 인덱스를 구성합니다.
문서를 일반적으로 삽입하고 업데이트합니다.

mongot 텍스트 필드를 읽고 구성된 임베딩 모델을 통해 임베딩을 생성하며 저장합니다.
미리 계산된 임베딩이 아닌 쿼리 텍스트로 $vectorSearch 쿼리를 실행합니다.

mongot 쿼리 텍스트에 대한 임베딩을 생성합니다.

지원되는 임베딩 제공자

자체 관리형 mongot 자동 임베딩은 Voyage AI 임베딩 모델과 통합됩니다.

모델	설명
`voyage-4`	권장하는 옵션입니다. 일반 텍스트 검색을 위한 균형 잡힌 성능.
`voyage-4-lite`	비용에 민감한 대용량 애플리케이션.
`voyage-4-large`	복잡한 시맨틱 관계에 대한 정확도를 극대화합니다.
`voyage-code-3`	코드 검색 및 기술 문서화에 전문화되어 있습니다.

임베딩 생성에 대한 비용이 발생합니다. 자세한 학습 은 자동 임베딩에 대한 청구 관리를 참조하세요.

전제 조건

자동 임베딩을 사용하려면 다음 사전 요건이 있어야 합니다.

mongot 자체 관리형 배포서버(Community tarball 또는 컨테이너, 지역 개발, Kubernetes Operator를 통한 엔터프라이즈 에디션)에서 1.70.1 이상을 사용합니다.
MongoDB 8.3 or later for standalone and Kubernetes Operator-managed deployments. To learn more, see Compatibility and Requirements for mongot.
Two Voyage AI API keys.

인덱싱 시간 임베딩 생성용 키 하나와 쿼리 시간용 키 하나를 사용하세요. 별도 키는 인덱싱 워크로드에서 쿼리 워크로드를 분리하고 동리적인 요금 한도 계산을 허용합니다. 자세한 학습은 요금 한도를 참조하세요.
mongot 에서 임베딩 엔드포인트로의 외부 네트워크 액세스

The default endpoint is https://ai.mongodb.com/v1/embeddings. This endpoint proxies Voyage AI with MongoDB-managed billing, for keys generated using the Atlas UI. You can also use https://api.voyageai.com/v1/embeddings for direct Voyage AI access if you generated the API key directly from Voyage AI.

절차

Generate Voyage AI API Keys.

You can generate Voyage AI API keys through either of the following methods:

(Recommended) Through your Atlas account. Atlas provides API key management with built-in rate-limit configuration. The keys are not tied to an Atlas cluster. To learn more, see Manage API Keys.
Through Voyage AI directly at voyageai.com.

두 개의 키를 생성하고 이름을 명확히 지정합니다. 예시: mongot-prod-index, mongot-prod-query 키를 보안이 강화된 비밀 저장소에 저장합니다.

Configure `mongot` for Automated Embedding.

구성은 배포 경로에 따라 다릅니다. 배포에 해당하는 탭을 선택하세요.

자동 임베딩에는 preview 지역 개발 이미지(mongodb/mongodb-atlas-local:preview)가 필요합니다. preview 이미지에는 자동 임베딩 통합이 포함된 mongot의 Community 빌드가 포함되어 있습니다.

If you launch the container directly with docker run, pass the Voyage AI API key with the VOYAGE_API_KEY environment variable and use the :preview tag:

docker run \
   -e VOYAGE_API_KEY=<your-voyage-api-key> \
   -p 27017:27017 \
   mongodb/mongodb-atlas-local:preview

Atlas를 통하지 않고 Voyage AI를 통해 직접 Voyage AI 키를 발급한 경우 기본 엔드포인트를 재정의합니다.

docker run \
   -e VOYAGE_API_KEY=<your-voyage-api-key> \
   -e EMBEDDING_PROVIDER_ENDPOINT=https://api.voyageai.com/v1/embeddings \
   -p 27017:27017 \
   mongodb/mongodb-atlas-local:preview

참고

Local Development accepts only a single Voyage AI API key and uses it for both index-time and query-time embedding generation. A single key is acceptable for development. For production deployments that need separate index-time and query-time keys, use the Community Edition or Kubernetes Operator deployment path.

embedding 블록을 mongot 설정 파일에 추가합니다.

embedding:
  queryKeyFile: /etc/mongot/secrets/voyage-api-query-key
  indexingKeyFile: /etc/mongot/secrets/voyage-api-indexing-key
  providerEndpoint: https://ai.mongodb.com/v1/embeddings

Each key file contains the API key as its only content. Set the file permissions to 0600 and set the file owner to the user that runs the mongot process.

자동화된 임베딩 인덱스 만들기.

After you configure mongot with your Voyage AI API keys, define a MongoDB Vector Search index that uses the autoEmbed field type. The index definition specifies which text field mongot embeds and which model it uses. It also specifies the indexing method, quantization, and other parameters.

db.movies.createSearchIndex(
  "movie-semantic-index",
  "vectorSearch",
    {
      "fields": [
        {
          "type": "autoEmbed",
          "modality": "text",
          "path": "plot",
          "model": "voyage-4",
          "numDimensions": 1024,
          "similarity": "cosine",
          "indexingMethod": "hnsw",
          "hnswOptions": {
            "maxEdges": 16,
            "numEdgeCandidates": 50
          },
          "quantization": "scalar"
        },
        {
          "type": "filter",
          "path": "genre"
        }
      ]
    }
)

다음 표에서는 autoEmbed 인덱스 정의 필드에 대해 설명합니다.

필드	목적
`type: "autoEmbed"`	자동 임베딩을 위한 필드를 표시합니다.
`modality: "text"`	데이터 모달리티. `text` 만이 지원되는 모달리티입니다.
`path`	컬렉션에 임베딩할 필드입니다.
`model`	The Voyage AI model name. The model must be one that your API key has access to.
`numDimensions`	임베딩 벡터의 차원 수입니다. 지원되는 차원은 모델에 따라 결정됩니다.
`similarity`	벡터 검색에 사용할 유사성 함수입니다. 지원되는 함수는 `cosine`, `dotProduct`, `euclidean`입니다.
`indexingMethod`	사용할 인덱싱 방법입니다. 지원되는 방법은 `flat` 및 `hnsw`입니다.
`hnswOptions`	(Optional) The HNSW index options. Required if `indexingMethod` is `hnsw`.
`quantization`	(선택 사항) 사용할 양자화 유형. 지원되는 유형은 `float`, `scalar`, `binary`, `binaryNoRescore`입니다.

동일한 인덱스에 autoEmbed 필드와 filter 필드를 혼합할 수 있습니다. 동일한 경로에서 autoEmbed 와 원시 벡터 필드를 혼합할 수 없습니다. 필드당 하나의 접근 방식을 선택합니다.

자동 임베딩 쿼리를 실행합니다.

미리 계산된 임베딩이 아닌 쿼리 텍스트를 제출합니다. mongot 가 사용자를 위해 쿼리 임베딩을 생성합니다.

db.movies.aggregate([
  {
    "$vectorSearch": {
      "index": "movie-semantic-index",
      "path":  "plot",
      "query": "a heist gone wrong in a rainy city",
      "model": "voyage-4",
      "numCandidates": 100,
      "limit": 10
    }
  },
  {
    "$project": {
      "_id":   0,
      "title": 1,
      "score": { $meta: "vectorSearchScore" }
    }
  }
])

더 학습하려면 벡터 검색 근사 최근접 이웃 및 등가 최근접 이웃 쿼리 실행을 참조하세요.

임베딩 저장

mongot 클러스터의 전용 내부 데이터베이스에 임베딩을 유지합니다. mongot 은 소스 컬렉션에 임베딩을 저장하지 않습니다. mongot 은 소스 텍스트에서 임베딩을 다시 생성할 수 있으며, 임베딩 생성에 대한 요금이 부과됩니다.

임베딩 모델, 출력 차원 또는 양자화에 대한 변경은 영향을 받는 인덱스의 전체 재임베딩을 trigger하며, 이로 인해 임베딩 생성에 대한 요금이 발생합니다. mongot 이 임베딩을 다시 생성하는 경우를 참조하세요.

자세한 내용은 생성된 임베딩 컬렉션을 참조하십시오.

When `mongot` Regenerates Embeddings

mongot 다음 중 하나라도 발생하면 autoEmbed 필드에 대한 임베딩을 다시 생성합니다.

문서를 삽입합니다.
문서에서 임베딩된 필드를 변경합니다. mongot 은 change streams를 통해 변경 사항을 감지합니다.
인덱스 정의에서 임베딩 모델을 변경합니다.
임베딩 출력 차원 또는 데이터 유형을 변경합니다.
텍스트 필드 경로를 변경합니다.

마지막 세 항목 중 하나라도 변경하면 mongot 은(는) 전체 인덱스를 처음부터 다시 빌드합니다. 대규모 컬렉션의 경우 재구축 비용이 많이 발생할 수 있습니다. 모델 변경을 신중하게 계획하십시오.

비용 및 속도 제한

MongoDB는 모델 특정 요금으로 백만 토큰당 부과합니다. 인덱싱 비용은 컬렉션의 인덱스 필드의 총 텍스트 볼륨에 비례합니다. 쿼리 비용은 쿼리 텍스트 볼륨에 비례합니다.

If you use the Voyage AI API key that you created using your Atlas account, you can view API key usage and rate limits in the Atlas UI. To learn more, see Manage Billing for the Embedding and Reranking API. If you use keys created directly from Voyage AI, you must monitor your usage and rate limits in the Voyage AI dashboard.

Voyage AI 측 제한 서비스 오류는 mongot 로그에 나타나며 해당 인덱스에 실패한 문서 지표기로 표시됩니다. 이러한 오류로 인덱스가 비활성화되지는 않지만 새 문서 인덱싱이 지연될 수 있습니다.

실패 모드

증상	가능한 원인	작업
인덱스가 수분 동안 `PENDING` 상태로 유지됩니다.	`mongot` cannot reach the embedding endpoint, or the API key is invalid.	임베딩 엔드포인트에 대한 HTTP 오류를 확인하려면 `mongot` 로그를 확인합니다.
인덱싱 지연이 간호적으로 나타납니다.	Voyage AI 측 속도 제한.	요금 한도를 늘리거나 인덱싱 시간 임베딩 부하를 줄이세요.
인덱스에 대한 쿼리는 임베딩을 언급하는 오류를 반환합니다.	The query API key is invalid or expired.	`queryKeyFile`의 내용을 확인합니다.
인덱스에 대한 모든 쿼리는 빈 결과를 반환합니다.	인덱스가 다시 빌드되어 있고 여전히 코퍼스를 다시 임벡딩하고 있을 수 있습니다.	`db.collection.getSearchIndexes()`으로 인덱스 상태를 확인합니다.

제한 사항

자동 임베딩에는 다음과 같은 제한 사항이 적용됩니다.

미리 보기 상태. 자동 임베딩이 일반적으로 사용가능해지기 전에 설정 형상, 지원되는 모델 및 기본 엔드포인트가 변경될 수 있습니다.
필드당 하나의 임베딩 모델. 혼합 모델 인덱스는 지원되지 않습니다.
임베딩 모델 페일오버가 없습니다. Voyage AI 엔드포인트에 액세스할 수 없는 경우, 새 문서의 인덱싱이 중단됩니다.

다음 단계

크로스 플랫폼 개념적 개요에 대한 자동화된 임베딩 개요 를 참조하세요.
전체 mongot 구성 참조를 위해 mongot 구성 합니다.

돌아가기

mongot 구성 참조

인증 및 권한 부여 구성

Configure mongot for MongoDB Vector Search Automated Embedding