Tentukan model data Anda

Microsoft.Extensions.VectorData menggunakan pendekatan model-first untuk berinteraksi dengan database.

Semua metode untuk melakukan upsert atau mendapatkan rekaman menggunakan kelas model yang ditik dengan kuat. Ada dua cara untuk menentukan model data:

  • Dengan mendekorasi properti pada kelas model dengan atribut yang menunjukkan tujuan setiap properti.
  • Dengan menentukan skema penyimpanan Anda menggunakan definisi rekaman yang Anda berikan secara terpisah dari model data. Definisi rekaman adalah yang VectorStoreCollectionDefinition berisi properti.

Berikut adalah contoh kelas, atau model data, yang propertinya dihiasi dengan VectorStore*Attribute atribut.

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

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

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

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

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

Properti model data

Nota

Jenis properti .NET yang didukung untuk kunci, data, dan vektor bervariasi di seluruh database. Untuk informasi tentang jenis yang didukung, periksa dokumentasi penyedia penyimpanan vektor yang Anda pilih.

Properti kunci

Setiap model data harus memiliki properti kunci yang secara unik mengidentifikasi setiap rekaman dalam koleksi.

VectorStoreKeyAttribute Gunakan atribut untuk menunjukkan bahwa properti Anda adalah kunci utama rekaman.

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

Tabel berikut menunjukkan parameter untuk VectorStoreKeyAttribute.

Parameter Required Deskripsi
IsAutoGenerated No Menunjukkan apakah nilai kunci dibuat secara otomatis oleh database. Defaultnya adalah false.
StorageName No Dapat digunakan untuk memberikan nama alternatif untuk properti dalam database. Parameter ini tidak didukung oleh semua penyedia, misalnya, di mana alternatif seperti JsonPropertyNameAttribute didukung.

Properti data

Properti data menyimpan konten tujuan umum seperti teks, tag, atau metadata lain yang diambil saat mencari rekaman, dan secara opsional juga dapat diindeks untuk pemfilteran.

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

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

Tabel berikut menunjukkan parameter untuk VectorStoreDataAttribute.

Parameter Required Deskripsi
IsIndexed No Menunjukkan apakah properti harus diindeks untuk pemfilteran jika database mengharuskan memilih untuk mengindeks per properti. Defaultnya adalah false.
IsFullTextIndexed No Menunjukkan apakah properti harus diindeks untuk pencarian teks lengkap untuk database yang mendukung pencarian teks lengkap. Defaultnya adalah false.
StorageName No Dapat digunakan untuk memberikan nama alternatif untuk properti dalam database. Parameter ini tidak didukung oleh semua penyedia, misalnya, di mana alternatif seperti JsonPropertyNameAttribute didukung.

Properti vektor

Properti vektor berisi vektor penyematan yang digunakan untuk pencarian kesamaan; dalam skenario lanjutan, model data dapat memiliki beberapa properti vektor untuk mendukung pencarian atas berbagai aspek rekaman.

VectorStoreVectorAttribute Gunakan atribut 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, Anda perlu menyediakan IEmbeddingGenerator instans ke penyimpanan vektor. Saat meningkatkan rekaman, teks yang ada di properti secara otomatis dikonversi string 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 Properti vektor dan pembuatan penyematan.

Tabel berikut menunjukkan parameter untuk VectorStoreVectorAttribute.

Parameter Required Deskripsi
Dimensions Yes Jumlah dimensi yang dimiliki vektor. Ini diperlukan saat membuat indeks vektor untuk koleksi.
IndexKind No Jenis indeks untuk mengindeks vektor dengan. Default bervariasi menurut jenis penyimpanan vektor.
DistanceFunction No Jenis fungsi yang digunakan saat melakukan perbandingan vektor selama pencarian vektor melalui vektor ini. Default bervariasi menurut jenis penyimpanan vektor.
StorageName No Dapat digunakan untuk memberikan nama alternatif untuk properti dalam database. Parameter ini tidak didukung oleh semua penyedia, misalnya, di mana alternatif seperti JsonPropertyNameAttribute didukung.

Jenis indeks umum dan jenis fungsi jarak disediakan sebagai nilai statis pada IndexKind kelas dan DistanceFunction . Implementasi penyimpanan vektor individu mungkin juga menggunakan jenis indeks dan fungsi jaraknya sendiri, di mana database mendukung jenis yang tidak biasa.

Properti vektor dan pembuatan penyematan

Database vektor adalah tentang menyimpan penyematan - atau representasi numerik data Anda - yang dihasilkan oleh model penyematan. Saat menyimpan atau mencari data, pembuatan penyematan harus dilakukan terlebih dahulu untuk mengonversi data yang dapat dicari ke penyematan tersebut. MEVD menyediakan dua pendekatan untuk menyematkan pembuatan: manual dan otomatis.

Pembuatan penyematan manual tingkat rendah

Anda dapat menentukan properti vektor Anda sebagai float[] atau ReadOnlyMemory<float>, yang mewakili penyematan secara langsung, dan menghasilkan penyematan sendiri sebelum setiap operasi:

[VectorStoreVector(Dimensions: 1536)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

Saat mencari, Anda akan membuat penyematan untuk teks kueri Anda dan meneruskannya ke SearchAsync:

ReadOnlyMemory<float> searchEmbedding =
    (await embeddingGenerator.GenerateAsync("Find a happy hotel")).Vector;

var searchResult = collection.SearchAsync(searchEmbedding, top: 3);

Meskipun ini berfungsi, Anda perlu mengelola pembuatan penyematan di setiap situs panggilan.

Pendekatan yang disarankan adalah mengonfigurasi IEmbeddingGenerator<TInput,TEmbedding> di penyimpanan vektor Anda. Ini memungkinkan Anda menentukan properti vektor Anda menggunakan jenis sumber (misalnya, string) alih-alih float[] atau ReadOnlyMemory<float>. MEVD kemudian menangani pembuatan penyematan secara otomatis selama operasi upsert dan pencarian.

Pertama, tentukan properti vektor sebagai string:

[VectorStoreVector(Dimensions: 1536)]
public string DescriptionEmbedding { get; set; }

Kemudian, konfigurasikan generator penyematan saat membuat penyimpanan vektor Anda:

VectorStore vectorStore = new QdrantVectorStore(
    new QdrantClient("localhost"),
    ownsClient: true,
    new QdrantVectorStoreOptions
    {
        EmbeddingGenerator = embeddingGenerator
    });

Anda sekarang dapat meneruskan teks secara langsung - MEVD menghasilkan penyematan di bawah tenda:

// Search with a plain text query - embedding is generated automatically.
var searchResult = collection.SearchAsync("Find a happy hotel", top: 3);

Penting

Properti vektor yang dikonfigurasi dengan cara ini tidak mendukung pengambilan vektor yang dihasilkan atau teks asli dari database. Jika Anda perlu menyimpan teks asli, tambahkan properti data terpisah.

Generator penyematan juga dapat dikonfigurasi pada tingkat properti koleksi, definisi rekaman, atau vektor individual. Model penyematan yang berbeda mendukung ukuran vektor yang berbeda; pastikan Dimensions nilainya cocok dengan model yang telah Anda konfigurasi. Untuk informasi selengkapnya tentang menyematkan generator dan abstraksi Microsoft.Extensions.AI, lihat Embeddings di .NET.

Pemetaan dinamis ke Kamus .NET

Ada kasus di mana tidak diinginkan atau dimungkinkan untuk memetakan jenis .NET yang sangat ditik ke database. Misalnya, bayangkan Anda tidak tahu pada waktu kompilasi seperti apa skema database Anda, dan skema hanya disediakan melalui konfigurasi. Membuat jenis .NET yang mencerminkan skema tidak mungkin dalam hal ini. Sebagai gantinya, Anda dapat memetakan secara dinamis dengan menggunakan Dictionary<string, object?> untuk jenis catatan. Properti ditambahkan ke Dictionary dengan kunci sebagai nama properti dan nilai sebagai nilai properti.

Nota

Sebagian besar aplikasi hanya akan menggunakan jenis .NET yang diketik dengan kuat untuk memodelkan data mereka. Pemetaan dinamis melalui Dictionary<string, object?> adalah untuk skenario pemetaan data lanjutan dan semena-mena.

Menyediakan informasi skema saat menggunakan Dictionary

Saat Anda menggunakan Dictionary, penyedia masih perlu mengetahui seperti apa skema database. Tanpa informasi skema, penyedia tidak akan dapat membuat koleksi atau tahu cara memetakan ke dan dari representasi penyimpanan yang digunakan setiap database.

Anda dapat menggunakan definisi rekaman untuk memberikan informasi skema. Tidak seperti model data, definisi rekaman dapat dibuat dari konfigurasi saat runtime saat informasi skema tidak diketahui pada waktu kompilasi.

Example

Untuk digunakan Dictionary dengan penyedia, tentukan sebagai model data Anda saat Anda membuat koleksi. Berikan juga definisi rekaman.

VectorStoreCollectionDefinition definition = new()
{
    Properties =
    [
        new VectorStoreKeyProperty("Key", typeof(string)),
        new VectorStoreDataProperty("Term", typeof(string)),
        new VectorStoreDataProperty("Definition", typeof(string)),
        new VectorStoreVectorProperty("DefinitionEmbedding", typeof(ReadOnlyMemory<float>), dimensions: 1536)
    ]
};

// Use GetDynamicCollection instead of the regular GetCollection method
// to get an instance of a collection using Dictionary<string, object?>.
VectorStoreCollection<object, Dictionary<string, object?>> dynamicDataModelCollection =
    vectorStore.GetDynamicCollection("glossary", definition);

// Since schema information is available from the record definition,
// it's possible to create a collection with the right vectors,
// dimensions, indexes, and distance functions.
await dynamicDataModelCollection.EnsureCollectionExistsAsync();

// When retrieving a record from the collection,
// access key, data, and vector values via the dictionary entries.
Dictionary<string, object?>? record = await dynamicDataModelCollection.GetAsync("SK");
Console.WriteLine(record["Definition"]);
  • Last updated on