Rövid útmutató: Vektor alapú keresés Python használatával az Azure Cosmos DB-ben

  • A következőre érvényes:: ✅ NoSQL

Használjon vektoros keresést az Azure Cosmos DB-ban a Python ügyfélkönyvtárral. A vektoradatok hatékony tárolása és lekérdezése az alkalmazásokban.

Ez a rövid útmutató egy szállodai mintaadatkészletet használ egy JSON-fájlban a szövegbeágyazási-3-kicsi modell vektoraival. Az adathalmaz szállodaneveket, helyszíneket, leírásokat és vektoros beágyazásokat tartalmaz.

Keresse meg az erőforrás-kiépítéssel rendelkező mintakódot a GitHubon.

Prerequisites

Adatfájl létrehozása vektorokkal

  1. Hozzon létre egy új adatkönyvtárat a hotels adatfájlhoz:

    mkdir data

  2. Töltse le a raw adatfájlt vektorokkal a data könyvtárba:

    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-projekt létrehozása

  1. Hozzon létre egy új testvérkönyvtárat a projekthez az adatkönyvtárral megegyező szinten, és nyissa meg a Visual Studio Code-ban:

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

  2. A terminálban hozzon létre és aktiváljon egy Python virtuális környezetet:

    python -m venv .venv

    source .venv/bin/activate

  3. Hozzon létre egy requirements.txt fájlt a projekt gyökérkönyvtárában a következő tartalommal:

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

  4. Telepítse a szükséges csomagokat:

    pip install -r requirements.txt
    • azure-cosmos – Azure Cosmos DB adatbázis-műveletek ügyfélkódtára
    • azure-identity – Azure hitelesítési kódtár jelszó nélküli (felügyelt identitás) kapcsolatokhoz
    • openai – OpenAI SDK beágyazások létrehozásához Azure OpenAI-val
    • python-dotenv – Környezeti változók betöltése fájlból .env

  5. Hozzon létre egy .env fájlt a projekt gyökerében környezeti változókhoz:

    # 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

    Cserélje le a .env fájl helyőrzőit a saját adataival.

    • AZURE_OPENAI_EMBEDDING_ENDPOINT: A Azure OpenAI-erőforrásvégpont URL-címe
    • AZURE_COSMOSDB_ENDPOINT: Az Azure Cosmos DB-végpont URL-je

A dokumentumséma ismertetése

Az alkalmazás létrehozása előtt ismerje meg, hogyan tárolják a vektorokat az Azure Cosmos DB-dokumentumok. Minden szállodai dokumentum a következőket tartalmazza:

  • Standard mezők: HotelId, HotelName, Description, Categorystb.
  • Vektormező: DescriptionVector - 1536 lebegőpontos számból álló tömb, amely a szálloda leírásának szemantikai jelentését jelöli

Íme egy egyszerűsített példa egy szállodai dokumentum struktúrájára:

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

A beágyazások tárolásának főbb pontjai:

  • A vektortömbök standard JSON-tömbökként vannak tárolva a dokumentumokban
  • A vektorszabályzat meghatározza az elérési utat (/DescriptionVector), az adattípust (float32), a dimenziókat (1536) és a távolságfüggvényt (koszinusz)
  • Az indexelési szabályzat vektorindexet hoz létre a vektormezőn a hatékony hasonlóság kereséséhez
  • A vektormezőt ki kell zárni a standard indexelésből a beszúrási teljesítmény optimalizálása érdekében

Ezek a szabályzatok a mintaprojekt távolságmetrikáinak Bicep-sablonjaiban vannak definiálva. További információ a vektorszabályzatokról és az indexelésről: Vektorkeresés az Azure Cosmos DB-ben.

Hozzon létre egy src könyvtárat a Python-fájlokhoz. Adjon hozzá két fájlt: vector_search.py és utils.py a vektorkeresés implementációjához:

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

Illessze be a következő kódot a vector_search.py fájlba.

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

Ez a kód:

  • Környezeti változókból DiskANN vagy quantizedFlat vektoros algoritmusokat konfigurál.
  • Jelszó nélküli hitelesítéssel csatlakozik az Azure OpenAI-hoz és az Azure Cosmos DB-hez.
  • Előre vektorizált szállodaadatokat tölt be egy JSON-fájlból.
  • Adatokat szúr be a megfelelő tárolóba.
  • Beágyazást hoz létre egy természetes nyelvű lekérdezéshez (quintessential lodging near running trails, eateries, retail).
  • SQL-lekérdezést VectorDistance hajt végre, amely lekéri az 5 legjobb szemantikailag hasonló szállodát a hasonlósági pontszám alapján rangsorolva.
  • Kezeli a hibákat a hiányzó ügyfelek esetén, az érvénytelen algoritmusválasztásnál, valamint a nem létező tárolók és adatbázisok esetén.

A kód ismertetése: Beágyazások létrehozása Azure OpenAI használatával

A kód beágyazásokat hoz létre a lekérdezés szövegéhez:

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

Ez a client.embeddings.create OpenAI API-hívás a "futó ösvények közelében lévő kvintesszenciális szállás" szöveget egy 1536 dimenziós vektorsá alakítja, amely rögzíti annak szemantikai jelentését. A beágyazások létrehozásával kapcsolatos további részletekért tekintse meg az Azure OpenAI-beágyazások dokumentációját.

A kód ismertetése: Vektorok tárolása az Azure Cosmos DB-ben

A függvény használatával minden vektortömböt tartalmazó dokumentum beszúrható upsert_item :

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

Ez beszúrja a szállodai dokumentumokat, beleértve az előre létrehozott DescriptionVector tömböket a tárolóba. Minden dokumentumhoz hozzárendelünk egy id mezőt a HotelId alapján, és a függvény kezeli az upserteket, így a dokumentumok biztonságosan újra beilleszthetők.

A kód vektorkeresést hajt végre a VectorDistance függvény használatával:

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

Ez a kód létrehoz egy paraméteres SQL-lekérdezést, amely a VectorDistance függvénnyel hasonlítja össze a lekérdezés beágyazási vektorát (@embedding) az egyes dokumentumok tárolt vektormezőivel (DescriptionVector), és visszaadja az első 5 szállodát a nevükkel és a hasonlósági pontszámukkal, a legkevésbé hasonlóhoz leginkább hasonló sorrendben. A lekérdezésbeágyazás paraméterként van átadva az injektálás elkerülése érdekében, és egy korábbi Azure OpenAI embeddings.create hívásból származik.

A lekérdezés eredménye:

  • Az 5 legtöbb hasonló szálloda vektoros távolság alapján
  • Szállodai tulajdonságok: HotelName, Description, Rating
  • SimilarityScore: Numerikus érték, amely jelzi, hogy az egyes hotelek mennyire hasonlítanak a lekérdezéshez
  • A leginkább hasonlótól a legkevésbé hasonló eredmények

A függvényről további információt a VectorDistanceVectorDistance dokumentációjában talál.

Segédprogramfüggvények létrehozása

Illessze be a következő kódot ide 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)

Ez a segédprogrammodul a következő fő függvényeket biztosítja:

  • get_clients_passwordless: Jelszó nélküli hitelesítéssel hoz létre és ad vissza ügyfeleket az Azure OpenAI és az Azure Cosmos DB számára. Engedélyezze az RBAC-t mindkét erőforráson, és jelentkezzen be az Azure CLI szolgáltatásba.
  • insert_data: Adatokat szúr be egy Azure Cosmos DB tárolóba, és nyomon követi az egyes műveletek kérelemegységeit
  • print_search_results: Egy vektorkeresés eredményeit nyomtatja ki, beleértve a pontszámot és a szálloda nevét
  • validate_field_name: Ellenőrzi, hogy létezik-e mezőnév az adatokban
  • get_bulk_operation_rus: Az Azure Cosmos DB válaszfejlécekből kinyeri a teljes RU-költséget

Hitelesítés az Azure CLI-vel

Jelentkezzen be az Azure CLI-be az alkalmazás futtatása előtt, hogy az alkalmazás biztonságosan hozzáférhessen az Azure-erőforrásokhoz.

az login

A kód a helyi fejlesztői hitelesítéssel fér hozzá az Azure Cosmos DB-hez és az Azure OpenAI-hoz a get_clients_passwordlessutils.py függvényével. Amikor beállítja a AZURE_TOKEN_CREDENTIALS=AzureCliCredential-t, determinisztikusan meghatározza, hogy a DefaultAzureCredential mely hitelesítő adatot használja a hitelesítő adatok láncából. A függvény a DefaultAzureCredential-re az azure-identity-ből támaszkodik, mely a hitelesítő adatok szolgáltatóinak rendezett láncolatát járja végig, és a környezeti változót figyelembe véve elsőként az Azure CLI hitelesítő adatokat alkalmazza. Tudjon meg többet arról, hogyan azonosíthatja a Python alkalmazásokat az Azure szolgáltatásokkal az Azure Identitás könyvtár használatával.

Az alkalmazás futtatása

VECTOR_ALGORITHM A környezeti változóval kiválaszthatja, hogy melyik vektorindex-implementációt szeretné futtatni. A változó azt szabályozza, hogy melyik Azure Cosmos DB tárolóhoz csatlakozik az alkalmazás.

Linux/macOS:

VECTOR_ALGORITHM=diskann python -m src.vector_search

Windows:

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

Az alkalmazás naplózása és kimenete a következő:

  • Tárolókapcsolat állapota
  • Adatbeszúrási állapot
  • Keresési eredmények hotelnevekkel és hasonlósági pontszámokkal
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

Távolsági metrikák

Azure Cosmos DB három távolságfüggvényt támogat a vektorok hasonlóságához:

Távolság függvény Pontszámtartomány Értelmezés A legjobb választás erre
Koszinusz (alapértelmezett) 0,0–1,0 A magasabb pontszámok (közelebb az 1,0-hoz) nagyobb hasonlóságot jeleznek Általános szöveghasonlóság, Azure OpenAI-beágyazások (ebben a gyorstalpalóban használatos)
Euklideszi (L2) 0,0–∞ Alacsonyabb = hasonlóbb Térbeli adatok, ha a magnitúdó számít
Pont termék -∞ a +∞ Magasabb = hasonlóbb Vektorok nagyságának normalizálása esetén

A távolságfüggvény a tároló létrehozásakor a vektorbeágyazási szabályzatban van beállítva. Ezt a mintaadattár infrastruktúrája biztosítja. Ez a tárolódefiníció részeként van definiálva.

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

Ez a Bicep kód egy Azure Cosmos DB tárolókonfigurációt határoz meg a szállodai dokumentumok vektorkeresési képességekkel való tárolásához.

Property Description
partitionKeyPaths A dokumentumokat HotelId mentén particionálja elosztott tárolás céljából.
indexingPolicy Automatikus indexelést konfigurál az összes dokumentumtulajdonságon (/*kivéve a rendszermezőt _etag és a tömböt az DescriptionVector írási teljesítmény optimalizálásához). A vektormezőknek nincs szükségük szabványos indexelésre, mert ehelyett speciális vectorIndexes konfigurációt használnak.
vectorIndexes DiskANN vagy quantizedFlat indexet hoz létre a /DescriptionVector elérési útvonalon a hatékony hasonlósági keresésekhez.
vectorEmbeddingPolicy Meghatározza a vektormező jellemzőit: float32 az adattípust 1536 dimenzióval (a modell kimenetével egyező text-embedding-3-small ) és a koszinuszt a távolságfüggvényként a vektorok közötti hasonlóság mérésére a lekérdezések során.

Hasonlósági pontszámok értelmezése

A példában a koszinusz-hasonlóságot használó kimenetben:

  • 0.4991 (Royal Cottage Resort) - Legmagasabb hasonlóság, legjobb egyezés a "futóösvények, éttermek, üzletek közelében lévő szállás"
  • 0.4388 (Roach Motel) - Alacsonyabb hasonlóság, még mindig releváns, de kevésbé egyező
  • Az 1,0-hoz közelebbi pontszámok erősebb szemantikai hasonlóságot jeleznek
  • A 0-hoz közeli pontszámok kevés hasonlóságot jeleznek

Fontos megjegyzések:

  • Az abszolút pontszám értéke a beágyazási modelltől és az adatoktól függ
  • Az abszolút küszöbértékek helyett a relatív rangsorolásra kell összpontosítani
  • Azure OpenAI-beágyazások a koszinusz hasonlóságával működnek a legjobban

A távolságfüggvényekkel kapcsolatos részletes információkért lásd: Mik azok a távolságfüggvények?

Adatok megtekintése és kezelése a Visual Studio Code-ban

  1. Válassza ki a Cosmos DB-bővítményt a Visual Studio Code-ban az Azure Cosmos DB-fiókhoz való csatlakozáshoz.

  2. Az adatok és indexek megtekintése a Hotels adatbázisban.

    Képernyőkép a Visual Studio Code-ról, amelyen az Azure Cosmos DB-bővítmény a Hotels adatbáziselemeivel és egy JSON-dokumentumszerkesztővel látható.

Erőforrások tisztítása

Ha már nincs szüksége a NoSQL-fiók API-jára, törölheti a megfelelő erőforráscsoportot.

  1. Lépjen a korábban az Azure Portalon létrehozott erőforráscsoportra.

    Jótanács

    Ebben a rövid útmutatóban a nevet msdocs-cosmos-quickstart-rgajánlottuk.

  2. Válassza az Erőforráscsoport törlése lehetőséget.

    Képernyőkép az erőforráscsoport navigációs sávjának Erőforráscsoport törlése lehetőségéről.

  3. A Törlés párbeszédpanelen adja meg az erőforráscsoport nevét, majd válassza a Törlés lehetőséget.

    Képernyőkép egy erőforráscsoport törlési megerősítési oldaláról.

Kapcsolódó tartalom

  • Last updated on