Utilisation du connecteur Oracle Database Vector Store (préversion)

Mise en route

Ajoutez le package NuGet du connecteur Oracle Database Vector Store à votre projet.

dotnet add package Oracle.VectorData --prerelease

Vous pouvez ajouter le magasin de vecteurs au conteneur d’injection de dépendances à l’aide IServiceCollection de méthodes d’extension fournies par le noyau sémantique. Dans ce cas, une instance de la Oracle.VectorData.OracleVectorStore classe est également inscrite auprès du conteneur.

using Microsoft.SemanticKernel;
using Oracle.VectorData;
using Microsoft.Extensions.DependencyInjection;

// Using Kernel Builder.
var builder = Kernel.CreateBuilder();
builder.Services.AddOracleVectorStore("<connection string>");

using Microsoft.AspNetCore.Builder;
using Oracle.VectorData;
using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOracleVectorStore("<connection string>");

Les méthodes d’extension qui ne prennent aucun paramètre ne sont également disponibles. Celles-ci nécessitent qu’une instance de la Oracle.ManagedDataAccess.Client.OracleDataSource classe soit inscrite séparément auprès du conteneur d’injection de dépendances.

using Microsoft.SemanticKernel;
using Oracle.VectorData;
using Microsoft.Extensions.DependencyInjection;
using Oracle.ManagedDataAccess.Client;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
builder.Services.AddSingleton<OracleDataSource>(sp =>
{
    OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
    return dataSourceBuilder.Build();
});

builder.Services.AddOracleVectorStore();

using Microsoft.AspNetCore.Builder;
using Oracle.VectorData;
using Microsoft.Extensions.DependencyInjection;
using Oracle.ManagedDataAccess.Client;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<OracleDataSource>(sp =>
{
    OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
    return dataSourceBuilder.Build();
});

builder.Services.AddOracleVectorStore();

Vous pouvez construire une instance Oracle Database Vector Store directement avec une source de données personnalisée ou avec une chaîne de connexion.

using Oracle.VectorData;
using Oracle.ManagedDataAccess.Client;

OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
var dataSource = dataSourceBuilder.Build();

var connection = new OracleVectorStore(dataSource);

using Oracle.VectorData;

var connection = new OracleVectorStore("<connection string>");

Il est possible de construire une référence directe à une collection nommée avec une source de données personnalisée ou avec une chaîne de connexion.

using Oracle.VectorData;
using Oracle.ManagedDataAccess.Client;

OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
var dataSource = dataSourceBuilder.Build();

var collection = new OracleCollection<string, Hotel>(dataSource, "skhotels");

using Oracle.VectorData;

var collection = new OracleCollection<string, Hotel>("<connection string>", "skhotels");

Mise en route

Installez le connecteur Oracle Database Vector Store :

pip install semantic-kernel[oracledb]

Importez les classes OracleSettings, OracleStore et OracleCollection.

from semantic_kernel.connectors.oracle import OracleSettings, OracleStore, OracleCollection

La classe OracleSettings contient la configuration requise pour créer une connexion asynchrone à Oracle Database. La classe OracleStore est utilisée pour stocker et récupérer des données, tandis que la classe OracleCollection gère et recherche des enregistrements dans une collection. Utilisez ces classes pour configurer oracle Vector Store.

# Read the environment settings
oracle_settings = OracleSettings()

# Create a connection pool
pool = await oracle_settings.create_connection_pool(
    wallet_location=<wallet_location>,
    wallet_password=<wallet_password>)

# Create an Oracle Vector Store
store = OracleStore(
    connection_pool=pool,
)

# Get a collection
collection = await store.get_collection(
    record_type=HotelSample,
    collection_name=Hotel,
    embedding_generator=text_embedding)

# Create a collection if it does not exist
await collection.ensure_collection_exists()

Mise en route

Configurez le connecteur Oracle Database Vector Store.

// Copyright (c) Microsoft. All rights reserved.
package com.microsoft.semantickernel.samples.syntaxexamples.memory;

import com.microsoft.semantickernel.data.jdbc.JDBCVectorStore;
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStoreOptions;
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStoreRecordCollection;
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStoreRecordCollectionOptions;
import com.microsoft.semantickernel.data.jdbc.oracle.OracleVectorStoreQueryProvider;
import com.microsoft.semantickernel.data.vectorstorage.VectorStoreRecordCollection;
import com.microsoft.semantickernel.samples.documentationexamples.data.index.Hotel;
import java.sql.SQLException;
import java.util.Collections;
import oracle.jdbc.datasource.impl.OracleDataSource;

public class VectorStoreWithOracle {

    public static void main(String[] args) throws SQLException {
        System.out.println("==============================================================");
        System.out.println("============== Oracle Vector Store Example ===================");
        System.out.println("==============================================================");

        // Configure the data source
        OracleDataSource dataSource = new OracleDataSource();
        dataSource.setURL("jdbc:oracle:thin:@localhost:1521/FREEPDB1");
        dataSource.setUser("scott");
        dataSource.setPassword("tiger");

        // Build a query provider
        OracleVectorStoreQueryProvider queryProvider = OracleVectorStoreQueryProvider.builder()
            .withDataSource(dataSource)
            .build();

        // Build a vector store
        JDBCVectorStore vectorStore = JDBCVectorStore.builder()
            .withDataSource(dataSource)
            .withOptions(JDBCVectorStoreOptions.builder()
                .withQueryProvider(queryProvider)
                .build())
            .build();

        // Get a collection from the vector store
        VectorStoreRecordCollection<String, Hotel> collection = vectorStore.getCollection(
            "skhotels",
            JDBCVectorStoreRecordCollectionOptions.<Hotel>builder()
                .withRecordClass(Hotel.class)
                .build());

        // Create the collection if it doesn't exist yet.
        collection.createCollectionAsync().block();

        collection.upsertAsync(new Hotel("1",
            "HotelOne",
            "Desc for HotelOne",
            Collections.emptyList(), Collections.emptyList()),
            null)
            .block();

    }

}

Mappage de données

Le connecteur Oracle Database Vector Store fournit un mappeur par défaut lors du mappage des données du modèle de données au stockage. Ce mappeur effectue une conversion directe de la liste des propriétés du modèle de données vers les colonnes de base de données Oracle à convertir en schéma de stockage.

Le connecteur Oracle Database Vector Store prend en charge les annotations de modèle de données et les définitions d’enregistrements. À l’aide d’annotations, les informations peuvent être fournies au modèle de données pour créer des index et un mappage de colonnes de base de données. À l’aide de définitions d’enregistrements, les informations peuvent être définies et fournies séparément du modèle de données.

Le tableau suivant montre le mappage de type de données de clé primaire par défaut entre Oracle Database et C# :

Le tableau suivant montre le mappage de type de propriété de données par défaut, y compris les types nullables :

À compter d’Oracle Database 23ai, les vecteurs de base de données peuvent être mappés à .NET. types de données. Plusieurs colonnes vectorielles sont prises en charge. Le tableau suivant montre le mappage de type de propriété vectorielle par défaut, y compris les types nullables :

Remplacement du nom de propriété

Pour les propriétés de données et les propriétés vectorielles, vous pouvez remplacer les noms à utiliser dans le stockage qui sont différents des noms de propriétés du modèle de données. Le remplacement du nom de propriété se produit lors de la définition de l’option StorageName dans les propriétés du modèle de données ou la définition d’enregistrement.

Voici un modèle de données avec StorageName un exemple de code défini et comment cela sera représenté dans une commande Oracle SQL.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public long HotelId { get; set; }

    [VectorStoreData(StorageName = "hotel_name")]
    public string? HotelName { get; set; }

    [VectorStoreData(StorageName = "hotel_description")]
    public string? Description { get; set; }

    [VectorStoreVector(Dimensions: 384, DistanceFunction = DistanceFunction.CosineDistance)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

CREATE TABLE "MYSCHEMA"."Hotels"
  ("HotelId" NUMBER(10),
   "hotel_name" NVARCHAR2(2000),
   "hotel_description" NVARCHAR2(2000),
   "DescriptionEmbedding" VECTOR(384, FLOAT32),
   PRIMARY KEY ( "HotelId" )
);

En savoir plus

Pour en savoir plus, consultez les ressources de connecteur Oracle Database Vector Store suivantes :

• Présentation du connecteur oracle Database Vector Store pour le noyau sémantique Décrit les fonctionnalités clés du connecteur, les classes et guide le lecteur dans un exemple d’application de recherche vectorielle IA à l’aide du connecteur.
• Documentation : Classes de connecteur du magasin vectoriel Oracle Database pour les API de noyau sémantique (.NET) Contient des informations sur les classes de connecteur Oracle Database Vector Store pour ajouter des données, récupérer des données et effectuer une recherche vectorielle dans la base de données vectorielle Oracle.
• Documentation : Fournisseur de données Oracle pour .NET Contient des informations sur le fournisseur de données Oracle pour .NET (ODP.NET), le fournisseur de données ADO.NET pour le connecteur Oracle Database Vector Store.

Mappage des données

Le connecteur Oracle Database Vector Store fournit un mappeur par défaut lors du mappage du modèle de données au stockage. Ce mappeur effectue une conversion directe de la liste des propriétés du modèle de données vers les colonnes Oracle Database à convertir en schéma de stockage.

Le connecteur Oracle Database Vector Store prend en charge les annotations de modèle de données et les définitions d’enregistrements. À l’aide d’annotations, les informations peuvent être fournies au modèle de données pour créer des index et un mappage de colonnes de base de données. À l’aide de définitions d’enregistrements, les informations peuvent être définies et fournies séparément du modèle de données.

Le tableau suivant montre le mappage de type de données de clé primaire par défaut entre Oracle Database et Python :

À compter d’Oracle Database 23ai, les vecteurs de base de données peuvent être mappés aux types de données Python. Plusieurs colonnes vectorielles sont prises en charge. Le tableau suivant montre le mappage de type de propriété vectorielle par défaut :

En savoir plus

Pour en savoir plus, consultez les ressources suivantes :

• Documentation : python-oracledb

Mappage de données

Le connecteur Oracle Database Vector Store fournit un mappeur par défaut lors du mappage des données du modèle de données au stockage. Ce mappeur effectue une conversion directe de la liste des propriétés du modèle de données vers les colonnes de base de données Oracle à convertir en schéma de stockage.

Le connecteur Oracle Database Vector Store prend en charge les annotations de modèle de données et les définitions d’enregistrements. À l’aide d’annotations, les informations peuvent être fournies au modèle de données pour créer des index et un mappage de colonnes de base de données. À l’aide de définitions d’enregistrements, les informations peuvent être définies et fournies séparément du modèle de données.

Le tableau suivant présente le mappage de type de données de clé primaire par défaut entre Oracle Database et Java, ainsi que les méthodes correspondantes pour récupérer des données à partir d’un ResultSet:

Le tableau suivant présente le mappage de type de propriété de données par défaut, ainsi que les méthodes correspondantes pour récupérer des données à partir d’un ResultSet:

À compter d’Oracle Database 23ai, les vecteurs de base de données peuvent être mappés aux types de données Java. Plusieurs colonnes vectorielles sont prises en charge. Le tableau suivant montre le mappage de type de propriété vectorielle par défaut :