Veri modelinizi tanımlama

Microsoft.Extensions.VectorData veritabanlarıyla etkileşime geçmek için model öncelikli bir yaklaşım kullanır.

Kayıt eklemek veya almak için kullanılan tüm yöntemler, kesin olarak belirlenmiş model sınıflarını kullanır. Veri modelini tanımlamanın iki yolu vardır:

  • Model sınıflarında özellikleri, her özelliğin amacını gösteren özniteliklerle süsleyerek.
  • Veri modelinden ayrı olarak sağladığınız bir kayıt tanımı kullanarak depolama şemanızı tanımlayarak. Kayıt tanımıVectorStoreCollectionDefinition içeren bir tanımdır.

Aşağıda özellikleri özniteliklerle VectorStore*Attribute donatılmış bir sınıf veya veri modeli örneği verilmiştir.

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; }
}

Veri modeli özellikleri

Uyarı

Anahtarlar, veriler ve vektörler için desteklenen .NET özellik türleri veritabanları arasında farklılık gösterir. Desteklenen türler hakkında bilgi için seçtiğiniz vektör deposu sağlayıcısının belgelerine bakın.

Anahtar özelliği

Her veri modelinin koleksiyondaki her kaydı benzersiz olarak tanımlayan bir anahtar özelliği olmalıdır.

VectorStoreKeyAttribute özelliğinizin kaydın birincil anahtarı olduğunu belirtmek için özniteliğini kullanın.

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

Aşağıdaki tabloda için VectorStoreKeyAttributeparametreleri gösterilmektedir.

Parametre Zorunlu Açıklama
IsAutoGenerated Hayır Anahtar değerinin veritabanı tarafından otomatik olarak oluşturulup oluşturulmadığını gösterir. Varsayılan false değeridir.
StorageName Hayır Veritabanındaki özelliği için alternatif bir ad sağlamak için kullanılabilir. Bu parametre, gibi alternatiflerin desteklendiği tüm sağlayıcılar JsonPropertyNameAttribute tarafından desteklenmez.

Veri özelliği

Veri özellikleri, kayıt ararken alınan metin, etiket veya diğer meta veriler gibi genel amaçlı içeriği barındırabilir ve isteğe bağlı olarak filtreleme için dizine alınabilir.

VectorStoreDataAttribute özelliğinizin anahtar veya vektör olmayan genel veriler içerdiğini belirtmek için özniteliğini kullanın.

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

Aşağıdaki tabloda için VectorStoreDataAttributeparametreleri gösterilmektedir.

Parametre Zorunlu Açıklama
IsIndexed Hayır Bir veritabanının özellik başına dizin oluşturmayı kabul etmesi gereken durumlarda, filtreleme için özelliğin dizine alınıp alınmayacağını gösterir. Varsayılan değer: false.
IsFullTextIndexed Hayır Tam metin aramasını destekleyen veritabanları için tam metin araması için özelliğin dizine alınıp alınmayacağını gösterir. Varsayılan değer: false.
StorageName Hayır Veritabanındaki özelliği için alternatif bir ad sağlamak için kullanılabilir. Bu parametre, gibi alternatiflerin desteklendiği tüm sağlayıcılar JsonPropertyNameAttribute tarafından desteklenmez.

Vector özelliği

Vektör özellikleri, benzerlik araması için kullanılan ekleme vektörlerini içerir; gelişmiş senaryolarda, bir veri modelinin kaydın farklı yönleri üzerinde aramayı desteklemek için birden çok vektör özelliği olabilir.

VectorStoreVectorAttribute özelliğinizin bir vektör içerdiğini belirtmek için özniteliğini kullanın.

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

Vektör türü olmayan özelliklerde (örneğin, türünde VectorStoreVectorAttributebir özellik) kullanmak string da mümkündür. Bir özellik bu şekilde dekore edildiğinde, vektör deposuna bir IEmbeddingGenerator örnek sağlamanız gerekir. Kayıt artırılırken, özelliğindeki string metin otomatik olarak dönüştürülür ve veritabanında vektör olarak depolanır. (Bu mekanizmayı kullanarak vektör almak mümkün değildir.)

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

Tip

Yerleşik ekleme oluşturma özelliğini kullanma hakkında daha fazla bilgi için bkz . Vektör özellikleri ve ekleme oluşturma.

Aşağıdaki tabloda için VectorStoreVectorAttributeparametreleri gösterilmektedir.

Parametre Zorunlu Açıklama
Dimensions Evet Vektördeki boyut sayısı. Bu, bir koleksiyon için vektör dizini oluştururken gereklidir.
IndexKind Hayır Vektör ile dizine eklemek için dizin türü. Varsayılan değer vektör deposu türüne göre değişir.
DistanceFunction Hayır Bu vektör üzerinde vektör araması sırasında vektör karşılaştırması yapılırken kullanılacak işlev türü. Varsayılan değer vektör deposu türüne göre değişir.
StorageName Hayır Veritabanındaki özelliği için alternatif bir ad sağlamak için kullanılabilir. Bu parametre, gibi alternatiflerin desteklendiği tüm sağlayıcılar JsonPropertyNameAttribute tarafından desteklenmez.

Ortak dizin türleri ve uzaklık işlev türleri ve IndexKind sınıflarında DistanceFunction statik değerler olarak sağlanır. Tek tek vektör deposu uygulamaları, veritabanının olağan dışı türleri desteklediği kendi dizin türlerini ve uzaklık işlevlerini de kullanabilir.

Vektör özellikleri ve ekleme oluşturma

Vektör veritabanlarının tamamı, ekleme modeli tarafından oluşturulan eklemeleri veya verilerinizin sayısal gösterimlerini depolamaktır. Verileri depolarken veya ararken, aranabilir verileri bu tür eklemelere dönüştürmek için önce ekleme oluşturma gerçekleştirilmelidir. MEVD, ekleme oluşturma için iki yaklaşım sağlar: el ile ve otomatik.

El ile, alt düzey ekleme oluşturma

Vektör özelliğinizi veya ReadOnlyMemory<float>olarak float[] tanımlayabilir ve ekleme işlemini doğrudan temsil edebilir ve her işlemden önce kendiniz ekleme oluşturabilirsiniz:

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

Arama yaparken, sorgu metniniz için ekleme oluşturur ve öğesine geçirirsiniz SearchAsync:

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

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

Bu işe yarasa da, her çağrı sitesinde ekleme oluşturmayı yönetmenizi gerektirir.

Önerilen yaklaşım, vektör deponuzda bir IEmbeddingGenerator<TInput,TEmbedding> yapılandırmaktır. Bu, vektör özelliğinizi veya ReadOnlyMemory<float>yerine float[] kaynak türünü (örneğin, string) kullanarak tanımlamanızı sağlar. MEVD daha sonra hem upsert hem de arama işlemleri sırasında ekleme oluşturmayı otomatik olarak işler.

İlk olarak, vector özelliğini olarak stringtanımlayın:

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

Ardından, vektör deponuzu oluştururken bir ekleme oluşturucu yapılandırın:

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

Artık metni doğrudan geçirebilirsiniz- MEVD, arka planda eklemeler oluşturur:

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

Önemli

Bu şekilde yapılandırılan vektör özellikleri, oluşturulan vektör veya özgün metnin veritabanından alınmasını desteklemez. Özgün metni depolamanız gerekiyorsa ayrı bir veri özelliği ekleyin.

Ekleme oluşturucuları koleksiyon, kayıt tanımı veya tek tek vektör özelliği düzeyinde de yapılandırılabilir. Farklı ekleme modelleri farklı vektör boyutlarını destekler; değerin Dimensions yapılandırdığınız modelle eşleştiğinden emin olun. Oluşturucuları ekleme ve Microsoft.Extensions.AI soyutlamaları hakkında daha fazla bilgi için bkz. Embeddings in .NET.

.NET Sözlüğüne dinamik eşleme

Kesin olarak belirlenmiş bir .NET türünü veritabanına eşlemenin istendiği veya mümkün olmadığı durumlar vardır. Örneğin, derleme zamanında veritabanı şemanızın nasıl göründüğünü bilmediğinizi ve şemanın yalnızca yapılandırma aracılığıyla sağlandığını düşünün. Şemayı yansıtan bir .NET türü oluşturmak bu durumda imkansız olabilir. Bunun yerine, kayıt türü için bir kullanarak Dictionary<string, object?> eşleyebilirsiniz. Özellikler, özelliğin adı olarak anahtarı ve özellik değeri olarak değeri ile öğesine eklenir Dictionary .

Uyarı

Çoğu uygulama, verilerini modellemek için kesin olarak yazılan .NET türlerini kullanır. aracılığıyla Dictionary<string, object?> dinamik eşleme, gelişmiş, rastgele veri eşleme senaryoları içindir.

Kullanırken şema bilgilerini sağlayın Dictionary

kullandığınızda Dictionary, sağlayıcıların yine de veritabanı şemasının nasıl göründüğünü bilmesi gerekir. Şema bilgileri olmadan sağlayıcı bir koleksiyon oluşturamaz veya her veritabanının kullandığı depolama gösterimiyle eşlemeyi bilemez.

Şema bilgilerini sağlamak için bir kayıt tanımı kullanabilirsiniz. Veri modellerinden farklı olarak, şema bilgileri derleme zamanında bilinmediğinde çalışma zamanında yapılandırmadan bir kayıt tanımı oluşturulabilir.

Example

Bir sağlayıcıyla kullanmak Dictionary için, koleksiyonu oluştururken bunu veri modeliniz olarak belirtin. Ayrıca bir kayıt tanımı da sağlayın.

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