Usando o conector do Repositório de Vetores do Banco de Dados Oracle (versão prévia)

Como começar

Adicione o pacote NuGet do conector do Repositório de Vetores do Banco de Dados Oracle ao seu projeto.

dotnet add package Oracle.VectorData --prerelease

Você pode adicionar o repositório de vetores ao IServiceCollection contêiner de injeção de dependência usando métodos de extensão fornecidos pelo Kernel Semântico. Nesse caso, uma instância da Oracle.VectorData.OracleVectorStore classe também é registrada com o contêiner.

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

Métodos de extensão que não têm parâmetros também estão disponíveis. Isso exige que uma instância da Oracle.ManagedDataAccess.Client.OracleDataSource classe seja registrada separadamente com o contêiner de injeção de dependência.

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

Você pode construir uma instância do Repositório de Vetores do Banco de Dados Oracle diretamente com uma fonte de dados personalizada ou com uma cadeia de conexão.

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

É possível construir uma referência direta a uma coleção nomeada com uma fonte de dados personalizada ou com uma cadeia de conexão.

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

Como começar

Instale o conector do Repositório de Vetores do Banco de Dados Oracle:

pip install semantic-kernel[oracledb]

Importe as classes OracleSettings, OracleStore e OracleCollection.

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

A classe OracleSettings contém a configuração necessária para criar uma conexão assíncrona com o Oracle Database. A classe OracleStore é usada para armazenar e recuperar dados, enquanto a classe OracleCollection gerencia e pesquisa registros em uma coleção. Use essas classes para configurar o Repositório de Vetores Oracle.

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

Como começar

Configurar o conector do Repositório de Vetores do Banco de Dados Oracle.

// 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();

    }

}

Mapeamento de dados

O conector do Repositório de Vetores do Banco de Dados Oracle fornece um mapeador padrão ao mapear dados do modelo de dados para o armazenamento. Esse mapeador faz uma conversão direta da lista de propriedades do modelo de dados para as colunas de banco de dados Oracle a serem convertidas no esquema de armazenamento.

O conector do Repositório de Vetores do Banco de Dados Oracle dá suporte a anotações de modelo de dados e definições de registro. Usando anotações, as informações podem ser fornecidas ao modelo de dados para criar índices e mapeamento de coluna de banco de dados. Usando definições de registro, as informações podem ser definidas e fornecidas separadamente do modelo de dados.

A tabela a seguir mostra o mapeamento de tipo de dados de chave primária padrão entre o Banco de Dados Oracle e o C#:

A tabela a seguir mostra o mapeamento de tipo de propriedade de dados padrão, incluindo tipos anuláveis:

A partir do Oracle Database 23ai, os vetores de banco de dados podem ser mapeados para o .NET. tipos de dados. Há suporte para várias colunas de vetor. A tabela a seguir mostra o mapeamento de tipo de propriedade de vetor padrão, incluindo tipos anuláveis:

Substituição do nome da propriedade

Para propriedades de dados e propriedades de vetor, você pode substituir nomes a serem usados no armazenamento que são diferentes dos nomes de propriedades do modelo de dados. A substituição do nome da propriedade ocorre ao definir a opção StorageName nas propriedades do modelo de dados ou na definição de registro.

Aqui está um modelo de dados com StorageName exemplo de código definido e como isso será representado em um comando 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" )
);

Saiba Mais

Consulte os seguintes recursos do conector do Repositório de Vetores de Banco de Dados Oracle para saber mais:

• Apresentando o Conector do Repositório de Vetores do Banco de Dados Oracle para Kernel Semântico Descreve os principais recursos do conector, classes e orienta o leitor por meio de uma aplicação de busca vetorial em IA de exemplo usando o conector.
• Documentação: Classes do Conector do Armazenamento Vetorial do Oracle Database para APIs de Kernel Semântico (.NET) Contém informações sobre classes do conector do Armazenamento Vetorial do Oracle Database para adicionar dados, recuperar dados e executar pesquisa vetorial no banco de dados vetorial da Oracle.
• Documentação: Provedor de Dados Oracle para .NET Contém informações sobre o Provedor de Dados Oracle para .NET (ODP.NET), o provedor de dados ADO.NET para o conector do Repositório de Vetores do Banco de Dados Oracle.

Mapeamento de dados

O conector do Repositório de Vetores do Banco de Dados Oracle fornece um mapeador padrão ao mapear do modelo de dados para o armazenamento. Esse mapeador faz uma conversão direta da lista de propriedades no modelo de dados para as colunas do Banco de Dados Oracle a serem convertidas no esquema de armazenamento.

O conector do Repositório de Vetores do Banco de Dados Oracle dá suporte a anotações de modelo de dados e definições de registro. Usando anotações, as informações podem ser fornecidas ao modelo de dados para criar índices e mapeamento de coluna de banco de dados. Usando definições de registro, as informações podem ser definidas e fornecidas separadamente do modelo de dados.

A tabela a seguir mostra o mapeamento de tipo de dados de chave primária padrão entre o Banco de Dados Oracle e o Python:

A partir do Oracle Database 23ai, os vetores de banco de dados podem ser mapeados para tipos de dados python. Há suporte para várias colunas de vetor. A tabela a seguir mostra o mapeamento de tipo de propriedade de vetor padrão:

Saiba Mais

Consulte os seguintes recursos para saber mais:

• Documentação: python-oracledb

Mapeamento de dados

O conector do Repositório de Vetores do Banco de Dados Oracle fornece um mapeador padrão ao mapear dados do modelo de dados para o armazenamento. Esse mapeador faz uma conversão direta da lista de propriedades do modelo de dados para as colunas de banco de dados Oracle a serem convertidas no esquema de armazenamento.

O conector do Repositório de Vetores do Banco de Dados Oracle dá suporte a anotações de modelo de dados e definições de registro. Usando anotações, as informações podem ser fornecidas ao modelo de dados para criar índices e mapeamento de coluna de banco de dados. Usando definições de registro, as informações podem ser definidas e fornecidas separadamente do modelo de dados.

A tabela a seguir mostra o mapeamento de tipo de dados de chave primária padrão entre o Banco de Dados Oracle e Java, juntamente com os métodos correspondentes para recuperar dados de um ResultSet:

A tabela a seguir mostra o mapeamento de tipo de propriedade de dados padrão junto com os métodos correspondentes para recuperar dados de um ResultSet:

A partir do Oracle Database 23ai, os vetores de banco de dados podem ser mapeados para tipos de dados Java. Há suporte para várias colunas de vetor. A tabela a seguir mostra o mapeamento de tipo de propriedade de vetor padrão: