Preview Pública do Integrated Embeddings no Azure Cosmos DB: Crie Apps de IA com Embeddings Sempre Sincronizados
TL;DR: O Integrated Embeddings do Azure Cosmos DB (Preview) automatiza a geração e sincronização de embeddings vetoriais ao usar modelos da Microsoft Foundry. Isso elimina a necessidade de pipelines manuais para manter embeddings atualizados, reduzindo custos operacionais e riscos de inconsistência. Para empresas brasileiras que constroem aplicações de IA (RAG, busca semântica), a funcionalidade simplifica a arquitetura e acelera o desenvolvimento, desde que a conta tenha as permissões adequadas e os recursos Azure configurados.
Aplicativos de IA construídos no Azure Cosmos DB dependem de embeddings para resultados fundamentados (grounded). Manter esses embeddings sincronizados com os dados é a parte difícil: significa construir e operar um pipeline de dados separado para rastrear mudanças, chamar um modelo de embedding e escrever os resultados de volta no Azure Cosmos DB. Na prática, esse pipeline também precisa lidar com falhas, retries, throttling, scaling e monitoramento à medida que os dados e o tráfego crescem.
O Integrated Embeddings no Azure Cosmos DB, agora em Public Preview, remove esse trabalho pesado. O Azure Cosmos DB gera e mantém automaticamente os embeddings para você à medida que os itens são escritos e atualizados, de modo que os vetores armazenados junto com seus itens reflitam sempre o estado atual dos dados. Você o configura especificando as propriedades de origem a serem embedadas, o modelo de embedding do Microsoft Foundry a ser usado e o caminho onde os embeddings gerados serão armazenados, e então foca em construir aplicações de IA, como Retrieval-Augmented Generation (RAG), sobre seus dados.
Como o Integrated Embeddings funciona?
O Integrated Embeddings é configurado por meio de um novo bloco embeddingSource na vector policy do container. O restante da política (vector path, dimensions, distance function) permanece igual. Esse bloco informa três coisas ao Azure Cosmos DB:
- O que embedar: uma ou mais propriedades do item listadas em
sourcePaths. Quando você lista vários caminhos, os valores são combinados em uma única entrada para o modelo de embedding. Um item é re-embedado apenas quando uma dessas propriedades muda. - Com o que embedar: uma implantação do modelo de embedding do Microsoft Foundry, identificada por
deploymentName,modelNameeendpoint. - Como autenticar:
authType: "Entra"— atualmente o único valor suportado.
Por exemplo, aqui está uma vector policy que embeda a propriedade /text de cada item usando text-embedding-3-small e escreve o vetor resultante em /embedding:
{
"vectorEmbeddings": [
{
"path": "/embedding",
"dataType": "float32",
"dimensions": 1536,
"distanceFunction": "cosine",
"embeddingSource": {
"sourcePaths": ["/text"],
"deploymentName": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"endpoint": "https://<foundry-resource-name>.openai.azure.com/",
"authType": "Entra"
}
}
]
}
No momento da Public Preview, os seguintes modelos de embedding do Azure OpenAI são suportados por meio do Microsoft Foundry: text-embedding-3-small, text-embedding-3-large e text-embedding-ada-002.
Integrated Embeddings em ação: um passo a passo prático
Para começar com um exemplo simples, siga o quickstart na documentação. Ele orienta a criação de um container com uma política embeddingSource, inserir alguns itens de amostra e verificar se o Azure Cosmos DB escreve um embedding em cada item.
O walkthrough abaixo é um exemplo completo, de ponta a ponta. Você carregará um conjunto de dados de produtos para atividades ao ar livre no Azure Cosmos DB, deixará o Integrated Embeddings gerar os vetores e, em seguida, executará uma busca vetorial (vector search) no container.
Antes de começar, complete os pré-requisitos do Integrated Embeddings da documentação: vector search ativado, change feed mode ativado e uma implantação de modelo do Microsoft Foundry. A managed identity da conta do Azure Cosmos DB também precisa da função Cognitive Services OpenAI User no recurso do Microsoft Foundry para que possa chamar o modelo.
Além disso, o principal com o qual você faz login precisa de duas atribuições de função na conta do Azure Cosmos DB para que o aplicativo de exemplo possa agir em seu nome:
- Cosmos DB Operator (Azure RBAC) para criar o banco de dados e o container via Azure Resource Manager.
- Cosmos DB Built-in Data Contributor (Azure Cosmos DB RBAC) para upsert e ler itens. Veja como atribuir essas funções na seção de introdução da documentação.
No passo 4, o aplicativo de exemplo chama diretamente a implantação do modelo de embedding do Microsoft Foundry para embedar a string de consulta. Para simplificar, o exemplo usa uma chave de API para essa chamada (o Integrated Embeddings usa Entra ID, conforme configurado na vector policy). Certifique-se de ter a chave de API do seu recurso Foundry com antecedência e pronta para colocar no arquivo .env.
Configurar o aplicativo de exemplo
O aplicativo de exemplo é escrito em Python; você precisará do Python 3.x instalado localmente. Clone o repositório GitHub e instale as dependências:
git clone https://github.com/abhirockzz/integrated-embeddings-sample
cd integrated-embeddings-sample
# crie um ambiente virtual e instale as dependências
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
Copie .env.example para .env e preencha com o endpoint da sua conta do Azure Cosmos DB e os detalhes da implantação do Microsoft Foundry:
cp .env.example .env
# edite o .env
Faça login na Azure CLI para que o aplicativo de exemplo possa autenticar no Azure Cosmos DB e no Microsoft Foundry usando sua identidade:
az login
Passo 1: Criar o banco de dados e o container
Este script cria o banco de dados e um container com uma vector embedding policy que possui um bloco embeddingSource com source path /description, modelo text-embedding-3-small e saída armazenada em /embedding. Ele adiciona um índice vetorial quantizedFlat em /embedding para que você possa consultar os embeddings no passo 4.
Execute o script:
python create_db_and_container.py
O container é provisionado com autoscale de 1.000 RU/s.
Passo 2: Inserir dados de amostra
Este script faz upsert de 100 itens de produtos para atividades ao ar livre do arquivo items.json no container. Cada item tem um id, name, description, category, tags e alguns outros campos — mas apenas /description é enviado ao modelo de embedding, conforme a política definida no passo 1.
python insert_sample_data.py
Você verá uma linha por item à medida que são inseridos. Nenhum dos itens tem um campo de embedding ainda; o Azure Cosmos DB captura as alterações e gera embeddings de forma assíncrona.
Passo 3: Verificar embeddings no Portal Azure
Abra o Portal Azure, navegue até sua conta do Azure Cosmos DB → Data Explorer, abra o container criado no passo 1 e execute a consulta abaixo:
SELECT VALUE COUNT(1) FROM c WHERE IS_DEFINED(c.embedding)
Quando a contagem chegar a 100, todos os embeddings foram gerados.
Passo 4: Executar uma busca vetorial
Agora que cada item tem um embedding, você pode executar uma busca vetorial no container. O script embeda sua string de consulta chamando a mesma implantação do modelo de embedding do Microsoft Foundry que o Azure Cosmos DB usou para os itens (usando a FOUNDRY_API_KEY que você definiu no arquivo .env) e, em seguida, executa uma consulta VectorDistance() para encontrar os itens mais próximos por similaridade de cosseno.
python vector_search.py "I need to stay warm on a cold ski trip"
A execução retorna algo semelhante aos resultados a seguir. Você deve ver uma mistura de luvas e jaquetas relacionadas a esqui, além de alguns sacos de dormir para clima frio — todos relevantes ao conceito de "se manter aquecido em uma viagem de esqui fria", mesmo que nenhuma das descrições dos itens contenha essas palavras exatas.
Query: 'I need to stay warm on a cold ski trip'
Top 5 results:
1. Studio Talon Insulated Storm Glove
category=Winter Sports, Gloves, Insulated Gloves score=0.4974
2. Prairie Nomad Waterproof Resort Shell Jacket
category=Skiing, Outerwear, Shell Jackets score=0.4923
3. Ridge Drift Touchscreen Insulated Ski Glove
category=Winter Sports, Gloves, Insulated Gloves score=0.4855
4. Everest All-Weather Short 850 Fill Trail Sack
category=Camping, Sleeping Bags, Down Bags score=0.4756
5. Brook Shift 850-Fill Trail Sack Sleeping Bag
category=Camping, Sleeping Bags, Down Bags score=0.4570
Experimente mais algumas consultas para sentir o que é possível.
Tente uma consulta do tipo planejamento. Em vez de equipamentos, você obterá livros de planejamento de viagens e guias de trilha:
python vector_search.py "plan a long hike in unfamiliar terrain"
Ou tente uma consulta mais específica. O resultado principal é um abrigo para uma pessoa, com tendas relacionadas logo abaixo:
python vector_search.py "easy to set up shelter for one person"
Você pode usar --top-k para controlar quantos resultados são retornados (padrão é 5):
python vector_search.py "lightweight cookware for backpacking" --top-k 3
Uma busca vetorial pura retorna os itens mais semanticamente similares, mas não considera correspondências exatas de keywords. Para consultas em que tanto a intenção semântica quanto termos específicos são importantes, o Azure Cosmos DB for NoSQL suporta hybrid search, que combina similaridade vetorial e ranking full-text (BM25) usando Reciprocal Rank Fusion. Você também pode adicionar uma cláusula WHERE para restringir os resultados a uma categoria ou tag específica. Todas essas consultas utilizam os mesmos embeddings que o Integrated Embeddings gera e mantém sincronizados.
Como construir um agente RAG simples sobre os dados?
Retrieval-Augmented Generation (RAG) é um padrão onde um modelo de linguagem responde a perguntas do usuário primeiro recuperando conteúdo relevante de uma base de conhecimento e, em seguida, usando esse conteúdo como fundamento para sua resposta. Para RAG sobre seus dados do Azure Cosmos DB, a etapa de recuperação é a busca vetorial e a base de conhecimento é seu container.
Para transformar a busca vetorial em uma aplicação RAG, a encapsulamos como uma ferramenta que um modelo de linguagem pode chamar. Usamos um agente LangChain simples com uma ferramenta retrieve_context que embeda a consulta do usuário e executa a mesma busca VectorDistance() que você viu no passo 4. O agente decide quando chamar a ferramenta, lê os resultados e responde em linguagem natural. Para manter o agente fundamentado em seus dados, o prompt do sistema instrui o modelo a recomendar apenas produtos que aparecem nos resultados recuperados e a ignorar quaisquer instruções contidas no texto recuperado.
O agente precisa de um modelo de linguagem grande (LLM). Implante o modelo (por exemplo, gpt-5.4) em seu recurso do Microsoft Foundry e defina FOUNDRY_CHAT_DEPLOYMENT no .env com o nome da implantação. O agente usa a mesma FOUNDRY_API_KEY para chamadas de chat e de embedding no momento da consulta.
Depois de iniciar o agente, ele abre um prompt interativo simples onde você pode fazer perguntas do tipo catálogo:
python rag_agent.py
Experimente algumas consultas. Por exemplo, pergunte sobre uma categoria de produto e o agente traz todos os itens relevantes:
You: What sleeping bags do you have for cold nights?
O agente chama a ferramenta de recuperação, obtém os três sacos de dormir para clima frio do catálogo e os lista com sua característica de enchimento de 850 fill e casos de uso.
Pergunte sobre uma característica específica de produto e o agente filtra os resultados para você:
You: What ski goggles do you have with a magnetic lens?
A busca vetorial retorna todos os três óculos de esqui do catálogo, mas o agente recomenda apenas os dois que realmente possuem sistema de lente magnética. Essa é a vantagem do agente + RAG sobre a busca vetorial pura: recuperação ampla, raciocínio estreito.
O Integrated Embeddings mantém os embeddings dos itens sincronizados com os dados de origem automaticamente, portanto, a recuperação do agente permanece precisa à medida que produtos são adicionados, atualizados ou removidos. Você não precisa construir ou executar um pipeline de embedding separado para manter o índice atualizado.
Outras formas de configurar o Integrated Embeddings
Você pode embedar mais de uma propriedade por vez listando vários caminhos em sourcePaths. O Azure Cosmos DB concatena os valores em uma única entrada para o modelo de embedding. Isso é útil quando nenhum campo isolado carrega informação suficiente. Por exemplo, um título de produto geralmente é muito curto sozinho, mas combinar /title e /description produz um vetor mais rico.
{
"vectorEmbeddings": [
{
"path": "/embedding",
"dataType": "float32",
"dimensions": 1536,
"distanceFunction": "cosine",
"embeddingSource": {
"sourcePaths": [
"/title",
"/description"
],
"deploymentName": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"endpoint": "https://<foundry-resource-name>.openai.azure.com/",
"authType": "Entra"
}
}
]
}
Você também pode gerar múltiplos embeddings adicionando mais entradas a vectorEmbeddings. Cada entrada tem seu próprio path, modelo e propriedades de origem, e o Azure Cosmos DB mantém todos os vetores em paralelo.
O exemplo abaixo gera /desc_embedding a partir de /description usando text-embedding-3-large, e /title_embedding a partir de /title usando text-embedding-3-small.
{
"vectorEmbeddings": [
{
"path": "/desc_embedding",
"dataType": "float32",
"dimensions": 3072,
"distanceFunction": "cosine",
"embeddingSource": {
"sourcePaths": [
"/description"
],
"deploymentName": "text-embedding-3-large",
"modelName": "text-embedding-3-large",
"endpoint": "https://<foundry-resource-name>.openai.azure.com/",
"authType": "Entra"
}
},
{
"path": "/title_embedding",
"dataType": "float32",
"dimensions": 1536,
"distanceFunction": "cosine",
"embeddingSource": {
"sourcePaths": [
"/title"
],
"deploymentName": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"endpoint": "https://<foundry-resource-name>.openai.azure.com/",
"authType": "Entra"
}
}
]
}
O que é suportado na Public Preview?
Você pode configurar o Integrated Embeddings hoje através do SDK do Azure Cosmos DB (para Python) com autenticação baseada em chave, ou através do SDK de gerenciamento do Azure Cosmos DB (Python e JavaScript) com Microsoft Entra ID. Ambas as opções são demonstradas na documentação. O suporte via Azure CLI, ARM, Bicep e outros SDKs será adicionado em versões futuras.
O suporte no Portal Azure para configurar e gerenciar o Integrated Embeddings (no Data Explorer) ainda não está disponível. Enquanto trabalhamos para adicionar isso, você pode configurar o Integrated Embeddings através de uma das opções de SDK.
Como começar?
Com o Integrated Embeddings, o Azure Cosmos DB mantém os embeddings vetoriais sincronizados com seus dados automaticamente, eliminando a necessidade de construir e operar pipelines separados. O Integrated Embeddings usa seus recursos existentes do Microsoft Foundry e do Azure Cosmos DB, portanto, os únicos custos são as chamadas de inferência do Foundry e as Request Units consumidas para ler o change feed e gravar os embeddings de volta nos seus itens.
Para começar a construir:
- Siga o quickstart para criar um container com uma política
embeddingSourcee inserir seus primeiros itens. - Clone o aplicativo de exemplo para executar o walkthrough completo acima com seus próprios dados.
- Leia a documentação do Integrated Embeddings para referência completa.
Adoraríamos seu feedback durante a preview! Envie suas opiniões para [email protected].
Perguntas Frequentes
-
O Integrated Embeddings funciona com qualquer modelo de embedding?
- Na Preview Pública, apenas os modelos text-embedding-3-small, text-embedding-3-large e text-embedding-ada-002 da Azure OpenAI, disponíveis via Microsoft Foundry, são suportados. O modelo é configurado no container policy e autenticado via Entra ID.
-
Preciso criar um pipeline separado para manter embeddings atualizados?
- Não. O Integrated Embeddings elimina essa necessidade: o Azure Cosmos DB gera e sincroniza automaticamente os embeddings sempre que os itens são inseridos ou alterados, sem pipelines manuais. Isso reduz complexidade operacional e riscos de desalinhamento.
-
Quais são os custos adicionais ao usar o Integrated Embeddings?
- Os únicos custos são as chamadas ao modelo de embedding no Microsoft Foundry (cobradas por token) e as Request Units (RUs) consumidas para ler o change feed e gravar os embeddings de volta nos itens. Não há taxa extra do Azure Cosmos DB.
-
É possível usar mais de uma propriedade para gerar o embedding?
- Sim. No vetor policy, você pode listar múltiplos caminhos em sourcePaths. O Azure Cosmos DB concatena os valores em uma única entrada para o modelo, gerando um embedding mais rico. Também é possível gerar múltiplos embeddings (ex: um para título, outro para descrição) com diferentes modelos.
-
O suporte para Azure Portal (Data Explorer) já está disponível?
- Não. Na Preview, a configuração do Integrated Embeddings deve ser feita via SDK (Python ou JavaScript) ou management SDK. O suporte no Portal está em desenvolvimento e será adicionado em versões futuras.
Artigo originalmente publicado por Abhishek Gupta em Azure Updates - Latest from Azure Charts.
