원문은 https://devblogs.microsoft.com/cosmosdb/introducing-omnivec-an-open-source-embedding-platform-for-ai-apps-on-azure/에 게시되었습니다.

오늘 우리는 운영 데이터가 변경됨에 따라 벡터 표현 (vector representation)을 동기화 상태로 유지하는 임베딩 파이프라인 (embedding pipelines)을 구축하고 운영하기 위한 플랫폼인 OmniVec을 오픈 소스로 공개합니다. 사용자가 데이터 소스, 임베딩 모델 (embedding model), 벡터 저장소 (vector stores, 목적지)를 등록하면 OmniVec이 나머지 작업을 수행합니다: 초기 백필 (backfill), 변경 사항 추적 (change tracking), 생성을 위한 모델 호출 (model invocation), 그리고 이를 벡터 저장소에 다시 쓰는 작업입니다. 우리는 이를 Azure Cosmos DB, PostgreSQL, SQL Server (소스 및 목적지), 그리고 Azure Blob Storage (목적지)에 대한 지원과 함께 출시합니다. 사용자는 자신의 Azure 구독에 OmniVec을 배포하고, 웹 UI, CLI 또는 REST API를 사용하여 이를 관리할 수 있습니다.

대부분의 AI 애플리케이션은 해당 벡터 표현을 동기화하기 위해 동일한 배관 (plumbing) 작업을 구축하게 됩니다: 소스에 대한 변경 캡처 (change-capture) 프로세스, 임베딩을 생성하는 컨슈머 풀 (consumer pool), 재시도 (retry) 및 백필 (backfill) 로직, 데드 레터 (dead-letter) 처리, 그리고 이 모든 것을 계속 실행하기 위한 운영 작업 등이 포함됩니다. OmniVec은 이 스택을 네 가지 구성 가능한 구성 요소, 즉 소스 (source), 모델 (model), 목적지 (destination), 그리고 앞의 세 가지를 함께 연결하는 파이프라인 (pipeline)으로 압축합니다.

심층 분석 (Deep Dive)

OmniVec을 귀하의 Azure 구독에 배포하면 OmniVec 서비스(API, controller, workers)를 호스팅하는 Azure Kubernetes Service (AKS) 클러스터, 파이프라인 (pipeline) 메타데이터, 작업 상태(job state) 및 진행 지표(progress metrics)를 위한 Azure Cosmos DB 계정, AKS가 가져올 서비스 이미지를 저장하는 Azure Container Registry 등을 포함한 여러 Azure 리소스가 프로비저닝(provisioning)됩니다. 귀하는 임베딩 모델(호스팅된 Azure OpenAI 또는 자체 호스팅 GPU 모델), AKS 노드 크기 및 개수, GPU 풀(pool) 프로비저닝 여부 등 비용과 용량에 영향을 미치는 선택 사항들을 직접 제어할 수 있습니다.

핵심 개념 (Key concepts)

OmniVec은 다음과 같은 핵심 프리미티브 (primitives)를 제공합니다:

• Source (소스): OmniVec이 레코드(record)를 읽어오는 시스템입니다. 소스 정의는 OmniVec에 해당 시스템에 연결하는 방법과 변경 사항을 추적하는 방법을 알려줍니다.
• Model (모델): OmniVec이 레코드 콘텐츠를 벡터(vector)로 변환하기 위해 호출하는 임베딩 모델 (embedding model)입니다. 모델 등록 (model registration) 시 제공자(provider), 모델 이름, 엔드포인트(endpoint) 및 자격 증명(credentials)을 캡처하며, 런타임(runtime)에서 배치(batching) 및 재시도(retries)와 함께 이를 호출합니다.
• Destination (대상): 생성된 임베딩이 원래의 레코드와 함께(또는 레코드의 업데이트로서) 기록되는 벡터 스토어 (vector store)입니다.
• Pipeline (파이프라인): 소스, 모델, 대상을 하나로 묶는 바인딩 (binding)입니다. 또한 어떤 소스 필드(field)를 임베딩할지, 어떤 대상 필드가 벡터를 받을지를 선언합니다.

아키텍처 개요 (Architecture at a glance)

OmniVec은 Azure Kubernetes Service 상에서 일련의 서비스 세트로 실행됩니다:

• REST API: 소스(sources), 모델(models), 목적지(destinations) 및 파이프라인(pipelines)의 설정을 보유하고 이를 REST를 통해 노출하는 FastAPI 기반의 컨트롤 플레인 (control plane)입니다. CLI와 웹 UI는 백그라운드에서 이 API를 사용합니다.
• Ingestion (수집): 각 소스의 변경 사항을 감시하고 임베딩 (embedding)이 필요한 레코드를 큐 (queue)에 쌓습니다. 변경 사항을 추적하는 방식은 소스에 따라 다릅니다: Azure Cosmos DB의 경우 변경 피드 (change feed), Azure Blob Storage의 경우 블롭 이벤트 (blob events), SQL Server 및 PostgreSQL의 경우 CDC (Change Data Capture)를 사용합니다.
• Workers (워커): 큐에서 레코드를 가져와 임베딩 모델을 호출하고, 결과물인 임베딩을 목적지에 쓰는 컴퓨팅 상의 수평 확장 가능한 (horizontally scalable) 풀 (pool)입니다.
• Model routing layer (모델 라우팅 계층): 임베딩 모델 앞단의 통합 엔트리 포인트 (entry point)입니다. 이를 통해 파이프라인이 Azure OpenAI와 같은 외부 제공업체나 자체 호스팅된 GPU 모델을 호출할 수 있습니다.
• Metadata store (메타데이터 저장소): 배포 시 자동으로 프로비저닝되는 Azure Cosmos DB 계정입니다. 파이프라인 정의, 작업 상태, 진행 메트릭 (metrics) 등을 보유합니다.

OmniVec 작동 예시

OmniVec을 처음부터 끝까지 실제로 작동시켜 보겠습니다. 이 실습을 통해 다음을 수행하게 됩니다:

• 사용자의 구독(subscription)에 배포
• Azure Cosmos DB 컨테이너를 대상으로 지정
• 벡터 임베딩 (vector embeddings)을 자동으로 생성하도록 파이프라인 연결
• 해당 데이터에 대해 벡터 검색 (vector search) 실행

여기서는 예시로 Azure Cosmos DB를 소스와 목적지 모두로 사용하지만, 이는 지원되는 모든 소스, 모델 및 목적지의 조합에 적용됩니다.

사전 요구 사항

시작하기 전에 다음 사항을 확인하십시오:

• 리소스 그룹, AKS 클러스터, ACR 및 Azure Cosmos DB 계정을 생성할 수 있는 권한이 있는 Azure 구독.
• 임베딩 모델 (Embedding model). 이 실습에서는 Microsoft Foundry에 배포된 Azure OpenAI 임베딩 모델을 사용합니다. 구독에 모델을 배포하고 엔드포인트(endpoint), 모델 이름(model name), API 키(API key)를 기록해 두십시오. 나중에 OmniVec에서 이를 구성하게 됩니다.
• CLI 도구:
  • 배포를 위한 Azure Developer CLI (azd).
  • Azure Cosmos DB 설정을 위한 Azure CLI (az) (Azure 포털을 통해 직접 수행할 수도 있습니다).
  • kubectl 및 Helm
  • 소스(source), 목적지(destination), 파이프라인(pipeline) 및 구성(config)을 관리하기 위한 OmniVec releases page의 OmniVec CLI.

그런 다음, 나중에 사용될 샘플 데이터와 시드 스크립트(seed script)가 포함된 퀵스타트(quickstart) 리포지토리를 클론(clone)합니다:

git clone https://github.com/AzureCosmosDB/omnivec-cosmosdb-quickstart

cd omnivec-cosmosdb-quickstart

OmniVec 배포 및 구성

배포를 위해 새로운 azd 환경을 생성합니다. ENV_NAME(리소스 이름의 일부가 됩니다)을 정하고, 구독 내에서 AKS 및 Azure Cosmos DB를 지원하는 LOCATION을 선택하십시오:

export ENV_NAME="my-omnivec"
export LOCATION="westus2"
export SUBSCRIPTION_ID="<your-subscription-id>"
...

배포를 구성합니다:

azd env set OMNIVEC_METADATA_STORE "cosmosdb-provisioned"
azd env set OMNIVEC_ENABLE_BLOB_SOURCE "false"
azd env set OMNIVEC_SYSTEM_NODE_VM_SIZE "Standard_D2ds_v5"
...

• OMNIVEC_METADATA_STORE는 OmniVec 자체의 파이프라인 메타데이터 (metadata), 작업 상태 (job state), 그리고 진행 지표 (progress metrics)를 위해 전용 Azure Cosmos DB 계정을 프로비저닝 (provision) 합니다.
• OMNIVEC_ENABLE_BLOB_SOURCE는 이 가이드에서 Azure Cosmos DB만을 소스 (source)로 사용하기 때문에 꺼져 있습니다. Azure Blob Storage가 필요한 경우 이 설정을 켜십시오.
• 예상되는 워크로드 (workload)에 따라 OMNIVEC_SYSTEM_NODE_VM_SIZE 및 OMNIVEC_SYSTEM_NODE_COUNT를 사용하여 AKS 시스템 풀 (system pool)의 크기를 조정하십시오.
• GPU 풀 (OMNIVEC_GPU_NODE_VM_SIZE, OMNIVEC_GPU_NODE_COUNT)은 현재 호스팅된 Azure OpenAI 모델을 호출하고 있으므로 비어 있습니다. 클러스터 내부에서 자체 호스팅되는 임베딩 (embedding) 모델을 실행하려면 이 값들을 설정하십시오.
• OMNIVEC_BUILD_MODE=acr은 프로비저닝된 ACR에서 서비스 이미지 (service images)를 빌드하며, OMNIVEC_BUILD=true는 이 배포의 일부로 해당 빌드를 트리거 (trigger) 합니다.

배포를 위해 단 하나의 명령만 필요합니다:

azd up

이 작업은 몇 분 정도 소요됩니다. AKS 클러스터 (cluster), Azure Cosmos DB 계정, 그리고 ACR을 프로비저닝하고, ACR에서 OmniVec 서비스 이미지를 빌드하며, 클러스터에 Helm 차트 (Helm chart)를 설치합니다. 완료되면 다음과 유사한 요약 정보가 표시됩니다 (사용자 값은 다를 수 있습니다):

//..... redacted
Instance ID: my-omnivec-dhmzlhlv4lk7s
Environment: my-omnivec
...

관리자 토큰 (admin token)과 OmniVec FQDN을 저장하십시오. 다음 단계에서 CLI가 이 배포를 가리키도록 하는 데 두 가지 모두를 사용하게 됩니다. 또한 웹 UI (web UI)가 정상적으로 작동하는지 확인하기 위해 브라우저에서 FQDN을 열 수 있습니다.

이 가이드의 나머지 부분은 CLI를 사용합니다 (웹 UI에서도 클릭을 통해 동일한 작업을 수행할 수 있습니다). CLI가 배포를 가리키도록 설정하고 인증하십시오:

export SERVER_URL=<예: http://my-omnivec-dhmzlhlv4lk7s.westus2.cloudapp.azure.com/>
export ADMIN_TOKEN=<admin-token>

...

/ui 접미사 (suffix) 없이 순수한 FQDN을 사용하십시오.

CLI가 제대로 연결되었는지 확인합니다:

omnivec config view

마지막으로, Azure OpenAI 임베딩 모델을 OmniVec에 등록합니다. 파이프라인 (pipelines)은 여기서 지정한 이름으로 모델을 참조합니다:

export FOUNDRY_ENDPOINT=<your-foundry-endpoint>
export FOUNDRY_MODEL_NAME=<e.g. text-embedding-3-small>
export FOUNDRY_API_KEY=<your-foundry-api-key>
...

Azure Cosmos DB 설정

OmniVec이 임베딩 (embeddings)을 읽고 쓸 Azure Cosmos DB 계정, 데이터베이스, 그리고 컨테이너 (container)가 필요합니다. 이 실습에서는 동일한 컨테이너를 소스 (source)이자 목적지 (destination)로 사용합니다. 아직 Azure Cosmos DB 계정이 없다면, 계속하기 전에 계정을 생성하세요.

Azure CLI에 로그인하고 계정이 포함된 구독 (subscription)을 선택합니다:

az login
az account set --subscription "$SUBSCRIPTION_ID"

로그인한 사용자에게는 해당 계정에 데이터베이스와 컨테이너를 생성할 수 있는 권한이 필요합니다. 내장된 Cosmos DB Operator 역할 (또는 Microsoft.DocumentDB/databaseAccounts/sqlDatabases/* 및 .../containers/* 쓰기 작업을 허용하는 모든 역할)이면 충분합니다. 계정 Contributor (기여자) 또는 Owner (소유자) 역할도 가능합니다.

남은 실습 과정 동안 사용할 이름들을 설정합니다:

export RG=<your-resource-group>
export COSMOS_ACCOUNT=<your-cosmos-account>
export COSMOS_DB=omnivec-demodb
...

데이터베이스를 생성합니다:

az cosmosdb sql database create \
--account-name $COSMOS_ACCOUNT \
--resource-group $RG \
...

벡터 임베딩 정책 (vector embedding policy)과 /embedding 경로에 DiskANN 벡터 인덱스 (vector index)를 포함한 컨테이너를 생성합니다. 1536 차원 (dimension)은 text-embedding-3-small과 일치합니다. 다른 모델을 등록했다면 이 값을 변경하세요:

az cosmosdb sql container create \
--account-name $COSMOS_ACCOUNT \
--resource-group $RG \
...

이제 샘플 데이터로 시딩 (seed)을 진행합니다. 시드 스크립트는 DefaultAzureCredential을 사용하므로, 먼저 로그인한 사용자에게 Azure Cosmos DB 계정에 대한 Cosmos DB Built-in Data Contributor 역할을 부여해야 합니다:

export USER_PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)

az cosmosdb sql role assignment create \
...

그 다음 샘플 앱의 종속성(dependencies)을 설치하고 시드 스크립트(seed script)를 실행하세요 (이 스크립트는 환경 변수에서 COSMOS_ACCOUNT, COSMOS_DB, COSMOS_CONTAINER를 읽어옵니다):

cd sample-app
python3 -m venv .venv && source .venv/bin/activate

...

이제 컨테이너에 각각 이름(name)과 설명(description) 필드를 가진 100개의 제품 문서가 생성되었을 것입니다.

OmniVec에 Azure Cosmos DB 액세스 권한 부여하기

OmniVec 포드(pods)는 연결 문자열(connection string)이 아닌 관리 ID(managed identity)를 사용하여 Azure Cosmos DB에 인증합니다. 소스(source) 또는 대상(destination)을 생성하기 전에, 해당 ID에 Azure Cosmos DB 계정에 대한 두 가지 역할(roles)을 부여해야 합니다:

• 데이터 평면 (Data plane) (Cosmos DB Built-in Data Contributor): 소스 문서를 읽고 임베딩(embeddings)을 작성합니다.
• 제어 평면 (Control plane) (Cosmos DB Account Reader Role): 변경 피드 프로세서(change-feed processor)가 시작 시 검사하는 계정 수준의 메타데이터(metadata) 및 벡터 정책(vector policies)을 읽습니다. 이 단계를 건너뛰면 readMetadata 오류와 함께 파이프라인 실패가 발생합니다.

먼저, OmniVec 워크로드 ID(workload identity)의 주체 ID(principal ID)를 찾으세요. 이는 OmniVec 배포의 리소스 그룹(Azure Cosmos DB 계정의 $RG가 아님)에 존재합니다. 해당 리소스 그룹에는 여러 관리 ID가 있으므로, 첫 번째 항목을 선택하기보다는 azd가 내보낸 클라이언트 ID(client ID)로 필터링하세요:

export OMNIVEC_RG=$(azd env get-value AZURE_RESOURCE_GROUP)

export OMNIVEC_PRINCIPAL_ID=$(az identity list -g "$OMNIVEC_RG" \
...

데이터 평면(data-plane) 역할을 부여합니다:

az cosmosdb sql role assignment create \
--account-name "$COSMOS_ACCOUNT" \
--resource-group "$RG" \
...

제어 평면(control-plane) 역할을 부여합니다:

az role assignment create \
--assignee "$OMNIVEC_PRINCIPAL_ID" \
--role "Cosmos DB Account Reader Role" \
...