教學:使用 Azure Managed Redis 建置代理記憶體

在本教學中,您將使用 Azure Managed Redis實作 AI 代理程式的記憶體。 代理記憶體並不是 Azure Managed Redis 的獨立受控功能。 這是一種結合 Redis 資料結構、到期政策與向量搜尋的應用程式模式。

這個模式有兩層:

  • 短期或會話記憶體:近期聊天回合、會話狀態、工具輸出、當前計畫,以及自動過期或刪除的檢查點。
  • 長期語意記憶:從互動中擷取的持久事實、偏好、摘要與觀察,並以嵌入與元資料儲存,並透過向量相似度與濾波器檢索。

當您的快取具備所需的 RediSearch/向量搜尋功能時,Azure Managed Redis 支援向量搜尋。 如需更多資訊,請參閱 Azure Managed Redis 中的向量嵌入與向量搜尋。 RediSearch 和 RedisJSON 是 Redis 模組,且在建立 Azure Managed Redis 實例時必須啟用模組。 如需更多資訊,請參閱〈在 Azure Managed Redis 中使用 Redis 模組〉。

Prerequisites

  • 一個 Azure Managed Redis 實例。 如果您需要建立一個,請參閱「快速入門:建立 Azure Managed Redis 實例」。
  • 短期記憶(清單、雜湊、串流)在沒有任何模組的情況下運作。 長期語意記憶需要 RediSearch,它能儲存並搜尋雜湊值或 JSON 文件中的向量,如 Azure 管理式 Redis 向量搜尋與 Redis 向量搜尋概念所述。 這個教學會同時建立兩個圖層,因此你需要 RediSearch 才能完整跟著本教學進行。 如果您以 JSON 文件而不是雜湊資料結構儲存工作階段或記憶體記錄,也請同時啟用 RedisJSON。 模組只能在你建立實例時啟用,之後不能再新增,所以事先決定你需要哪些模組。 請參閱使用 Azure Managed Redis 的 Redis 模組。
  • Python 3.10 或更新版本,包含 redis-entraid、azure-identity、redis 等套件,以及您的嵌入或代理框架 SDK。

Architecture

以下概念架構將揮發性會話上下文與持久語意記憶區分開來。

User request
    |
    v
Agent runtime
    |
    +--> Short-term memory in Azure Managed Redis
    |       - Lists: bounded chat history
    |       - Hashes or JSON: session state, current plan, checkpoints
    |       - Streams: tool events and intermediate outputs
    |       - TTL and trimming on every write
    |
    +--> Long-term semantic memory in Azure Managed Redis
            - Extracted facts, preferences, summaries
            - Embedding vector + tenant/user/session metadata
            - RediSearch vector index
            - KNN search with metadata filters

Redis非常適合代理狀態,因為代理需要快速的記憶體、搜尋與有狀態的工作流程。 Redis AI 代理概念描述了短期記憶、長期記憶、規劃與工具執行,作為代理架構的核心部分。 欲了解更多資訊,請參閱 Redis AI 代理概念。

連接至 Azure Managed Redis

在正式環境中使用 Microsoft Entra ID 驗證與 TLS。 以下範例僅使用佔位符。

import redis
from azure.identity import DefaultAzureCredential
from redis_entraid.cred_provider import create_from_default_azure_credential

credential_provider = create_from_default_azure_credential(
    ("https://redis.azure.com/.default",)
)

redis_client = redis.Redis(
    host="<azure-managed-redis-hostname>",
    port=10000,
    ssl=True,
    decode_responses=False,
    credential_provider=credential_provider,
)

新增短期會話記憶體

短期記憶應該是有界的。 將最近的原始切削資料儲存在清單中,狀態與檢查點則存放在雜湊或 JSON 文件中,工具輸出則儲存在串流中。 每次寫入時套用 TTL 和修剪,讓非活躍的工作階段自動過時。

儲存有上限的聊天記錄

import json
import time

SESSION_TTL_SECONDS = 60 * 60
MAX_RECENT_TURNS = 40

def history_key(tenant_id: str, session_id: str) -> str:
    return f"agent:{tenant_id}:session:{session_id}:history"

def add_turn(tenant_id: str, session_id: str, role: str, content: str) -> None:
    turn = {
        "role": role,
        "content": content,
        "created_at": int(time.time()),
    }
    key = history_key(tenant_id, session_id)

    pipe = redis_client.pipeline()
    pipe.rpush(key, json.dumps(turn))
    pipe.ltrim(key, -MAX_RECENT_TURNS, -1)
    pipe.expire(key, SESSION_TTL_SECONDS)
    pipe.execute()

def load_recent_turns(tenant_id: str, session_id: str) -> list[dict]:
    return [
        json.loads(item)
        for item in redis_client.lrange(history_key(tenant_id, session_id), 0, -1)
    ]

儲存會話狀態、計畫與檢查點

使用雜湊來儲存經常變動的緊湊狀態。 當你需要巢狀計畫或複雜的檢查點結構時,請使用 RedisJSON。 RedisJSON 需要 RedisJSON 模組,且在建立快取時必須啟用此模組。 有關模組的可用性與建立時需求,請參閱 Azure Managed Redis 的 Redis 模組。

def state_key(tenant_id: str, session_id: str) -> str:
    return f"agent:{tenant_id}:session:{session_id}:state"

def save_checkpoint(
    tenant_id: str,
    session_id: str,
    *,
    summary: str,
    current_plan: list[str],
    checkpoint_name: str,
) -> None:
    key = state_key(tenant_id, session_id)
    redis_client.hset(
        key,
        mapping={
            "summary": summary,
            "current_plan": json.dumps(current_plan),
            "checkpoint": checkpoint_name,
            "updated_at": str(int(time.time())),
        },
    )
    redis_client.expire(key, SESSION_TTL_SECONDS)

儲存工具事件與輸出

大型工具輸出將儲存在應用程式儲存空間或有界的 Redis 鍵中,並在串流中只放置參考或摘要。 使用 MAXLEN 時,串流不會無限制地擴大。

def tool_events_key(tenant_id: str, session_id: str) -> str:
    return f"agent:{tenant_id}:session:{session_id}:tool-events"

def record_tool_event(
    tenant_id: str,
    session_id: str,
    tool_name: str,
    status: str,
    output_ref: str,
) -> None:
    key = tool_events_key(tenant_id, session_id)
    redis_client.xadd(
        key,
        {
            "tool": tool_name,
            "status": status,
            "output_ref": output_ref,
            "created_at": str(int(time.time())),
        },
        maxlen=200,
        approximate=True,
    )
    redis_client.expire(key, SESSION_TTL_SECONDS)

加入長期語意記憶

長期記憶只儲存被選定的持久資訊。 不要把每個原始回合都嵌入。 相反地,在萃取步驟後,建議提供簡潔的事實、偏好、摘要或觀察。 以元資料儲存每個記憶,以便檢索時可依租戶、使用者、來源、記憶類型及保留政策進行篩選。

Redis 向量搜尋使用建立在雜湊或 JSON 文件上的次級索引,支援 FLAT 和 HNSW 向量索引,並支援使用元資料篩選器的向量搜尋。 更多資訊請參閱 Redis 向量搜尋概念。 在 Azure Managed Redis 上,向量搜尋需要 RediSearch/向量搜尋功能。 如需更多資訊,請參閱 Azure Managed Redis 向量搜尋。

建立記憶體索引

每個索引使用一個嵌入模型、一個維度與距離指標。 如果您變更嵌入模型,請重建或建立新的索引。

from redis.commands.search.field import NumericField, TagField, TextField, VectorField
from redis.commands.search.index_definition import IndexDefinition, IndexType
from redis.exceptions import ResponseError

INDEX_NAME = "idx:agent_memories"
MEMORY_PREFIX = "agent:memory:"
VECTOR_DIMENSIONS = 1536

def create_memory_index() -> None:
    try:
        redis_client.ft(INDEX_NAME).create_index(
            fields=[
                TagField("tenant_id"),
                TagField("user_id"),
                TagField("memory_type"),
                TextField("text"),
                TextField("source"),
                NumericField("created_at"),
                VectorField(
                    "embedding",
                    "HNSW",
                    {
                        "TYPE": "FLOAT32",
                        "DIM": VECTOR_DIMENSIONS,
                        "DISTANCE_METRIC": "COSINE",
                    },
                ),
            ],
            definition=IndexDefinition(
                prefix=[MEMORY_PREFIX],
                index_type=IndexType.HASH,
            ),
        )
    except ResponseError as ex:
        if "Index already exists" not in str(ex):
            raise

將事實轉入長期記憶

embed和 extract_memories 函式是應用程式專用的佔位符。 提取步驟應只回傳持久且經同意的記憶。 請註明來源,這樣未來的回應才能解釋為何使用某段記憶。

import uuid
import numpy as np

def embed(text: str) -> list[float]:
    return [0.0] * VECTOR_DIMENSIONS  # Replace with your embedding model call.

def extract_memories(transcript: list[dict]) -> list[dict]:
    return []  # Replace with your extraction logic (LLM call or rules).

def vector_bytes(values: list[float]) -> bytes:
    return np.array(values, dtype=np.float32).tobytes()

def store_memory(
    tenant_id: str,
    user_id: str,
    memory_type: str,
    text: str,
    source: str,
    source_turn_ids: list[str],
) -> str:
    memory_id = f"{MEMORY_PREFIX}{tenant_id}:{user_id}:{uuid.uuid4()}"
    created_at = int(time.time())

    redis_client.hset(
        memory_id,
        mapping={
            "tenant_id": tenant_id,
            "user_id": user_id,
            "memory_type": memory_type,
            "text": text,
            "source": source,
            "source_turn_ids": json.dumps(source_turn_ids),
            "created_at": created_at,
            "embedding": vector_bytes(embed(text)),
        },
    )
    return memory_id

為要求擷取記憶

在執行向量相似度之前,請依租戶與使用者進行篩選。 只回傳代理提示所需的欄位。

from redis.commands.search.query import Query

def escape_tag(value: str) -> str:
    return (
        value.replace("\\", "\\\\")
        .replace("{", "\\{")
        .replace("}", "\\}")
        .replace("|", "\\|")
    )

def retrieve_memories(tenant_id: str, user_id: str, user_message: str) -> list[dict]:
    tenant_filter = escape_tag(tenant_id)
    user_filter = escape_tag(user_id)

    query = (
        Query(
            f"(@tenant_id:{{{tenant_filter}}} @user_id:{{{user_filter}}})"
            "=>[KNN 5 @embedding $vector AS score]"
        )
        .sort_by("score")
        .return_fields("text", "memory_type", "source", "created_at", "score")
        .dialect(2)
    )

    results = redis_client.ft(INDEX_NAME).search(
        query,
        query_params={"vector": vector_bytes(embed(user_message))},
    )

    return [
        {
            "text": doc.text,
            "type": doc.memory_type,
            "source": doc.source,
            "score": doc.score,
        }
        for doc in results.docs
    ]

在代理迴圈中使用記憶體

在每個環節中,將工作階段摘要、最近幾輪及相關長期記憶結合。 保持注入的記憶精簡且有歸屬。

async def run_agent_turn(tenant_id: str, user_id: str, session_id: str, message: str):
    recent_turns = load_recent_turns(tenant_id, session_id)
    state = redis_client.hgetall(state_key(tenant_id, session_id))
    memories = retrieve_memories(tenant_id, user_id, message)

    prompt_context = {
        "session_summary": state.get(b"summary", b"").decode("utf-8"),
        "recent_turns": recent_turns,
        "relevant_memories": memories,
    }

    response = await call_agent_model(
        user_message=message,
        context=prompt_context,
    )

    add_turn(tenant_id, session_id, "user", message)
    add_turn(tenant_id, session_id, "assistant", response.text)
    return response

Microsoft Agent Framework 整合說明

Microsoft Agent Framework 支援會話、記憶體、上下文提供者及歷史記錄提供者。 使用工作階段在多次執行之間分享內容。 欲了解更多資訊,請參閱 Agent Framework 記憶體與持久性。

整合 Azure Managed Redis 時,請使用以下對應:

代理框架概念 Azure Managed Redis 模式
Session 使用 TTL 儲存會話範圍的摘要、規劃、檢查點及近期輪次鍵。
歷程提供者 從有界清單或串流載入並儲存最近的訊息。
上下文提供者 在跑前從 RediSearch 擷取長期記憶,跑完跑後擷取/提升新的記憶。
提供者狀態 將每個工作階段的提供者狀態儲存在 AgentSession 中,並使用以租戶、使用者及工作階段 ID 為鍵的 Redis 金鑰。

Agent Framework 的上下文提供者會在每次呼叫前後執行,可在執行前新增上下文,並能在執行後處理資料。 此模式適用於 Redis 記憶體擷取與記憶體推廣。 如需更多資訊及自訂提供者範例,請參閱Agent Framework 上下文提供者。

針對內建整合,Agent Framework 會列出 Python Redis 歷史提供者與 Python Redis 提供者作為預覽記憶體提供者。 整合頁面也列出了透過向量儲存抽象的 .NET Redis 向量儲存連接器,但未列出內建的 .NET Redis 聊天歷史提供者。 有關目前提供者狀態,請參閱 Agent Framework 整合與記憶體 AI 情境提供者。

Important

在 Agent Framework Python 中,請使用 load_messages=True 僅設定一個歷史提供者。 使用額外的歷史提供者 load_messages=False 來進行稽核或評估記錄,避免相同的訊息重複載入。 此指引已在 Agent Framework 上下文提供者中記錄。

設計指引

關注 Guidance
TTL 與有界視窗 在 session 鍵上使用 TTL,每次寫入時修剪 Lists 和 Streams。 只保留近期回合,以維持回應品質。
Summarization 在剪輯前,將較早的對話輪次摘要成會話摘要。 請使用 summary + recent turns + retrieved memories,不要使用完整逐字稿。
轉入長期記憶 僅將穩定的事實、明確的偏好、持久的摘要或高價值的觀察納入長期記憶。 避免將每個助理回應都嵌入其中。
元資料與租戶分離 使用租戶感知的鍵前綴及可篩選的元資料欄位,如 tenant_id、 user_id、 memory_type、 source、 和 created_at。 請務必依租戶與使用者篩選檢索。
刪除與隱私 保留一個金鑰模式或次要查詢,讓你可以刪除使用者的所有會話金鑰和記憶體金鑰。 對不該永久保留的記憶套用保留原則。
來源標註 儲存 source、來源回合 ID、時間戳、信心度及擷取原因,以便對擷取的記憶進行稽核與說明。
反饋迴路 僅從外部使用者輸入及選定的最終助理回應中擷取新記憶。 不要把上下文提供者訊息或擷取的記憶當作新事實重新匯入。
嵌入一致性 每個索引使用一個嵌入模型、向量維度與距離指標。 變更嵌入模型時建立新索引。
承載大小 僅回傳代理程式所需的欄位,例如文字、類型、來源及分數。 保持 K 足夠小以符合模型上下文視窗。

刪除工作階段與使用者記憶體

將刪除功能內建在您的應用程式中。 當工作階段結束或使用者請求刪除時,刪除短期工作階段金鑰。 依租戶與使用者金鑰前綴刪除長期金鑰,或透過維護每位使用者的一組記憶體 ID。

def delete_session(tenant_id: str, session_id: str) -> None:
    redis_client.delete(
        history_key(tenant_id, session_id),
        state_key(tenant_id, session_id),
        tool_events_key(tenant_id, session_id),
    )

def delete_user_memory_ids(memory_ids: list[str]) -> None:
    if memory_ids:
        redis_client.delete(*memory_ids)