Utilizar o conector do Vector Store do Oracle Database (Pré-visualização)

Como Começar

Adicione o pacote NuGet do conector do Oracle Database Vetor Store ao seu projeto.

dotnet add package Oracle.VectorData --prerelease

Pode adicionar o armazenamento vetorial ao IServiceCollection contentor de injeção de dependências usando métodos de extensão fornecidos pelo pacote conector. 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 usam parâmetros também estão disponíveis. Isso requer 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 Oracle Database Vetor Store 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 Oracle Database Vector Store:

pip install semantic-kernel[oracledb]

Importa as classes OracleSettings, OracleStore e OracleCollection.

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

A classe OracleSettings detém a configuração necessária para criar uma ligação assíncrona à Oracle Database. A classe OracleStore é usada para armazenar e recuperar dados, enquanto a classe OracleCollection gere e pesquisa registos dentro de uma coleção. Utilize estas classes para configurar o 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()

Como Começar

Configure o conector do Oracle Database Vetor 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();

    }

}

Mapeamento de dados

O conector Oracle Database Vetor Store 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 do banco de dados Oracle para converter no esquema de armazenamento.

O conector de armazenamento vetorial do Oracle Database suporta anotações de modelo de dados e definições de registo. Utilizando anotações, as informações podem ser fornecidas ao modelo de dados para a criação de índices e para o mapeamento de colunas da base 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 padrão do tipo de dados de chave primária entre o Oracle Database 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 .NET. tipos de dados. Várias colunas vetoriais são suportadas. A tabela a seguir mostra o mapeamento de tipo de propriedade vetorial padrão, incluindo tipos anuláveis:

Substituição do nome da propriedade

Para propriedades de dados e propriedades de vetor, pode substituir os nomes a utilizar no armazenamento por nomes diferentes dos nomes das propriedades do modelo de dados. A substituição do nome da propriedade ocorre ao definir a StorageName opção nas propriedades do modelo de dados ou na definição do 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 Oracle Database Vetor Store para saber mais:

• Apresentando o Conector de Armazenamento Vetorial da Base de Dados Oracle para o Núcleo Semântico Descreve as características-chave do conector, classes e orienta o leitor através de uma aplicação de pesquisa vetorial de IA utilizando o conector.
• Documentação: Classes de Conectores de Armazenamento Vetorial da Oracle Database para APIs do Kernel Semântico (.NET) Contém informações sobre as classes de conectores Oracle Database Vector Store para adicionar dados, recuperar dados e realizar pesquisa vetorial na base de dados vetorial Oracle.
• Documentação: Oracle Data Provider para .NET Contém informações sobre o Oracle Data Provider para .NET (ODP.NET), o ADO.NET fornecedor de dados para o conector Oracle Database Vector Store.

Mapeamento de dados

O conector Oracle Database Vector Store fornece um mapeador padrão ao mapear do modelo de dados para o armazenamento. Este mapeador faz uma conversão direta da lista de propriedades no modelo de dados para as colunas Oracle Database para converter no esquema de armazenamento.

O conector Oracle Database Vector Store suporta anotações de modelos de dados e definições de registos. Usando anotações, a informação pode ser fornecida ao modelo de dados para criar índices e mapeamento de colunas na base de dados. Usando definições de registro, as informações podem ser definidas e fornecidas separadamente do modelo de dados.

A tabela seguinte mostra o mapeamento padrão de tipos de dados da chave primária entre Oracle Database e Python:

A partir do Oracle Database 23ai, os vetores de base de dados podem ser mapeados para tipos de dados em Python. Várias colunas vetoriais são suportadas. A tabela a seguir mostra o mapeamento de tipo de propriedade vetorial padrão:

Saiba mais

Consulte os seguintes recursos para saber mais:

• Documentação: python-oracledb

Mapeamento de dados

O conector Oracle Database Vetor Store 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 do banco de dados Oracle para converter no esquema de armazenamento.

O conector Oracle Database Vector Store suporta anotações do modelo de dados e definições de registos. Através de anotações, as informações podem ser fornecidas ao modelo de dados para a criação de índices e o mapeamento de colunas da base 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 padrão do tipo de dados de chave primária entre o Oracle Database e o 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 juntamente 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. Várias colunas vetoriais são suportadas. A tabela a seguir mostra o mapeamento de tipo de propriedade vetorial padrão: