Sohbet Geçmişi Bellek Sağlayıcısı

, ChatHistoryMemoryProvider tüm sohbet geçmişini bir vektör deposunda depolayan ve geçerli konuşmayı artırmak için ilgili iletileri alan bir Yapay Zeka Bağlam Sağlayıcısıdır. Bu, aracıların anlamsal benzerlik araması kullanarak önceki etkileşimlerden ilgili bağlamı geri çağırmasını sağlar.

Nasıl çalışır?

Sağlayıcı iki aşamada çalışır:

Depolama: Her aracı çağrısından sonra, yeni istek ve yanıt iletileri içeriklerinden oluşturulan eklemelerle vektör deposunda depolanır.
Getirme: Her çağrıdan önce (veya bir işlev çağrısıyla talep üzerine), sağlayıcı, vektör deposunda geçerli kullanıcı girişine anlamsal olarak benzeyen iletileri arar ve bunları bağlam olarak ekler.

Depolanan iletilerin kapsamı yapılandırılabilir tanımlayıcılar (uygulama, aracı, kullanıcı, oturum) kullanılarak yapılır ve bu sayede hangi geçmişin depolandığı ve aranabilir olduğu üzerinde ayrıntılı denetim sağlanır.

Önkoşullar

📦 Microsoft.Extensions.VectorData.Abstractions'tan bir vektör deposu uygulaması (örneğin, 📦InMemoryVectorStore, 📦Azure Yapay Zeka Arama veya diğer desteklenen depolar)
Vektör deponuzda yapılandırılmış bir ekleme modeli
Sohbet modeli için Azure OpenAI veya OpenAI dağıtımı
.NET 8.0 veya üzeri

Tavsiye

VectorData soyutlaması ve kullanılabilir uygulamalar hakkında daha fazla bilgi almak için Vector Stores entegrasyonu belgelerine bakın.

Kullanım

Aşağıdaki örnek, bir bellek içi vektör deposu kullanılarak ChatHistoryMemoryProvider ile bir aracı oluşturmayı göstermektedir.

Arama kapsamı için yalnızca userid kullanımına dikkat edin. Bu, aracının yeni yanıtları bilgilendirmek için aynı kullanıcıyla yapılan önceki konuşmalardan bilgileri geri çağırmasına olanak tanır.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") 
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") 
    ?? "text-embedding-3-large";

// Create a vector store with an embedding generator.
// For production, replace InMemoryVectorStore with a persistent store.
VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions()
{
    EmbeddingGenerator = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
        .GetEmbeddingClient(embeddingDeploymentName)
        .AsIEmbeddingGenerator()
});

// Create the agent with ChatHistoryMemoryProvider
AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new() { Instructions = "You are a helpful assistant." },
        Name = "MemoryAgent",
        AIContextProviders = [new ChatHistoryMemoryProvider(
            vectorStore,
            collectionName: "chathistory",
            vectorDimensions: 3072,
            session => new ChatHistoryMemoryProvider.State(
                // Configure where messages are stored
                storageScope: new() { UserId = "user-123", SessionId = Guid.NewGuid().ToString() },
                // Configure where to search (can be broader than storage scope)
                searchScope: new() { UserId = "user-123" }))]
    });

// Start a session and interact with the agent
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("I prefer window seats on flights.", session));

// Start a new session - the agent can recall the user's preference
AgentSession session2 = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Book me a flight to Seattle.", session2));

Tavsiye

Bellek yalıtımını denetlemek için farklı storageScope ve searchScope yapılandırmaları kullanın. Örneğin, oturum başına depolayın ancak bir kullanıcının tüm oturumlarında arama yapın.

Yapılandırma seçenekleri

sınıfı, ChatHistoryMemoryProviderOptions sağlayıcı davranışı için yapılandırma sağlar.

Arama davranışı

Seçenek	Türü	Varsayılan	Açıklama
`SearchTime`	`SearchBehavior`	`BeforeAIInvoke`	Bellek araması ne zaman yürütüleceğini denetler.

Enum SearchBehavior iki değeri vardır.

BeforeAIInvoke: Her yapay zeka çağrısı öncesinde ilgili anıları otomatik olarak arar ve bağlam iletileri olarak ekler. Bu varsayılan davranıştır.
OnDemandFunctionCalling: Yapay zeka modelinin isteğe bağlı bellekleri aramak için çağırabileceği bir işlev aracını kullanıma sunar. Modelin bellekleri ne zaman geri çekeceğine karar vermesini istediğinizde bunu kullanın.

Arama sonucu seçenekleri

Seçenek	Türü	Varsayılan	Açıklama
`MaxResults`	`int?`	`3`	Arama başına alınacak en fazla sohbet geçmişi sonucu sayısı.
`ContextPrompt`	`string?`	`"## Memories\nConsider the following memories..."`	Eklemeden önce arama sonuçlarına ön ekli istem metni.

İsteğe bağlı işlev aracı seçenekleri

Bu seçenekler yalnızca SearchTime ayarlandığında OnDemandFunctionCalling geçerlidir.

Seçenek	Türü	Varsayılan	Açıklama
`FunctionToolName`	`string?`	`"Search"`	Modele sunulan arama işlevi aracının adı.
`FunctionToolDescription`	`string?`	`"Allows searching for related previous chat history..."`	Arama işlevi aracının açıklaması.

İleti filtreleme

Seçenek	Türü	Varsayılan	Açıklama
`SearchInputMessageFilter`	`Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>?`	Yalnızca dış iletiler	Arama sorguları oluştururken istek iletilerine uygulanan filtre.
`StorageInputRequestMessageFilter`	`Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>?`	Yalnızca dış iletiler	Depolamadan önce istek iletilerine uygulanan filtre.
`StorageInputResponseMessageFilter`	`Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>?`	Filtre yok	Depolamadan önce yanıt iletilerine uygulanan filtre.

Kaydedici ve telemetri

Seçenek	Türü	Varsayılan	Açıklama
`EnableSensitiveTelemetryData`	`bool`	`false`	`true` hassas veriler (kullanıcı kimlikleri, ileti içeriği) değişmeden günlüklerde görünür.
`Redactor`	`Redactor?`	Metni `"<redacted>"` ile değiştiren dönüştürücü	Hassas verileri günlük kaydı sırasında düzenlemek için özel düzenleyici. Eğer `EnableSensitiveTelemetryData` ise `true` yoksayılır.

Durum yönetimi

Seçenek	Türü	Varsayılan	Açıklama
`StateKey`	`string?`	Sağlayıcı türü adı	sağlayıcı durumunu içinde depolamak için kullanılan anahtar `AgentSession.StateBag`. Aynı oturumda birden çok `ChatHistoryMemoryProvider` örneği kullanırken geçersiz kılma.

Kapsam yapılandırması

sınıfı, ChatHistoryMemoryProviderScope iletilerin vektör deposunda nasıl düzenlendiğini ve filtrelendiğini denetler.

Mülkiyet	Türü	Açıklama
`ApplicationId`	`string?`	İletileri belirli bir uygulamanın kapsamına ekleme. Ayarlanmadıysa, tüm uygulamaları kapsıyor.
`AgentId`	`string?`	Belirli bir aracıya iletileri yönlendir. Eğer ayarlanmazsa, tüm aracıları kapsar.
`UserId`	`string?`	İletileri belirli bir kullanıcıya kapsam olarak belirleyin. Ayarlanmadıysa, tüm kullanıcılara yayılacak.
`SessionId`	`string?`	İletileri belirli bir oturuma kapsam olarak belirleyin.

Depolama ve arama kapsamı karşılaştırması

ChatHistoryMemoryProvider.State sınıfı iki kapsamı kabul eder:

storageScope: Yeni iletilerin depolandığında nasıl etiketlenmiş olduğunu tanımlar. Tüm kapsam özellikleri meta veri olarak yazılır.
searchScope: Arama yaparken filtre ölçütlerini tanımlar. Birden çok oturumda veya aracıda arama yapmak için bu alanı depolama kapsamına göre daha geniş bir değere ayarlayın.

Örnek: Oturum başına depolama, kullanıcı için tüm oturumlarda arama:

new ChatHistoryMemoryProvider.State(
    storageScope: new() { UserId = "user-123", SessionId = "session-456" },
    searchScope: new() { UserId = "user-123" })

Güvenlik konuları

Uyarı

Üretim ortamında ChatHistoryMemoryProvider dağıtmadan önce bu güvenlik konularını gözden geçirin.

Dolaylı istem ekleme: Vektör deposundan alınan iletiler LLM bağlamı içine eklenir. Vektör deposu ele geçirilirse saldırgan içerik LLM davranışını etkileyebilir. Depolamadan gelen veriler doğrulama olmadan olduğu gibi kabul edilir.
PII ve hassas veriler: Konuşma iletileri (kullanıcı girişleri ve LLM yanıtları dahil) vektör olarak depolanır. Bu iletiler PII veya hassas bilgiler içerebilir. Vektör deponuzun uygun erişim denetimlerine sahip olduğundan ve hareketsiz iken şifrelemeyle korunduğundan emin olun.
İsteğe bağlı arama aracı: kullanırken OnDemandFunctionCallingyapay zeka modeli ne zaman ve ne aranacaklarını denetler. Arama sorgusu yapay zeka tarafından oluşturulur ve vektör deposu uygulaması tarafından güvenilmeyen giriş olarak kabul edilmelidir.
İzleme günlüğü: Etkinleştirildiğinde LogLevel.Trace , tam arama sorguları ve sonuçları günlüğe kaydedilebilir. Bu veriler PII içerebilir. Redactor Seçeneğini kullanın veya üretimde hassas telemetriyi devre dışı bırakın.

Bu sağlayıcı henüz Python için kullanılamıyor. Kullanım örnekleri için C# sekmesine bakın.

Sonraki Adımlar

Bağlam Sağlayıcılarına genel bakış

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-09