Início Rápido: Pesquisa de vetor com Python no Azure Cosmos DB

Use a pesquisa de vetor em Azure Cosmos DB com a biblioteca de clientes Python. Armazene e consulte dados de vetor com eficiência em seus aplicativos.

Este guia de início rápido usa um conjunto de dados de hotel de exemplo em um arquivo JSON com vetores do modelo text-embedding-3-small. O conjunto de dados inclui nomes de hotéis, locais, descrições e inserções de vetor.

Localize o código de exemplo com provisionamento de recursos em GitHub.

Prerequisites

• Uma assinatura de Azure

  • Se você não tem uma assinatura do Azure, crie uma conta gratuita

• Um acesso existente ao plano de dados de recursos do Azure Cosmos DB

  • Se você não tiver um recurso, crie um novo recurso
  • Firewall configurado para permitir o acesso ao endereço IP do cliente
  • Funções de RBAC (controle de acesso baseado em função) atribuídas:
    • Colaborador de dados interno do Cosmos DB (plano de dados)
    • ID da função: 00000000-0000-0000-0000-000000000002

• Recurso do Azure OpenAI

  • Domínio personalizado configurado
  • Função RBAC (controle de acesso baseado em função) atribuída:
    • Usuário do OpenAI de Serviços Cognitivos
    • ID da função: 5e0bd9bd-7b93-4f28-af87-19fc36ad61bd
  • text-embedding-3-small modelo implantado

• Código do Visual Studio

  • Extensão do Cosmos DB

• Python 3.10 ou posterior

Criar arquivo de dados com vetores

1. Crie um novo diretório de dados para o arquivo de dados de hotéis:

   • Linux/macOS
   • Windows

   mkdir data
   

2. Baixe o arquivo de dados raw com vetores para o diretório data:

   • Linux/macOS
   • Windows

   curl -o data/HotelsData_toCosmosDB_Vector.json https://raw.githubusercontent.com/Azure-Samples/cosmos-db-vector-samples/refs/heads/main/data/HotelsData_toCosmosDB_Vector.json
   

Criar um projeto de Python

1. Crie um novo diretório irmão para seu projeto, no mesmo nível do diretório de dados e abra-o no Visual Studio Code:

   mkdir vector-search-quickstart
   code vector-search-quickstart
   

2. No terminal, crie e ative um ambiente virtual Python:

   python -m venv .venv
   

   • Linux/macOS
   • Windows

   source .venv/bin/activate
   

3. Crie um requirements.txt arquivo na raiz do projeto com o seguinte conteúdo:

   azure-cosmos>=4.7.0
   azure-identity>=1.18.0
   openai>=1.57.0
   python-dotenv>=1.0.1
   

4. Instale os pacotes necessários:

   pip install -r requirements.txt
   

   • azure-cosmos – Azure Cosmos DB biblioteca de clientes para operações de banco de dados
   • azure-identity - biblioteca de autenticação Azure para conexões sem senha (identidade gerenciada)
   • openai – SDK do OpenAI para gerar inserções com o Azure OpenAI
   • python-dotenv – Carrega variáveis de ambiente de um .env arquivo

5. Crie um .env arquivo na raiz do projeto para variáveis de ambiente:

   # Identity for local developer authentication with Azure CLI
   AZURE_TOKEN_CREDENTIALS=AzureCliCredential
   
   # Azure OpenAI Embedding Settings
   AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
   AZURE_OPENAI_EMBEDDING_API_VERSION=2024-08-01-preview
   AZURE_OPENAI_EMBEDDING_ENDPOINT=
   
   # Cosmos DB configuration
   AZURE_COSMOSDB_ENDPOINT=
   
   # Data file
   DATA_FILE_WITH_VECTORS=../data/HotelsData_toCosmosDB_Vector.json
   FIELD_TO_EMBED=Description
   EMBEDDED_FIELD=DescriptionVector
   EMBEDDING_DIMENSIONS=1536
   

   Substitua os valores de espaço reservado no arquivo .env por suas próprias informações.

   • AZURE_OPENAI_EMBEDDING_ENDPOINT: URL do ponto de extremidade do seu recurso Azure OpenAI
   • AZURE_COSMOSDB_ENDPOINT: a URL de endpoint do Azure Cosmos DB

Entender o esquema do documento

Antes de criar o aplicativo, entenda como os vetores são armazenados em documentos do Azure Cosmos DB. Cada documento de hotel contém:

• Campos padrão: HotelId, , HotelName, Description, Categoryetc.
• Campo de vetor: DescriptionVector - uma matriz de 1536 números de ponto flutuante que representam o significado semântico da descrição do hotel

Aqui está um exemplo simplificado de uma estrutura de documentos de hotel:

{
  "HotelId": "1",
  "HotelName": "Stay-Kay City Hotel",
  "Description": "This classic hotel is fully-refurbished...",
  "Rating": 3.6,
  "DescriptionVector": [
    -0.04886505,
    -0.02030743,
    0.01763356,
    ...
    // 1536 dimensions total
  ]
}

Principais pontos sobre como armazenar inserções:

• As matrizes de vetor são armazenadas como matrizes JSON padrão em seus documentos
• A política de vetor define o caminho (/DescriptionVector), o tipo de dados (float32), as dimensões (1536) e a função de distância (cosseno)
• A política de indexação cria um índice de vetor no campo de vetor para uma pesquisa de similaridade eficiente
• O campo de vetor deve ser excluído da indexação padrão para otimizar o desempenho de inserção

Essas políticas são definidas nos modelos Bicep para as métricas de distância deste projeto de exemplo. Para obter mais informações sobre políticas de vetor e indexação, consulte a pesquisa de vetor no Azure Cosmos DB.

Criar arquivos de código para pesquisa de vetor

Crie um diretório src para seus arquivos de Python. Adicione dois arquivos: vector_search.py e utils.py para sua implementação de pesquisa de vetor:

mkdir src
touch src/__init__.py
touch src/vector_search.py
touch src/utils.py

New-Item -ItemType Directory -Force -Path src | Out-Null
New-Item -ItemType File -Path src/__init__.py | Out-Null
New-Item -ItemType File -Path src/vector_search.py | Out-Null
New-Item -ItemType File -Path src/utils.py | Out-Null

Criar código para pesquisa de vetor

Cole o código a seguir no vector_search.py arquivo.

"""Azure Cosmos DB NoSQL Vector Search — main entry point.

Loads hotel data, bulk-inserts into the selected container (DiskANN or
QuantizedFlat), generates a query embedding via Azure OpenAI, and
executes a VectorDistance() similarity search.
"""

import os
import sys
from pathlib import Path

from dotenv import load_dotenv

sys.path.insert(0, str(Path(__file__).parent))

from utils import (
    get_clients_passwordless,
    get_clients,
    insert_data,
    print_search_results,
    read_file_return_json,
    validate_field_name,
    get_query_activity_id,
)

# ---------------------------------------------------------------------------
# Load environment
# ---------------------------------------------------------------------------
load_dotenv()

ALGORITHM_CONFIGS: dict[str, dict[str, str]] = {
    "diskann": {
        "container_name": "hotels_diskann",
        "algorithm_name": "DiskANN",
    },
    "quantizedflat": {
        "container_name": "hotels_quantizedflat",
        "algorithm_name": "QuantizedFlat",
    },
}


def _build_config() -> dict[str, str | int]:
    """Build runtime configuration from environment variables."""
    return {
        "query": "quintessential lodging near running trails, eateries, retail",
        "db_name": os.getenv("AZURE_COSMOSDB_DATABASENAME", "Hotels"),
        "algorithm": os.getenv("VECTOR_ALGORITHM", "diskann").strip().lower(),
        "data_file": os.getenv("DATA_FILE_WITH_VECTORS", "../data/HotelsData_toCosmosDB_Vector.json"),
        "embedded_field": os.getenv("EMBEDDED_FIELD", "DescriptionVector"),
        "embedding_dimensions": int(os.getenv("EMBEDDING_DIMENSIONS", "1536")),
        "deployment": os.getenv("AZURE_OPENAI_EMBEDDING_MODEL", "text-embedding-3-small"),
        "distance_function": os.getenv("VECTOR_DISTANCE_FUNCTION", "cosine"),
    }


def main() -> None:
    """Run the vector search demonstration."""
    config = _build_config()

    # Try passwordless auth first, fall back to key-based
    clients = get_clients_passwordless()
    if not clients["ai_client"] or not clients["db_client"]:
        clients = get_clients()

    ai_client = clients["ai_client"]
    db_client = clients["db_client"]

    try:
        algorithm = config["algorithm"]
        if algorithm not in ALGORITHM_CONFIGS:
            valid = ", ".join(ALGORITHM_CONFIGS)
            raise ValueError(
                f"Invalid algorithm '{algorithm}'. Must be one of: {valid}"
            )

        if not ai_client:
            raise RuntimeError(
                "Azure OpenAI client is not configured. "
                "Please check your environment variables."
            )
        if not db_client:
            raise RuntimeError(
                "Cosmos DB client is not configured. "
                "Please check your environment variables."
            )

        algo_cfg = ALGORITHM_CONFIGS[algorithm]
        container_name = algo_cfg["container_name"]

        database = db_client.get_database_client(config["db_name"])
        print(f"Connected to database: {config['db_name']}")

        container = database.get_container_client(container_name)
        print(f"Connected to container: {container_name}")
        print(f"\n📊 Vector Search Algorithm: {algo_cfg['algorithm_name']}")
        print(f"📏 Distance Function: {config['distance_function']}")

        # Verify the container exists
        try:
            container.read()
        except Exception as e:
            status_code = getattr(e, "status_code", None)
            if status_code == 404:
                raise RuntimeError(
                    f"Container or database not found. Ensure database "
                    f"'{config['db_name']}' and container '{container_name}' "
                    f"exist before running this script."
                ) from e
            raise

        data_path = Path(__file__).parent.parent / config["data_file"]
        data = read_file_return_json(str(data_path))
        insert_data(container, data)

        embedding_response = ai_client.embeddings.create(
            model=config["deployment"],
            input=[config["query"]],
        )
        query_embedding = embedding_response.data[0].embedding

        safe_field = validate_field_name(config["embedded_field"])
        query_text = (
            f"SELECT TOP 5 c.HotelName, c.Description, c.Rating, "
            f"VectorDistance(c.{safe_field}, @embedding) AS SimilarityScore "
            f"FROM c "
            f"ORDER BY VectorDistance(c.{safe_field}, @embedding)"
        )

        print("\n--- Executing Vector Search Query ---")
        print(f"Query: {query_text}")
        print(
            f"Parameters: @embedding (vector with {len(query_embedding)} dimensions)"
        )
        print("--------------------------------------\n")

        results = list(
            container.query_items(
                query=query_text,
                parameters=[{"name": "@embedding", "value": query_embedding}],
                enable_cross_partition_query=True,
            )
        )

        # Extract diagnostics
        response_headers = container.client_connection.last_response_headers
        activity_id = get_query_activity_id(response_headers)
        if activity_id:
            print(f"Query activity ID: {activity_id}")

        request_charge_raw = response_headers.get("x-ms-request-charge", "0") if response_headers else "0"
        try:
            request_charge = float(request_charge_raw)
        except (ValueError, TypeError):
            request_charge = 0.0

        print_search_results(results, request_charge)

    except Exception as error:
        print(f"App failed: {error}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

Esse código:

• Configura um algoritmo de vetor DiskANN ou quantizedFlat a partir de variáveis de ambiente.
• Conecta-se ao Azure OpenAI e ao Azure Cosmos DB usando a autenticação sem senha.
• Carrega dados de hotel pré-vetorizados de um arquivo JSON.
• Insere dados no contêiner apropriado.
• Gera uma inserção para uma consulta de linguagem natural (quintessential lodging near running trails, eateries, retail).
• Executa uma VectorDistance consulta SQL para recuperar os cinco hotéis mais semanticamente semelhantes classificados por pontuação de similaridade.
• Lida com erros para clientes ausentes, seleção de algoritmo inválida e contêineres ou bancos de dados inexistentes.

Entender o código: gerar inserções com o Azure OpenAI

O código cria inserções para o texto da consulta:

embedding_response = ai_client.embeddings.create(
    model=config["deployment"],  # OpenAI embedding model, e.g. "text-embedding-3-small"
    input=[config["query"]],     # List of description strings to embed
)
query_embedding = embedding_response.data[0].embedding

Essa chamada à API OpenAI para client.embeddings.create converte texto como "hospedagem quintessencial perto de trilhas para corrida" em um vetor de 1.536 dimensões que captura seu significado semântico. Para obter mais detalhes sobre como gerar incorporações, consulte a documentação de incorporações do Azure OpenAI.

Entender o código: armazenar vetores no Azure Cosmos DB

Todos os documentos com matrizes de vetor são inseridos usando a upsert_item função:

for item in data:
    doc = {"id": item["HotelId"], **item}
    response = container.upsert_item(body=doc)

Isso insere documentos de hotel, incluindo suas matrizes pré-geradas DescriptionVector, no contêiner. Cada documento obtém um campo id mapeado de HotelId, e a função manipula upserts para que os documentos possam ser re-inseridos com segurança.

Entender o código: executar pesquisa de similaridade de vetor

O código executa uma pesquisa de vetor usando a VectorDistance função:

query_text = (
    f"SELECT TOP 5 c.HotelName, c.Description, c.Rating, "
    f"VectorDistance(c.{safe_field}, @embedding) AS SimilarityScore "
    f"FROM c "
    f"ORDER BY VectorDistance(c.{safe_field}, @embedding)"
)

results = list(
    container.query_items(
        query=query_text,
        parameters=[{"name": "@embedding", "value": query_embedding}],
        enable_cross_partition_query=True,
    )
)

Esse código cria uma consulta SQL parametrizada que usa a função VectorDistance para comparar o vetor de inserção da consulta (@embedding) com o campo de vetor armazenado de cada documento (DescriptionVector), retornando os cinco principais hotéis com seu nome e pontuação de similaridade, ordenados da mais semelhante à menos semelhante. A vetorização da consulta é passada como um parâmetro para evitar a injeção de código e vem de uma chamada anterior ao método embeddings.create do Azure OpenAI.

O que essa consulta retorna:

• Os 5 hotéis mais semelhantes com base na distância do vetor
• Propriedades do hotel: HotelName, Description, Rating
• SimilarityScore: um valor numérico que indica como cada hotel é semelhante à sua consulta
• Resultados ordenados da maioria semelhante a menos semelhante

Para obter mais informações sobre a função, consulte a VectorDistancedocumentação do VectorDistance.

Criar funções utilitárias

Cole o seguinte código em utils.py:

"""Shared utilities for Azure Cosmos DB NoSQL vector search.

Provides client initialization (passwordless and key-based), JSON I/O,
bulk insert with RU tracking, field validation, and result formatting.
"""

import json
import os
import re
import time
from typing import Any, Optional


def get_clients() -> dict[str, Any]:
    """Get Azure OpenAI and Cosmos DB clients using key-based authentication.

    Returns dict with 'ai_client' and 'db_client' (either may be None if
    the required environment variables are missing).
    """
    from azure.cosmos import CosmosClient
    from openai import AzureOpenAI

    ai_client = None
    db_client = None

    api_key = os.getenv("AZURE_OPENAI_EMBEDDING_KEY", "")
    api_version = os.getenv("AZURE_OPENAI_EMBEDDING_API_VERSION", "")
    endpoint = os.getenv("AZURE_OPENAI_EMBEDDING_ENDPOINT", "")
    deployment = os.getenv("AZURE_OPENAI_EMBEDDING_MODEL", "")

    if api_key and api_version and endpoint and deployment:
        ai_client = AzureOpenAI(
            api_key=api_key,
            api_version=api_version,
            azure_endpoint=endpoint,
            azure_deployment=deployment,
        )

    cosmos_endpoint = os.getenv("AZURE_COSMOSDB_ENDPOINT", "")
    cosmos_key = os.getenv("AZURE_COSMOSDB_KEY", "")

    if cosmos_endpoint and cosmos_key:
        db_client = CosmosClient(url=cosmos_endpoint, credential=cosmos_key)

    return {"ai_client": ai_client, "db_client": db_client}


def get_clients_passwordless() -> dict[str, Any]:
    """Get Azure OpenAI and Cosmos DB clients using DefaultAzureCredential.

    Uses managed identity / Azure CLI credentials for passwordless auth.
    Returns dict with 'ai_client' and 'db_client' (either may be None).
    """
    from azure.cosmos import CosmosClient
    from azure.identity import DefaultAzureCredential, get_bearer_token_provider
    from openai import AzureOpenAI

    ai_client = None
    db_client = None

    api_version = os.getenv("AZURE_OPENAI_EMBEDDING_API_VERSION", "")
    endpoint = os.getenv("AZURE_OPENAI_EMBEDDING_ENDPOINT", "")
    deployment = os.getenv("AZURE_OPENAI_EMBEDDING_MODEL", "")

    if api_version and endpoint and deployment:
        credential = DefaultAzureCredential()
        token_provider = get_bearer_token_provider(
            credential, "https://cognitiveservices.azure.com/.default"
        )
        ai_client = AzureOpenAI(
            api_version=api_version,
            azure_endpoint=endpoint,
            azure_deployment=deployment,
            azure_ad_token_provider=token_provider,
        )

    cosmos_endpoint = os.getenv("AZURE_COSMOSDB_ENDPOINT", "")

    if cosmos_endpoint:
        credential = DefaultAzureCredential()
        db_client = CosmosClient(url=cosmos_endpoint, credential=credential)

    return {"ai_client": ai_client, "db_client": db_client}


def read_file_return_json(file_path: str) -> list[dict[str, Any]]:
    """Read a JSON file and return its parsed contents."""
    print(f"Reading JSON file from {file_path}")
    try:
        with open(file_path, "r", encoding="utf-8") as f:
            return json.load(f)
    except FileNotFoundError:
        print(f"Error: File '{file_path}' not found")
        raise
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON in file '{file_path}': {e}")
        raise


def write_file_json(file_path: str, json_data: Any) -> None:
    """Serialize data to a JSON file."""
    try:
        with open(file_path, "w", encoding="utf-8") as f:
            json.dump(json_data, f, indent=2, ensure_ascii=False)
        print(f"Wrote JSON file to {file_path}")
    except IOError as e:
        print(f"Error writing to file '{file_path}': {e}")
        raise


def _get_document_count(container: Any) -> int:
    """Return the number of documents in a Cosmos DB container."""
    query = "SELECT VALUE COUNT(1) FROM c"
    results = list(container.query_items(query=query, enable_cross_partition_query=True))
    return results[0] if results else 0


def insert_data(
    container: Any, data: list[dict[str, Any]]
) -> dict[str, Any]:
    """Bulk-insert documents into a Cosmos DB container.

    Skips insertion if the container already has documents.
    Each item gets an 'id' field mapped from 'HotelId'.

    Returns a dict with total, inserted, failed, skipped, and requestCharge.
    """
    existing_count = _get_document_count(container)

    if existing_count > 0:
        print(f"Container already has {existing_count} documents. Skipping insert.")
        return {
            "total": 0,
            "inserted": 0,
            "failed": 0,
            "skipped": existing_count,
            "requestCharge": 0.0,
        }

    print(f"Inserting {len(data)} items...")

    inserted = 0
    failed = 0
    total_request_charge = 0.0

    start_time = time.time()

    for item in data:
        doc = {"id": item["HotelId"], **item}
        try:
            response = container.upsert_item(body=doc)
            inserted += 1
            ru = _extract_ru_from_headers(container.client_connection.last_response_headers)
            total_request_charge += ru
        except Exception as e:
            status_code = getattr(e, "status_code", None)
            if status_code == 409:
                inserted += 1
            else:
                failed += 1
                print(f"  Insert failed for item {item.get('HotelId', '?')}: {e}")

    duration = time.time() - start_time
    print(f"Bulk insert completed in {duration:.2f}s")
    print(f"\nInsert Request Charge: {total_request_charge:.2f} RUs\n")

    return {
        "total": len(data),
        "inserted": inserted,
        "failed": failed,
        "skipped": 0,
        "requestCharge": total_request_charge,
    }


def _extract_ru_from_headers(headers: Optional[dict[str, str]]) -> float:
    """Extract the request charge (RU) from Cosmos DB response headers."""
    if not headers:
        return 0.0
    raw = headers.get("x-ms-request-charge", "0")
    try:
        return float(raw)
    except (ValueError, TypeError):
        return 0.0


def validate_field_name(field_name: str) -> str:
    """Validate a field name is a safe SQL identifier.

    Prevents NoSQL injection when interpolating field names into queries.
    Allows only letters, digits, and underscores; must start with a letter
    or underscore.

    Raises ValueError if the field name is invalid.
    """
    pattern = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
    if not pattern.match(field_name):
        raise ValueError(
            f'Invalid field name: "{field_name}". '
            "Field names must start with a letter or underscore and "
            "contain only letters, numbers, and underscores."
        )
    return field_name


def print_search_results(
    search_results: list[dict[str, Any]],
    request_charge: Optional[float] = None,
) -> None:
    """Print vector search results in a consistent format."""
    print("\n--- Search Results ---")
    if not search_results:
        print("No results found.")
        return

    for i, result in enumerate(search_results, 1):
        score = result.get("SimilarityScore", 0.0)
        name = result.get("HotelName", "Unknown")
        print(f"{i}. {name}, Score: {score:.4f}")

    if request_charge is not None:
        print(f"\nVector Search Request Charge: {request_charge:.2f} RUs")
    print("")


def get_query_activity_id(response_headers: Optional[dict[str, str]]) -> Optional[str]:
    """Extract the activity ID from Cosmos DB query response headers."""
    if not response_headers:
        return None
    return response_headers.get("x-ms-activity-id")


def get_bulk_operation_rus(headers: Optional[dict[str, str]]) -> float:
    """Extract total RU cost from Cosmos DB response headers."""
    return _extract_ru_from_headers(headers)

Este módulo do utilitário fornece estas funções principais :

• get_clients_passwordless: cria e retorna clientes para o Azure OpenAI e o Azure Cosmos DB usando a autenticação sem senha. Habilitar o RBAC em ambos os recursos e fazer login no CLI do Azure
• insert_data: insere dados em um contêiner Azure Cosmos DB e rastreia RUs (Unidades de Solicitação) para cada operação
• print_search_results: imprime os resultados de uma pesquisa de vetor, incluindo a pontuação e o nome do hotel
• validate_field_name: valida se existe um nome de campo nos dados
• get_bulk_operation_rus: extrai o custo total de RU dos cabeçalhos de resposta do Azure Cosmos DB

Autenticar com a CLI do Azure

Entre na CLI do Azure antes de executar o aplicativo para que o aplicativo possa acessar os recursos do Azure com segurança.

az login

O código utiliza sua autenticação de desenvolvedor local para acessar o Azure Cosmos DB e o Azure OpenAI com a função get_clients_passwordless de utils.py. Ao definir AZURE_TOKEN_CREDENTIALS=AzureCliCredential, você seleciona deterministicamente qual credencial DefaultAzureCredential usa de sua cadeia de credenciais. A função se baseia em DefaultAzureCredential de azure-identity, que percorre uma cadeia ordenada de provedores de credenciais, mas respeita a variável de ambiente para resolver para credenciais do CLI do Azure primeiro. Saiba mais sobre como autenticar aplicativos Python em serviços Azure usando a biblioteca Azure Identity.

Executar o aplicativo

Use a VECTOR_ALGORITHM variável de ambiente para selecionar qual implementação de índice de vetor deve ser executada. A variável controla a qual contêiner do Azure Cosmos DB o aplicativo se conecta.

VECTOR_ALGORITHM=diskann python -m src.vector_search

$env:VECTOR_ALGORITHM="diskann"; python -m src.vector_search

VECTOR_ALGORITHM=quantizedflat python -m src.vector_search

$env:VECTOR_ALGORITHM="quantizedflat"; python -m src.vector_search

O registro em log e a saída do aplicativo mostram:

• Status da conexão de contêiner
• Status da inserção de dados
• Resultados da pesquisa com nomes de hotéis e pontuações de similaridade

Connected to database: Hotels
Connected to container: hotels_diskann

📊 Vector Search Algorithm: DiskANN
📏 Distance Function: cosine

Reading JSON file from ..\data\HotelsData_toCosmosDB_Vector.json
Container already has 50 documents. Skipping insert.

--- Executing Vector Search Query ---
Query: SELECT TOP 5 c.HotelName, c.Description, c.Rating, VectorDistance(c.DescriptionVector, @embedding) AS SimilarityScore FROM c ORDER BY VectorDistance(c.DescriptionVector, @embedding)
Parameters: @embedding (vector with 1536 dimensions)
--------------------------------------

Query activity ID: <ACTIVITY_ID>

--- Search Results ---
1. Royal Cottage Resort, Score: 0.4991
2. Country Comfort Inn, Score: 0.4786
3. Nordick's Valley Motel, Score: 0.4635
4. Economy Universe Motel, Score: 0.4461
5. Roach Motel, Score: 0.4388

Vector Search Request Charge: 5.33 RUs

Connected to database: Hotels
Connected to container: hotels_quantizedflat

📊 Vector Search Algorithm: QuantizedFlat
📏 Distance Function: cosine

Reading JSON file from ..\data\HotelsData_toCosmosDB_Vector.json
Container already has 50 documents. Skipping insert.

--- Executing Vector Search Query ---
Query: SELECT TOP 5 c.HotelName, c.Description, c.Rating, VectorDistance(c.DescriptionVector, @embedding) AS SimilarityScore FROM c ORDER BY VectorDistance(c.DescriptionVector, @embedding)
Parameters: @embedding (vector with 1536 dimensions)
--------------------------------------

Query activity ID: <ACTIVITY_ID>

--- Search Results ---
1. Royal Cottage Resort, Score: 0.4991
2. Country Comfort Inn, Score: 0.4786
3. Nordick's Valley Motel, Score: 0.4635
4. Economy Universe Motel, Score: 0.4461
5. Roach Motel, Score: 0.4388

Vector Search Request Charge: 5.33 RUs

Métricas de distância

O Azure Cosmos DB dá suporte a três funções de distância para similaridade de vetor:

A função de distância é definida na política de inserção de vetor ao criar o contêiner. Isso é disponibilizado na infraestrutura do repositório de exemplo. Ele é definido como parte da definição de contêiner.

{
    name: 'hotels_diskann'
    partitionKeyPaths: [
        '/HotelId'
    ]
    indexingPolicy: {
        indexingMode: 'consistent'
        automatic: true
        includedPaths: [
        {
            path: '/*'
        }
        ]
        excludedPaths: [
        {
            path: '/_etag/?'
        }
        {
            path: '/DescriptionVector/*'
        }
        ]
        vectorIndexes: [
        {
            path: '/DescriptionVector'
            type: 'diskANN'
        }
        ]
    }
    vectorEmbeddingPolicy: {
        vectorEmbeddings: [
        {
            path: '/DescriptionVector'
            dataType: 'float32'
            dimensions: 1536
            distanceFunction: 'cosine'
        }
        ]
    }
}

{
    name: 'hotels_quantizedflat'
    partitionKeyPaths: [
        '/HotelId'
    ]
    indexingPolicy: {
        indexingMode: 'consistent'
        automatic: true
        includedPaths: [
        {
            path: '/*'
        }
        ]
        excludedPaths: [
        {
            path: '/_etag/?'
        }
        {
            path: '/DescriptionVector/*'
        }
        ]
        vectorIndexes: [
        {
            path: '/DescriptionVector'
            type: 'quantizedFlat'
        }
        ]
    }
    vectorEmbeddingPolicy: {
        vectorEmbeddings: [
        {
            path: '/DescriptionVector'
            dataType: 'float32'
            dimensions: 1536
            distanceFunction: 'cosine'
        }
        ]
    }
}

Esse código Bicep define uma configuração de contêiner do Azure Cosmos DB para armazenar documentos de hotel com recursos de pesquisa de vetor.

Interpretar pontuações de similaridade

Na saída de exemplo usando similaridade de cosseno:

• 0.4991 (Royal Cottage Resort) - Maior semelhança, melhor correspondência para "hospedagem perto de trilhas, restaurantes, varejo"
• 0,4388 (Motel Roach) - Menor semelhança, ainda relevante, mas menos correspondente
• Pontuações mais próximas de 1,0 indicam similaridade semântica mais forte
• Pontuações próximas a 0 indicam pouca similaridade

Notas importantes:

• Os valores de pontuação absoluta dependem do modelo de inserção e dos dados
• Concentre-se na classificação relativa em vez de limites absolutos
• As incorporações do Azure OpenAI funcionam melhor com similaridade cosenoidal

Para obter informações detalhadas sobre funções de distância, consulte O que são funções de distância?

Exibir e gerenciar dados no Visual Studio Code

1. Selecione a extensão Cosmos DB em Visual Studio Code para se conectar à sua conta Azure Cosmos DB.

2. Exiba os dados e índices no banco de dados Hotéis.

   

Limpar os recursos

Quando você não precisar mais da API para a conta NoSQL, poderá excluir o grupo de recursos correspondente.

az group delete --name $resourceGroupName

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Conteúdo relacionado

• pesquisa de vetores no Azure Cosmos DB
• Indexador de documentos para o Azure Cosmos DB (versão prévia)
• Incorporações vetoriais no Azure Cosmos DB
• Funções internas do Azure RBAC