مشاركة عبر

إنشاء واستخدام الذاكرة في خدمة وكلاء الصاهر (معاينة)

مهم

الذاكرة (المعاينة) في خدمة Foundry Agent وواجهة برمجة تطبيقات Memory Store (المعاينة) مرخصة لك كجزء من اشتراكك في Azure وتخضع للشروط المطبقة على "المعاينات" في شروط منتجات Microsoftوملحق حماية بيانات منتجات وخدمات مايكروسوفت، بالإضافة إلى شروط معاينة خدمات الذكاء الاصطناعي التوليدي في شروط الاستخدام التكميلية لمعاينات Microsoft Azure.

الذاكرة في خدمة وكلاء الصاهر هي حل ذاكرة مدارة وطويلة الأمد. يتيح استمرارية الوكلاء عبر الجلسات والأجهزة وسير العمل. من خلال إنشاء وإدارة مخازن الذاكرة، يمكنك بناء وكلاء يحتفظون بتفضيلات المستخدم، ويحافظون على سجل المحادثات، ويقدمون تجارب شخصية.

تعمل مخازن الذاكرة كتخزين مستمر، تحدد أنواع المعلومات ذات الصلة بكل وكيل. تتحكم في الوصول باستخدام المعاملة scope ، التي تقسم الذاكرة بين المستخدمين لضمان تجارب آمنة ومعزولة.

تشرح هذه المقالة كيفية إنشاء وإدارة واستخدام مخازن الذاكرة. للحصول على معلومات مفاهيمية، انظر الذاكرة في خدمة وكيل المسبك.

دعم الاستخدام

القدرة حزمة تطوير التطوير الخاصة لبايثون حزمة تطوير جافاسكريبت واجهة برمجة تطبيقات REST
إنشاء وتحديث وقائمة وحذف مخازن الذاكرة ✔️ ✔️ ✔️
تحديث وبحث الذكريات ✔️ ✔️ ✔️
ربط الذاكرة بوكيل التوجيه ✔️ ✔️ ✔️

المتطلبات المسبقه

التفويض والتصاريح

نوصي بالتحكم في الوصول القائم على الأدوار لنشر الإنتاج. إذا لم تكن الأدوار ممكنة، تجاوز هذا القسم واستخدم المصادقة القائمة على المفاتيح بدلا من ذلك.

لتكوين الوصول المستند إلى الدور:

  1. سجل الدخول إلى مدخل Azure.
  2. عن مشروعك:
    1. من اللوحة اليسرى، اخترهوية إدارة >الموارد.
    2. استخدم المفتاح لتمكين هوية مدارة معينة من النظام.
  3. بالنسبة للمورد الذي يحتوي على مشروعك:
    1. من الجزء الأيمن، حدد Access control (IAM).
    2. حدد إضافة>Add role assignmen.
    3. قم بتعيين مستخدم Azure الذكاء الاصطناعي لهوية مشروعك المدارة.

تعيين متغيرات البيئة

حدد متغيرات البيئة لنقاط نهاية المشروع وأسماء نشر النموذج:

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"
export MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME="<chat-model-deployment-name>"
export MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME="<embedding-model-deployment-name>"

حدد متغيرات البيئة لنقطة نهاية مشروعك، ونشر النماذج، وإصدار واجهة برمجة التطبيقات، ورمز الوصول:

FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"
MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME="<chat-model-deployment-name>" # For example, gpt-5.2
MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME="<embedding-model-deployment-name>" # For example, text-embedding-3-small
API_VERSION="2025-11-15-preview"

# Get a short-lived access token using Azure CLI
ACCESS_TOKEN="$(az account get-access-token --resource https://ai.azure.com/ --query accessToken -o tsv)"

فهم النطاق

يتحكم المعامل scope في كيفية تقسيم الذاكرة. كل منظار في مخزن الذاكرة يحتفظ بمجموعة معزولة من عناصر الذاكرة. على سبيل المثال، إذا أنشأت وكيل دعم عملاء مع ذاكرة، يجب أن يكون لكل عميل ذاكرته الخاصة.

كمطور، تختار المفتاح المستخدم لتخزين واسترجاع عناصر الذاكرة. يمكنك تمرير قيمة ثابتة، مثل معرف فريد عالمي (UUID) أو معرف مستقر آخر من نظامك.

بدلا من ذلك، عند تحديد {{$userId}} النطاق، يقوم النظام تلقائيا باستخراج معرف المستأجر (TID) ومعرف الكائن (OID) من رأس مصادقة الطلب. يمنح هذا النهج كل مستخدم مصادق قسمه الخاص للذاكرة المعزولة، مما يلغي الحاجة لإدارة المعرفات يدويا.

إنشاء مخزن ذاكرة

أنشئ مخزن ذاكرة مخصص لكل وكيل لوضع حدود واضحة للوصول إلى الذاكرة وتحسينها. عند إنشاء مخزن ذاكرة، حدد نموذج الدردشة ونشر نموذج التضمين الذي يعالج محتوى ذاكرتك.

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
chat_model = os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"]
embedding_model = os.environ["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"]

definition = MemoryStoreDefaultDefinition(
    chat_model=chat_model,
    embedding_model=embedding_model,
    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}")

import { DefaultAzureCredential } from "@azure/identity";
import type {
  MemoryStoreDefaultDefinition,
  MemoryStoreDefaultOptions,
} from "@azure/ai-projects";
import { AIProjectClient } from "@azure/ai-projects";

const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] ||
  "<project endpoint>";
const chatModelDeployment =
  process.env["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"] ||
  "<chat model deployment name>";
const embeddingModelDeployment =
  process.env["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"] ||
  "<embedding model deployment name>";

const memoryStoreName = "my_memory_store";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

const memoryOptions: MemoryStoreDefaultOptions = {
  user_profile_enabled: true,
  chat_summary_enabled: true,
  user_profile_details:
    "Avoid irrelevant or sensitive data, such as age, " +
    "financials, precise location, and credentials",
};

const definition: MemoryStoreDefaultDefinition = {
  kind: "default",
  chat_model: chatModelDeployment,
  embedding_model: embeddingModelDeployment,
  options: memoryOptions,
};

const memoryStore = await project.beta.memoryStores.create(
  memoryStoreName,
  definition,
  {
    description: "Memory store for customer support agent",
  },
);

console.log(
  `Created memory store: ${memoryStore.name} (${memoryStore.id})`,
);

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_memory_store",
    "description": "Memory store for customer support agent",
    "definition": {
      "kind": "default",
      "chat_model": "'"${MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME}"'",
      "embedding_model": "'"${MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME}"'",
      "options": {
        "chat_summary_enabled": true,
        "user_profile_enabled": true,
        "user_profile_details": "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
      }
    }
  }'

نصيحة

مقتطفات الكود في الأقسام المتبقية من هذا المقال تعتمد على العميل والمتغيرات المعرفة في إنشاء مخزن ذاكرة. إذا قمت بتشغيل تلك المقتطفات بشكل مستقل، أدرج كود الاستيراد وتهيئة العميل من هذا القسم.

تخصيص الذاكرة

خصص المعلومات التي يخزنها الوكيل للحفاظ على كفاءة الذاكرة، وملائمتها، واحترامها للخصوصية. استخدم المعلمة user_profile_details لتحديد أنواع البيانات التي تعتبر حاسمة لوظيفة الوكيل.

على سبيل المثال، قم بتعيين user_profile_details "تفضيل شركة الطيران والقيود الغذائية" لوكيل السفر. يساعد هذا النهج المركز نظام الذاكرة على معرفة التفاصيل التي يجب استخراجها وتلخيصها والالتزام بها في الذاكرة طويلة الأمد.

يمكنك أيضا استخدام هذا المعامل لاستبعاد أنواع معينة من البيانات، مما يحافظ على رشاقة الذاكرة ومتوافقا مع متطلبات الخصوصية. على سبيل المثال، تم ضبطه user_profile_details ل"تجنب البيانات غير ذات الصلة أو الحساسة، مثل العمر، البيانات المالية، الموقع الدقيق، والاعتمادات."

تحديث مخزن الذاكرة

تحديث خصائص مخزن الذاكرة، مثل description أو metadata، لإدارة مخازن الذاكرة بشكل أفضل.

# 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}")

const updatedStore = await project.beta.memoryStores.update(
  memoryStoreName,
  {
    description: "Updated description",
  },
);

console.log(`Updated: ${updatedStore.description}`);

MEMORY_STORE_NAME="my_memory_store"

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/${MEMORY_STORE_NAME}?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description"
  }'

قائمة مخازن الذاكرة

استرجع قائمة بمخازن الذاكرة في مشروعك لإدارة ومراقبة بنية الذاكرة التحتية.

# 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})")

const storeList = project.beta.memoryStores.list();

console.log("Listing all memory stores...");
for await (const store of storeList) {
  console.log(`  - Memory Store: ${store.name} (${store.id})`);
}

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

استخدم الذكريات عبر أداة وكيل

بعد إنشاء مخزن الذاكرة، يمكنك ربط أداة البحث بالذاكرة بوكيل المطالبات. تمكن هذه الأداة الوكيل من القراءة من مخزن ذاكرتك والكتابة إليه أثناء المحادثات. قم بتكوين الأداة مع الطريقة المناسبة scope وللتحكم update_delay في كيفية وموعد تحديث الذكريات.

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=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
        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})")

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

const agent = await project.agents.createVersion(
  "memory-search-agent",
  {
    kind: "prompt",
    model: chatModelDeployment,
    instructions:
      "You are a helpful assistant that retrieves relevant " +
      "information from the user's memory store to answer their questions.",
    tools: [
      {
        type: "memory_search_preview",
        memory_store_name: memoryStoreName,
        scope: scope,
        update_delay: 1,
      },
    ],
  },
);

console.log(
  `Created agent with memory search tool, agent ID: ${agent.id}, ` +
    `name: ${agent.name}, version: ${agent.version}`,
);

# Note: The agents API uses api-version=v1, which differs from the memory store API version
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/agents?api-version=v1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyAgent",
    "definition": {
        "kind": "prompt",
        "model": "gpt-5.2",
        "instructions": "You are a helpful assistant that answers general questions",
        "tools": [
            {
              "type": "memory_search_preview",
              "memory_store_name": "my_memory_store",
              "scope": "user_123",
              "update_delay": 1
            }
        ]
    }
}'

إنشاء محادثة

يمكنك الآن إنشاء محادثات وطلب ردود الوكلاء. في بداية كل محادثة، يتم حقن ذكريات ثابتة بحيث يكون للوكيل سياق فوري ومستمر. يتم استرجاع الذكريات السياقية في كل دور بناء على أحدث الرسائل التي تهدف إلى كل رد.

بعد كل رد وكيل، تتصل update_memoriesالخدمة داخليا ب . ومع ذلك، فإن الكتابة الفعلية على الذاكرة طويلة الأمد يتم تثبيتها بواسطة update_delay الإعداد. يتم جدولة التحديث ولا يكتمل إلا بعد فترة عدم النشاط المكونة.

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}")

import { setTimeout } from "timers/promises";

const openaiClient = project.getOpenAIClient();

// Create a conversation with the agent with memory tool enabled
const conversation = await openaiClient.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);

// Create an agent response to initial user message
const response = await openaiClient.responses.create(
  {
    conversation: conversation.id,
    input: "I prefer dark roast coffee",
  },
  {
    body: {
      agent: { name: agent.name, type: "agent_reference" },
    },
  },
);

console.log(`Response output: ${response.output_text}`);

// After inactivity, memories are extracted and stored
console.log("Waiting for memories to be stored...");
await setTimeout(65_000);

// Create a new conversation to demonstrate cross-session recall
const newConversation = await openaiClient.conversations.create();
console.log(`Created new conversation (id: ${newConversation.id})`);

// Create an agent response with stored memories
const newResponse = await openaiClient.responses.create(
  {
    conversation: newConversation.id,
    input: "Please order my usual coffee",
  },
  {
    body: {
      agent: { name: agent.name, type: "agent_reference" },
    },
  },
);

console.log(`Response output: ${newResponse.output_text}`);

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/conversations" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{}'

# Copy the "id" field from the previous response
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "I prefer dark roast coffee",
      "conversation": "{conversation-id}",
      "agent_reference": {
        "type": "agent_reference",
        "name": "MyAgent"
      }
    }'

استخدم الذكريات عبر واجهات برمجة التطبيقات

يمكنك التفاعل مع مخزن الذاكرة مباشرة باستخدام واجهات برمجة تطبيقات مخزن الذاكرة. ابدأ بإضافة ذكريات من محتوى المحادثة إلى مخزن الذاكرة، ثم ابحث عن الذكريات ذات الصلة لتوفير سياق لتفاعلات الوكلاء.

إضافة الذكريات إلى مخزن الذاكرة

أضف الذكريات عن طريق توفير محتوى المحادثة إلى مخزن الذكريات. يقوم النظام بمعالجة البيانات مسبقا ومعالجتها لاحقا، بما في ذلك استخراج الذاكرة وتجميعها، لتحسين ذاكرة الوكيل. قد تستغرق هذه العملية الطويلة حوالي دقيقة واحدة.

قرر كيفية تقسيم الذاكرة عبر المستخدمين من خلال تحديد المعاملة scope . يمكنك توسيع نطاق الذاكرة لمستخدم نهائي محدد، أو فريق، أو معرف آخر.

يمكنك تحديث مخزن الذاكرة بمحتوى من عدة أدوار للمحادثة، أو تحديثه بعد كل دور وتحديثات سلسلة باستخدام معرف عملية التحديث السابق.

# 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}"
    )

const scope = "user_123";

const userMessage: Record<string, unknown> = {
  type: "message",
  role: "user",
  content: [
    {
      type: "input_text",
      text: "I prefer dark roast coffee and usually drink it in the morning",
    },
  ],
};

console.log("\nSubmitting memory update request...");
const updatePoller = project.beta.memoryStores.updateMemories(
  memoryStoreName,
  scope,
  {
    items: [userMessage],
    updateDelayInSecs: 0,
  },
);

const updateResult = await updatePoller.pollUntilDone();
console.log(
  `Updated with ${updateResult.memory_operations.length} ` +
    `memory operation(s)`,
);
for (const operation of updateResult.memory_operations) {
  console.log(
    `  - Operation: ${operation.kind}, ` +
      `Memory ID: ${operation.memory_item.memory_id}, ` +
      `Content: ${operation.memory_item.content}`,
  );
}

// Extend the previous update with another message
const newMessage = {
  role: "user",
  content: "I also like cappuccinos in the afternoon",
  type: "message",
};

const newUpdatePoller = project.beta.memoryStores.updateMemories(
  memoryStoreName,
  scope,
  {
    items: [newMessage],
    updateDelayInSecs: 0,
  },
);

const newUpdateResult = await newUpdatePoller.pollUntilDone();
console.log(
  `Updated with ${newUpdateResult.memory_operations.length} ` +
    `memory operation(s)`,
);
for (const operation of newUpdateResult.memory_operations) {
  console.log(
    `  - Operation: ${operation.kind}, ` +
      `Memory ID: ${operation.memory_item.memory_id}, ` +
      `Content: ${operation.memory_item.content}`,
  );
}

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:update_memories?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123",
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "I prefer dark roast coffee and usually drink it in the morning"
          }
        ]
      }
    ],
    "update_delay": 0
  }'

# Get add memory status by polling the update_id
# Use the "update_id" from previous response
UPDATE_ID=<your_update_id>
curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/updates/${UPDATE_ID}?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

ابحث عن الذكريات في مخزن الذكريات

ابحث في الذكريات لاسترجاع السياق المناسب لتفاعلات الوكلاء. حدد اسم مخزن الذاكرة والنطاق لتضييق نطاق البحث.

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}")

const queryMessage: Record<string, unknown> = {
  type: "message",
  role: "user",
  content: [
    { type: "input_text", text: "What are my coffee preferences?" },
  ],
};

console.log("\nSearching memories for stored preferences...");
const searchResponse =
  await project.beta.memoryStores.searchMemories(
    memoryStoreName,
    scope,
    {
      items: [queryMessage],
      options: { max_memories: 5 },
    },
  );

console.log(`Found ${searchResponse.memories.length} memory item(s)`);
for (const memory of searchResponse.memories) {
  console.log(
    `  - Memory ID: ${memory.memory_item.memory_id}, ` +
      `Content: ${memory.memory_item.content}`,
  );
}

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:search_memories?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123",
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What are my coffee preferences?"
          }
        ]
      }
    ],
    "options": {
      "max_memories": 5
    }
  }'

استرجاع الذكريات الثابتة أو السياقية

غالبا لا يمكن استرجاع ذكريات ملف المستخدم بناء على التشابه الدلالي مع رسالة المستخدم. نوصي بأن تضخ ذكريات ثابتة في بداية كل محادثة وتستخدم الذكريات السياقية لتوليد استجابة كل وكيل.

  • لاسترجاع الذكريات الثابتة، اتصل search_memories ب scope "لكن بدون items أو previous_search_id". هذا يعيد ذكريات ملف المستخدم المرتبط بالنصاب.

  • لاسترجاع الذكريات السياقية، اتصل search_memories بتعيين items على أحدث الرسائل. يمكن أن يعيد هذا كل من ملفات تعريف المستخدم وذكريات ملخص الدردشة الأكثر صلة بالعناصر المعنية.

لمزيد من المعلومات حول ملفات تعريف المستخدم وذكريات ملخص الدردشة، راجع أنواع الذاكرة.

حذف الذكريات

تحذير

قبل أن تحذف ذاكرة مخزنة، ضع في اعتبارك تأثيره على الوكلاء التابعين. قد يفقد الوكلاء الذين لديهم مخازن ذاكرة متصلة الوصول إلى السياق التاريخي.

يتم تنظيم الذكريات حسب النطاق داخل مخزن الذاكرة. يمكنك حذف الذكريات الخاصة بنطاق معين لإزالة بيانات خاصة بالمستخدم، أو يمكنك حذف كامل مخزن الذاكرة لإزالة جميع الذكريات عبر جميع النطاقات.

حذف الذكريات حسب النطاق

إزالة جميع الذكريات المرتبطة بنطاق مستخدم أو مجموعة معين مع الحفاظ على هيكل مخزن الذاكرة. استخدم هذه العملية للتعامل مع طلبات حذف بيانات المستخدم أو إعادة ضبط الذاكرة لمستخدمين محددين.

# 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")

console.log("\nDeleting memories for scope...");
await project.beta.memoryStores.deleteScope(memoryStoreName, scope);

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:delete_scope?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123"
  }'

حذف مخزن الذاكرة

قم بإزالة مخزن الذاكرة بالكامل وجميع الذكريات المرتبطة عبر جميع النطاقات. هذه العملية لا رجعة فيها.

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

console.log("Deleting memory store...");
await project.beta.memoryStores.delete(memoryStoreName);

curl -X DELETE "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

أفضل الممارسات

  • تنفيذ ضوابط وصول لكل مستخدم: تجنب منح الوكلاء إمكانية الوصول إلى الذكريات المشتركة بين جميع المستخدمين. استخدم الخاصية scope لتقسيم مخزن الذاكرة حسب المستخدم. عندما تشارك scope بين المستخدمين، استخدم user_profile_details توجيه نظام الذاكرة بعدم تخزين المعلومات الشخصية.

  • تعيين النطاق إلى مستخدم مصادق عليه: عند تحديد النطاق في أداة البحث عن الذاكرة، قم بتعيين scope={{$userId}} المستخدم من رمز المصادقة ({tid}_{oid}). هذا يضمن أن عمليات البحث في الذاكرة تستهدف المستخدم الصحيح تلقائيا.

  • تقليل وحماية البيانات الحساسة: خزن فقط ما هو ضروري لحالتك. إذا كان عليك تخزين بيانات حساسة، مثل البيانات الشخصية، أو البيانات الصحية، أو المدخلات التجارية السرية، قم بحذف أو حذف محتوى آخر يمكن استخدامه لتتبع شخص ما.

  • ادعم الخصوصية والامتثال: توفير شفافية للمستخدمين، بما في ذلك خيارات الوصول إلى بياناتهم وحذفها. سجل جميع الحذف في سجل تدقيق واضح في التلاعب. تأكد من التزام النظام بمتطلبات الامتثال المحلية والمعايير التنظيمية.

  • تقسيم البيانات وعزل الذاكرة: في أنظمة الوكلاء المتعددين، يتم تقسيم الذاكرة بشكل منطقي وتشغيلي. السماح للعملاء بتحديد وعزل وفحص وحذف بصمة ذاكرتهم الخاصة.

  • استخدام ذاكرة المراقبة: تتبع استخدام الرموز وعمليات الذاكرة لفهم التكاليف وتحسين الأداء.

استكشاف الأخطاء وإصلاحها

مشكلة السبب الحل
تفشل الطلبات بسبب خطأ في المصادقة أو التفويض. هويتك أو هوية إدارة المشروع لا تحتوي على الأدوار المطلوبة. تحقق من الأدوار في التفويض والأصوات. بالنسبة لمكالمات REST، قم بإنشاء رمز وصول جديد وأعد المحاولة.
الذكريات لا تظهر بعد المحادثة. تحديثات الذاكرة يتم إلغاء الارتداد أو المعالجة حتى الآن. زد وقت الانتظار أو اتصل بواجهة برمجة تطبيقات التحديث مع update_delay تعيين ل 0 لتفعيل المعالجة فورا.
البحث في الذاكرة لا يعطي أي نتائج. scope القيمة لا تتطابق مع النطاق المستخدم عند تخزين الذكريات. استخدم نفس النطاق للتحديث والبحث. إذا قمت بتعيين النطاق للمستخدمين، استخدم معرف مستخدم مستقر.
استجابة الوكيل لا تستخدم الذاكرة المخزنة. الوكيل غير مهيأ باستخدام أداة البحث عن الذاكرة، أو أن اسم مخزن الذاكرة غير صحيح. تأكد من أن تعريف الوكيل يتضمن الأداة memory_search_preview ويشير إلى اسم مخزن الذاكرة الصحيح.

المحتوى ذو الصلة

  • Last updated on