Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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 Azure-abonnement
- Als u geen Azure-abonnement hebt, maakt u een gratis account
Toegang tot een bestaand Azure Cosmos DB-gegevensvlak
- Als u geen resource hebt, maakt u een nieuwe resource
- Firewall geconfigureerd om toegang tot uw client-IP-adres toe te staan
- Rollen voor op rollen gebaseerd toegangsbeheer (RBAC) toegewezen:
- Ingebouwde Gegevensbijdrager van Cosmos DB (gegevensvlak)
- Rol-ID:
00000000-0000-0000-0000-000000000002
-
- Aangepast domein geconfigureerd
- Rol op basis van op rollen gebaseerd toegangsbeheer (RBAC) toegewezen:
- Cognitive Services OpenAI-gebruiker
- Rol-ID:
5e0bd9bd-7b93-4f28-af87-19fc36ad61bd
-
text-embedding-3-smallmodel geïmplementeerd
Een gegevensbestand maken met vectoren
Maak een nieuwe gegevensmap voor het gegevensbestand hotels:
mkdir dataDownload 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
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 .Maak een
pom.xmlbestand 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
Maak de bronmapstructuur:
mkdir -p src/main/java/com/example/cosmos/vectorsearchMaak een
.envbestand 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=diskannVervang de waarden van de tijdelijke aanduidingen in het
.envbestand 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 gebruikenazd env get-valuesom ze in te stellen. Het bestand fungeert als referentiesjabloon. Het.envwordt 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.
Codebestanden maken voor vectorzoekopdrachten
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
Code maken voor vectorzoekopdrachten
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
DiskANNofquantizedFlatvector-algoritme van deVECTOR_ALGORITHMomgevingsvariabele. - 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
VectorDistanceSQL-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.
Meer informatie over de code: Zoeken naar vector-overeenkomsten uitvoeren
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
Selecteer de Cosmos DB-extensie in Visual Studio Code om verbinding te maken met uw Azure Cosmos DB-account.
Bekijk de gegevens en indexen in de database Hotels.
De hulpbronnen opschonen
Wanneer u de API voor het NoSQL-account niet meer nodig hebt, kunt u de bijbehorende resourcegroep verwijderen.
Navigeer naar de resourcegroep die u eerder hebt gemaakt in Azure Portal.
Tip
In deze quickstart raden we de naam
msdocs-cosmos-quickstart-rgaan.Selecteer Resourcegroep verwijderen.
Voer in het dialoogvenster Weet u zeker dat u wilt verwijderen de naam van de resourcegroep in en selecteer Vervolgens Verwijderen.