원문은 https://devblogs.microsoft.com/cosmosdb/announcing-the-public-preview-of-integrated-embeddings-in-azure-cosmos-db-build-ai-apps-with-embeddings-that-stay-in-sync/에 게시되었습니다.

Azure Cosmos DB를 기반으로 구축된 AI 애플리케이션은 근거 있는 결과를 위해 임베딩 (embeddings)에 의존합니다. 이를 데이터와 동기화 상태로 유지하는 것이 어려운 부분입니다. 즉, 변경 사항을 추적하고, 임베딩 모델을 호출하며, 결과를 다시 Azure Cosmos DB에 쓰는 별도의 데이터 파이프라인 (data pipeline)을 구축하고 운영해야 함을 의미합니다. 실제로 데이터와 트래픽이 증가함에 따라 해당 파이프라인은 실패 및 재시도, 스로틀링 (throttling), 확장 (scaling), 모니터링 (monitoring)도 처리해야 합니다.

현재 퍼블릭 프리뷰 (Public Preview) 단계인 Azure Cosmos DB의 통합 임베딩 (Integrated Embeddings)은 이러한 힘든 작업을 제거합니다. Azure Cosmos DB는 항목이 작성되고 업데이트됨에 따라 자동으로 임베딩을 생성하고 유지 관리하므로, 항목과 함께 저장된 벡터 (vectors)가 항상 데이터의 현재 상태를 반영합니다. 임베딩할 소스 속성, 사용할 Microsoft Foundry 임베딩 모델, 생성된 임베딩이 저장될 경로를 지정하여 구성하면, 검색 증강 생성 (Retrieval-Augmented Generation (RAG))과 같은 AI 애플리케이션을 데이터 위에 구축하는 데 집중할 수 있습니다.

통합 임베딩 (Integrated Embeddings) 작동 방식

통합 임베딩은 컨테이너 벡터 정책 (container vector policy) 내의 새로운 embeddingSource 블록을 통해 구성됩니다. 나머지 정책 (벡터 경로, 차원, 거리 함수)은 동일하게 유지됩니다. 이 블록은 Azure Cosmos DB에 세 가지 사항을 알려줍니다:

• 임베딩할 대상 (What to embed): sourcePaths에 나열된 하나 이상의 아이템 속성입니다. 여러 경로를 나열하면 해당 값들이 임베딩 모델을 위한 단일 입력으로 결합됩니다. 아이템은 이 속성 중 하나가 변경될 때만 다시 임베딩됩니다.
• 함께 임베딩할 대상 (What to embed with): deploymentName, modelName, endpoint로 식별되는 Microsoft Foundry 임베딩 모델 배포입니다.
• 인증 방법 (How to authenticate): authType: "Entra" — 현재 유일하게 지원되는 값입니다.

예를 들어, 다음은 text-embedding-3-small을 사용하여 각 아이템의 /text 속성을 임베딩하고 결과 벡터를 /embedding에 쓰는 벡터 정책입니다:

{
  "vectorEmbeddings": [
    {
...

퍼블릭 프리뷰 (Public Preview) 시점에서, Microsoft Foundry를 통해 다음 Azure OpenAI 임베딩 모델들이 지원됩니다: text-embedding-3-small, text-embedding-3-large, 그리고 text-embedding-ada-002.

통합 임베딩 (Integrated Embeddings) 작동 예시

간단한 예제로 시작하려면 문서의 퀵스타트(quickstart)를 시도해 보세요. 이 가이드는 embeddingSource 정책이 포함된 컨테이너를 생성하고, 몇 개의 샘플 아이템을 삽입하며, Azure Cosmos DB가 각 아이템에 임베딩을 작성하는지 확인하는 과정을 안내합니다.

아래의 워크스루 (walkthrough)는 더 긴 엔드 투 엔드 (end-to-end) 예제입니다. 야외 제품 데이터셋을 Azure Cosmos DB에 로드하고, 통합 임베딩 (Integrated Embeddings)이 벡터를 생성하도록 한 다음, 컨테이너에 대해 벡터 검색 (vector search)을 실행하게 됩니다.

시작하기 전에, 문서에 명시된 통합 임베딩 (Integrated Embeddings) 사전 요구 사항을 완료하세요: 벡터 검색 (vector search), 변경 피드 (change feed) 모드 활성화, 그리고 Microsoft Foundry 모델 배포가 필요합니다. 또한 Azure Cosmos DB 계정의 관리 ID (managed identity)가 모델을 호출할 수 있도록 Microsoft Foundry 리소스에 대해 Cognitive Services OpenAI User 역할을 가지고 있어야 합니다.

또한, 샘플 앱이 사용자를 대신하여 동작할 수 있도록 로그인하는 주체(principal)에게 Azure Cosmos DB 계정에 대한 두 가지 역할 할당(role assignments)이 필요합니다:

• Cosmos DB Operator (Azure RBAC): Azure Resource Manager을 통해 데이터베이스 및 컨테이너를 생성하기 위해 필요합니다.
• Cosmos DB Built-in Data Contributor (Azure Cosmos DB RBAC): 항목을 업서트(upsert)하고 읽기 위해 필요합니다. 시작하기 섹션의 이러한 역할 할당 방법을 참조하세요.

4단계에서 샘플 앱은 쿼리 문자열을 임베딩하기 위해 Microsoft Foundry 임베딩 배포(deployment)를 직접 호출합니다. 단순화를 위해 샘플은 이 호출에 API 키를 사용합니다 (통합 임베딩 (Integrated Embeddings) 자체는 벡터 정책에 구성된 대로 Microsoft Entra ID를 사용합니다). Foundry 리소스에 대한 API 키를 미리 확보하여 .env 파일에 바로 넣을 수 있도록 준비해 두세요.

샘플 애플리케이션 설정

샘플 앱은 Python으로 작성되었습니다. 로컬에 Python 3.x가 설치되어 있어야 합니다. GitHub 리포지토리를 클론(clone)하고 종속성을 설치하세요:

git clone https://github.com/abhirockzz/integrated-embeddings-sample
cd integrated-embeddings-sample

...

.env.example을 .env로 복사하고 Azure Cosmos DB 계정 엔드포인트와 Microsoft Foundry 배포 세부 정보를 입력하세요:

cp .env.example .env
# .env 편집

샘플 앱이 사용자의 신원을 사용하여 Azure Cosmos DB 및 Microsoft Foundry에 인증할 수 있도록 Azure CLI에 로그인하세요:

az login

1단계: 데이터베이스 및 컨테이너 생성

이 스크립트는 데이터베이스와 컨테이너를 생성하며, 소스 경로가 /description이고 모델이 text-embedding-3-small이며 출력이 /embedding에 저장되는 embeddingSource 블록을 포함한 벡터 임베딩 정책(vector embedding policy)을 함께 생성합니다. 또한 4단계에서 임베딩을 쿼리할 수 있도록 /embedding에 quantizedFlat 벡터 인덱스를 추가합니다.

스크립트를 실행합니다:

python create_db_and_container.py

컨테이너는 자동 확장(autoscale) 1,000 RU/s로 프로비저닝됩니다.

2단계: 샘플 데이터 삽입

이 스크립트는 items.json에 있는 100개의 야외 제품 항목을 컨테이너에 업서트(upsert)합니다. 각 항목은 id, name, description, category, tags 및 기타 몇 가지 필드를 가지고 있지만, 1단계에서 설정한 정책에 따라 /description 필드만 임베딩 모델로 전송됩니다.

python insert_sample_data.py

항목이 삽입될 때마다 한 줄씩 표시됩니다. 아직 어떤 항목에도 임베딩 필드가 없지만, Azure Cosmos DB가 변경 사항을 감지하고 비동기적으로 임베딩을 생성합니다.

3단계: Azure 포털에서 임베딩 확인

Azure portal을 열고, Azure Cosmos DB 계정 → Data Explorer로 이동하여 1단계에서 생성한 컨테이너를 열고 아래 쿼리를 실행합니다.

SELECT VALUE COUNT(1) FROM c WHERE IS_DEFINED(c.embedding)

카운트가 100에 도달하면 모든 임베딩이 생성된 것입니다.

4단계: 벡터 검색 실행

이제 모든 항목에 임베딩이 생성되었으므로, 컨테이너를 대상으로 벡터 검색(vector search)을 실행할 수 있습니다. 이 스크립트는 Azure Cosmos DB가 항목 생성에 사용했던 것과 동일한 Microsoft Foundry 임베딩 모델 배포를 호출하여( .env 파일에 설정한 FOUNDRY_API_KEY 사용) 쿼리 문자열을 임베딩한 다음, VectorDistance() 쿼리를 실행하여 코사인 유사도(cosine similarity)를 기준으로 가장 유사한 항목을 찾습니다.

python vector_search.py "I need to stay warm on a cold ski trip"

이를 실행하면 다음과 유사한 결과가 반환됩니다. 항목 설명에 해당 단어가 정확히 포함되어 있지 않더라도, "추운 스키 여행에서 따뜻하게 지내야 한다"는 개념과 관련된 스키 관련 장갑, 재킷, 그리고 일부 추운 날씨용 침낭 등이 섞여서 나타날 것입니다.

Query: 'I need to stay warm on a cold ski trip'
Top 5 results:

...

가능한 작업들을 체감해 볼 수 있는 몇 가지 추가 쿼리입니다.

계획 중심의 쿼리를 시도해 보세요. 장비 대신 여행 계획 도서나 트레일 가이드가 결과로 나옵니다:

vector_search.py "plan a long hike in unfamiliar terrain"

또는 더 구체적인 쿼리를 시도해 보세요. 최상단 결과는 1인용 쉘터(shelter)이며, 그 아래로 밀접하게 관련된 텐트들이 나타납니다:

vector_search.py "easy to set up shelter for one person"

--top-k를 사용하여 반환되는 결과의 개수를 제어할 수 있습니다 (기본값은 5입니다):

vector_search.py "lightweight cookware for backpacking" --top-k 3

순수 벡터 검색 (Pure vector search)은 의미론적으로 가장 유사한 항목을 반환하지만, 정확한 키워드 일치 여부는 고려하지 않습니다. 의미론적 의도와 특정 용어가 모두 중요한 쿼리의 경우, Azure Cosmos DB for NoSQL은 하이브리드 검색 (hybrid search)을 지원하며, 이는 Reciprocal Rank Fusion을 사용하여 벡터 유사도 (vector similarity)와 전문 검색 (full-text, BM25) 랭킹을 결합합니다. 또한 WHERE 절을 추가하여 결과를 특정 카테고리나 태그로 좁힐 수도 있습니다. 이 모든 쿼리는 통합 임베딩 (Integrated Embeddings)이 생성하고 동기화 상태를 유지하는 동일한 임베딩을 대상으로 실행됩니다.

데이터 기반의 간단한 RAG 에이전트 구축하기

검색 증강 생성 (Retrieval-Augmented Generation, RAG)은 언어 모델이 지식 베이스 (knowledge base)에서 관련 콘텐츠를 먼저 검색한 다음, 해당 콘텐츠를 답변의 근거 (grounding)로 사용하여 사용자의 질문에 답하는 패턴입니다. Azure Cosmos DB 데이터를 활용한 RAG의 경우, 검색 (retrieval) 단계는 벡터 검색 (vector search)이며, 지식 베이스는 사용자의 컨테이너 (container)가 됩니다.

벡터 검색 (vector search)을 검색 증강 생성 (Retrieval-Augmented Generation, RAG) 애플리케이션으로 전환하려면, 이를 언어 모델 (language model)이 호출할 수 있는 도구 (tool)로 래핑 (wrap)합니다. 우리는 사용자의 쿼리 (query)를 임베딩 (embedding)하고 단계 4에서 보았던 것과 동일한 VectorDistance() 검색을 실행하는 retrieve_context 도구를 갖춘 간단한 LangChain 에이전트 (agent)를 사용합니다. 에이전트는 도구를 호출할 시점을 결정하고, 결과를 읽고, 자연어 (natural language)로 답변합니다. 에이전트가 사용자의 데이터에 근거하도록 (grounded) 하기 위해, 시스템 프롬프트 (system prompt)는 모델에게 검색된 결과에 나타나는 제품만을 추천하고 검색된 텍스트에 포함된 어떠한 지침도 무시하도록 지시합니다.

에이전트에는 대규모 언어 모델 (large language model, LLM)이 필요합니다. Microsoft Foundry 리소스에 모델 (예: gpt-5.4)을 배포 (Deploy the model)하고, .env 파일의 FOUNDRY_CHAT_DEPLOYMENT를 배포 이름으로 설정하세요. 에이전트는 채팅 (chat)과 쿼리 시점의 임베딩 (embedding) 호출 모두에 동일한 FOUNDRY_API_KEY를 사용합니다.

에이전트를 시작하면 카탈로그 스타일의 질문을 할 수 있는 간단한 대화형 프롬프트 (interactive prompt)가 열립니다:

python rag_agent.py

몇 가지 쿼리를 시도해 보세요. 예를 들어, 제품 카테고리에 대해 질문하면 에이전트가 모든 관련 항목을 찾아냅니다:

사용자: 추운 밤에 사용할 수 있는 침낭은 어떤 것들이 있나요?

에이전트는 검색 도구를 호출하여 카탈로그에 있는 세 가지 추운 날씨용 다운 백 (down bags)을 가져오고, 공통된 850 필 (850-fill) 충전량과 용도를 함께 나열합니다.

특정 제품 기능에 대해 질문하면 에이전트가 결과를 필터링해 줍니다:

사용자: 마그네틱 렌즈가 있는 스키 고글은 무엇이 있나요?

벡터 검색은 카탈로그에 있는 세 가지 스키 고글을 모두 반환하지만, 에이전트는 실제로 마그네틱 렌즈 시스템을 갖춘 두 가지만 추천합니다. 이것이 순수 벡터 검색 (pure vector search) 위에 더해진 에이전트 + RAG의 장점입니다: 광범위한 검색 (broad retrieval), 정교한 추론 (narrow reasoning).

통합 임베딩 (Integrated Embeddings)은 아이템 임베딩을 소스 데이터와 자동으로 동기화하므로, 제품이 추가, 업데이트 또는 삭제되더라도 에이전트의 검색 (retrieval) 정확도가 유지됩니다. 인덱스를 최신 상태로 유지하기 위해 별도의 임베딩 파이프라인 (embedding pipeline)을 구축하거나 실행할 필요가 없습니다.

통합 임베딩 (Integrated Embeddings)을 구성하는 다른 방법

sourcePaths에 여러 경로를 나열함으로써 한 번에 하나 이상의 속성을 임베딩할 수 있습니다. Azure Cosmos DB는 해당 값들을 임베딩 모델 (embedding model)을 위한 단일 입력값으로 결합합니다. 이는 단일 필드에 충분한 정보가 담겨 있지 않을 때 유용합니다. 예를 들어, 제품 제목 (product title)은 그 자체로는 너무 짧은 경우가 많지만, /title과 /description을 결합하면 더 풍부한 벡터 (vector)를 생성할 수 있습니다.

{
  "vectorEmbeddings": [
    {
...

또한 vectorEmbeddings에 더 많은 항목을 추가하여 여러 개의 임베딩을 생성할 수도 있습니다. 각 항목은 고유한 경로 (path), 모델 (model), 소스 속성 (source properties)을 가지며, Azure Cosmos DB는 모든 벡터를 병렬로 유지 관리합니다.

아래 예시는 text-embedding-3-large를 사용하여 /description으로부터 /desc_embedding을 생성하고, text-embedding-3-small를 사용하여 /title로부터 /title_embedding을 생성하는 방법을 보여줍니다.

{
  "vectorEmbeddings": [
    {
...

퍼블릭 프리뷰 (Public Preview)에서 지원되는 기능