/ /

`$vectorSearch` 애그리게이션 단계

정의

$vectorSearch 단계는 MongoDB 벡터 검색 쿼리 결과로 각 스트리밍 문서를 보강합니다. 각 입력 문서에 대해 이 단계는 컬렉션에 대해 $vectorSearch 쿼리를 실행하고 지정한 필드에 결과를 추가합니다.

배치

$vectorSearch 파이프라인의 중간 단계여야 합니다. 파이프라인의 $source 또는 싱크로 사용하지 마십시오.

구문

$vectorSearch 파이프라인 단계의 프로토타입 형식은 다음과 같습니다.

{
  "$vectorSearch": {
    "from": {
      "connectionName": "<registered-atlas-connection>",
      "db": "<database>",
      "coll": "<collection>"
    },
    "as": "<output-field>",
    "queryVector": [<number>, ...] | <expression>,
    "query": {
      "text": "<string>" | <expression>
    },
    "model": "<embedding-model>",
    "index": "<vector-index-name>",
    "path": "<field-containing-vectors>",
    "numCandidates": <int>,
    "limit": <int>,
    "filter": { ... },
    "exact": <bool>,
    "searchNodePreference": {
      "key": "<preference>"
    },
    "pipeline": [ { $<aggregation-stage>: { ... } }, ... ],
    "let": {
      "<variable>": <expression>,
      . . .
    }
  }
}

$vectorSearch 단계에서는 다음 필드가 있는 문서를 사용합니다.

필드	유형	필요성	설명
`from`	문서	필수 사항	각 입력 문서에 대해 `$vectorSearch`이(가) 쿼리하는 대상 Atlas 컬렉션을 지정하는 문서입니다.
`from.connectionName`	문자열	필수 사항	연결 레지스트리에 있는 Atlas 연결 이름입니다. Atlas Stream Processing은 파스 시간에 다른 연결 유형을 거부합니다.
`from.db`	리터럴 string	필수 사항	대상 데이터베이스의 이름입니다.
`from.coll`	리터럴 string	필수 사항	MongoDB 벡터 검색 인덱스가 포함된 대상 컬렉션의 이름입니다.
`as`	문자열	필수 사항	검색 결과 배열을 위한 스트리밍 문서의 출력 필드입니다. MongoDB 벡터 검색이 일치하는 문서를 반환하지 않으면 Atlas Stream Processing은 이 필드를 빈 배열로 설정합니다. 경고: 이 필드가 비어 있거나 스트림 메타데이터 필드 이름과 충돌되면 Atlas Stream Processing은 시작 시간에 `StreamProcessorInvalidOptions` 오류를 보고합니다.
`queryVector`	배열 \| 필드 경로 표현식	조건부	일치하는 문서를 검색 위한 명시적 벡터 임베딩입니다.
`query`	문서	조건부	자동 임베딩을 위한 텍스트 쿼리 지정하는 문서입니다.
`query.text`	string \| 필드 경로 표현식	조건부	자동 임베딩에 사용할 쿼리 텍스트.
`model`	문자열	옵션	`query.text`을 벡터로 변환하기 위해 MongoDB 벡터 검색이 사용하는 임베딩 모델. `query`와 함께 사용할 경우에만 유효합니다. `model`를 생략하면 MongoDB Vector Search는 대상 MongoDB Vector Search 인덱스의 정의에 구성된 모델을 사용합니다.
`index`	문자열	필수 사항	쿼리할 MongoDB Vector Search 인덱스의 이름입니다.
`path`	문자열	필수 사항	검색할 벡터 임베딩이 포함된 대상 컬렉션의 필드입니다.
`numCandidates`	int	조건부	MongoDB Vector Search가 검색 중에 고려하는 후보의 수입니다. `exact`이(가) `true`이(가) 아닌 경우 필수입니다. 값을 선택하는 방법을 학습 numCandidates 선택을 참조하세요.
`limit`	int	필수 사항	반환할 최대 결과 수입니다. `numCandidates`을 초과할 수 없습니다. 경고: `limit`이 `numCandidates`를 초과하면 모든 문서가 `PlanExecutor` 오류로 실행 시간에 실패합니다.
`filter`	문서	옵션	벡터 검색 전에 적용 할 사전 필터 표현식 . 지원되는 연산자는 필터를 참조하세요. 경고: `filter` 에서 지원되지 않는 연산자 사용하는 경우 모든 문서 런타임에 `PlanExecutor` 오류와 함께 실패합니다.
`exact`	부울	옵션	ANN 또는 ENN 검색 실행 할지 여부를 지정하는 플래그입니다. `numCandidates`를 생략한 경우 이 필드 제공합니다. 값은 다음 중 하나일 수 있습니다. `false` ANN 검색 실행 하려면 `true` ENN 검색 실행 하려면 기본값은 `false`입니다.
`searchNodePreference`	문서	옵션	Atlas Stream Processing이 특정 검색 노드로 쿼리를 라우팅하는 데 사용하는 `key` 필드가 있는 문서입니다. `key` 값은 비어 있는 string이어야 합니다.
`pipeline`	배열	옵션	Atlas Stream Processing이 검색 결과를 입력 문서에 첨부하기 전에 실행하는 추가 집계 단계입니다.
`let`	문서	옵션	Atlas Stream Processing 이 각 입력 문서 에 대해 평가하는 변수입니다. 각 값은 리터럴, 필드 경로 또는 표현식 일 수 있습니다. `pipeline` 단계는 확인된 값을 `$$<variable>`로 참조할 수 있습니다.

행동

쿼리 모드

$vectorSearch 벡터 임베딩을 위한 queryVector 및 자동 임베딩을 위한 query.text라는 상호 배타적인 두 가지 쿼리 모드를 지원합니다. 두 모드 모두 리터럴 값이나 필드 경로 표현식 지정하여 단일 스트림 프로세서가 각 입력 문서 에 대해 서로 다른 쿼리 실행할 수 있습니다.

Error Handling

대상 MongoDB 벡터 검색 인덱스가 존재하지 않으면 $vectorSearch이 처음 실행될 때 스트림 프로세서가 오류 상태에 진입합니다. Atlas Stream Processing은 MongoServerError 오류를 보고하고 문서 처리를 중지합니다.

런타임에 queryVector 또는 query.text이 잘못된 유형으로 평가되는 경우, Atlas Stream Processing 은 문제가 되는 문서 만 데드 레터 큐( 구성된 경우)로 라우팅하고, 그렇지 않으면 삭제합니다.스트림 프로세서는 이후 문서를 계속 프로세스 . DLQ 문서 스키마 에 대해서는 데드 레터 대기열을 참조하세요.

결과 처리

Atlas Stream Processing이 검색 결과를 입력 문서에 첨부하기 전에 pipeline을 사용하여 검색 결과를 추가 처리합니다. Atlas Stream Processing은 pipeline을 MongoDB Vector Search로 그대로 전송합니다. pipeline 내의 입력 문서에서 값을 참조하려면 let을 통해 전달하고 $$<variable>로 참조합니다.

예시

다음 예시는 입력 검색 이벤트에 영화 추천을 추가합니다. 각 입력 문서에는 topic 필드가 있습니다. 이 파이프라인에서는 query.text을 사용하며 MongoDB 벡터 검색은 voyage-4-lite 모델을 사용하여 각 문서의 topic 값에 대한 임베딩을 생성합니다. 이 집계는 세 단계로 구성됩니다.

$source 단계는 Atlas 데이터베이스와 연결을 수립하여 특히 app 데이터베이스의 searches 컬렉션을 대상으로 합니다. fullDocumentOnly 옵션은 소스 컬렉션에 사전 이미지와 사후 이미지가 활성화되어 있어야 합니다.
$vectorSearch 단계는 각 문서의 topic 필드의 텍스트를 사용하여 sample_mflix.embedded_movies 컬렉션의 plot_vector_index 인덱스를 쿼리하고 최대 5개의 결과를 recommendations 필드에 추가합니다. pipeline 필드는 각 결과를 title 및 plot 필드로 제한합니다.
$merge 단계는 인리치된 문서 app 데이터베이스 의 enriched_searches 컬렉션 에 씁니다.

{
  "$source": {
    "connectionName": "srcCluster",
    "db": "app",
    "coll": "searches",
    "config": { "fullDocument": "required", "fullDocumentOnly": true }
  },
  "$vectorSearch": {
    "from": {
      "connectionName": "atlasCluster",
      "db": "sample_mflix",
      "coll": "embedded_movies"
    },
    "as": "recommendations",
    "query": {
      "text": "$topic"
    },
    "model": "voyage-4-lite",
    "index": "plot_vector_index",
    "path": "plot",
    "numCandidates": 50,
    "limit": 5,
    "pipeline": [
      { "$project": { "_id": 0, "title": 1, "plot": 1 } }
    ]
  },
  "$merge": {
    "into": {
      "connectionName": "atlasCluster",
      "db": "app",
      "coll": "enriched_searches"
    }
  }
}

출력 컬렉션에 작성된 강화된 문서는 다음과 같습니다.

{
  _id: ObjectId('6a4beebd75f00b6ddf98a8c0'),
  topic: 'gangster crime drama',
  recommendations: [
    { title: 'Scarface', plot: 'An ambitious and near insanely violent gangster climbs the ladder of success in the mob, but his weaknesses prove to be his downfall.' },
    { title: 'That Demon Within', plot: 'A dutiful cop, guilt-ridden over saving the life of a gang leader, becomes obsessed with bringing down the crime syndicate of the man he saved.' },
    { title: 'Billa 2', plot: 'An ordinary man from the slums enters an underworld gang and becomes the most feared underworld don.' },
    { title: 'A Better Tomorrow', plot: 'A reforming ex-gangster tries to reconcile with his estranged policeman brother, but the ties to his former gang are difficult to break.' },
    { title: 'Singham', plot: 'A humiliated gangster uses his influence and goon power to terrorize a newly transferred police officer.' }
  ]
}

다음 예시 RAG 파이프라인 에 대한 고정밀 영화 줄거리 구절을 검색합니다. 각 수신 이벤트 미리 계산된 queryEmbedding 필드 이미 포함되어 있으므로 파이프라인 queryVector를 사용합니다. $vectorSearch 단계는 재현율을 극대화하기 위해 광범위한 후보 구절 설정하다 검색하고,pipeline의 $rerank 단계는 가장 관련성이 높은 구절만 다운스트림에 계속되도록 해당 후보를 재정렬합니다. 이 집계 4단계로 이루어집니다.

$source 단계는 Atlas 데이터베이스와 연결을 수립하여 특히 llm_requests 데이터베이스의 events 컬렉션을 대상으로 합니다. fullDocumentOnly 옵션은 소스 컬렉션에 사전 이미지와 사후 이미지가 활성화되어 있어야 합니다.
$vectorSearch 단계는 각 문서의 queryEmbedding 필드를 queryVector로 사용하여 sample_mflix.embedded_movies 컬렉션에서 plot_embedding_index 인덱스를 쿼리합니다. 검색 결과를 최대화하기 위해 numCandidates를 높게 설정하고 최대 50 개의 일치를 pipeline로 전달합니다. pipeline 내부:
- $rerank는 rerank-2.5-lite 모델을 사용하여 쿼리 텍스트와의 관련성에 따라 후보를 재정렬합니다.
- $limit 가장 관련성 높은 8개의 구절을 유지합니다.
- $project 프롬프트를 빌드하는 데 필요한 필드만 반환합니다.
query.text 값은 let에 정의된 searchText 변수를 참조하며, 이 변수는 각 문서의 queryText 필드로 해결됩니다. Atlas Stream Processing은 context 필드에 결과를 저장합니다.
$unset 단계에서는 queryEmbedding 및 queryText 필드가 더 이상 다운스트림에 필요하지 않으므로 제거합니다.
$emit 단계는 풍부해진 문서를 qa_enriched 주제로 보냅니다.

중요

$rerank를 사용하는 파이프라인 실행 전에 Atlas 프로젝트 관리자가 Native Reranking을 활성화했는지 확인하세요.

{
  "$source": {
    "connectionName": "appCluster",
    "db": "llm_requests",
    "coll": "events",
    "config": { "fullDocument": "required", "fullDocumentOnly": true }
  },
  "$vectorSearch": {
    "from": {
      "connectionName": "atlasCluster",
      "db": "sample_mflix",
      "coll": "embedded_movies"
    },
    "as": "context",
    "queryVector": "$queryEmbedding",
    "index": "plot_embedding_index",
    "path": "plot_embedding",
    "numCandidates": 200,
    "limit": 50,
    "let": { "searchText": "$queryText" },
    "pipeline": [
      {
        "$rerank": {
          "query": { "text": "$$searchText" },
          "path": "plot",
          "model": "rerank-2.5-lite",
          "numDocsToRerank": 50
        }
      },
      { "$limit": 8 },
      { "$project": { "_id": 0, "title": 1, "plot": 1 } }
    ]
  },
  "$unset": ["queryEmbedding", "queryText"],
  "$emit": {
    "connectionName": "appKafka",
    "topic": "qa_enriched"
  }
}

주제에 전송되는 문서는 다음과 같습니다.

{
  _id: ObjectId('6a4c0cbc37d690084f3115da'),
  context: [
    { title: 'A Better Tomorrow', plot: 'A reforming ex-gangster tries to reconcile with his estranged policeman brother, but the ties to his former gang are difficult to break.' },
    { title: 'Yuma', plot: 'A story about the rise and fall of Zyga - a Polish kid in his early twenties.' },
    { title: 'Ghost Dog: The Way of the Samurai', plot: 'An African American mafia hit man who models himself after the samurai of old finds himself targeted for death by the mob.' }
    ...
  ]
}

돌아가기

$iceberg

보안

$vectorSearch 애그리게이션 단계

정의

배치

구문

행동

쿼리 모드

Error Handling

결과 처리

예시

자동 임베딩을 사용한 시맨틱 검색 강화

Precision-Critical RAG Context Retrieval with $rerank

`$vectorSearch` 애그리게이션 단계