Aracılığıyla paylaş

Foundry Agent Service'te bellek oluşturma ve kullanma (önizleme)

Önemli

Foundry Agent Hizmeti'ndeki bellek (önizleme) ve Bellek Deposu API'sinin (önizleme) lisansı Size Azure aboneliğinizin bir parçası olarak verilir ve Microsoft Ürün Koşulları ve Microsoft Ürün ve Hizmetler Veri Koruma Eki'ndeki "Önizlemeler" için geçerli koşulların yanı sıra Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları'ndaki Microsoft Generative AI Services Önizlemeleri koşullarına tabidir.

Foundry Aracısı Hizmeti'ndeki bellek, yönetilen, uzun vadeli bir bellek çözümüdür. Oturumlar, cihazlar ve iş akışları arasında aracı sürekliliğini mümkün kılar. Bellek depoları oluşturup yöneterek, kullanıcı tercihlerini koruyan, konuşma geçmişini koruyan ve kişiselleştirilmiş deneyimler sunan aracılar oluşturabilirsiniz.

Bellek depoları kalıcı depolama görevi görür ve her aracıyla ilgili bilgi türlerini tanımlar. Güvenli ve yalıtılmış deneyimler sağlamak için kullanıcılar arasında belleği bölümleyen parametresini kullanarak scope erişimi denetleyebilirsiniz.

Bu makalede bellek depolarını oluşturma, yönetme ve kullanma işlemleri açıklanmaktadır. Kavramsal bilgi için bkz Döküm Aracı Hizmeti'nde Bellek.

Kullanım desteği

Kapasite Python SDK'sı REST API
Bellek depolarını oluşturma, güncelleştirme, listeleme ve silme ✔️ ✔️
Bellekleri güncelleştirme ve arama ✔️ ✔️
İstem aracısına bellek ekleme ✔️ ✔️

Önkoşullar

Yetkilendirme ve izinler

Üretim dağıtımları için rol tabanlı erişim denetimi öneririz. Roller uygun değilse, bu bölümü atlayın ve bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Rol tabanlı erişimi yapılandırmak için:

  1. Azure portalınaoturum açın.
  2. Projenizde:
    1. Sol bölmeden Kaynak Yönetimi>Kimliği'ni seçin.
    2. Sistem tarafından atanan yönetilen kimliği etkinleştirmek için anahtarı kullanın.
  3. Projenizi içeren kaynakta:
    1. Sol bölmeden Erişim denetimi (IAM) öğesini seçin.
    2. Ekle>Rol ataması ekle’yi seçin.
    3. Azure AI Kullanıcısını projenizin yönetilen kimliğine atayın.

Proje uç noktasını ayarlama

Bu makaledeki Python örnekleri için proje uç noktanız için bir ortam değişkeni ayarlayın:

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

$env:FOUNDRY_PROJECT_ENDPOINT = "https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

Kapsamı anlama

parametresi, scope belleğin nasıl bölümlendiğini denetler. Bellek deposundaki her kapsam, yalıtılmış bir bellek öğeleri koleksiyonu tutar. Örneğin, belleği olan bir müşteri destek aracısı oluşturursanız, her müşterinin kendi ayrı belleği olmalıdır.

Geliştirici olarak, bellek öğelerini depolamak ve almak için kullanılan anahtarı seçersiniz. Sisteminizden evrensel olarak benzersiz tanımlayıcı (UUID) veya başka bir kararlı tanımlayıcı gibi statik bir değer geçirebilirsiniz.

Alternatif olarak, kapsamı {{$userId}} olarak belirttiğinizde, sistem istek kimlik doğrulaması üst bilgisinden kiracı kimliğini (TID) ve nesne kimliğini (OID) otomatik olarak ayıklar. Bu yaklaşım kimliği doğrulanmış her kullanıcıya kendi yalıtılmış bellek bölümünü verir ve tanımlayıcıları el ile yönetme gereksinimini ortadan kaldırır.

Bellek deposu oluşturma

Bellek erişimi ve iyileştirme için net sınırlar oluşturmak üzere her aracı için ayrılmış bir bellek deposu oluşturun. Bellek deposu oluşturduğunuzda, bellek içeriğinizi işleyen sohbet modelini ve ekleme modeli dağıtımlarını belirtin.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

memory_store_name = "my_memory_store"

# Specify memory store options
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
    user_profile_details="Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
)

# Create memory store
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",  # Your chat model deployment name
    embedding_model="text-embedding-3-small",  # Your embedding model deployment name
    options=options
)

memory_store = project_client.beta.memory_stores.create(
    name=memory_store_name,
    definition=definition,
    description="Memory store for customer support agent",
)

print(f"Created memory store: {memory_store.name}")

Belleği özelleştirme

Belleği verimli, ilgili ve gizliliğe saygılı tutmak için aracının hangi bilgileri depolayanı özelleştirin. Ajanın işlevi açısından kritik olan veri türlerini belirtmek için user_profile_details parametresini kullanın.

Örneğin, bir seyahat acentesi için "uçuş operatörü tercihi ve diyet kısıtlamaları"na öncelik vermek üzere ayarlayın user_profile_details . Bu odaklanmış yaklaşım, bellek sisteminin hangi ayrıntıları ayıklayacağını, özetleyeceğini ve uzun süreli belleğe aktaracağını bilmesine yardımcı olur.

Bu parametreyi belirli veri türlerini dışlamak için de kullanabilir, belleğin zayıf ve gizlilik gereksinimleriyle uyumlu olmasını sağlayabilirsiniz. Örneğin, "yaş, finansal bilgiler, kesin konum ve kimlik bilgileri gibi ilgisiz veya hassas verilerden kaçının" olarak ayarlayın user_profile_details .

Bellek depolarını güncelleştirme

Bellek depolarını daha iyi yönetmek için description veya metadata gibi bellek deposu özelliklerini güncelleştirin.

# Update memory store properties
updated_store = project_client.beta.memory_stores.update(
    name=memory_store_name,
    description="Updated description"
)

print(f"Updated: {updated_store.description}")

Bellek depolarını listeleme

Bellek altyapınızı yönetmek ve izlemek için projenizdeki bellek depolarının listesini alın.

# List all memory stores
stores_list = list(project_client.beta.memory_stores.list())

print(f"Found {len(stores_list)} memory stores")
for store in stores_list:
    print(f"- {store.name} ({store.description})")

Bellekleri bir aracı yardımcısı ile kullanma

Bellek deposu oluşturduktan sonra, bellek arama aracını bir istem aracısına ekleyebilirsiniz. Bu araç, ajanınızın sohbet esnasında bellek deposuna veri okumasını ve yazmasını sağlar. Aracı, belleklerin nasıl ve ne zaman güncelleneceğini denetlemek için uygun scope ve update_delay ile yapılandırın.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchPreviewTool, PromptAgentDefinition

# Set scope to associate the memories with
# You can also use "{{$userId}}" to take the TID and OID of the request authentication header
scope = "user_123"

openai_client = project_client.get_openai_client()

# Create memory search tool
tool = MemorySearchPreviewTool(
    memory_store_name=memory_store_name,
    scope=scope,
    update_delay=1,  # Wait 1 second of inactivity before updating memories
    # In a real application, set this to a higher value like 300 (5 minutes, default)
)

# Create a prompt agent with memory search tool
agent = project_client.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5.2",
        instructions="You are a helpful assistant that answers general questions",
        tools=[tool],
    )
)

print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

Konuşma oluşturma

Artık konuşmalar oluşturabilir ve aracı yanıtları isteyebilirsiniz. Her konuşmanın başlangıcında statik bellekler eklenir, böylece aracı anında ve kalıcı bir bağlama sahip olur. Bağlamsal bellekler, her yanıtı bilgilendirmek için en son iletilere göre sırayla alınır.

Her bir aracı yanıtından sonra hizmet dahili olarak update_memories öğesini çağırır. Ancak, uzun süreli belleğe gerçek yazma işlemleri ayar tarafından update_delay iptal edilir. Güncelleştirme zamanlanır ve yalnızca yapılandırılan etkinlik dışı kalma süresinden sonra tamamlanır.

import time

# Create a conversation with the agent with memory tool enabled
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Create an agent response to initial user message
response = openai_client.responses.create(
    input="I prefer dark roast coffee",
    conversation=conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {response.output_text}")

# After an inactivity in the conversation, memories will be extracted from the conversation and stored
print("Waiting for memories to be stored...")
time.sleep(65)

# Create a new conversation
new_conversation = openai_client.conversations.create()
print(f"Created new conversation (id: {new_conversation.id})")

# Create an agent response with stored memories
new_response = openai_client.responses.create(
    input="Please order my usual coffee",
    conversation=new_conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {new_response.output_text}")

Bellekleri API'ler aracılığıyla kullanma

Bellek deposu API'lerini kullanarak bir bellek deposuyla doğrudan etkileşim kurabilirsiniz. Konuşma içeriğinden bellek deposuna veri eklemeye başlayın ve ardından etmen etkileşimlerine bağlam sağlamak için ilgili verileri arayın.

Bellek deposuna anı ekleme

Bellek deposuna konuşma içeriği sağlayarak bellek ekleyin. Sistem, aracının belleğini optimize etmek için bellek ayıklama ve birleştirme de dahil olmak üzere veriyi ön işlemden geçirir ve son işlemden geçirir. Bu uzun süre çalışan işlem yaklaşık bir dakika sürebilir.

parametresini belirterek bellekleri kullanıcılar arasında nasıl segmentlere ayırmaya scope karar verin. Belleğin kapsamını belirli bir son kullanıcı, ekip veya başka bir tanımlayıcıyla belirleyebilirsiniz.

Bir bellek deposunu birden çok konuşma döngüsünün içeriğiyle veya her döngüden sonra önceki güncelleştirme işlem kimliğini kullanarak güncellemeleri zincirleyerek güncelleştirebilirsiniz.

# Continue from the previous Python snippets.
# Set scope to associate the memories with
scope = "user_123"

user_message = {
  "role": "user",
  "content": "I prefer dark roast coffee and usually drink it in the morning",
   "type": "message"
}

update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[user_message],  # Pass conversation items that you want to add to memory
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)

# Wait for the update operation to complete, but can also fire and forget
update_result = update_poller.result()
print(f"Updated with {len(update_result.memory_operations)} memory operations")
for operation in update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

# Extend the previous update with another update and more messages
new_message = {
    "role":"user", 
    "content":"I also like cappuccinos in the afternoon", 
    "type":"message"}

new_update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[new_message],
    previous_update_id=update_poller.update_id,  # Extend from previous update ID
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)
new_update_result = new_update_poller.result()
for operation in new_update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

Bellek deposunda hafıza araması yap

Aracı etkileşimleriyle alakalı bağlamı getirmek için hafızaları arayın. Aramayı daraltmak için bellek deposu adını ve kapsamını belirtin.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchOptions

# Search memories by a query
query_message = {"role": "user", "content": "What are my coffee preferences?", "type": "message"}

search_response = project_client.beta.memory_stores.search_memories(
    name=memory_store_name,
    scope=scope,
    items=[query_message],
    options=MemorySearchOptions(max_memories=5)
)
print(f"Found {len(search_response.memories)} memories")
for memory in search_response.memories:
    print(f"  - Memory ID: {memory.memory_item.memory_id}, Content: {memory.memory_item.content}")

Statik veya bağlamsal bellekleri alma

Genellikle kullanıcı profili bellekleri, kullanıcının iletisine anlamsal benzerlik temelinde alınamaz. Her konuşmanın başına sabit bellekler eklemenizi ve her bir aracı yanıtını oluşturmak için bağlamsal bellekler kullanmanızı öneririz.

  • Statik bellekleri almak için search_memories ile, ancak scope veya items olmadan previous_search_id çağırın. Bu, kapsamla ilişkili kullanıcı profili belleklerini döndürür.

  • Bağlamla ilgili anıları almak için search_memories en son iletilere ayarlanmış olarak çağrılmalıdır. Bu, hem kullanıcı profili hem de belirli öğelerle en ilgili sohbet özeti anılarını döndürebilir.

Kullanıcı profili ve sohbet özeti anıları hakkında daha fazla bilgi için bkz. Bellek türleri.

Anıları silme

Uyarı

Bellek depolarını silmeden önce bağımlı aracılar üzerindeki etkiyi göz önünde bulundurun. Ekli bellek depolarına sahip aracılar tarihsel bağlam erişimini kaybedebilir.

Bellekler, bir bellek deposu içinde kapsama göre düzenlenir. Kullanıcıya özgü verileri kaldırmak için belirli bir kapsama ilişkin bellekleri silebilir veya tüm kapsamlardaki tüm bellekleri kaldırmak için bellek deposunun tamamını silebilirsiniz.

Kapsama göre hafızaları sil

Bellek deposu yapısını korurken belirli bir kullanıcı veya grup kapsamıyla ilişkili tüm bellekleri kaldırın. Kullanıcı veri silme isteklerini işlemek veya belirli kullanıcılar için belleği sıfırlamak için bu işlemi kullanın.

# Delete memories for a specific scope
project_client.beta.memory_stores.delete_scope(
    name=memory_store_name,
    scope="user_123"
)

print(f"Deleted memories for scope: user_123")

Bellek depolarını silme

Tüm kapsamlarda bellek deposunun tamamını ve ilişkili tüm bellekleri kaldırın. Bu işlem geri alınamaz.

# Delete the entire memory store
delete_response = project_client.beta.memory_stores.delete(memory_store_name)
print(f"Deleted memory store: {delete_response.deleted}")

En iyi yöntemler

  • Kullanıcı başına erişim denetimleri uygulayın: Aracılara tüm kullanıcılar arasında paylaşılan anılara erişim vermekten kaçının. bellek depoyu scope kullanıcıya göre bölümlendirmek için özelliğini kullanın. Kullanıcılar arasında scope paylaşırken, bellek sistemine kişisel bilgileri depolamaması talimatını vermek için user_profile_details kullanın.

  • Kapsamı kimliği doğrulanmış bir kullanıcıyla eşleyin:Bellek arama aracında kapsam belirttiğinizde, scope={{$userId}} kimlik doğrulama belirtecinden kullanıcıya eş olacak şekilde ayarlayın ({tid}_{oid}). Bu, bellek aramalarının otomatik olarak doğru kullanıcıyı hedeflemesini sağlar.

  • Hassas verileri en aza indir ve koru: Yalnızca kullanım örneğiniz için gerekenleri depolayın. Eğer kişisel veriler, sağlık verileri veya gizli iş bilgileri gibi hassas verileri depolamanız gerekiyorsa, bir kişiye ulaşmak için kullanılabilecek diğer içeriği sansürleyin veya kaldırın.

  • Gizlilik ve uyumluluk desteği: Kullanıcılara verilerine erişme ve verileri silme seçenekleri de dahil olmak üzere saydamlık sağlayın. Tüm silmeleri kurcalamaya karşı korumalı bir denetim kaydına kaydedin. Sistemin yerel uyumluluk gereksinimlerine ve mevzuat standartlarına uydığından emin olun.

  • Verileri segmentlere ayırma ve belleği yalıtma: Çok aracılı sistemlerde belleği mantıksal ve operasyonel olarak segmentlere ayırın. Müşterilerin kendi bellek ayak izlerini tanımlamasına, yalıtmasına, incelemesine ve silmesine izin verin.

  • Bellek kullanımını izleme: Maliyetleri anlamak ve performansı iyileştirmek için belirteç kullanımını ve bellek işlemlerini izleyin.

Sorun giderme

Sorun Nedeni Çözüm
İstekler bir kimlik doğrulaması veya yetkilendirme hatasıyla başarısız olur. Kimliğiniz veya proje tarafından yönetilen kimliğiniz gerekli rollere sahip değil. Yetkilendirme ve izinler bölümünde rolleri doğrulayın. REST çağrıları için yeni bir erişim belirteci oluşturun ve yeniden deneyin.
Anılar konuşmadan sonra görünmez. Bellek güncelleştirmeleri iptal edildi veya hala işleniyor. Bekleme süresini artırın veya işleme hemen başlatmak için update_delay değeri 0 olarak ayarlanmış güncelleştirme API'sini çağırın.
Bellek araması sonuç döndürmez. scope değeri, bellekler depolandığında kullanılan kapsamla eşleşmiyor. Güncelleştirme ve arama için aynı kapsamı kullanın. Kapsamı kullanıcılarla eşlerseniz, kararlı bir kullanıcı tanımlayıcısı kullanın.
Ajan yanıtı sistemin belleğini kullanmaz. Aracı bellek arama aracıyla yapılandırılmamış veya bellek deposu adı yanlış. Aracı tanımının, memory_search aracını içerdiğini ve doğru bellek deposu adına atıfta bulunduğunu onaylayın.

İlgili içerik

  • Last updated on