使用記錄定義來定義記憶體架構 (預覽)

警告

語意核心向量存放區功能處於預覽狀態,且需要重大變更的改善可能仍會在發行前有限的情況下發生。

警告

語意核心向量存放區功能處於預覽狀態,且需要重大變更的改善可能仍會在發行前有限的情況下發生。

概觀

語意核心向量存放區連接器會使用模型第一種方法來與資料庫互動,並允許批註數據模型,其中包含建立索引或將數據對應至資料庫架構所需的資訊。

提供這項資訊的另一種方式是透過記錄定義,可以分別定義和提供給數據模型。 這在多個案例中很有用:

  • 在某些情況下,開發人員想要搭配多個組態使用相同的數據模型。
  • 在某些情況下,開發人員想要使用內建類型,例如聽寫或數據框架等優化格式,但仍想要利用向量存放區功能。

以下是如何建立記錄定義的範例。

using Microsoft.Extensions.VectorData;

var hotelDefinition = new VectorStoreCollectionDefinition
{
    Properties = new List<VectorStoreProperty>
    {
        new VectorStoreKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },
        new VectorStoreDataProperty("Description", typeof(string)) { IsFullTextIndexed = true },
        new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4) { DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw },
    }
};

建立定義時,您一律必須提供架構中每個屬性的名稱和類型,因為這是建立索引和數據對應的必要專案。

若要使用定義,請將它傳遞至 GetCollection 方法。

var collection = vectorStore.GetCollection<ulong, Hotel>("skhotels", hotelDefinition);

Record 屬性組態類別

VectorStoreKeyProperty

使用此類別指出您的屬性是記錄的索引鍵。

new VectorStoreKeyProperty("HotelId", typeof(ulong)),

VectorStoreKeyProperty 組態設定

參數 必要 描述
名稱 是的 數據模型上屬性的名稱。 對應程式用來在記憶體架構和數據模型之間自動對應,以及用來建立索引。
類型 否 數據模型上屬性的類型。 對應程式用來在記憶體架構和數據模型之間自動對應,以及用來建立索引。
存儲名稱 否 可用來提供資料庫中屬性的替代名稱。 請注意,所有連接器都不支援此參數,例如支援的替代 JsonPropertyNameAttribute 專案。

提示

如需哪些連接器支援 StorageName 及有哪些替代方案的詳細資訊,請參閱 每個連接器的檔。

VectorStoreDataProperty

使用這個類別表示您的屬性包含不是索引鍵或向量的一般數據。

new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },

VectorStoreDataProperty 組態設定

參數 必要 描述
名稱 是的 數據模型上屬性的名稱。 對應程式用來在記憶體架構和數據模型之間自動對應,以及用來建立索引。
類型 否 數據模型上屬性的類型。 對應程式用來在記憶體架構和數據模型之間自動對應,以及用來建立索引。
IsIndexed 否 指出當資料庫需要加入每個屬性的索引編製索引時,是否應該為屬性編製索引以進行篩選。 預設為 False。
IsFullTextIndexed 否 指出是否應該針對支援全文搜索的資料庫,為全文搜索編製屬性的索引。 預設為 False。
存儲名稱 否 可用來提供資料庫中屬性的替代名稱。 請注意,所有連接器都不支援此參數,例如支援的替代 JsonPropertyNameAttribute 專案。

提示

如需哪些連接器支援 StorageName 及有哪些替代方案的詳細資訊,請參閱 每個連接器的檔。

VectorStoreVectorProperty

使用此類別表示您的屬性包含向量。

new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4) { DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw },

VectorStoreVectorProperty 組態設定

參數 必要 描述
名稱 是的 數據模型上屬性的名稱。 對應程式用來在記憶體架構和數據模型之間自動對應,以及用來建立索引。
類型 否 數據模型上屬性的類型。 對應程式用來在記憶體架構和數據模型之間自動對應,以及用來建立索引。
維度 是的 向量擁有的維度數目。 若要建立集合的向量索引,這是必要專案。
IndexKind 否 要用來為向量編製索引的索引型別。 預設值會依向量存放區類型而有所不同。
DistanceFunction 否 在此向量搜尋期間執行向量比較時所要使用的函式類型。 預設值會依向量存放區類型而有所不同。
存儲名稱 否 可用來提供資料庫中屬性的替代名稱。 請注意,所有連接器都不支援此參數,例如支援的替代 JsonPropertyNameAttribute 專案。
EmbeddingGenerator 否 允許指定 Microsoft.Extensions.AI.IEmbeddingGenerator 實例,以自動產生裝飾屬性的內嵌。

提示

如需哪些連接器支援 StorageName 及有哪些替代方案的詳細資訊,請參閱 每個連接器的檔。

以下是如何建立記錄定義的範例,以搭配 pandas DataFrame 使用。

注意

此處會使用與 數據模型定義 中相同的欄位,針對數據模型,它們會新增為批注,此處為具有名稱的聽寫。

有幾個重要事項要注意,其他則欄位定義本身。 第一個是 container_mode 參數。 當設定為 True 時,這表示數據模型是容器類型,例如 DataFrame,因此數據模型是記錄的容器,而不是單一的容器記錄,可以完全相同的方式使用容器記錄,主要差異在於 get ,而且 get_batch 會傳回相同的數據類型。 具有的單一記錄 get ,以及一或多個 的 get_batch記錄。 當您想要執行 upsert, upsert 而且 upsert_batch 可以交替使用時,換句話說,將容器傳遞至 upsert 會導致多個 upsert,而不是單一插入。

第二個是 新增 to_dict 和 from_dict 方法,用來在數據模型與記憶體架構之間轉換。 在此情況下,方法 to_dict 會用來將 DataFrame 轉換成記錄清單,而 from_dict 方法會用來將記錄清單轉換成 DataFrame。 您也可以有 和 serializedeserialize 方法(如下列範例所示),如需有關串行 化文件之間差異的詳細數據。

from semantic_kernel.data import (
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
)

hotel_definition = VectorStoreRecordDefinition(
    fields={
        "hotel_id": VectorStoreRecordKeyField(property_type="str"),
        "hotel_name": VectorStoreRecordDataField(property_type="str", is_filterable=True),
        "description": VectorStoreRecordDataField(
            property_type="str", has_embedding=True, embedding_property_name="description_embedding"
        ),
        "description_embedding": VectorStoreRecordVectorField(property_type="list[float]"),
    },
    container_mode=True,
    to_dict=lambda record, **_: record.to_dict(orient="records"),
    from_dict=lambda records, **_: DataFrame(records),
)

建立定義時,您一律必須提供名稱(如聽寫中的 fields 索引鍵),以及架構中每個屬性的類型,因為這是建立索引和數據對應的必要專案。

若要使用定義,請將它傳遞給 GetCollection 方法或集合建構函式,以及數據模型類型。

collection = vector_store.get_collection(
    collection_name="skhotels", 
    record_type=pd.DataFrame, 
    definition=hotel_definition,
)

以下是如何建立記錄定義的範例。

var hotelDefinition = VectorStoreRecordDefinition.fromFields(
    Arrays.asList(
        VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),
        VectorStoreRecordDataField.builder()
            .withName("name")
            .withFieldType(String.class)
            .isFilterable(true).build(),
        VectorStoreRecordDataField.builder()
            .withName("description")
            .withFieldType(String.class)
            .isFullTextSearchable(true).build(),
        VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
            .withDimensions(4)
            .withIndexKind(IndexKind.HNSW)
            .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
            .withFieldType(List.class).build()
    )
);

建立定義時,您一律必須提供架構中每個欄位的名稱和類型,因為這是建立索引和數據對應的必要專案。

若要使用定義,請將它傳遞至 GetCollection 方法。

var collection = vectorStore.getCollection("skhotels",
        JDBCVectorStoreRecordCollectionOptions.builder()
            .withRecordDefinition(hotelDefinition)
            .build()
    );

記錄欄位組態類別

VectorStoreRecordKeyField

使用此類別指出您的欄位是記錄的索引鍵。

VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),

VectorStoreRecordKeyField 組態設定

參數 必要 描述
NAME 是的 數據模型上的功能變數名稱。 由內建對應器用來自動對應記憶體架構和數據模型,以及用來建立索引。
fieldType 是的 數據模型上的欄位類型。 由內建對應器用來自動對應記憶體架構和數據模型,以及用來建立索引。
存儲名稱 否 可用來提供資料庫中欄位的替代名稱。 請注意,所有連接器都不支援此參數,例如使用 Jackson 的位置,在此情況下,可以使用 Jackson 註釋來指定儲存名稱。

提示

如需哪些連接器支援 storageName 和哪些替代專案的詳細資訊,請參閱 每個連接器的檔。

VectorStoreRecordDataField

使用這個類別表示您的屬性包含不是索引鍵或向量的一般數據。

VectorStoreRecordDataField.builder()
    .withName("name")
    .withFieldType(String.class)
    .isFilterable(true).build(),

VectorStoreRecordDataField 組態設定

參數 必要 描述
NAME 是的 數據模型上的功能變數名稱。 由內建對應器用來自動對應記憶體架構和數據模型,以及用來建立索引。
fieldType 是的 數據模型上的欄位類型。 由內建對應器用來自動對應記憶體架構和數據模型,以及用來建立索引。
isFilterable 否 指出當資料庫需要加入每個欄位的索引編製索引時,是否應該為欄位編製索引以進行篩選。 預設為 False。
isFullTextSearchable 否 指出是否應該為支援全文搜索的資料庫編製全文搜索索引欄位。 預設為 False。
存儲名稱 否 可用來提供資料庫中欄位的替代名稱。 請注意,所有連接器都不支援此參數,例如使用 Jackson 的位置,在此情況下,可以使用 Jackson 註釋來指定儲存名稱。

提示

如需哪些連接器支援 storageName 和哪些替代專案的詳細資訊,請參閱 每個連接器的檔。

VectorStoreRecordVectorField

使用此類別指出您的欄位包含向量。

VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
    .withDimensions(4)
    .withIndexKind(IndexKind.HNSW)
    .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
    .withFieldType(List.class).build(),

VectorStoreRecordVectorField 組態設定

參數 必要 描述
NAME 是的 數據模型上的功能變數名稱。 由內建對應器用來自動對應記憶體架構和數據模型,以及用來建立索引。
fieldType 是的 數據模型上的欄位類型。 由內建對應器用來自動對應記憶體架構和數據模型,以及用來建立索引。
尺寸 [是] 用於集合建立,否則為選擇性 向量擁有的維度數目。 建立集合的向量索引時,通常需要這樣做。
indexKind 否 要用來為向量編製索引的索引型別。 預設值會依向量存放區類型而有所不同。
distanceFunction 否 在此向量搜尋期間執行向量比較時所要使用的函式類型。 預設值會依向量存放區類型而有所不同。
存儲名稱 否 可用來提供資料庫中欄位的替代名稱。 請注意,所有連接器都不支援此參數,例如使用 Jackson 的位置,在此情況下,可以使用 Jackson 註釋來指定儲存名稱。

提示

如需哪些連接器支援 storageName 和哪些替代專案的詳細資訊,請參閱 每個連接器的檔。