InfoGrab DocsInfoGrab Docs

Active Context

요약

시맨틱 검색은 gitlab-active-context gem으로 구현된 Active Context 프레임워크가 구동합니다. 이 프레임워크는 확장할 수 있으며 서로 다른 유형의 시맨틱 검색 컬렉션을 지원하도록 설계되었습니다.

시맨틱 검색은 gitlab-active-context gem으로 구현된 Active Context 프레임워크가 구동합니다. 이 프레임워크는 여러 벡터 스토어(Elasticsearch, OpenSearch, pgvector를 사용하는 PostgreSQL)를 위한 변환 계층을 제공하므로, 벡터 스토어별 구현 없이도 같은 코드가 지원되는 모든 벡터 스토어에서 동작합니다.

이 프레임워크는 확장할 수 있으며 서로 다른 유형의 시맨틱 검색 컬렉션을 지원하도록 설계되었습니다. 각 시맨틱 검색 컬렉션은 다음으로 구현됩니다.

  • 컬렉션(Ai::ActiveContext::Collections::): 인덱싱할 콘텐츠와 저장 방식을 정의합니다
  • 참조(Ai::ActiveContext::References::): 인덱싱할 콘텐츠 항목 하나를 나타내며, 이를 벡터 스토어에 기록하는 전처리기와 연산을 정의합니다
  • 큐(Ai::ActiveContext::Queues::): 백그라운드 job이 배치로 처리하기 전까지 추적 중인 참조를 샤딩된 Redis 큐에 보관합니다
  • 쿼리(Ai::ActiveContext::Queries::): 벡터 스토어에서 유사한 콘텐츠를 가져옵니다
  • 마이그레이션: 벡터 스토어의 스키마 변경과 데이터 변환을 실행합니다

머지 리퀘스트나 문서 같은 새로운 유형의 콘텐츠를 지원하려면 새 컬렉션에 대해 이 구성 요소를 구현합니다. 자세한 내용은 시맨틱 검색 컬렉션 추가를 참고합니다.

참조 처리#

참조는 코드 청크처럼 인덱싱할 콘텐츠 항목 하나를 나타냅니다. 콘텐츠가 변경되면 컬렉션은 track!으로 해당 참조를 추적하며, 이 호출은 참조를 컬렉션의 큐에 넣습니다.

BulkProcessWorker job은 하나의 큐 샤드에서 참조 배치를 처리합니다.

  1. 샤드에서 처리 시점이 된 참조를 읽고 역직렬화합니다.
  2. 참조 클래스의 전처리기를 순서대로 실행합니다. 각 전처리기는 이전 단계에서 성공한 참조만 받습니다.
  3. 모든 전처리기를 통과한 참조를 벌크 프로세서로 보냅니다. 벌크 프로세서는 각 참조의 연산을 적용하고 벡터 스토어에 일괄 기록합니다.
  4. 처리된 참조를 큐에서 제거합니다. 실패한 참조는 큐의 실패 큐로 이동합니다. 자세한 내용은 재시도와 데드 큐를 참고합니다.

배치 로직은 ActiveContext::BulkProcessQueue에 있습니다.

전처리기#

전처리기는 참조의 연산이 벡터 스토어에 적용되기 전에 참조를 준비합니다. 참조 클래스는 add_preprocessor로 전처리기를 선언하며, 전처리기는 선언된 순서대로 실행됩니다. 전처리기에는 should_run 조건을 지정할 수 있으며, 조건이 false이면 건너뜁니다. 각 전처리기는 성공한 참조, 실패한 참조, 무한 재시도 참조를 반환합니다.

gitlab-active-context gem은 다음 전처리기를 제공합니다.

  • EmbeddedSkipper: 선택한 임베딩 필드에 문서의 임베딩이 이미 있는 참조를 제외하여, 이후 전처리기가 해당 참조에 임베딩을 다시 요청하지 않게 합니다.
  • ContentFetcher: 벡터 스토어에서 기존 문서의 콘텐츠를 읽습니다.
  • Embeddings: 기존 문서의 콘텐츠 필드 또는 참조의 메서드를 사용하여 모든 참조의 임베딩을 일괄 생성합니다.

연산#

각 참조는 문서를 벡터 스토어에 기록하는 방식을 결정하는 연산을 정의합니다.

  • upsert: 참조의 문서를 생성하거나 업데이트합니다. 참조의 문서 수가 이전보다 줄었다면 남은 문서를 삭제합니다.
  • update: 이미 존재하는 문서를 업데이트합니다. 인덱서가 문서를 생성하므로 Ai::ActiveContext::References::Code는 update를 사용합니다.
  • delete: 참조의 모든 문서를 삭제합니다.

큐#

큐는 BulkProcessWorker job이 처리하기 전까지 추적 중인 참조를 보관합니다. 큐는 Redis에 저장됩니다. 각 큐는 샤드로 나뉘며 각 샤드는 Redis 정렬 집합(sorted set)입니다. 참조를 추적할 때 참조의 일관된 해시로 샤드가 정해집니다. ActiveContext.raw_queues는 샤드마다 항목 하나를 반환하며, 각 샤드는 별도의 job이 처리합니다.

큐 클래스는 config/initializers/active_context.rb의 config.queue_classes에 등록합니다.

Ai::ActiveContext::BulkProcessWorker 크론 job은 매분 실행되며 큐 샤드마다 job 하나를 큐에 넣습니다. 각 job이 배치로 수행하는 작업은 참조 처리를 참고합니다.

config/initializers/active_context.rb에서 re_enqueue_indexing_workers가 켜져 있으면 job은 배치를 처리한 후 스스로 다시 큐에 들어가므로, 크론 실행 사이에도 샤드가 계속 비워집니다. 배치 전체가 실패하거나 큐가 처리량을 제한하는 경우(limit_throughput?) job은 일찍 재큐잉을 멈춥니다.

큐 속성#

큐 클래스는 ActiveContext::Concerns::Queue를 포함하며 다음 속성을 정의할 수 있습니다.

  • number_of_shards: 샤드 수. 각 샤드는 별도의 job이 처리하므로 이 값이 큐를 병렬로 처리하는 job 수를 정합니다. 필수입니다.
  • shard_limit: job이 한 번 실행될 때 샤드에서 읽는 최대 참조 수. 기본값은 1000입니다.
  • processing_delay: 항목을 처리할 수 있게 되기까지의 지연. 설정하면 큐는 시간 기반이 되며, job은 지연 시간이 지난 후에만 항목을 처리합니다. ActiveContext::Queues.all_queued_items 같은 다른 읽기는 지연과 관계없이 모든 항목을 반환합니다. 설정하지 않으면 큐는 선입선출(FIFO)입니다.
  • failure_queue: 실패한 참조를 받는 큐. 기본값은 RetryQueue입니다.
  • infinite_retry_queue: 속도 제한 같은 일시적 오류로 실패한 참조를 받는 큐. 기본값은 RetryQueue입니다.
  • limit_throughput?: true이면 job이 배치를 처리한 후 스스로 다시 큐에 들어가지 않습니다. 기본값은 false입니다.
  • extra_preprocess_options: queue_name 외에 모든 전처리기에 전달되는 옵션.

재시도와 데드 큐#

임베딩 생성이 실패하면 참조는 지연 시간이 점점 늘어나는 재시도 큐 체인을 거칩니다.

  1. RetryQueue: 5분
  2. SecondRetryQueue: 30분
  3. ThirdRetryQueue: 2시간
  4. FourthRetryQueue: 8시간

각 단계에서 한 번씩 재시도하므로 AI Gateway 시간 초과 같은 일시적 오류는 시도 사이에 해소될 시간을 가집니다. 모든 단계에서 실패한 참조는 자동으로 처리되지 않는 데드 큐에 들어갑니다. 각 큐 클래스가 failure_queue를 정의하므로 재시도 횟수는 큐 체인에서 정해지며, 참조에는 추가 상태가 없습니다.

속도 제한 오류는 예외입니다. 속도 제한에 걸린 참조는 어느 단계에서든 첫 번째 재시도 큐로 돌아갑니다. 속도 제한이 풀릴 때까지 5분마다 재시도하며 데드 큐에는 도달하지 않습니다.

마이그레이션#

Active Context 프레임워크는 마이그레이션 시스템을 사용하여 연결된 벡터 스토어의 스키마 변경과 데이터 변환을 관리합니다. 마이그레이션은 데이터베이스에서 추적되며 워커 프로세스가 비동기로 실행합니다.

Ai::ActiveContext::MigrationWorker는 5분마다 크론 job으로 실행되어 완료되지 않은 마이그레이션을 실행합니다. 워커는 활성 연결의 마이그레이션만 적용합니다. 다른 연결이 활성화되면 워커는 해당 연결의 미완료 마이그레이션을 적용합니다.

마이그레이션 파일은 ee/active_context/migrate/에 있습니다.

태스크#

Note

아키텍처에 관한 자세한 내용은 Active Context Tasks 설계 문서를 참고합니다.

Active Context 프레임워크는 오래 실행되는 비동기 작업을 관리하기 위해 태스크 실행 시스템을 사용합니다. Active Context Tasks 시스템은 임베딩 모델 활성화, 증분 인덱싱, 데이터 마이그레이션 같은 복잡한 워크플로를 처리합니다. 재시도, 오류 처리, 상태 유지를 기본으로 지원하므로 중요한 작업을 안정적으로 실행합니다.

임베딩 모델#

Note

아키텍처에 관한 자세한 내용은 임베딩 모델 설계 문서를 참고합니다.

모델 메타데이터#

시맨틱 검색은 임베딩 모델을 사용하여 인덱싱과 검색에 쓰이는 임베딩을 생성합니다.

임베딩 모델은 Ai::ActiveContext::Collection 레코드의 metadata에 current_indexing_embedding_model, next_indexing_embedding_model, search_embedding_model로 저장됩니다.

각 임베딩 모델 메타데이터에는 다음 정보가 있습니다.

  • model_type: gitlab_managed 또는 self_hosted
  • model_ref: 모델 식별자(예: text_embedding_005_vertex 또는 Ai::SelfHostedModel ID)
  • field: 임베딩을 저장하는 벡터 스토어 필드
  • dimensions: 임베딩 벡터 차원이며 벡터 스토어 필드를 생성할 때와 임베딩을 생성할 때 사용합니다

ActiveContext::EmbeddingModel 객체와 임베딩 생성#

컬렉션 클래스(예: Ai::ActiveContext::Collections::Code)에서 임베딩 모델은 Ai::ActiveContext::Embeddings::ModelFactory를 통해 ActiveContext::EmbeddingModel 객체로 노출됩니다.

임베딩은 생성된 ActiveContext::EmbeddingModel 객체에서 generate_embeddings를 호출하여 생성합니다. 예를 들면 다음과 같습니다.

ac_embedding_model = Ai::ActiveContext::Collections::Code.current_indexing_embedding_model # this returns an ActiveContext::EmbeddingModel
ac_embedding_model.generate_embeddings(<array_of_content>, user: <optional_user>)

내부적으로 ActiveContext::EmbeddingModel#generate_embeddings는 AI Gateway로 임베딩 요청을 보내는 Gitlab::Llm::Embeddings::* 클래스를 실행합니다.

모델 전환#

Ai::ActiveContext::EmbeddingModelActivationService는 컬렉션의 첫 번째 임베딩 모델을 설정하거나 새 모델로 전환합니다.

이 서비스는 먼저 요청을 검증합니다. 진행 중인 전환이 없는지, 모델이 현재 모델과 다른지, 모델과 배치 크기가 유효한지 확인합니다. 건너뛰도록 지정하지 않는 한 서비스는 테스트 임베딩 요청도 보냅니다.

그런 다음 서비스는 새 모델을 버전이 지정된 새 필드 이름과 함께 next_indexing_embedding_model로 설정하고 Active Context 태스크 체인을 시작합니다.

  1. AddEmbeddingsField: 새 모델의 벡터 필드를 추가합니다.
  2. BackfillEmbeddings: 기존 모델에서 전환할 때만 실행합니다. 새 필드가 없는 문서를 찾아 컬렉션의 백필 큐에서 추적합니다. 큐가 비고 해당 필드가 없는 문서가 없으면 태스크가 완료됩니다.
  3. UpdateCollectionMetadata: 새 모델을 current_indexing_embedding_model과 search_embedding_model로 만들고 next_indexing_embedding_model을 지웁니다.
  4. SyncFeatureSettings: 사용자가 임베딩 모델을 선택하고 컬렉션에 일치하는 기능 설정이 있을 때만 실행합니다.
  5. NullifyField: 기존 모델에서 전환할 때만 실행합니다. 모든 문서에서 이전 필드를 지웁니다.

검색은 UpdateCollectionMetadata가 실행될 때까지 이전 모델을 계속 사용하므로 전환 중에도 검색이 중단되지 않습니다.

벡터 스토어#

Active Context는 어댑터를 통해 벡터 스토어를 읽고 씁니다. 각 어댑터는 같은 인터페이스를 구현하므로 컬렉션, 쿼리, 마이그레이션은 지원되는 모든 벡터 스토어에서 같은 방식으로 동작합니다.

Active Context는 다음 어댑터를 제공합니다.

  • ActiveContext::Databases::Elasticsearch::Adapter: Elasticsearch.
  • ActiveContext::Databases::Opensearch::Adapter: OpenSearch.
  • ActiveContext::Databases::Postgresql::Adapter: pgvector 확장을 사용하는 PostgreSQL.

각 어댑터는 벡터 스토어별 클래스로 구성됩니다.

  • Client: 벡터 스토어에 대해 검색을 실행합니다.
  • Indexer: 처리된 참조를 수집하여 벡터 스토어에 일괄 기록합니다.
  • Executor: 컬렉션 생성이나 필드 추가 같은 스키마 변경을 적용합니다. 마이그레이션이 Executor를 사용합니다.

Active Context는 활성 연결의 어댑터를 사용합니다. 활성 연결은 어댑터 클래스와 연결 옵션을 저장하는 Ai::ActiveContext::Connection 레코드입니다. 한 번에 하나의 연결만 활성화할 수 있습니다.

쿼리 실행#

쿼리를 실행하면 다음과 같이 처리됩니다.

  1. 임베딩 생성: 사용자의 쿼리를 인덱싱된 콘텐츠와 같은 모델을 사용하여 임베딩으로 변환합니다
  2. 벡터 검색: k-최근접 이웃(KNN) 검색으로 임베딩을 저장된 벡터와 비교합니다
  3. 필터링: 관련 기준(예: 프로젝트, 파일 경로)으로 결과를 필터링합니다
  4. 인가: 사용자가 액세스할 수 있는 콘텐츠만 포함하도록 결과를 필터링합니다
  5. 결과 제한: 각 쿼리 클래스는 자체 제한을 설정합니다. Ai::ActiveContext::Queries::Code는 기본적으로 가장 유사한 결과 20개를 반환합니다.

Active Context

GitLab v19.6
원문 보기

요약

시맨틱 검색은 gitlab-active-context gem으로 구현된 Active Context 프레임워크가 구동합니다. 이 프레임워크는 확장할 수 있으며 서로 다른 유형의 시맨틱 검색 컬렉션을 지원하도록 설계되었습니다.

시맨틱 검색은 gitlab-active-context gem으로 구현된 Active Context 프레임워크가 구동합니다. 이 프레임워크는 여러 벡터 스토어(Elasticsearch, OpenSearch, pgvector를 사용하는 PostgreSQL)를 위한 변환 계층을 제공하므로, 벡터 스토어별 구현 없이도 같은 코드가 지원되는 모든 벡터 스토어에서 동작합니다.

이 프레임워크는 확장할 수 있으며 서로 다른 유형의 시맨틱 검색 컬렉션을 지원하도록 설계되었습니다. 각 시맨틱 검색 컬렉션은 다음으로 구현됩니다.

  • 컬렉션(Ai::ActiveContext::Collections::): 인덱싱할 콘텐츠와 저장 방식을 정의합니다
  • 참조(Ai::ActiveContext::References::): 인덱싱할 콘텐츠 항목 하나를 나타내며, 이를 벡터 스토어에 기록하는 전처리기와 연산을 정의합니다
  • 큐(Ai::ActiveContext::Queues::): 백그라운드 job이 배치로 처리하기 전까지 추적 중인 참조를 샤딩된 Redis 큐에 보관합니다
  • 쿼리(Ai::ActiveContext::Queries::): 벡터 스토어에서 유사한 콘텐츠를 가져옵니다
  • 마이그레이션: 벡터 스토어의 스키마 변경과 데이터 변환을 실행합니다

머지 리퀘스트나 문서 같은 새로운 유형의 콘텐츠를 지원하려면 새 컬렉션에 대해 이 구성 요소를 구현합니다. 자세한 내용은 시맨틱 검색 컬렉션 추가를 참고합니다.

참조 처리#

참조는 코드 청크처럼 인덱싱할 콘텐츠 항목 하나를 나타냅니다. 콘텐츠가 변경되면 컬렉션은 track!으로 해당 참조를 추적하며, 이 호출은 참조를 컬렉션의 큐에 넣습니다.

BulkProcessWorker job은 하나의 큐 샤드에서 참조 배치를 처리합니다.

  1. 샤드에서 처리 시점이 된 참조를 읽고 역직렬화합니다.
  2. 참조 클래스의 전처리기를 순서대로 실행합니다. 각 전처리기는 이전 단계에서 성공한 참조만 받습니다.
  3. 모든 전처리기를 통과한 참조를 벌크 프로세서로 보냅니다. 벌크 프로세서는 각 참조의 연산을 적용하고 벡터 스토어에 일괄 기록합니다.
  4. 처리된 참조를 큐에서 제거합니다. 실패한 참조는 큐의 실패 큐로 이동합니다. 자세한 내용은 재시도와 데드 큐를 참고합니다.

배치 로직은 ActiveContext::BulkProcessQueue에 있습니다.

전처리기#

전처리기는 참조의 연산이 벡터 스토어에 적용되기 전에 참조를 준비합니다. 참조 클래스는 add_preprocessor로 전처리기를 선언하며, 전처리기는 선언된 순서대로 실행됩니다. 전처리기에는 should_run 조건을 지정할 수 있으며, 조건이 false이면 건너뜁니다. 각 전처리기는 성공한 참조, 실패한 참조, 무한 재시도 참조를 반환합니다.

gitlab-active-context gem은 다음 전처리기를 제공합니다.

  • EmbeddedSkipper: 선택한 임베딩 필드에 문서의 임베딩이 이미 있는 참조를 제외하여, 이후 전처리기가 해당 참조에 임베딩을 다시 요청하지 않게 합니다.
  • ContentFetcher: 벡터 스토어에서 기존 문서의 콘텐츠를 읽습니다.
  • Embeddings: 기존 문서의 콘텐츠 필드 또는 참조의 메서드를 사용하여 모든 참조의 임베딩을 일괄 생성합니다.

연산#

각 참조는 문서를 벡터 스토어에 기록하는 방식을 결정하는 연산을 정의합니다.

  • upsert: 참조의 문서를 생성하거나 업데이트합니다. 참조의 문서 수가 이전보다 줄었다면 남은 문서를 삭제합니다.
  • update: 이미 존재하는 문서를 업데이트합니다. 인덱서가 문서를 생성하므로 Ai::ActiveContext::References::Code는 update를 사용합니다.
  • delete: 참조의 모든 문서를 삭제합니다.

큐#

큐는 BulkProcessWorker job이 처리하기 전까지 추적 중인 참조를 보관합니다. 큐는 Redis에 저장됩니다. 각 큐는 샤드로 나뉘며 각 샤드는 Redis 정렬 집합(sorted set)입니다. 참조를 추적할 때 참조의 일관된 해시로 샤드가 정해집니다. ActiveContext.raw_queues는 샤드마다 항목 하나를 반환하며, 각 샤드는 별도의 job이 처리합니다.

큐 클래스는 config/initializers/active_context.rb의 config.queue_classes에 등록합니다.

Ai::ActiveContext::BulkProcessWorker 크론 job은 매분 실행되며 큐 샤드마다 job 하나를 큐에 넣습니다. 각 job이 배치로 수행하는 작업은 참조 처리를 참고합니다.

config/initializers/active_context.rb에서 re_enqueue_indexing_workers가 켜져 있으면 job은 배치를 처리한 후 스스로 다시 큐에 들어가므로, 크론 실행 사이에도 샤드가 계속 비워집니다. 배치 전체가 실패하거나 큐가 처리량을 제한하는 경우(limit_throughput?) job은 일찍 재큐잉을 멈춥니다.

큐 속성#

큐 클래스는 ActiveContext::Concerns::Queue를 포함하며 다음 속성을 정의할 수 있습니다.

  • number_of_shards: 샤드 수. 각 샤드는 별도의 job이 처리하므로 이 값이 큐를 병렬로 처리하는 job 수를 정합니다. 필수입니다.
  • shard_limit: job이 한 번 실행될 때 샤드에서 읽는 최대 참조 수. 기본값은 1000입니다.
  • processing_delay: 항목을 처리할 수 있게 되기까지의 지연. 설정하면 큐는 시간 기반이 되며, job은 지연 시간이 지난 후에만 항목을 처리합니다. ActiveContext::Queues.all_queued_items 같은 다른 읽기는 지연과 관계없이 모든 항목을 반환합니다. 설정하지 않으면 큐는 선입선출(FIFO)입니다.
  • failure_queue: 실패한 참조를 받는 큐. 기본값은 RetryQueue입니다.
  • infinite_retry_queue: 속도 제한 같은 일시적 오류로 실패한 참조를 받는 큐. 기본값은 RetryQueue입니다.
  • limit_throughput?: true이면 job이 배치를 처리한 후 스스로 다시 큐에 들어가지 않습니다. 기본값은 false입니다.
  • extra_preprocess_options: queue_name 외에 모든 전처리기에 전달되는 옵션.

재시도와 데드 큐#

임베딩 생성이 실패하면 참조는 지연 시간이 점점 늘어나는 재시도 큐 체인을 거칩니다.

  1. RetryQueue: 5분
  2. SecondRetryQueue: 30분
  3. ThirdRetryQueue: 2시간
  4. FourthRetryQueue: 8시간

각 단계에서 한 번씩 재시도하므로 AI Gateway 시간 초과 같은 일시적 오류는 시도 사이에 해소될 시간을 가집니다. 모든 단계에서 실패한 참조는 자동으로 처리되지 않는 데드 큐에 들어갑니다. 각 큐 클래스가 failure_queue를 정의하므로 재시도 횟수는 큐 체인에서 정해지며, 참조에는 추가 상태가 없습니다.

속도 제한 오류는 예외입니다. 속도 제한에 걸린 참조는 어느 단계에서든 첫 번째 재시도 큐로 돌아갑니다. 속도 제한이 풀릴 때까지 5분마다 재시도하며 데드 큐에는 도달하지 않습니다.

마이그레이션#

Active Context 프레임워크는 마이그레이션 시스템을 사용하여 연결된 벡터 스토어의 스키마 변경과 데이터 변환을 관리합니다. 마이그레이션은 데이터베이스에서 추적되며 워커 프로세스가 비동기로 실행합니다.

Ai::ActiveContext::MigrationWorker는 5분마다 크론 job으로 실행되어 완료되지 않은 마이그레이션을 실행합니다. 워커는 활성 연결의 마이그레이션만 적용합니다. 다른 연결이 활성화되면 워커는 해당 연결의 미완료 마이그레이션을 적용합니다.

마이그레이션 파일은 ee/active_context/migrate/에 있습니다.

태스크#

Note

아키텍처에 관한 자세한 내용은 Active Context Tasks 설계 문서를 참고합니다.

Active Context 프레임워크는 오래 실행되는 비동기 작업을 관리하기 위해 태스크 실행 시스템을 사용합니다. Active Context Tasks 시스템은 임베딩 모델 활성화, 증분 인덱싱, 데이터 마이그레이션 같은 복잡한 워크플로를 처리합니다. 재시도, 오류 처리, 상태 유지를 기본으로 지원하므로 중요한 작업을 안정적으로 실행합니다.

임베딩 모델#

Note

아키텍처에 관한 자세한 내용은 임베딩 모델 설계 문서를 참고합니다.

모델 메타데이터#

시맨틱 검색은 임베딩 모델을 사용하여 인덱싱과 검색에 쓰이는 임베딩을 생성합니다.

임베딩 모델은 Ai::ActiveContext::Collection 레코드의 metadata에 current_indexing_embedding_model, next_indexing_embedding_model, search_embedding_model로 저장됩니다.

각 임베딩 모델 메타데이터에는 다음 정보가 있습니다.

  • model_type: gitlab_managed 또는 self_hosted
  • model_ref: 모델 식별자(예: text_embedding_005_vertex 또는 Ai::SelfHostedModel ID)
  • field: 임베딩을 저장하는 벡터 스토어 필드
  • dimensions: 임베딩 벡터 차원이며 벡터 스토어 필드를 생성할 때와 임베딩을 생성할 때 사용합니다

ActiveContext::EmbeddingModel 객체와 임베딩 생성#

컬렉션 클래스(예: Ai::ActiveContext::Collections::Code)에서 임베딩 모델은 Ai::ActiveContext::Embeddings::ModelFactory를 통해 ActiveContext::EmbeddingModel 객체로 노출됩니다.

임베딩은 생성된 ActiveContext::EmbeddingModel 객체에서 generate_embeddings를 호출하여 생성합니다. 예를 들면 다음과 같습니다.

ac_embedding_model = Ai::ActiveContext::Collections::Code.current_indexing_embedding_model # this returns an ActiveContext::EmbeddingModel
ac_embedding_model.generate_embeddings(<array_of_content>, user: <optional_user>)

내부적으로 ActiveContext::EmbeddingModel#generate_embeddings는 AI Gateway로 임베딩 요청을 보내는 Gitlab::Llm::Embeddings::* 클래스를 실행합니다.

모델 전환#

Ai::ActiveContext::EmbeddingModelActivationService는 컬렉션의 첫 번째 임베딩 모델을 설정하거나 새 모델로 전환합니다.

이 서비스는 먼저 요청을 검증합니다. 진행 중인 전환이 없는지, 모델이 현재 모델과 다른지, 모델과 배치 크기가 유효한지 확인합니다. 건너뛰도록 지정하지 않는 한 서비스는 테스트 임베딩 요청도 보냅니다.

그런 다음 서비스는 새 모델을 버전이 지정된 새 필드 이름과 함께 next_indexing_embedding_model로 설정하고 Active Context 태스크 체인을 시작합니다.

  1. AddEmbeddingsField: 새 모델의 벡터 필드를 추가합니다.
  2. BackfillEmbeddings: 기존 모델에서 전환할 때만 실행합니다. 새 필드가 없는 문서를 찾아 컬렉션의 백필 큐에서 추적합니다. 큐가 비고 해당 필드가 없는 문서가 없으면 태스크가 완료됩니다.
  3. UpdateCollectionMetadata: 새 모델을 current_indexing_embedding_model과 search_embedding_model로 만들고 next_indexing_embedding_model을 지웁니다.
  4. SyncFeatureSettings: 사용자가 임베딩 모델을 선택하고 컬렉션에 일치하는 기능 설정이 있을 때만 실행합니다.
  5. NullifyField: 기존 모델에서 전환할 때만 실행합니다. 모든 문서에서 이전 필드를 지웁니다.

검색은 UpdateCollectionMetadata가 실행될 때까지 이전 모델을 계속 사용하므로 전환 중에도 검색이 중단되지 않습니다.

벡터 스토어#

Active Context는 어댑터를 통해 벡터 스토어를 읽고 씁니다. 각 어댑터는 같은 인터페이스를 구현하므로 컬렉션, 쿼리, 마이그레이션은 지원되는 모든 벡터 스토어에서 같은 방식으로 동작합니다.

Active Context는 다음 어댑터를 제공합니다.

  • ActiveContext::Databases::Elasticsearch::Adapter: Elasticsearch.
  • ActiveContext::Databases::Opensearch::Adapter: OpenSearch.
  • ActiveContext::Databases::Postgresql::Adapter: pgvector 확장을 사용하는 PostgreSQL.

각 어댑터는 벡터 스토어별 클래스로 구성됩니다.

  • Client: 벡터 스토어에 대해 검색을 실행합니다.
  • Indexer: 처리된 참조를 수집하여 벡터 스토어에 일괄 기록합니다.
  • Executor: 컬렉션 생성이나 필드 추가 같은 스키마 변경을 적용합니다. 마이그레이션이 Executor를 사용합니다.

Active Context는 활성 연결의 어댑터를 사용합니다. 활성 연결은 어댑터 클래스와 연결 옵션을 저장하는 Ai::ActiveContext::Connection 레코드입니다. 한 번에 하나의 연결만 활성화할 수 있습니다.

쿼리 실행#

쿼리를 실행하면 다음과 같이 처리됩니다.

  1. 임베딩 생성: 사용자의 쿼리를 인덱싱된 콘텐츠와 같은 모델을 사용하여 임베딩으로 변환합니다
  2. 벡터 검색: k-최근접 이웃(KNN) 검색으로 임베딩을 저장된 벡터와 비교합니다
  3. 필터링: 관련 기준(예: 프로젝트, 파일 경로)으로 결과를 필터링합니다
  4. 인가: 사용자가 액세스할 수 있는 콘텐츠만 포함하도록 결과를 필터링합니다
  5. 결과 제한: 각 쿼리 클래스는 자체 제한을 설정합니다. Ai::ActiveContext::Queries::Code는 기본적으로 가장 유사한 결과 20개를 반환합니다.