`$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 Selection을 참조하십시오.
`limit`	int	필수 사항	반환할 최대 결과 수입니다. `numCandidates`을 초과할 수 없습니다. 경고: `limit`이 `numCandidates`를 초과하면 모든 문서가 `PlanExecutor` 오류로 실행 시간에 실패합니다.
`filter`	문서	옵션	벡터 검색 전에 적용할 사전 필터 표현식입니다. 지원되는 연산자에 대한 자세한 내용은 필터를 참조하십시오. 경고: `filter` 에서 지원되지 않는 연산자 사용하는 경우 모든 문서 런타임에 `PlanExecutor` 오류와 함께 실패합니다.
`exact`	부울	옵션	근사 최근접 이웃 또는 등가 최근접 이웃 검색을 실행할지 여부를 지정하는 플래그입니다. `numCandidates`를 생략하는 경우 이 필드를 제공하세요. 값은 다음 중 하나일 수 있습니다. `false` 근사 최근접 이웃 검색실행 시 `true` 등가 최근접 이웃 search실행 시 기본값은 `false`입니다.
`searchNodePreference`	문서	옵션	Atlas Stream Processing이 특정 검색 노드로 쿼리를 라우팅하는 데 사용하는 `key` 필드가 있는 문서입니다. `key` 값은 비어 있는 string이어야 합니다.
`pipeline`	배열	옵션	Atlas Stream Processing이 검색 결과를 입력 문서에 첨부하기 전에 실행하는 추가 집계 단계입니다.
`let`	문서	옵션	Variables that Atlas Stream Processing evaluates against each input 문서. 각 값은 리터럴이거나 필드 경로 또는 표현식일 수 있습니다. `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>로 참조합니다.

예시

다음 예시는 영화 및 영화관에 대한 데이터가 포함된 sample_mflix 데이터 세트를 쿼리합니다. 이를 실행하려면 샘플 데이터를 Atlas 클러스터에 로드하고 embedded_movies 컬렉션에 MongoDB 벡터 검색 인덱스를 만들어야 합니다.

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

다음 예시는 입력 검색 이벤트에 영화 추천을 추가합니다. 각 입력 문서에는 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.' }
  ]
}

Precision-Critical RAG Context Retrieval with $rerank

다음 예시는 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 프로젝트 관리자가 네이티브 재순위 지정을 활성화했는지 확인합니다.

{
  "$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.' }
    ...
  ]
}

$vectorSearch 애그리게이션 단계

정의

배치

구문

행동