Oracle Database Vector Store コネクタの使用 (プレビュー)

Warnung

Oracle Database Vector Store の機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

Warnung

セマンティック カーネル ベクター ストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

Warnung

セマンティック カーネル ベクター ストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

概要

Oracle Database Vector Store Connector を使用すると、Oracle Database のデータにアクセスして管理できます。 コネクタには次の特性があります。

機能領域	Support
コレクションのマップ	Oracle データベース テーブル
サポートされているキー プロパティの種類	short 整数 (int) long 文字列 Guid
サポートされているデータ プロパティ型	ブール (bool) byte short 整数 (int) 10 進 long float ダブル DateTime DateTimeOffset TimeSpan char char[] byte[] String Guid 上記の型の null 許容型
サポートされているベクター プロパティ型	ReadOnlyMemory<float> 埋め込み<float> float[] ReadOnlyMemory<ダブル> 埋め込み<二つ> double[] 読み取り専用メモリ<ショート> 埋め込み<short> short[] 読み取り専用メモリ<バイト> 埋め込み<バイト> byte[] BitArray BinaryEmbedding
サポートされているインデックスの種類	フラット (既定値) HNSW IVF
サポートされている距離関数	CosineDistance FLOAT32、FLOAT64、INT8 ベクターの既定値 CosineSimilarity DotProductSimilarity NegativeDotProductSimilarity EuclideanDistance EuclideanSquaredDistance HammingDistance BINARY ベクターの既定値 ManhattanDistance JaccardSimilarity Jaccard の類似性を使用するには、DistanceFunction 文字列を "JACCARD" または "JACCARDSIMILARITY" (DistanceFunction = "JACCARDSIMILARITY" など) に設定します。 この値は、大文字と小文字が区別されます。 Jaccard の類似性には BINARY 数値書式ベクトルが必要です。
サポートされているフィルター句	== != < <= > >= List.Contains() モデル プロパティが一覧に含まれているかどうかを確認する場合のみ
レコード内の 0、1、または複数のベクターをサポートします	イエス
IsIndexed はサポートされていますか?	イエス
IsFullTextSearchable がサポートされていますか?	いいえ
StorageName がサポートされていますか?	イエス
HybridSearch はサポートされていますか?	いいえ

Important

ベクター データ検索には、Oracle Database 23ai 以上が必要です。 その他の Oracle コネクタ機能はすべて、Oracle Database 19c 以降を使用して使用できます。

機能領域	Support
コレクションのマップ	Oracle データベース テーブル
サポートされているキー プロパティの種類	str 整数 (int) uuid.UUID
サポートされているデータ プロパティ型	str 整数 (int) long float ブール (bool) 10 進 byte バイト uuid.UUID datetime.date datetime.datetime datetime.timedelta list[str] dict[str, Any] list[dict[str, Any]]
サポートされているベクター プロパティ型	list[float] numpy 配列 (numpy array)
サポートされているインデックスの種類	HNSW IVF
サポートされている距離関数	COSINE_DISTANCE（コサイン距離） ユークリッド距離 欧州距離の2乗距離 DOT_PROD ハミング マンハッタン DEFAULT
サポートされているフィルター句	比較を含む Python ラムダ、ブール演算子、文字列メソッド (startswith、endswith)、between、datetime、バインド変数を使用して SQL に変換される
IsIndexed はサポートされていますか?	イエス
IsFullTextSearchable がサポートされていますか?	いいえ
StoragePropertyName がサポートされていますか?	イエス
HybridSearch はサポートされていますか?	いいえ

Important

ベクター データ検索には、Oracle Database 23ai 以降が必要です。 その他の Oracle コネクタ機能はすべて、Oracle Database 19c 以降を使用して使用できます。 また、python-oracledb 3.3 以降が必要です。

機能領域	Support
サポートされているフィルター句	AnyTagEqualTo EqualTo
コレクションのマップ	SQL データベース テーブル
サポートされているキー プロパティの種類	ショート/短い int/Integer ロング型 String UUID（ユニバーサリー・ユニーク・アイデンティファイア）
サポートされているデータ プロパティ型	byte/Byte ショート/短い int/Integer ロング型 浮動小数点/Float double/Double decimal/少数 DateTime オフセット日時 タイムスタンプ String UUID（ユニバーサリー・ユニーク・アイデンティファイア） リスト<of all above types>
サポートされているベクター プロパティ型	String 徴収<Float> リスト<Float> Float[] float[]
サポートされているインデックスの種類	HNSW IVF
サポートされている距離関数	DOT_PRODUCT COSINE_SIMILARITY COSINE_DISTANCE（コサイン距離） ユークリッド距離
レコード内の複数のベクターをサポートします	イエス
IsIndexed のサポート	イエス
IsFullTextSearchable がサポートされていますか?	いいえ
StoragePropertyName がサポートされていますか?	いいえ。代わりに @JsonProperty を使用してください
HybridSearch はサポートされていますか?	いいえ

作業の開始

Oracle Database Vector Store コネクタ NuGet パッケージをプロジェクトに追加します。

dotnet add package Oracle.VectorData --prerelease

セマンティック カーネルによって提供される拡張メソッドを使用して、 IServiceCollection 依存関係挿入コンテナーにベクター ストアを追加できます。 この場合、 Oracle.VectorData.OracleVectorStore クラスのインスタンスもコンテナーに登録されます。

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

パラメーターを受け取たない拡張メソッドも使用できます。 これらには、 Oracle.ManagedDataAccess.Client.OracleDataSource クラスのインスタンスを依存関係挿入コンテナーに個別に登録する必要があります。

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

Oracle Database Vector Store インスタンスは、カスタム データ ソースまたは接続文字列を使用して直接構築できます。

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

カスタム データ ソースまたは接続文字列を使用して、名前付きコレクションへの直接参照を構築できます。

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

作業の開始

Oracle Database Vector Store コネクタをインストールします。

pip install semantic-kernel[oracledb]

OracleSettings、OracleStore、OracleCollection クラスをインポートします。

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

OracleSettings クラスは、Oracle Database への非同期接続を作成するために必要な構成を保持します。 OracleStore クラスはデータの格納と取得に使用され、OracleCollection クラスはコレクション内のレコードを管理および検索します。 これらのクラスを使用して、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()

作業の開始

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

    }

}

データ マッピング

Oracle Database Vector Store コネクタは、データ モデルからストレージにデータをマッピングするときに、既定のマッパーを提供します。 このマッパーは、データ モデルのプロパティ リストを Oracle データベース列に直接変換して、ストレージ スキーマに変換します。

Oracle Database Vector Store コネクタは、データ モデルの注釈とレコード定義をサポートしています。注釈を使用すると、インデックスとデータベース列マッピングを作成するための情報をデータ モデルに提供できます。 レコード定義を使用すると、データ モデルとは別に情報を定義および指定できます。

次の表は、Oracle Database と C# の間の既定の主キー データ型マッピングを示しています。

C# データ型	データベースの種類
short/int16	NUMBER(5)
int/int32	NUMBER(10)
long/int64	NUMBER(19)
文字列	NVARCHAR2(2000)
Guid	RAW(16)

次の表は、null 許容型を含む、既定のデータ プロパティ型マッピングを示しています。

C# データ型	データベースの種類
ブール (bool)	Oracle Database 23ai 以降の BOOLEAN 以前のバージョンの NUMBER(1)
byte	NUMBER(3)
short/int16	NUMBER(5)
int/int32	NUMBER(10)
10 進	NUMBER(18,2)
long/int64	NUMBER(19)
float	バイナリーフロート
ダブル	BINARY_DOUBLE
DateTime	TIMESTAMP(7)
DateTimeOffset	タイム ゾーンを持つ TIMESTAMP(7)
TimeSpan	INTERVAL DAY(8) から SECOND(7)
char	NVARCHAR2(1)
char[]	NVARCHAR2(2000)
byte[]	RAW(2000)
文字列	NVARCHAR2(2000)
Guid	RAW(16)

Oracle Database 23ai 以降では、データベース ベクターを .NET にマップできます。 データ型。 複数のベクター列がサポートされています。 次の表は、null 許容型を含む、既定のベクター プロパティ型マッピングを示しています。

C# データ型	データベースの種類
読み取り専用メモリ<バイト> 埋め込み<System.Byte> BinaryEmbedding 埋め込み<バイト> byte[] System.Byte[] BitArray	VECTOR(次元, バイナリ)
読み取り専用メモリ<ショート> ReadOnlyMemory<System.Int16> 埋め込み<short> 埋め込み<System.Int16> short[] System.Int16[]	VECTOR(次元, 8ビット整数)
ReadOnlyMemory<ダブル> ReadOnlyMemory<System.Double> 埋め込み<System.Double> 埋め込み<二つ> double[] System.Double[]	VECTOR(ディメンション, FLOAT64)
ReadOnlyMemory<float> ReadOnlyMemory<System.Float> 埋め込み<float> 埋め込み<システム.フロート> float[] System.Float[]	VECTOR(ディメンション, FLOAT32)

プロパティ名のオーバーライド

データ プロパティとベクター プロパティの場合は、データ モデルのプロパティ名とは異なるストレージで使用する名前をオーバーライドできます。 プロパティ名のオーバーライドは、データ モデルプロパティまたはレコード定義で StorageName オプションを設定するときに発生します。

以下に、 StorageName セット コード サンプルを含むデータ モデルと、それが 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" )
);

詳細情報

詳細については、次の Oracle Database Vector Store コネクタ リソースを参照してください。

• セマンティック カーネル用の Oracle データベース ベクター ストア コネクタの概要 コネクタの主要な機能、クラスについて説明し、コネクタを使用してサンプル AI ベクター検索アプリケーションをリーダーに案内します。
• ドキュメント: セマンティック カーネル (.NET) API 用の Oracle データベース ベクター ストア コネクタ クラス データの追加、データの取得、Oracle ベクター データベースでのベクター検索の実行に関する Oracle Database Vector Store コネクタ クラスに関する情報が含まれています。
• ドキュメント: Oracle Data Provider for .NET Oracle Database Vector Store コネクタの ADO.NET データ プロバイダーである Oracle Data Provider for .NET (ODP.NET) に関する情報が含まれています。

データ マッピング

Oracle Database Vector Store コネクタは、データ モデルからストレージにマッピングするときに、既定のマッパーを提供します。 このマッパーは、データ モデルのプロパティの一覧を Oracle Database 列に直接変換して、ストレージ スキーマに変換します。

Oracle Database Vector Store コネクタは、データ モデルの注釈とレコード定義をサポートしています。 注釈を使用すると、インデックスとデータベース列マッピングを作成するための情報をデータ モデルに提供できます。 レコード定義を使用すると、データ モデルとは別に情報を定義および指定できます。

次の表は、Oracle Database と Python の間の既定の主キー データ型マッピングを示しています。

Python 型	Oracle SQL 型
str	VARCHAR(n)、type オプションで str(n) を使用すると、Oracle VARCHAR の長さが n に設定されます。 n を指定しない場合、既定の長さは 4000 です。
整数 (int)	NUMBER(10)
byte	NUMBER(3)
long	NUMBER(19)
10 進	数
float	バイナリーフロート
ダブル	BINARY_DOUBLE
ブール (bool)	BOOLEAN
UUID（ユニバーサリー・ユニーク・アイデンティファイア）	RAW(16)
date	DATE
datetime.datetime	TIMESTAMP
datetime.timedelta	INTERVAL DAY TO SECOND (日から秒への間隔)
Clob	CLOB は、ネイティブ Python 型ではなく明示的に指定できます
BLOB	BLOB は、ネイティブ Python 型ではなく明示的に指定できます
list[str], dict[str, Any]	JSON
list[dict[str, Any]]	JSON
バイト	RAW(2000)

Oracle Database 23ai 以降では、データベース ベクターを Python データ型にマップできます。 複数のベクター列がサポートされています。 次の表に、既定のベクター プロパティの型マッピングを示します。

Python 型	データベースの種類
uint8	バイナリ
int8	INT8
float	FLOAT64
float32	FLOAT32
float64	FLOAT64
binary	バイナリ

詳細情報

詳細については、次のリソースを参照してください。

• ドキュメント: python-oracledb

データ マッピング

Oracle Database Vector Store コネクタは、データ モデルからストレージにデータをマッピングするときに、既定のマッパーを提供します。 このマッパーは、データ モデルのプロパティ リストを Oracle データベース列に直接変換して、ストレージ スキーマに変換します。

Oracle Database Vector Store コネクタは、データ モデルの注釈とレコード定義をサポートしています。注釈を使用すると、インデックスとデータベース列マッピングを作成するための情報をデータ モデルに提供できます。 レコード定義を使用すると、データ モデルとは別に情報を定義および指定できます。

次の表は、Oracle Database と Java の間の既定の主キー データ型マッピングと、 ResultSetからデータを取得するための対応するメソッドを示しています。

Java 型	データベースの種類	ResultSet Getter メソッド
byte/Byte	NUMBER(3)	resultSet.getByte(name)
ショート/短い	NUMBER(5)	resultSet.getShort(name)
int/Integer	NUMBER(10)	resultSet.getInt(name)
ロング型	NUMBER(19)	resultSet.getLong(name)
String	NVARCHAR2(2000)	resultSet.getString(name)
UUID（ユニバーサリー・ユニーク・アイデンティファイア）	RAW(16)	resultSet.getObject(name, java_type)

次の表は、既定のデータ プロパティ型マッピングと、 ResultSetからデータを取得するための対応するメソッドを示しています。

Java 型	データベースの種類	ResultSet Getter メソッド
ブーリアン	BOOLEAN	resultSet.getByte(name)
byte/Byte	NUMBER(3)	resultSet.getByte(name)
byte[]	RAW(2000)	resultSet.getBytes(name)
ショート/短い	NUMBER(5)	resultSet.getShort(name)
int/Integer	NUMBER(10)	resultSet.getInt(name)
ロング型	NUMBER(19)	resultSet.getLong(name)
浮動小数点/Float	バイナリーフロート	resultSet.getFloat(name)
double/Double	BINARY_DOUBLE	resultSet.getDouble(name)
BigDecimal	NUMBER(18,2)	resultSet.getBigDecimal(name)
OffsetDateTime	タイム ゾーンを持つ TIMESTAMP(7)	resultSet.getTIMESTAMPTZ(name).offsetDateTimeValue()
String	CLOB/NVARCHAR2(%s)	resultSet.getString(name)
UUID（ユニバーサリー・ユニーク・アイデンティファイア）	RAW(16)	resultSet.getObject(name, java_type)
リスト<T>	JSON	resultSet.getObject(name, java_type) 使用 ojdbc-extensions-jackson-oson

Oracle Database 23ai 以降では、データベース ベクターを Java データ型にマップできます。 複数のベクター列がサポートされています。 次の表に、既定のベクター プロパティの型マッピングを示します。

Java 型	データベースの種類
String	ベクトル(%d, フロート32)
徴収<Float>	ベクトル(%d, フロート32)
リスト<Float>	ベクトル(%d, フロート32)
Float[]	ベクトル(%d, フロート32)
float[]	ベクトル(%d, フロート32)