Bagikan melalui

Menentukan model data Anda (Pratinjau)

Peringatan

Fungsionalitas Penyimpanan Vektor Kernel Semantik sedang dalam pratinjau, dan peningkatan yang memerlukan perubahan yang melanggar mungkin masih terjadi dalam keadaan terbatas sebelum rilis.

Peringatan

Fungsionalitas Penyimpanan Vektor Kernel Semantik sedang dalam pratinjau, dan peningkatan yang memerlukan perubahan yang melanggar mungkin masih terjadi dalam keadaan terbatas sebelum rilis.

Gambaran Umum

Konektor Semantic Kernel Vector Store menggunakan pendekatan pertama model untuk berinteraksi dengan database.

Semua metode untuk melakukan upsert atau mendapatkan rekaman menggunakan kelas model yang ditik dengan kuat. Properti pada kelas ini dihiasi dengan atribut yang menunjukkan tujuan setiap properti.

Petunjuk / Saran

Untuk alternatif menggunakan atribut, lihat menentukan skema Anda dengan definisi rekaman.

Petunjuk / Saran

Sebagai alternatif untuk menentukan model data Anda sendiri, lihat menggunakan abstraksi Vector Store tanpa menentukan model data Anda sendiri.

Berikut adalah contoh model yang dihiasi dengan atribut ini.

using Microsoft.Extensions.VectorData;

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

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

    [VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string[] Tags { get; set; }
}

Atribut

VectorStoreKeyAttribute

Gunakan atribut ini untuk menunjukkan bahwa properti Anda adalah kunci rekaman.

[VectorStoreKey]
public ulong HotelId { get; set; }

Parameter VectorStoreKeyAttribute

Pengaturan Wajib Deskripsi
NamaPenyimpanan Tidak. Dapat digunakan untuk memberikan nama alternatif untuk properti dalam database. Perhatikan bahwa parameter ini tidak didukung oleh semua konektor, misalnya di mana alternatif seperti JsonPropertyNameAttribute didukung.

Petunjuk / Saran

Untuk informasi selengkapnya tentang dukungan StorageName konektor dan alternatif apa yang tersedia, lihat dokumentasi untuk setiap konektor.

VectorStoreDataAttribute

Gunakan atribut ini untuk menunjukkan bahwa properti Anda berisi data umum yang bukan kunci atau vektor.

[VectorStoreData(IsIndexed = true)]
public string HotelName { get; set; }

Parameter VectorStoreDataAttribute

Pengaturan Wajib Deskripsi
IsIndexed Tidak. Menunjukkan apakah properti harus diindeks untuk pemfilteran jika database mengharuskan memilih untuk mengindeks per properti. Defaultnya adalah false.
IsFullTextIndexed Tidak. Menunjukkan apakah properti harus diindeks untuk pencarian teks lengkap untuk database yang mendukung pencarian teks lengkap. Defaultnya adalah false.
NamaPenyimpanan Tidak. Dapat digunakan untuk memberikan nama alternatif untuk properti dalam database. Perhatikan bahwa parameter ini tidak didukung oleh semua konektor, misalnya di mana alternatif seperti JsonPropertyNameAttribute didukung.

Petunjuk / Saran

Untuk informasi selengkapnya tentang dukungan StorageName konektor dan alternatif apa yang tersedia, lihat dokumentasi untuk setiap konektor.

VectorStoreVectorAttribute

Gunakan atribut ini untuk menunjukkan bahwa properti Anda berisi vektor.

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

Dimungkinkan juga untuk menggunakan VectorStoreVectorAttribute pada properti yang tidak memiliki jenis vektor, misalnya properti jenis string. Ketika properti didekorasi dengan cara ini, Microsoft.Exntesions.AI.IEmbeddingGenerator instans perlu diberikan ke penyimpanan vektor. Saat meningkatkan rekaman, teks yang ada di string properti akan secara otomatis diubah menjadi vektor dan disimpan sebagai vektor dalam database. Tidak dimungkinkan untuk mengambil vektor menggunakan mekanisme ini.

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public string DescriptionEmbedding { get; set; }

Petunjuk / Saran

Untuk informasi selengkapnya tentang cara menggunakan pembuatan penyematan bawaan, lihat Membiarkan Penyimpanan Vektor menghasilkan penyematan.

Parameter VectorStoreVectorAttribute

Pengaturan Wajib Deskripsi
Dimensi Ya Jumlah dimensi yang dimiliki vektor. Ini diperlukan saat membuat indeks vektor untuk koleksi.
IndexKind Tidak. Jenis indeks untuk mengindeks vektor dengan. Default bervariasi menurut jenis penyimpanan vektor.
DistanceFunction Tidak. Jenis fungsi yang digunakan saat melakukan perbandingan vektor selama pencarian vektor melalui vektor ini. Default bervariasi menurut jenis penyimpanan vektor.
NamaPenyimpanan Tidak. Dapat digunakan untuk memberikan nama alternatif untuk properti dalam database. Perhatikan bahwa parameter ini tidak didukung oleh semua konektor, misalnya di mana alternatif seperti JsonPropertyNameAttribute didukung.

Jenis indeks umum dan jenis fungsi jarak disediakan sebagai nilai statis pada Microsoft.SemanticKernel.Data.IndexKind kelas dan Microsoft.SemanticKernel.Data.DistanceFunction . Implementasi Penyimpanan Vektor individu juga dapat menggunakan jenis indeks dan fungsi jarak mereka sendiri, di mana database mendukung jenis yang tidak biasa.

Petunjuk / Saran

Untuk informasi selengkapnya tentang dukungan StorageName konektor dan alternatif apa yang tersedia, lihat dokumentasi untuk setiap konektor.

Semua metode untuk upsert atau mendapatkan rekaman menggunakan kelas dan definisi rekaman penyimpanan vektor.

Ini dapat dilakukan dengan mendefinisikan kelas Anda sendiri dengan anotasi untuk bidang, atau dengan menggunakan kelas/jenis dalam kombinasi dengan definisi rekaman. Dua hal yang perlu dilakukan untuk kelas, yang pertama adalah menambahkan anotasi dengan jenis bidang, yang kedua adalah menghias kelas dengan vectorstoremodel dekorator.

Petunjuk / Saran

Untuk pendekatan alternatif menggunakan definisi rekaman, lihat menentukan skema Anda dengan definisi rekaman.

Berikut adalah contoh model yang dihiasi dengan anotasi ini.

from dataclasses import dataclass, field
from typing import Annotated
from semantic_kernel.data import (
    DistanceFunction,
    IndexKind,
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
    vectorstoremodel,
)

@vectorstoremodel
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreRecordKeyField()] = field(default_factory=lambda: str(uuid4()))
    hotel_name: Annotated[str, VectorStoreRecordDataField(is_filterable=True)]
    description: Annotated[str, VectorStoreRecordDataField(is_full_text_searchable=True)]
    description_embedding: Annotated[list[float], VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)]
    tags: Annotated[list[str], VectorStoreRecordDataField(is_filterable=True)]

Petunjuk / Saran

Menentukan kelas dengan anotasi ini dapat dilakukan dengan beberapa cara, salah satunya menggunakan dataclasses modul di Python, yang ditunjukkan di sini. Sampel ini menunjukkan pendekatan lain (menggunakan Pydantic BaseModels dan kelas python vanilla) juga.

Anotasi

Ada tiga jenis anotasi yang akan digunakan, dan memiliki kelas dasar yang sama.

VectorStoreRecordField

Ini adalah kelas dasar untuk semua anotasi, itu tidak dimaksudkan untuk digunakan secara langsung.

Parameter VectorStoreRecordField

Pengaturan Wajib Deskripsi
nama Tidak. Dapat ditambahkan secara langsung tetapi akan diatur selama penguraian model.
property_type Tidak. Harus berupa string, juga akan diturunkan selama penguraian.

Petunjuk / Saran

Anotasi diurai oleh vectorstoremodel dekorator dan salah satu hal yang dilakukannya adalah membuat definisi rekaman untuk kelas, oleh karena itu tidak perlu membuat instans kelas bidang ketika tidak ada parameter yang diatur, bidang dapat dianotasi hanya dengan kelas, seperti ini:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Gunakan anotasi ini untuk menunjukkan bahwa atribut ini adalah kunci rekaman.

VectorStoreRecordKeyField()

Parameter VectorStoreRecordKeyField

Tidak ada parameter lain di luar kelas dasar yang ditentukan.

VectorStoreRecordDataField

Gunakan anotasi ini untuk menunjukkan bahwa atribut Anda berisi data umum yang bukan kunci atau vektor.

VectorStoreRecordDataField(is_filterable=True)

Parameter VectorStoreRecordDataField

Pengaturan Wajib Deskripsi
has_embedding Tidak. Menunjukkan apakah properti memiliki penyematan yang terkait dengannya, defaultnya adalah Tidak Ada.
embedding_property_name Tidak. Nama properti yang berisi penyematan, defaultnya adalah Tidak Ada.
is_filterable Tidak. Menunjukkan apakah properti harus diindeks untuk pemfilteran jika database mengharuskan memilih untuk mengindeks per properti. Defaultnya adalah false.
is_full_text_searchable Tidak. Menunjukkan apakah properti harus diindeks untuk pencarian teks lengkap untuk database yang mendukung pencarian teks lengkap. Defaultnya adalah false.

VectorStoreRecordVectorField

Gunakan anotasi ini untuk menunjukkan bahwa atribut Anda berisi vektor.

VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)

Parameter VectorStoreRecordVectorField

Pengaturan Wajib Deskripsi
ukuran Ya untuk pembuatan koleksi, opsional jika tidak Jumlah dimensi yang dimiliki vektor. Ini biasanya diperlukan saat membuat indeks vektor untuk koleksi.
index_kind Tidak. Jenis indeks untuk mengindeks vektor dengan. Default bervariasi menurut jenis penyimpanan vektor.
distance_function Tidak. Jenis fungsi yang digunakan saat melakukan perbandingan vektor selama pencarian vektor melalui vektor ini. Default bervariasi menurut jenis penyimpanan vektor.
local_embedding Tidak. Menunjukkan apakah properti memiliki penyematan lokal yang terkait dengannya, defaultnya adalah Tidak Ada.
embedding_settings Tidak. Pengaturan untuk penyematan, dalam bentuk dict dengan service_id sebagai kunci dan PromptExecutionSettings sebagai nilai, defaultnya adalah None.
serialize_function Tidak. Fungsi yang digunakan untuk menserialisasikan vektor, jika jenisnya bukan daftar[float | int] fungsi ini diperlukan, atau seluruh model perlu diserialisasikan.
deserialize_function Tidak. Fungsi yang digunakan untuk mendeserialisasi vektor, jika jenisnya bukan daftar[float | int] fungsi ini diperlukan, atau seluruh model perlu dideserialisasi.

Jenis indeks umum dan jenis fungsi jarak disediakan sebagai nilai statis pada semantic_kernel.data.IndexKind kelas dan semantic_kernel.data.DistanceFunction . Implementasi Penyimpanan Vektor individu juga dapat menggunakan jenis indeks dan fungsi jarak mereka sendiri, di mana database mendukung jenis yang tidak biasa.

Semua metode untuk melakukan upsert atau mendapatkan rekaman menggunakan kelas model yang ditik dengan kuat. Bidang pada kelas ini dihiasi dengan anotasi yang menunjukkan tujuan setiap bidang.

Petunjuk / Saran

Untuk alternatif menggunakan atribut, lihat menentukan skema Anda dengan definisi rekaman.

Berikut adalah contoh model yang dihiasi dengan anotasi ini. Secara default, sebagian besar toko vektor di luar kotak menggunakan Jackson, dengan demikian adalah praktik yang baik untuk memastikan objek model dapat diserialisasikan oleh Jackson, yaitu kelas terlihat, memiliki getter, konstruktor, anotasi, dll.

import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordData;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordKey;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordVector;
import com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction;
import com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind;

import java.util.List;

public class Hotel {
    @VectorStoreRecordKey
    private String hotelId;

    @VectorStoreRecordData(isFilterable = true)
    private String name;

    @VectorStoreRecordData(isFullTextSearchable = true)
    private String description;

    @VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
    private List<Float> descriptionEmbedding;

    @VectorStoreRecordData(isFilterable = true)
    private List<String> tags;

    public Hotel() { }

    public Hotel(String hotelId, String name, String description, List<Float> descriptionEmbedding, List<String> tags) {
        this.hotelId = hotelId;
        this.name = name;
        this.description = description;
        this.descriptionEmbedding = descriptionEmbedding;
        this.tags = tags;
    }

    public String getHotelId() { return hotelId; }
    public String getName() { return name; }
    public String getDescription() { return description; }
    public List<Float> getDescriptionEmbedding() { return descriptionEmbedding; }
    public List<String> getTags() { return tags; }
}

Anotasi

VectorStoreRecordKey

Gunakan anotasi ini untuk menunjukkan bahwa bidang Anda adalah kunci rekaman.

@VectorStoreRecordKey
private String hotelId;

Parameter VectorStoreRecordKey

Pengaturan Wajib Deskripsi
Nama penyimpanan Tidak. Dapat digunakan untuk memberikan nama alternatif untuk bidang dalam database. Perhatikan bahwa parameter ini tidak didukung oleh semua konektor, misalnya di mana Jackson digunakan, dalam hal ini nama penyimpanan dapat ditentukan menggunakan anotasi Jackson.

Petunjuk / Saran

Untuk informasi selengkapnya tentang konektor mana yang mendukung storageName dan alternatif apa yang tersedia, lihat dokumentasi untuk setiap konektor.

VectorStoreRecordData

Gunakan anotasi ini untuk menunjukkan bahwa bidang Anda berisi data umum yang bukan kunci atau vektor.

@VectorStoreRecordData(isFilterable = true)
private String name;

Parameter VectorStoreRecordData

Pengaturan Wajib Deskripsi
isFilterable Tidak. Menunjukkan apakah bidang harus diindeks untuk pemfilteran jika database memerlukan pengindeksan per bidang. Defaultnya adalah false.
isFullTextSearchable Tidak. Menunjukkan apakah bidang harus diindeks untuk pencarian teks lengkap untuk database yang mendukung pencarian teks lengkap. Defaultnya adalah false.
Nama penyimpanan Tidak. Dapat digunakan untuk memberikan nama alternatif untuk bidang dalam database. Perhatikan bahwa parameter ini tidak didukung oleh semua konektor, misalnya di mana Jackson digunakan, dalam hal ini nama penyimpanan dapat ditentukan menggunakan anotasi Jackson.

Petunjuk / Saran

Untuk informasi selengkapnya tentang konektor mana yang mendukung storageName dan alternatif apa yang tersedia, lihat dokumentasi untuk setiap konektor.

VectorStoreRecordVector

Gunakan anotasi ini untuk menunjukkan bahwa bidang Anda berisi vektor.

@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;

Parameter VectorStoreRecordVector

Pengaturan Wajib Deskripsi
ukuran Ya untuk pembuatan koleksi, opsional jika tidak Jumlah dimensi yang dimiliki vektor. Ini biasanya diperlukan saat membuat indeks vektor untuk koleksi.
indexKind Tidak. Jenis indeks untuk mengindeks vektor dengan. Default bervariasi menurut jenis penyimpanan vektor.
distanceFunction Tidak. Jenis fungsi yang digunakan saat melakukan perbandingan vektor selama pencarian vektor melalui vektor ini. Default bervariasi menurut jenis penyimpanan vektor.
Nama penyimpanan Tidak. Dapat digunakan untuk memberikan nama alternatif untuk bidang dalam database. Perhatikan bahwa parameter ini tidak didukung oleh semua konektor, misalnya di mana Jackson digunakan, dalam hal ini nama penyimpanan dapat ditentukan menggunakan anotasi Jackson.

Jenis indeks umum dan jenis fungsi jarak disediakan pada com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind enum dan com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction . Implementasi Penyimpanan Vektor individu juga dapat menggunakan jenis indeks dan fungsi jarak mereka sendiri, di mana database mendukung jenis yang tidak biasa.

Petunjuk / Saran

Untuk informasi selengkapnya tentang konektor mana yang mendukung storageName dan alternatif apa yang tersedia, lihat dokumentasi untuk setiap konektor.

Info lebih lanjut akan segera hadir.

  • Last updated on