Quickstart: Vectorzoekopdrachten met Java in Azure Cosmos DB

Gebruik vectorzoekopdrachten in Azure Cosmos DB met de Java-clientbibliotheek. Gegevens van vectorgegevens efficiënt opslaan en opvragen in uw toepassingen.

In deze quickstart wordt gebruikgemaakt van een voorbeeldgegevensset van een hotel in een JSON-bestand met vectoren uit het model text-embedding-3-small. De gegevensset bevat hotelnamen, locaties, beschrijvingen en vector embeddings.

Zoek de voorbeeldcode met resourceinrichting op GitHub.

Prerequisites

Een gegevensbestand maken met vectoren

  1. Maak een nieuwe gegevensmap voor het gegevensbestand hotels:

    mkdir data
    
  2. Download het raw-gegevensbestand met vectoren naar de map data:

    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
    

Een Java-project maken

  1. Maak een nieuwe zusterdirectory voor uw project, op hetzelfde niveau als de gegevensdirectory, en open deze in Visual Studio Code.

    mkdir vector-search-quickstart
    cd vector-search-quickstart
    code .
    
  2. Maak een pom.xml bestand in de hoofdmap van het project met de Maven-configuratie:

    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    
        <groupId>com.example.cosmos.samples</groupId>
        <artifactId>nosql-vector-search-sample</artifactId>
        <version>1.0.0</version>
        <name>Azure Cosmos DB NoSQL Vector Search - Java</name>
    
        <properties>
            <maven.compiler.release>21</maven.compiler.release>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        </properties>
    
        <dependencies>
            <!-- Azure Cosmos DB SDK (NoSQL API) -->
            <dependency>
                <groupId>com.azure</groupId>
                <artifactId>azure-cosmos</artifactId>
                <version>4.69.0</version>
            </dependency>
    
            <!-- Azure Identity (DefaultAzureCredential) -->
            <dependency>
                <groupId>com.azure</groupId>
                <artifactId>azure-identity</artifactId>
                <version>1.18.1</version>
            </dependency>
    
            <!-- Azure OpenAI (embeddings) -->
            <dependency>
                <groupId>com.azure</groupId>
                <artifactId>azure-ai-openai</artifactId>
                <version>1.0.0-beta.16</version>
            </dependency>
    
            <!-- Jackson (JSON serialization) -->
            <dependency>
                <groupId>tools.jackson.core</groupId>
                <artifactId>jackson-databind</artifactId>
                <version>3.0.3</version>
            </dependency>
    
            <!-- Suppress noisy SDK logging -->
            <dependency>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-nop</artifactId>
                <version>2.0.17</version>
                <scope>runtime</scope>
            </dependency>
        </dependencies>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.codehaus.mojo</groupId>
                    <artifactId>exec-maven-plugin</artifactId>
                    <version>3.5.0</version>
                    <configuration>
                        <mainClass>com.example.cosmos.vectorsearch.VectorSearch</mainClass>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>
    

    Belangrijkste afhankelijkheden:

    • azure-identity - Azure verificatiebibliotheek voor verbindingen zonder wachtwoord (beheerde identiteit)
    • azure-cosmos - Azure Cosmos DB-clientbibliotheek voor databasebewerkingen
    • azure-ai-openai - Azure OpenAI SDK voor het genereren van insluitingen
    • slf4j-nop - Onderdrukt luide SDK-logboekregistratie tijdens de uitvoering
  3. Maak de bronmapstructuur:

    mkdir -p src/main/java/com/example/cosmos/vectorsearch
    
  4. Maak een .env bestand in de hoofdmap van uw project voor omgevingsvariabelen:

    # 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
    
    # Vector search algorithm: diskann or quantizedflat
    VECTOR_ALGORITHM=diskann
    

    Vervang de waarden van de tijdelijke aanduidingen in het .env bestand door uw eigen gegevens:

    • AZURE_OPENAI_EMBEDDING_ENDPOINT: de URL van uw Azure OpenAI-resource-eindpunt
    • AZURE_COSMOSDB_ENDPOINT: de URL van uw Azure Cosmos DB-eindpunt

    Opmerking

    In het Java voorbeeld wordt System.getenv() gebruikt om omgevingsvariabelen te lezen. U moet deze variabelen exporteren in uw shell-sessie of deze gebruiken azd env get-values om ze in te stellen. Het bestand fungeert als referentiesjabloon. Het .env wordt niet automatisch door de toepassing geladen.

Inzicht in het documentschema

Voordat u de toepassing bouwt, moet u begrijpen hoe vectoren worden opgeslagen in Azure Cosmos DB-documenten. Elk hoteldocument bevat:

  • Standaardvelden: HotelId, HotelName, Description, , Categoryenzovoort
  • Vectorveld: DescriptionVector - een matrix van 1536 drijvendekommanummers die de semantische betekenis van de hotelbeschrijving vertegenwoordigen

Hier volgt een vereenvoudigd voorbeeld van een hoteldocumentstructuur:

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

Belangrijke punten over het opslaan van insluitingen:

  • Vectormatrices worden opgeslagen als standaard JSON-matrices in uw documenten
  • Vectorbeleid definieert het pad (/DescriptionVector), het gegevenstype (float32), dimensies (1536) en de afstandsfunctie (cosinus)
  • Indexeringsbeleid maakt een vectorindex op het vectorveld voor efficiënte overeenkomsten zoeken
  • Het vectorveld moet worden uitgesloten van standaardindexering om de invoegprestaties te optimaliseren

Deze beleidsregels worden gedefinieerd in de Bicep-sjablonen voor de metrische afstandsgegevens voor dit voorbeeldproject. Zie Vector search in Azure Cosmos DB voor meer informatie over vectorbeleid en indexering.

Maak twee Java bronbestanden in de map src/main/java/com/example/cosmos/vectorsearch:

touch src/main/java/com/example/cosmos/vectorsearch/VectorSearch.java
touch src/main/java/com/example/cosmos/vectorsearch/Utils.java

Plak de volgende code in het VectorSearch.java bestand.

package com.example.cosmos.vectorsearch;

import com.azure.ai.openai.OpenAIClient;
import com.azure.ai.openai.models.EmbeddingItem;
import com.azure.ai.openai.models.EmbeddingsOptions;
import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.CosmosQueryRequestOptions;
import com.azure.cosmos.models.SqlParameter;
import com.azure.cosmos.models.SqlQuerySpec;

import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * Azure Cosmos DB NoSQL vector search sample — Java port of nosql-vector-search-typescript.
 *
 * Demonstrates:
 * - Passwordless authentication with DefaultAzureCredential
 * - Bulk insert of hotel data with pre-computed embeddings
 * - Vector similarity search using VectorDistance() SQL function
 * - DiskANN and QuantizedFlat algorithm selection via environment variable
 */
public final class VectorSearch {

    private static final String SAMPLE_QUERY =
            "quintessential lodging near running trails, eateries, retail";

    private static final Set<String> VALID_ALGORITHMS = Set.of("diskann", "quantizedflat");

    private static final Map<String, String> ALGORITHM_CONTAINERS = Map.of(
            "diskann", "hotels_diskann",
            "quantizedflat", "hotels_quantizedflat"
    );

    private static final Map<String, String> ALGORITHM_DISPLAY = Map.of(
            "diskann", "DiskANN",
            "quantizedflat", "QuantizedFlat"
    );

    public static void main(String[] args) {
        try {
            new VectorSearch().run();
        } catch (Exception e) {
            System.err.println("App failed: " + e.getMessage());
            e.printStackTrace();
            System.exit(1);
        }
        System.exit(0);
    }

    private void run() throws Exception {
        // ── Configuration ───────────────────────────────────────────────
        var algorithm = Utils.envOrDefault("VECTOR_ALGORITHM", "diskann").trim().toLowerCase();
        var dbName = Utils.envOrDefault("AZURE_COSMOSDB_DATABASENAME", "Hotels");
        var dataFile = Utils.requireEnv("DATA_FILE_WITH_VECTORS");
        var embeddedField = Utils.requireEnv("EMBEDDED_FIELD");
        var deployment = Utils.requireEnv("AZURE_OPENAI_EMBEDDING_MODEL");
        var distanceFunction = Utils.envOrDefault("VECTOR_DISTANCE_FUNCTION", "cosine");

        if (!VALID_ALGORITHMS.contains(algorithm)) {
            throw new IllegalArgumentException(
                    "Invalid algorithm '" + algorithm + "'. Must be one of: " +
                    String.join(", ", VALID_ALGORITHMS));
        }

        var containerName = ALGORITHM_CONTAINERS.get(algorithm);
        var algorithmDisplay = ALGORITHM_DISPLAY.get(algorithm);

        // ── Clients ─────────────────────────────────────────────────────
        OpenAIClient aiClient = Utils.createOpenAIClient();
        CosmosClient dbClient = Utils.createCosmosClient();

        try {
            var database = dbClient.getDatabase(dbName);
            System.out.println("Connected to database: " + dbName);

            CosmosContainer container = database.getContainer(containerName);
            System.out.println("Connected to container: " + containerName);
            System.out.println("\n[Algorithm] Vector Search Algorithm: " + algorithmDisplay);
            System.out.println("[Distance]  Distance Function: " + distanceFunction);

            // Verify container exists
            container.read();

            // ── Load & Insert Data ──────────────────────────────────────
            var dataPath = Path.of(dataFile);
            var data = Utils.readJsonFile(dataPath);
            Utils.insertData(container, data);

            // ── Generate Query Embedding ────────────────────────────────
            var embeddingOptions = new EmbeddingsOptions(List.of(SAMPLE_QUERY));
            var embeddingResult = aiClient.getEmbeddings(deployment, embeddingOptions);

            List<Float> embedding = embeddingResult.getData().get(0).getEmbedding();

            // Convert Float list to List<Double> for Cosmos DB parameter binding
            var embeddingDoubles = new ArrayList<Double>(embedding.size());
            for (var f : embedding) {
                embeddingDoubles.add(f.doubleValue());
            }

            // ── Build & Execute Vector Search Query ─────────────────────
            var safeField = Utils.validateFieldName(embeddedField);
            var queryText = "SELECT TOP 5 c.HotelName, c.Description, c.Rating, " +
                    "VectorDistance(c." + safeField + ", @embedding) AS SimilarityScore " +
                    "FROM c " +
                    "ORDER BY VectorDistance(c." + safeField + ", @embedding)";

            System.out.println("\n--- Executing Vector Search Query ---");
            System.out.println("Query: " + queryText);
            System.out.println("Parameters: @embedding (vector with " + embeddingDoubles.size() + " dimensions)");
            System.out.println("--------------------------------------\n");

            var sqlQuery = new SqlQuerySpec(
                    queryText,
                    List.of(new SqlParameter("@embedding", embeddingDoubles))
            );

            var queryOptions = new CosmosQueryRequestOptions();

            @SuppressWarnings("unchecked")
            var resultPages = container.queryItems(sqlQuery, queryOptions, Map.class);

            var results = new ArrayList<Map<String, Object>>();
            var requestCharge = 0.0;

            for (var page : resultPages.iterableByPage()) {
                requestCharge += page.getRequestCharge();
                for (var item : page.getResults()) {
                    @SuppressWarnings("unchecked")
                    var typedItem = (Map<String, Object>) item;
                    results.add(typedItem);
                }
            }

            Utils.printSearchResults(results, requestCharge);

        } finally {
            dbClient.close();
        }
    }
}

Deze code:

  • Hiermee configureert u een DiskANN of quantizedFlat vector-algoritme van de VECTOR_ALGORITHM omgevingsvariabele.
  • Maakt verbinding met Azure OpenAI en Azure Cosmos DB met behulp van verificatie zonder wachtwoord.
  • Laadt gevectoriseerde hotelgegevens vooraf uit een JSON-bestand.
  • Hiermee worden gegevens in de juiste container ingevoegd.
  • Hiermee genereert u een insluiting voor een query in natuurlijke taal (quintessential lodging near running trails, eateries, retail).
  • Hiermee wordt een VectorDistance SQL-query uitgevoerd om de top 5 meest semantisch vergelijkbare hotels op te halen, gerangschikt op overeenkomstenscore.
  • Verwerkt fouten voor ontbrekende clients, ongeldige algoritmeselectie en niet-bestaande containers/databases.

Meer informatie over de code: Insluitingen genereren met Azure OpenAI

Met de code worden insluitingen gemaakt voor querytekst:

EmbeddingsOptions options = new EmbeddingsOptions(
    List.of(queryText) // Array of description strings to embed
);
Embeddings embeddings = openAIClient.getEmbeddings(model, options);
List<Float> queryVector = embeddings.getData().get(0).getEmbedding();

Deze Azure OpenAI SDK-aanroep converteert tekst zoals 'typisch verblijf nabij hardlooproutes' naar een 1536-dimensionale vector die de semantische betekenis vastlegt. Zie de documentatie over het genereren van insluitingen in Azure OpenAI voor meer informatie over het genereren van insluitingen.

De code begrijpen: Vectoren opslaan in Azure Cosmos DB

Alle documenten met vectormatrices worden op schaal ingevoegd met behulp van de executeBulkOperations methode in Utils.insertData(). Elk document wordt toegewezen aan een bewerking voor bulksgewijs maken met behulp van de PartitionKeyBuilder partitiesleutelwaarde van elk document. Het hulpprogramma houdt tellingen voor ingevoegde, overgeslagen en mislukte items bij, samen met het totale RU-verbruik.

Hiermee worden hoteldocumenten in de container ingevoegd, inclusief hun vooraf gegenereerde DescriptionVector matrix. U kunt alle documentgegevens veilig doorgeven en de clientbibliotheek verwerkt de batchverwerking en nieuwe pogingen voor u.

De code voert een vectorzoekopdracht uit met behulp van de VectorDistance functie:

String queryText = String.format(
    "SELECT TOP 5 c.HotelName, c.Description, c.Rating, " +
    "VectorDistance(c.%s, @embedding) AS SimilarityScore " +
    "FROM c ORDER BY VectorDistance(c.%s, @embedding)",
    embeddedField, embeddedField
);

SqlQuerySpec querySpec = new SqlQuerySpec(queryText,
    new SqlParameter("@embedding", queryVector));

CosmosPagedIterable<ObjectNode> results = container.queryItems(
    querySpec, new CosmosQueryRequestOptions(), ObjectNode.class);

Met deze code wordt een geparameteriseerde SQL-query gebouwd die gebruikmaakt van de functie VectorDistance om de insluitvector (@embedding) van de query te vergelijken met het opgeslagen vectorveld van elk document (DescriptionVector), waarbij de top 5 hotels worden geretourneerd met hun naam en gelijkenisscore, gesorteerd van vrijwel gelijk aan minst vergelijkbaar. Het inbedden van de query wordt als parameter meegegeven om injectie te voorkomen en is afkomstig van een eerdere Azure OpenAI-embeddingsaanroep.

Wat deze query retourneert:

  • Top 5 meest vergelijkbare hotels op basis van vectorafstand
  • Hoteleigenschappen: HotelName, DescriptionRating
  • SimilarityScore: Een numerieke waarde die aangeeft hoe vergelijkbaar elk hotel is met uw query
  • Resultaten gesorteerd van het meest vergelijkbaar met minst vergelijkbaar

Zie VectorDistance voor meer informatie over de functie.

Hulpprogrammafuncties maken

Plak de volgende code in Utils.java:

package com.example.cosmos.vectorsearch;

import com.azure.ai.openai.OpenAIClientBuilder;
import com.azure.ai.openai.OpenAIClient;
import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.CosmosBulkOperations;
import com.azure.cosmos.models.CosmosItemOperation;
import com.azure.cosmos.models.PartitionKey;
import com.azure.cosmos.models.PartitionKeyBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;

import tools.jackson.databind.json.JsonMapper;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

/**
 * Shared utilities for Azure Cosmos DB NoSQL vector search sample.
 * Provides authentication, bulk insert, field validation, and result formatting.
 */
public final class Utils {

    private static final JsonMapper JSON_MAPPER = JsonMapper.builder().build();

    private Utils() {
        // utility class
    }

    // ── Authentication ──────────────────────────────────────────────────

    /**
     * Create an Azure OpenAI client using DefaultAzureCredential (passwordless).
     */
    public static OpenAIClient createOpenAIClient() {
        var endpoint = requireEnv("AZURE_OPENAI_EMBEDDING_ENDPOINT");
        var credential = new DefaultAzureCredentialBuilder().build();
        return new OpenAIClientBuilder()
                .endpoint(endpoint)
                .credential(credential)
                .buildClient();
    }

    /**
     * Create a Cosmos DB client using DefaultAzureCredential (passwordless).
     */
    public static CosmosClient createCosmosClient() {
        var endpoint = requireEnv("AZURE_COSMOSDB_ENDPOINT");
        var credential = new DefaultAzureCredentialBuilder().build();
        return new CosmosClientBuilder()
                .endpoint(endpoint)
                .credential(credential)
                .buildClient();
    }

    // ── Data Loading ────────────────────────────────────────────────────

    /**
     * Read a JSON array file and return its contents as a list of maps.
     */
    @SuppressWarnings("unchecked")
    public static List<Map<String, Object>> readJsonFile(Path filePath) throws IOException {
        System.out.println("Reading JSON file from " + filePath);
        var bytes = Files.readAllBytes(filePath);
        return JSON_MAPPER.readValue(bytes, List.class);
    }

    // ── Bulk Insert ─────────────────────────────────────────────────────

    /**
     * Insert documents into a Cosmos DB container using bulk operations.
     * Skips insert if the container already contains data.
     *
     * @return summary with counts and RU charge
     */
    public static BulkInsertResult insertData(CosmosContainer container,
                                               List<Map<String, Object>> data) {
        // Check existing document count
        var existingCount = getDocumentCount(container);
        if (existingCount > 0) {
            System.out.println("Container already has " + existingCount + " documents. Skipping insert.");
            return new BulkInsertResult(0, 0, 0, (int) existingCount, 0.0);
        }

        System.out.println("Inserting " + data.size() + " items using bulk operations...");

        // Build bulk create operations
        var operations = new ArrayList<CosmosItemOperation>();
        for (var item : data) {
            // Cosmos DB requires an "id" field — map HotelId to id
            var doc = new java.util.HashMap<>(item);
            var hotelId = String.valueOf(doc.get("HotelId"));
            doc.put("id", hotelId);
            operations.add(CosmosBulkOperations.getCreateItemOperation(doc,
                new PartitionKeyBuilder().add(hotelId).build()));
        }

        var inserted = 0;
        var failed = 0;
        var skipped = 0;
        var totalRUs = 0.0;

        var startTime = System.currentTimeMillis();
        System.out.println("Starting bulk insert (" + operations.size() + " items)...");

        var responses = container.executeBulkOperations(operations);
        for (var response : responses) {
            var statusCode = response.getResponse().getStatusCode();
            totalRUs += response.getResponse().getRequestCharge();

            if (statusCode >= 200 && statusCode < 300) {
                inserted++;
            } else if (statusCode == 409) {
                skipped++;
            } else {
                failed++;
            }
        }

        var durationSec = (System.currentTimeMillis() - startTime) / 1000.0;
        System.out.printf("Bulk insert completed in %.2fs%n", durationSec);
        System.out.printf("%nInsert Request Charge: %.2f RUs%n%n", totalRUs);

        return new BulkInsertResult(data.size(), inserted, failed, skipped, totalRUs);
    }

    private static long getDocumentCount(CosmosContainer container) {
        var result = container.queryItems(
                "SELECT VALUE COUNT(1) FROM c",
                new com.azure.cosmos.models.CosmosQueryRequestOptions(),
                Long.class
        );
        for (var count : result) {
            return count;
        }
        return 0;
    }

    // ── Field Name Validation ───────────────────────────────────────────

    /**
     * Validates a field name to prevent NoSQL injection when building queries
     * with string interpolation.
     *
     * @param fieldName the field name to validate
     * @return the validated field name
     * @throws IllegalArgumentException if the field name contains unsafe characters
     */
    public static String validateFieldName(String fieldName) {
        if (!fieldName.matches("^[A-Za-z_][A-Za-z0-9_]*$")) {
            throw new IllegalArgumentException(
                    "Invalid field name: \"" + fieldName + "\". " +
                    "Field names must start with a letter or underscore " +
                    "and contain only letters, numbers, and underscores.");
        }
        return fieldName;
    }

    // ── Output Formatting ───────────────────────────────────────────────

    /**
     * Print search results in a consistent tabular format.
     */
    public static void printSearchResults(List<Map<String, Object>> results, double requestCharge) {
        System.out.println("\n--- Search Results ---");

        if (results == null || results.isEmpty()) {
            System.out.println("No results found.");
            return;
        }

        for (var i = 0; i < results.size(); i++) {
            var r = results.get(i);
            var name = r.get("HotelName");
            var score = r.get("SimilarityScore");
            System.out.printf("%d. %s, Score: %.4f%n", i + 1, name, ((Number) score).doubleValue());
        }

        System.out.printf("%nVector Search Request Charge: %.2f RUs%n%n", requestCharge);
    }

    // ── Environment Helpers ─────────────────────────────────────────────

    public static String requireEnv(String key) {
        var value = System.getenv(key);
        if (value == null || value.isBlank()) {
            throw new IllegalStateException("Required environment variable not set: " + key);
        }
        return value;
    }

    public static String envOrDefault(String key, String defaultValue) {
        var value = System.getenv(key);
        return (value != null && !value.isBlank()) ? value : defaultValue;
    }

    // ── Result Record ───────────────────────────────────────────────────

    public record BulkInsertResult(int total, int inserted, int failed, int skipped, double requestCharge) {}
}

Deze hulpprogrammaklasse biedt de volgende belangrijke functies:

  • createOpenAIClient / createCosmosClient: clients maken voor Azure OpenAI en Azure Cosmos DB met behulp van verificatie zonder wachtwoord via DefaultAzureCredential. RBAC inschakelen op beide resources en aanmelden bij Azure CLI
  • insertData: Hiermee voegt u gegevens in batches in een Azure Cosmos DB-container in met behulp van bulkbewerkingen en traceert ingevoegde, overgeslagen en mislukte tellingen, samen met het totale RU-verbruik
  • printSearchResults: De resultaten van een vectorzoekopdracht afdrukken, inclusief de score en hotelnaam
  • validateFieldName: Valideert dat er een veldnaam bestaat in de gegevens om injectie te voorkomen

Verifiëren met Azure CLI

Meld u aan bij Azure CLI voordat u de toepassing uitvoert, zodat de app veilig toegang heeft tot Azure-resources.

az login

De code maakt gebruik van uw lokale verificatie voor ontwikkelaars om toegang te krijgen tot Azure Cosmos DB en Azure OpenAI met createOpenAIClient en createCosmosClient vanuit Utils.java. Deze functies zijn afhankelijk van DefaultAzureCredential van azure-identity, waarmee een geordende keten van referentieproviders wordt begeleid en wordt omgezet in Azure CLI referenties voor lokale ontwikkeling. Meer informatie over het verifiëren van Java-apps voor Azure-services met behulp van de Azure Identity-bibliotheek.

De toepassing bouwen en uitvoeren

Bouw en voer de toepassing uit met Maven:

Linux/macOS:

VECTOR_ALGORITHM=diskann mvn compile exec:java

Windows:

set VECTOR_ALGORITHM=diskann && mvn compile exec:java

In de logboekregistratie en uitvoer van de app wordt het volgende weergegeven:

  • Status van gegevensinvoeging
  • Vectorindex maken
  • Zoekresultaten met hotelnamen en overeenkomstenscores
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
Inserting 50 items using bulk operations...
Starting bulk insert (50 items)...
Bulk insert completed in 3.41s

Insert Request Charge: 6805.25 RUs


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


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

Metrische gegevens over afstand

Azure Cosmos DB ondersteunt drie afstandsfuncties voor vector-overeenkomsten:

Afstandsfunctie Scorebereik Interpretatie Geschikt voor
Cosinus (standaard) 0.0 tot 1.0 Hogere scores (dichter bij 1,0) geven een grotere gelijkenis aan Algemene overeenkomsten van tekst, Azure OpenAI-insluitingen (gebruikt in deze quickstart)
Euclidean (L2) 0,0 tot ∞ Lager = vergelijkbaarer Ruimtelijke gegevens, wanneer de grootte van belang is
Dot Product -∞ naar +∞ Hoger = vergelijkbaarer Wanneer vector-magnitudes worden genormaliseerd

De afstandsfunctie wordt ingesteld in het beleid voor het insluiten van vectoren bij het maken van de container. Dit wordt geleverd in de infrastructuur in de voorbeeldopslagplaats. Deze wordt gedefinieerd als onderdeel van de containerdefinitie.

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

Deze Bicep-code definieert een Azure Cosmos DB-containerconfiguratie voor het opslaan van hoteldocumenten met vectorzoekmogelijkheden.

Vastgoed Description
partitionKeyPaths Documenten worden HotelId gepartitioneerd voor gedistribueerde opslag.
indexingPolicy Hiermee configureert u automatische indexering voor alle documenteigenschappen (/*), behalve het systeemveld _etag en de matrix om de DescriptionVector schrijfprestaties te optimaliseren. Vectorvelden hebben geen standaardindexering nodig omdat ze in plaats daarvan een gespecialiseerde vectorIndexes configuratie gebruiken.
vectorIndexes Hiermee maakt u een DiskANN- of quantizedFlat-index op het /DescriptionVector pad voor efficiënte zoekopdrachten naar overeenkomsten.
vectorEmbeddingPolicy Definieert de kenmerken van het vectorveld: float32 gegevenstype met 1536 dimensies (overeenkomend met de text-embedding-3-small modeluitvoer) en cosinus als de afstandsfunctie om overeenkomsten tussen vectoren tijdens query's te meten.

Gelijkenisscores interpreteren

In de voorbeelduitvoer met cosinus-gelijkenis:

  • 0.4991 (Royal Cottage Resort) - Hoogste gelijkenis, beste match voor "accommodatie in de buurt van lopende paden, eetgelegenheden, detailhandel"
  • 0.4388 (Roach Motel) - Lagere gelijkenis, nog steeds relevant maar minder overeenkomend
  • Scores dichter bij 1,0 geven een sterkere semantische gelijkenis aan
  • Scores in de buurt van 0 geven weinig overeenkomsten aan

Important

  • Absolute scorewaarden zijn afhankelijk van uw insluitmodel en gegevens
  • Focus op relatieve rangschikking in plaats van absolute drempelwaarden
  • Azure OpenAI-insluitingen werken het beste met cosinus-overeenkomsten

Zie Wat zijn afstandsfuncties voor gedetailleerde informatie over afstandsfuncties?

Gegevens weergeven en beheren in Visual Studio Code

  1. Selecteer de Cosmos DB-extensie in Visual Studio Code om verbinding te maken met uw Azure Cosmos DB-account.

  2. Bekijk de gegevens en indexen in de database Hotels.

    Schermopname van Visual Studio Code met de Azure Cosmos DB-extensie met database-items van hotels en een JSON-documenteditor.

De hulpbronnen opschonen

Wanneer u de API voor het NoSQL-account niet meer nodig hebt, kunt u de bijbehorende resourcegroep verwijderen.

  1. Navigeer naar de resourcegroep die u eerder hebt gemaakt in Azure Portal.

    Tip

    In deze quickstart raden we de naam msdocs-cosmos-quickstart-rgaan.

  2. Selecteer Resourcegroep verwijderen.

    Schermopname van de optie Resourcegroep verwijderen in de navigatiebalk voor een resourcegroep.

  3. Voer in het dialoogvenster Weet u zeker dat u wilt verwijderen de naam van de resourcegroep in en selecteer Vervolgens Verwijderen.

    Schermopname van de pagina voor verwijderingsbevestiging van een resourcegroep.