Introducing OmniVec: An Open-Source Embedding Platform for AI Apps on Azure

Most AI applications end up building the same plumbing to keep that vector representation in sync: a change-capture process on the source, a consumer pool that generates embeddings, retry and backfill logic, dead-letter handling, and the operational work to keep it all running. OmniVec collapses that stack into four configurable components: a source, a model, a destination, and a pipeline that wires the first three together.

Deep Dive

Deploying OmniVec into your Azure subscription provisions multiple Azure resources, including an that stores the service images AKS pulls from, and more. You control the choices that affect cost and capacity, such as the embedding model (hosted Azure OpenAI or a self-hosted GPU model), the AKS node size and count, and whether to provision a GPU pool, etc.

Key concepts

or a self-hosted GPU model.

OmniVec in action

Let's put OmniVec to work end to end. In this walkthrough, you will:

• deploy it into your subscription


• point it at an Azure Cosmos DB container


• wire up a pipeline to automatically generate vector embeddings


• then run vector search over this data

We use Azure Cosmos DB as both the source and the destination here as an example, but this applies to any supported combination of sources, models, and destinations.

Prerequisites

Before you start, make sure you have:

• An Azure subscription with permissions to create resource groups, an AKS cluster, an ACR, and an Azure Cosmos DB account.


• An embedding model. This walkthrough uses an and note the endpoint, model name, and API key. You'll configure them in OmniVec later.


• CLI tools:
  
  
  
  
  • 
    to setup Azure Cosmos DB (but you can also do it directly via the Azure portal).
  
  
  • 
    
    
  
  
  • OmniVec CLI from the before continuing.
    
    
    

    Sign in to the Azure CLI and select the subscription that holds the account:
    
    

    
    
    
    
    

    CODE Kopieren

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

    
    
    
    
    
    
    
    

    Your signed-in user needs permission to create a database and container on the account. The built-in Cosmos DB Operator role (or any role granting Microsoft.DocumentDB/databaseAccounts/sqlDatabases/* and .../containers/* write actions) is sufficient. Account Contributor or Owner also works.

    
    
    

    Set the names you'll use throughout the rest of the walkthrough:
    
    

    
    
    
    
    

    CODE Kopieren

    export RG=<your-resource-group>
    
    export COSMOS_ACCOUNT=<your-cosmos-account>
    
    export COSMOS_DB=omnivec-demodb
    
    export COSMOS_CONTAINER=demo-container
    
    

    
    
    
    
    
    
    
    

    Create the database:
    
    

    
    
    
    
    

    CODE Kopieren

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

    
    
    
    
    
    
    
    

    Create the container with a vector embedding policy and a DiskANN vector index on /embedding. The 1536 dimension matches text-embedding-3-small; change it if you registered a different model:
    
    

    
    
    
    
    

    CODE Kopieren

    az cosmosdb sql container create \
    
    --account-name $COSMOS_ACCOUNT \
    
    --resource-group $RG \
    
    --database-name $COSMOS_DB \
    
    --name $COSMOS_CONTAINER \
    
    --partition-key-path /id \
    
    --vector-embeddings '{"vectorEmbeddings":[{"path":"/embedding","dataType":"float32","dimensions":1536,"distanceFunction":"cosine"}]}' \
    
    --idx '{"indexingMode":"consistent","automatic":true,"includedPaths":[{"path":"/*"}],"excludedPaths":[{"path":"/\"_etag\"/?"},{"path":"/embedding/*"}],"vectorIndexes":[{"path":"/embedding","type":"diskANN"}]}'
    
    

    
    
    
    
    
    
    
    

    Now seed it with sample data. The seed script uses DefaultAzureCredential, so first grant your signed-in user the Cosmos DB Built-in Data Contributor role on the Azure Cosmos DB account:
    
    

    
    
    
    
    

    CODE Kopieren

    export USER_PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)
    
    
    
    az cosmosdb sql role assignment create \
    
    --account-name "$COSMOS_ACCOUNT" \
    
    --resource-group "$RG" \
    
    --role-definition-id "00000000-0000-0000-0000-000000000002" \
    
    --principal-id "$USER_PRINCIPAL_ID" \
    
    --scope "/"
    
    

    
    
    
    
    
    
    
    

    Then install the sample app's dependencies and run the seed script (it reads COSMOS_ACCOUNT, COSMOS_DB, and COSMOS_CONTAINER from the environment):
    
    

    
    
    
    
    

    CODE Kopieren

    cd sample-app
    
    python3 -m venv .venv && source .venv/bin/activate
    
    
    
    pip install -r requirements.txt
    
    python insert_sample_data.py
    
    

    
    
    
    
    
    
    
    

    You should now have 100 product documents in the container, each with name and description fields.

    
    
    

    
    
    
    Grant OmniVec access to Azure Cosmos DB
    

    
    
    

    OmniVec pods authenticate to Azure Cosmos DB using a managed identity, not a connection string. Before you create a source or destination, grant that identity two roles on the Azure Cosmos DB account:

    
    
    
    
    
    • 
      Data plane (Cosmos DB Built-in Data Contributor): read source documents and write embeddings.
    
    
    • 
      Control plane (Cosmos DB Account Reader Role): read the account-level metadata and vector policies that the change-feed processor inspects at startup. Skipping it causes pipeline failures with a readMetadata error.
    
    
    
    
    

    First, find the principal ID of the OmniVec workload identity. It lives in the OmniVec deployment's resource group (not the Azure Cosmos DB account's $RG). That resource group has several managed identities, so filter by the client ID that azd exported rather than picking the first one:
    
    

    
    
    
    
    

    CODE Kopieren

    export OMNIVEC_RG=$(azd env get-value AZURE_RESOURCE_GROUP)
    
    
    
    export OMNIVEC_PRINCIPAL_ID=$(az identity list -g "$OMNIVEC_RG" \
    
    --query "[?clientId=='$(azd env get-value AZURE_IDENTITY_CLIENT_ID)'].principalId" -o tsv)
    
    

    
    
    
    
    
    
    
    

    Grant the data-plane role:
    
    

    
    
    
    
    

    CODE Kopieren

    az cosmosdb sql role assignment create \
    
    --account-name "$COSMOS_ACCOUNT" \
    
    --resource-group "$RG" \
    
    --role-definition-id "00000000-0000-0000-0000-000000000002" \
    
    --principal-id "$OMNIVEC_PRINCIPAL_ID" \
    
    --scope "/"
    
    

    
    
    
    
    
    
    
    

    Grant the control-plane role:
    
    

    
    
    
    
    

    CODE Kopieren

    az role assignment create \
    
    --assignee "$OMNIVEC_PRINCIPAL_ID" \
    
    --role "Cosmos DB Account Reader Role" \
    
    --scope "$(az cosmosdb show -n "$COSMOS_ACCOUNT" -g "$RG" --query id -o tsv)"
    
    

    
    
    
    
    
    
    
    

    Wait 1–2 minutes for the assignments to propagate before moving on.

    
    
    

    
    
    
    Wire up the pipeline
    

    
    
    

    With Azure Cosmos DB ready and OmniVec authorized, the rest of the setup is three OmniVec resources: a source, a destination, and a pipeline that binds them to the model you registered earlier.

    
    
    

    Register the Azure Cosmos DB container as a source. OmniVec will watch its change feed:
    
    

    
    
    
    
    

    CODE Kopieren

    omnivec source create --name demo-cosmosdb-source \
    
    --type cosmosdb \
    
    --config "{\"endpoint\":\"https://$COSMOS_ACCOUNT.documents.azure.com:443/\",\"database\":\"$COSMOS_DB\",\"container\":\"$COSMOS_CONTAINER\",\"auth_type\":\"managed-identity\"}"
    
    

    
    
    
    
    
    
    
    

    Register the same Azure Cosmos DB container as a destination. OmniVec will write embeddings back into it:
    
    

    
    
    
    
    

    CODE Kopieren

    omnivec destination create --name demo-cosmosdb-destination \
    
    --type cosmosdb-vector \
    
    --config "{\"endpoint\":\"https://$COSMOS_ACCOUNT.documents.azure.com:443/\",\"database\":\"$COSMOS_DB\",\"container\":\"$COSMOS_CONTAINER\",\"auth_type\":\"managed-identity\"}"
    
    

    
    
    
    
    
    
    
    

    The pipeline needs three IDs: source, destination, and model. Grab the source and destination IDs from omnivec source list and omnivec destination list (they look like src-… and dst-…). For the model, the registered name (demo-foundry-oai-model) isn't the ID; the internal mdl-ext-* ID is what the pipeline expects:
    
    

    
    
    
    
    

    CODE Kopieren

    export SOURCE_ID=<src-id-from-source-list>
    
    export DESTINATION_ID=<dst-id-from-destination-list>
    
    export MODEL_ID=$(omnivec model test demo-foundry-oai-model | sed 's/^OK: Model test returned: //' | jq -r '.id')
    
    

    
    
    
    
    
    
    
    

    Create the pipeline. --content-fields tells OmniVec which fields on each source document to embed (concatenated), --embedding-field is where the resulting vector lands on the destination document, and --vector-index-path is the path the destination container's vector index looks at (it should match the path you set in the az cosmosdb sql container create step):
    
    

    
    
    
    
    

    CODE Kopieren

    omnivec pipeline create --name demo-cosmosdb-pipeline \
    
    --source $SOURCE_ID --destination $DESTINATION_ID --model $MODEL_ID \
    
    --content-fields name,description --embedding-field embedding \
    
    --vector-index-path /embedding --processing-mode inline
    
    

    
    
    
    
    
    
    
    

    You should see something like:
    
    

    
    
    
    
    

    CODE Kopieren

    OK: Pipeline created: pip-94348d5e (status: paused)
    
    

    
    
    
    
    
    
    
    

    New pipelines start paused. Grab the pipeline ID from the output (or from omnivec pipeline list) and resume it:
    
    

    
    
    
    
    

    CODE Kopieren

    export PIPELINE_ID=<pip-id-from-create-output>
    
    omnivec pipeline resume $PIPELINE_ID
    
    

    
    
    
    
    
    
    
    

    Check the pipeline's progress:
    
    

    
    
    
    
    

    CODE Kopieren

    omnivec pipeline show $PIPELINE_ID
    
    

    
    
    
    
    
    
    
    

    Once the workers have processed the seed data, you'll see output similar to the following (truncated for brevity):
    
    

    
    
    
    
    

    CODE Kopieren

    Pipeline
    
    ID: pip-94348d5e
    
    Name: demo-cosmosdb-pipeline
    
    Status: active
    
    ...
    
    
    
    Stats
    
    Documents Embedded: 100
    
    Source Docs: 100
    
    Completion: 100.0%
    
    Failed: 0
    
    Pending: 0
    
    ...
    
    

    
    
    
    
    
    
    
    

    Completion: 100.0% means every seed document now has an embedding written back to its embedding field. From this point on, any insert or update to the source container flows through the change feed and gets re-embedded automatically.

    
    
    

    
    
    
    Run vector search
    

    
    
    

    The embeddings are in place, so you can run vector search against the destination. Use the OmniVec CLI's search command with a natural-language query:
    
    

    
    
    
    
    

    CODE Kopieren

    omnivec search "warm waterproof hiking pants" --index $DESTINATION_ID --top-k 3
    
    

    
    
    
    
    
    
    
    

    Try another query to confirm it generalizes beyond the obvious matches:
    
    

    
    
    
    
    

    CODE Kopieren

    omnivec search "lightweight running shoes" --index $DESTINATION_ID --top-k 3
    
    

    
    
    
    
    
    
    
    

    The web UI ships with a vector search playground that calls the same API.

    
    
    

    . It is a public preview, so expect changes as it matures. Clone it, deploy it into your own subscription, and try it on one of your own datasets. Bug reports, feedback, and requests are all welcome through GitHub issues. And if you build something interesting on top of it, we'd love to hear about that too!

    Vollständiger Original-Bericht

    Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

    ↗ Original-Artikel auf dev.to lesen