Hızlı Başlangıç: Azure Cosmos DB'da Python ile vektör araması

Python istemci kitaplığıyla Azure Cosmos DB vektör araması kullanın. Vektör verilerini uygulamalarınızda verimli bir şekilde depolayın ve sorgulayın.

Bu hızlı başlangıçta, text-embedding-3-small modelindeki vektörlerle birlikte bir JSON dosyasında örnek bir otel veri kümesi kullanılmaktadır. Veri kümesi otel adlarını, konumlarını, açıklamalarını ve vektör eklemelerini içerir.

GitHub üzerinde kaynak sağlama ile örnek kodu bulun.

Prerequisites

• Azure aboneliği

  • Azure aboneliğiniz yoksa ücretsiz bir hesap oluşturun

• Mevcut Azure Cosmos DB kaynak veri düzlemi erişimi

  • Kaynağınız yoksa, yeni bir kaynak oluşturun
  • İstemci IP adresinize erişime izin verecek şekilde yapılandırılmış güvenlik duvarı
  • Atanan rol tabanlı erişim denetimi (RBAC) rolleri:
    • Cosmos DB Yerleşik Veri Katkıda Bulunanı (veri düzlemi)
    • Rol Kimliği: 00000000-0000-0000-0000-000000000002

• Azure OpenAI kaynağı

  • Özel alan adı yapılandırıldı
  • Rol tabanlı erişim denetimi (RBAC) rolü atandı:
    • Bilişsel Hizmetler OpenAI Kullanıcısı
    • Rol Kimliği: 5e0bd9bd-7b93-4f28-af87-19fc36ad61bd
  • text-embedding-3-small dağıtılan model

• Visual Studio Code

  • Cosmos DB uzantısı

• Python 3.10 veya üzeri

Vektörlerle veri dosyası oluşturma

1. Oteller veri dosyası için yeni bir veri dizini oluşturun:

   • Linux/macOS
   • Windows

   mkdir data
   

2. vektörler içeren ham veri dosyasınıdata dizininize indirin.

   • 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
   

Python projesi oluşturma

1. Projeniz için veri diziniyle aynı düzeyde yeni bir eşdüzey dizin oluşturun ve bunu Visual Studio Code'da açın:

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

2. Terminalde Python bir sanal ortam oluşturun ve etkinleştirin:

   python -m venv .venv
   

   • Linux/macOS
   • Windows

   source .venv/bin/activate
   

3. Proje kökünde aşağıdaki içeriğe sahip bir requirements.txt dosya oluşturun:

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

4. Gerekli paketleri yükleyin:

   pip install -r requirements.txt
   

   • azure-cosmos - veritabanı işlemleri için Azure Cosmos DB istemci kitaplığı
   • azure-identity - parolasız (yönetilen kimlik) bağlantılar için Azure kimlik doğrulama kitaplığı
   • openai - Azure OpenAI ile eklemeler oluşturmak için OpenAI SDK'sı
   • python-dotenv - Bir dosyadan .env ortam değişkenlerini yükler

5. Ortam değişkenleri için proje kökünde bir .env dosya oluşturun:

   # 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
   

   Dosyadaki .env yer tutucu değerlerini kendi bilgilerinizle değiştirin:

   • AZURE_OPENAI_EMBEDDING_ENDPOINT: Azure OpenAI kaynak uç noktası URL'niz
   • AZURE_COSMOSDB_ENDPOINT: Azure Cosmos DB uç nokta URL'niz

Belge şemasını anlama

Uygulamayı oluşturmadan önce vektörlerin Azure Cosmos DB belgelerinde nasıl depolandığını anlayın. Her otel belgesinde aşağıdakiler bulunur:

• Standart alanlar: HotelId, HotelName, Description, Category, vb.
• Vektör alanı: DescriptionVector - Otel açıklamasının anlamsal anlamını temsil eden 1536 kayan noktalı sayı dizisi

Otel belgesi yapısının basitleştirilmiş bir örneği aşağıda verilmiştir:

{
  "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
  ]
}

Eklemeleri depolamayla ilgili önemli noktalar:

• Vektör dizileri belgelerinizde standart JSON dizileri olarak depolanır
• Vektör ilkesi yolu (/DescriptionVector), veri türünü (float32), boyutları (1536) ve uzaklık işlevini (kosinüs) tanımlar
• Dizin oluşturma ilkesi , verimli benzerlik araması için vektör alanında bir vektör dizini oluşturur
• Ekleme performansını iyileştirmek için vektör alanı standart dizin oluşturmanın dışında tutulmalıdır

Bu ilkeler, bu örnek projenin uzaklık ölçümleri için Bicep şablonlarında tanımlanır. Vektör ilkeleri ve dizin oluşturma hakkında daha fazla bilgi için bkz. Azure Cosmos DB'de vektör araması.

Vektör araması için kod dosyaları oluşturma

Python dosyalarınız için bir src dizini oluşturun. İki dosya ekleyin: vector_search.py ve utils.py vektör arama uygulamanız için:

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

Vektör araması için kod oluşturma

Aşağıdaki kodu dosyaya yapıştırın vector_search.py .

"""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()

Bu kod:

• Ortam değişkenlerinden bir DiskANN veya quantizedFlat vektör algoritması yapılandırılır.
• Azure OpenAI ve Azure Cosmos DB'ye parolasız kimlik doğrulaması kullanarak bağlanır.
• JSON dosyasından önceden vektörleştirilmiş otel verilerini yükler.
• Verileri uygun kapsayıcıya ekler.
• Doğal dil sorgusu (quintessential lodging near running trails, eateries, retail) için ekleme oluşturur.
• Benzerlik puanına göre sıralanan en benzer 5 oteli almak için bir VectorDistance SQL sorgusu yürütür.
• Eksik istemciler, geçersiz algoritma seçimi ve mevcut olmayan kapsayıcılar/veritabanları için hataları işler.

Kodu anlama: Azure OpenAI ile eklemeler oluşturma

Kod, sorgu metni için eklemeler oluşturur:

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

client.embeddings.create için bu OpenAI API çağrısı, "koşu patikalarının yakınında çok uygun bir konaklama" gibi metni anlamsal anlamını yakalayan 1536 boyutlu bir vektöre dönüştürür. Ekleme oluşturma hakkında daha fazla ayrıntı için bkz. Azure OpenAI ekleme belgeleri.

Kodu anlama: Azure Cosmos DB'de vektörleri depolama

Vektör dizilerine sahip tüm belgeler işlevi kullanılarak upsert_item eklenir:

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

Bu, önceden oluşturulmuş DescriptionVector dizilerini içeren otel belgelerini kapsayıcıya ekler. Her belge, id ile HotelId eşleşen bir alan alır ve işlev, upsert işlemlerini yönetir, böylece belgeler sorunsuz bir şekilde yeniden eklenebilir.

Kodu anlama: Vektör benzerlik araması çalıştırma

Kod, VectorDistance işlevi kullanılarak bir vektör araması gerçekleştirir.

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,
    )
)

Bu kod, sorgunun ekleme vektörünü (@embedding) her belgenin depolanan vektör alanıylaDescriptionVector ( ) karşılaştırmak için VectorDistance işlevini kullanan, adı ve benzerlik puanı en az benzer olan en iyi 5 oteli sıralanmış olarak döndüren parametreli bir SQL sorgusu oluşturur. Sorgu yerleştirmesi, enjeksiyondan kaçınmak için bir parametre olarak geçirilir ve önceden Azure OpenAI'nin embeddings.create çağrısının bir sonucu olarak elde edilir.

Bu sorgu ne döndürür:

• Vektör uzaklığı temelinde en benzer 5 otel
• Otel özellikleri: HotelName, Description, Rating
• SimilarityScore: Her otelin sorgunuza ne kadar benzer olduğunu gösteren sayısal değer
• En benzerden en az benzere sıralanmış sonuçlar

İşlev hakkında VectorDistance daha fazla bilgi için VectorDistance belgelerine bakın.

Yardımcı program işlevleri oluşturma

Aşağıdaki kodu içine utils.pyyapıştırın:

"""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)

Bu yardımcı program modülü şu temel işlevleri sağlar:

• get_clients_passwordless: Parolasız kimlik doğrulaması kullanarak Azure OpenAI ve Azure Cosmos DB için istemciler oluşturur ve döndürür. Her iki kaynakta da RBAC'yi etkinleştirin ve Azure CLI'da oturum açın
• insert_data: Azure Cosmos DB kapsayıcısına veri ekler ve her işlem için İstek Birimlerini (RU) izler
• print_search_results: Puan ve otel adı dahil olmak üzere bir vektör aramasının sonuçlarını yazdırır
• validate_field_name: Verilerde bir alan adının mevcut olduğunu doğrular
• get_bulk_operation_rus: Azure Cosmos DB yanıt üst bilgilerinden toplam RU maliyetini ayıklar

Azure CLI ile kimlik doğrulaması

Uygulamanın Azure kaynaklarına güvenli bir şekilde erişebilmesi için uygulamayı çalıştırmadan önce Azure CLI'da oturum açın.

az login

Kod, Azure Cosmos DB'ye ve Azure OpenAI'ye get_clients_passwordless'den utils.py işlevini kullanarak erişmek için yerel geliştirici kimlik doğrulamanızı kullanır. AZURE_TOKEN_CREDENTIALS=AzureCliCredential ayarladığınızda, kimlik bilgisi zincirinden DefaultAzureCredential'in hangi kimlik bilgisini kullanacağını deterministik olarak belirlersiniz. İşlev, azure-identity'den DefaultAzureCredential kullanır, bu da sıralı bir kimlik bilgisi sağlayıcısı zincirinde ilerler fakat önce Azure CLI kimlik bilgilerini çözümlemek için ortamdaki değişkene uyar. Azure Kimlik kitaplığını kullanarak Azure hizmetlerinde Python uygulamalarının kimliğini doğrulama hakkında daha fazla bilgi edinin.

Uygulamayı çalıştırma

VECTOR_ALGORITHM Çalıştırılacak vektör dizini uygulamasını seçmek için ortam değişkenini kullanın. değişken, uygulamanın bağlandığı kapsayıcıyı Azure Cosmos DB denetler.

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

Uygulamanın günlük ve çıktıları şunları gösterir:

• Kapsayıcı bağlantı durumu
• Veri ekleme durumu
• Otel adları ve benzerlik puanları ile arama sonuçları

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

Mesafe ölçümleri

Azure Cosmos DB, vektör benzerliği için üç uzaklık işlevini destekler:

Uzaklık işlevi, kapsayıcı oluşturulurken vektör ekleme ilkesinde ayarlanır. Bu, örnek depodaki altyapıda sağlanır. Kapsayıcı tanımının bir parçası olarak tanımlanır.

{
    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'
        }
        ]
    }
}

Bu Bicep kodu, otel belgelerini vektör arama özellikleriyle depolamak için Azure Cosmos DB kapsayıcı yapılandırmasını tanımlar.

Benzerlik puanlarını yorumlama

Kosinüs benzerliği kullanan örnek çıktıda:

• 0.4991 (Royal Cottage Resort) - En yüksek benzerlik, "koşu parkurlarına yakın konaklama, yemek mekanları, perakende" için en iyi eşleşme
• 0.4388 (Roach Motel) - Daha düşük benzerlik, hala ilgili ama daha az eşleştirme
• 1,0'a yakın puanlar daha güçlü semantik benzerliği gösterir
• 0'a yakın puanlar çok az benzerlik gösteriyor

Önemli notlar:

• Mutlak puan değerleri ekleme modelinize ve verilerinize bağlıdır
• Mutlak eşikler yerine göreli derecelendirmeye odaklanma
• Azure OpenAI eklemeleri kosinüs benzerliğiyle en iyi sonucu sağlar

Uzaklık işlevleri hakkında ayrıntılı bilgi için bkz. Uzaklık işlevleri nelerdir?

Visual Studio Code'da verileri görüntüleme ve yönetme

1. Azure Cosmos DB hesabınıza bağlanmak için Visual Studio Code'da Cosmos DB uzantısını seçin.

2. Hotels veritabanındaki verileri ve dizinleri görüntüleyin.

   

Kaynakları temizle

NoSQL hesabı için API'ye artık ihtiyacınız kalmadığında ilgili kaynak grubunu silebilirsiniz.

az group delete --name $resourceGroupName

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

İlgili içerik

• Azure Cosmos DB'de vektör araması
• Azure Cosmos DB için Belge Dizin Oluşturucu (önizleme)
• Azure Cosmos DB'de vektör eklemeleri
• Azure RBAC yerleşik rolleri