@
fix(memory): 修复 Hindsight provider 生命周期的三处缺陷
HindsightProvider 被 build_memory_manager 每轮重新构造,以下三个问题
都源于这个无状态特性未被正确处理:
1. document_id 每轮漂移 —— 原 _reset_retain_batch 用微秒时间戳拼接,
导致同一 thread 的每轮 retain 落到不同文档,文档数随对话轮数线性膨胀。
改为按 thread_id 确定性派生 (thread-{thread_id}),同一 thread 累积成一份。
2. retain_every_n_turns 失效 —— 进程内 _turn_counter 每轮被 initialize
重置,retain_every_n_turns > 1 时永不触发。新增 turn_index 参数贯穿
sync_turn/sync_all,由 MemoryMiddleware 按对话历史 (count_user_turns)
算出并传入;_turn_counter 仅作缺省退路。
3. aiohttp ClientSession 泄漏 —— 缓存的客户端从不 shutdown,且 _run_coro
每次新建事件循环使缓存客户端失效,触发 "Unclosed client session"。
改为客户端即开即关:_run_with_client 在 finally 保证关闭,_client_factory
作为可覆盖的测试注入点。
测试:test_hindsight_provider.py 全量重写 (含 TestDocumentId /
TestRetainEveryNTurnsAcrossRecreation / TestClientLifecycle),
新增 test_memory_message_processing.py,test_memory_manager.py 补
turn_index 透传用例。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@
This commit is contained in:
1 parent
8f88427d4e
commit
dba821a70e
8 files changed
+770
-61
No files matched your search
+11
-2
@@ -153,11 +153,20 @@ class MemoryManager:
|
||||
assistant_content: str,
|
||||
*,
|
||||
thread_id: str = "",
|
||||
turn_index: int | None = None,
|
||||
) -> None:
|
||||
"""把一轮完成的对话同步到所有 provider。"""
|
||||
"""把一轮完成的对话同步到所有 provider。
|
||||
|
||||
``turn_index`` 是当前对话的轮次序号,透传给各 provider 用于轮次节流。
|
||||
"""
|
||||
for provider in self._providers:
|
||||
try:
|
||||
provider.sync_turn(user_content, assistant_content, thread_id=thread_id)
|
||||
provider.sync_turn(
|
||||
user_content,
|
||||
assistant_content,
|
||||
thread_id=thread_id,
|
||||
turn_index=turn_index,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("记忆 provider '%s' sync_turn 失败:%s", provider.name, exc)
|
||||
|
||||
|
||||
+10
@@ -29,6 +29,16 @@ def extract_message_text(message: Any) -> str:
|
||||
return str(content)
|
||||
|
||||
|
||||
def count_user_turns(filtered_messages: list[Any]) -> int:
|
||||
"""统计已过滤消息里的用户轮次数 (= human 消息条数)。
|
||||
|
||||
供 MemoryMiddleware 算出当前轮次序号传给 provider 做轮次节流 ——
|
||||
provider 每轮被重建、无法靠自身计数,必须由这里按对话历史推算。
|
||||
入参应是 :func:`filter_messages_for_memory` 的输出。
|
||||
"""
|
||||
return sum(1 for msg in filtered_messages if getattr(msg, "type", None) == "human")
|
||||
|
||||
|
||||
def filter_messages_for_memory(messages: list[Any]) -> list[Any]:
|
||||
"""Keep only user inputs and final assistant responses for memory updates."""
|
||||
filtered = []
|
||||
|
||||
@@ -117,11 +117,17 @@ class MemoryProvider(ABC):
|
||||
assistant_content: str,
|
||||
*,
|
||||
thread_id: str = "",
|
||||
turn_index: int | None = None,
|
||||
) -> None:
|
||||
"""每轮对话结束后把对话持久化到后端。
|
||||
|
||||
实现应当非阻塞 —— 如果后端有延迟,排队到后台处理而不是直接调用。
|
||||
默认 no-op。
|
||||
|
||||
``turn_index`` 是当前对话的轮次序号 (从 1 开始,由编排层按对话历史算出)。
|
||||
provider 通常被每轮重新构造、无法靠自身计数,需要按轮次节流写入
|
||||
(例如 "每 N 轮 retain 一次") 的实现应当用它而非进程内计数器。
|
||||
缺省 ``None`` 表示调用方未提供。
|
||||
"""
|
||||
|
||||
# ---- LLM 工具 --------------------------------------------------------
|
||||
|
||||
+122
-57
@@ -17,6 +17,21 @@ HTTP 客户端方式接入一个用户自起的 Hindsight Docker 实例 (``local
|
||||
|
||||
召回:``prefetch`` 并发查两个 bank,合并结果。
|
||||
|
||||
document_id 与轮次计数
|
||||
======================
|
||||
本 provider 被 ``build_memory_manager`` 每轮重新构造 —— 是无状态的。因此:
|
||||
- ``document_id`` 由 ``thread_id`` **确定性**派生,同一 thread 的所有轮次 retain
|
||||
都落到同一个 Hindsight 文档,累积而非每轮碎片化成新文档。
|
||||
- ``retain_every_n_turns`` 的轮次判定依赖外部传入的 ``turn_index``
|
||||
(由 ``MemoryMiddleware`` 按对话历史算出);未传时退回进程内 ``_turn_counter``。
|
||||
|
||||
客户端生命周期
|
||||
==============
|
||||
``_run_coro`` 每次操作新建一个事件循环。aiohttp ``ClientSession`` 是
|
||||
loop-bound 的,跨 loop 复用会泄漏并失效。因此本 provider **不缓存客户端** ——
|
||||
每次记忆操作在 :meth:`_run_with_client` 里即开即关,保证 session 在其所属的
|
||||
loop 内被正常关闭。
|
||||
|
||||
降级
|
||||
====
|
||||
``hindsight-client`` 是可选依赖。未安装或未配置 ``api_url`` 时 :meth:`is_available`
|
||||
@@ -90,7 +105,6 @@ class HindsightProvider(MemoryProvider):
|
||||
|
||||
def __init__(self, config: HindsightMemoryConfig | None = None) -> None:
|
||||
self._config = config or HindsightMemoryConfig()
|
||||
self._client: Any = None
|
||||
|
||||
self._user_id: str = ""
|
||||
self._agent_id: str = "default"
|
||||
@@ -129,7 +143,7 @@ class HindsightProvider(MemoryProvider):
|
||||
base_dir: str = "",
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""解析双 bank 名称,准备 retain 批次状态。客户端按需懒创建。"""
|
||||
"""解析双 bank 名称,准备 retain 批次状态。客户端每次操作即开即关。"""
|
||||
self._user_id = user_id or "default"
|
||||
self._agent_id = (agent_id or "default").lower()
|
||||
self._thread_id = thread_id or ""
|
||||
@@ -154,41 +168,63 @@ class HindsightProvider(MemoryProvider):
|
||||
return name.strip("-") or "deerflow"
|
||||
|
||||
def _reset_retain_batch(self) -> None:
|
||||
"""重置 retain 批次状态 (新的 document_id + 轮次清零)。"""
|
||||
ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
|
||||
self._document_id = f"{self._thread_id or 'thread'}-{ts}"
|
||||
"""重置 retain 批次状态。
|
||||
|
||||
``document_id`` 由 ``thread_id`` **确定性**派生 —— provider 虽然被每轮
|
||||
重新构造,同一 thread 的所有轮次仍落到同一个 Hindsight 文档,累积成一份
|
||||
而不是碎片化成一轮一个文档。无 thread 时 (例如 memory 工具镜像) 用统一
|
||||
的兜底 id。轮次计数清零,仅作为 ``turn_index`` 缺失时的退路。
|
||||
"""
|
||||
self._document_id = f"thread-{self._thread_id}" if self._thread_id else "thread-default"
|
||||
self._turn_counter = 0
|
||||
|
||||
def _get_client(self) -> Any:
|
||||
"""懒创建并缓存 Hindsight HTTP 客户端。"""
|
||||
if self._client is None:
|
||||
from hindsight_client import Hindsight
|
||||
|
||||
kwargs: dict[str, Any] = {
|
||||
"base_url": self._config.api_url,
|
||||
"timeout": 30.0,
|
||||
}
|
||||
if self._config.api_key:
|
||||
kwargs["api_key"] = self._config.api_key
|
||||
self._client = Hindsight(**kwargs)
|
||||
return self._client
|
||||
|
||||
def shutdown(self) -> None:
|
||||
"""关闭客户端 (如果客户端暴露了 close)。"""
|
||||
client = self._client
|
||||
self._client = None
|
||||
if client is None:
|
||||
return
|
||||
"""无需清理 —— 客户端在每次操作内即开即关,不缓存。"""
|
||||
|
||||
# ---- 客户端生命周期 --------------------------------------------------
|
||||
|
||||
def _client_factory(self) -> Any:
|
||||
"""创建一个新的 Hindsight HTTP 客户端。
|
||||
|
||||
每次记忆操作都新建一个、用完即关,**不缓存** —— aiohttp ClientSession
|
||||
是 loop-bound 的,而 ``_run_coro`` 每次新建事件循环。测试可覆盖本方法
|
||||
注入 fake 客户端。
|
||||
"""
|
||||
from hindsight_client import Hindsight
|
||||
|
||||
kwargs: dict[str, Any] = {
|
||||
"base_url": self._config.api_url,
|
||||
"timeout": 30.0,
|
||||
}
|
||||
if self._config.api_key:
|
||||
kwargs["api_key"] = self._config.api_key
|
||||
return Hindsight(**kwargs)
|
||||
|
||||
@staticmethod
|
||||
async def _aclose_client(client: Any) -> None:
|
||||
"""关闭客户端 (兼容暴露 ``aclose`` 或 ``close`` 的实现)。"""
|
||||
close = getattr(client, "aclose", None) or getattr(client, "close", None)
|
||||
if close is None:
|
||||
return
|
||||
try:
|
||||
result = close()
|
||||
if asyncio.iscoroutine(result):
|
||||
_run_coro(result, timeout=10)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
await result
|
||||
except Exception as exc: # noqa: BLE001 - 关闭失败不影响结果
|
||||
logger.debug("Hindsight 客户端关闭失败:%s", exc)
|
||||
|
||||
async def _run_with_client(self, op: Any) -> Any:
|
||||
"""在当前事件循环内创建客户端、执行 ``op(client)``、保证关闭客户端。
|
||||
|
||||
``op`` 是一个接收 client、返回 awaitable 的协程函数。无论成功、异常还是
|
||||
被取消 (超时),``finally`` 都会关闭客户端 —— 杜绝 ``Unclosed client session``。
|
||||
"""
|
||||
client = self._client_factory()
|
||||
try:
|
||||
return await op(client)
|
||||
finally:
|
||||
await self._aclose_client(client)
|
||||
|
||||
# ---- 系统提示词块 -----------------------------------------------------
|
||||
|
||||
def system_prompt_block(self) -> str:
|
||||
@@ -226,13 +262,11 @@ class HindsightProvider(MemoryProvider):
|
||||
query = query[: self._config.recall_max_input_chars]
|
||||
|
||||
try:
|
||||
user_results = self._recall_bank(self._user_bank, query)
|
||||
work_results = self._recall_bank(self._work_bank, query)
|
||||
merged = self._recall_both(query)
|
||||
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
|
||||
logger.debug("Hindsight 召回失败 (非致命):%s", exc)
|
||||
return ""
|
||||
|
||||
merged = self._merge_results(user_results, work_results)
|
||||
if not merged:
|
||||
return ""
|
||||
lines = "\n".join(f"- {text}" for text in merged)
|
||||
@@ -242,18 +276,34 @@ class HindsightProvider(MemoryProvider):
|
||||
f"{lines}"
|
||||
)
|
||||
|
||||
def _recall_bank(self, bank_id: str, query: str) -> list[tuple[float, str]]:
|
||||
"""召回单个 bank,返回 ``[(score, text), ...]``。"""
|
||||
client = self._get_client()
|
||||
resp = _run_coro(
|
||||
client.arecall(
|
||||
bank_id=bank_id,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
max_tokens=self._config.recall_max_tokens,
|
||||
),
|
||||
timeout=15,
|
||||
def _recall_both(self, query: str) -> list[str]:
|
||||
"""并发召回 user + work 两个 bank,合并去重。一次操作共用一个客户端。"""
|
||||
|
||||
async def _op(client: Any) -> tuple[Any, Any]:
|
||||
return await asyncio.gather(
|
||||
client.arecall(
|
||||
bank_id=self._user_bank,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
max_tokens=self._config.recall_max_tokens,
|
||||
),
|
||||
client.arecall(
|
||||
bank_id=self._work_bank,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
max_tokens=self._config.recall_max_tokens,
|
||||
),
|
||||
)
|
||||
|
||||
user_resp, work_resp = _run_coro(self._run_with_client(_op), timeout=15)
|
||||
return self._merge_results(
|
||||
self._extract_results(user_resp),
|
||||
self._extract_results(work_resp),
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _extract_results(resp: Any) -> list[tuple[float, str]]:
|
||||
"""从一个 recall 响应里抽出 ``[(score, text), ...]``。"""
|
||||
results = getattr(resp, "results", None) or []
|
||||
out: list[tuple[float, str]] = []
|
||||
for r in results:
|
||||
@@ -285,15 +335,28 @@ class HindsightProvider(MemoryProvider):
|
||||
assistant_content: str,
|
||||
*,
|
||||
thread_id: str = "",
|
||||
turn_index: int | None = None,
|
||||
) -> None:
|
||||
"""自动 retain 一轮对话到 work bank。
|
||||
|
||||
``auto_retain=False`` 时不写。按 ``retain_every_n_turns`` 控制频率。
|
||||
|
||||
轮次判定优先用调用方传入的 ``turn_index`` (由 MemoryMiddleware 按对话历史
|
||||
算出) —— 因为本 provider 每轮被重建、进程内 ``_turn_counter`` 会被重置,
|
||||
单靠它在 ``retain_every_n_turns > 1`` 时会永远不触发。``turn_index`` 缺失
|
||||
时才退回 ``_turn_counter``。
|
||||
"""
|
||||
if not self._config.auto_retain:
|
||||
return
|
||||
self._turn_counter += 1
|
||||
if self._turn_counter % self._config.retain_every_n_turns != 0:
|
||||
|
||||
if turn_index is not None:
|
||||
counter = turn_index
|
||||
else:
|
||||
self._turn_counter += 1
|
||||
counter = self._turn_counter
|
||||
|
||||
every = max(1, self._config.retain_every_n_turns)
|
||||
if counter % every != 0:
|
||||
return
|
||||
|
||||
turn_text = (
|
||||
@@ -330,8 +393,7 @@ class HindsightProvider(MemoryProvider):
|
||||
logger.debug("Hindsight on_memory_write 镜像失败:%s", exc)
|
||||
|
||||
def _retain(self, bank_id: str, content: str, *, kind: str) -> None:
|
||||
"""向某 bank 写入一条记忆。"""
|
||||
client = self._get_client()
|
||||
"""向某 bank 写入一条记忆。客户端即开即关。"""
|
||||
metadata = {
|
||||
"retained_at": _utc_now_iso(),
|
||||
"kind": kind,
|
||||
@@ -340,33 +402,36 @@ class HindsightProvider(MemoryProvider):
|
||||
}
|
||||
if self._thread_id:
|
||||
metadata["thread_id"] = self._thread_id
|
||||
_run_coro(
|
||||
client.aretain(
|
||||
|
||||
async def _op(client: Any) -> Any:
|
||||
return await client.aretain(
|
||||
bank_id=bank_id,
|
||||
content=content,
|
||||
context=self._config.bank_retain_mission or None,
|
||||
metadata=metadata,
|
||||
document_id=self._document_id,
|
||||
retain_async=self._config.retain_async,
|
||||
),
|
||||
timeout=15,
|
||||
)
|
||||
)
|
||||
|
||||
_run_coro(self._run_with_client(_op), timeout=15)
|
||||
|
||||
def reflect(self, query: str, *, use_user_bank: bool = True) -> str:
|
||||
"""对某 bank 做跨记忆综合 (LLM 推理)。供 hindsight_reflect 工具调用。"""
|
||||
bank = self._user_bank if use_user_bank else self._work_bank
|
||||
client = self._get_client()
|
||||
resp = _run_coro(
|
||||
client.areflect(bank_id=bank, query=query, budget=self._config.recall_budget),
|
||||
timeout=30,
|
||||
)
|
||||
|
||||
async def _op(client: Any) -> Any:
|
||||
return await client.areflect(
|
||||
bank_id=bank,
|
||||
query=query,
|
||||
budget=self._config.recall_budget,
|
||||
)
|
||||
|
||||
resp = _run_coro(self._run_with_client(_op), timeout=30)
|
||||
return getattr(resp, "text", "") or ""
|
||||
|
||||
def recall(self, query: str) -> list[str]:
|
||||
"""召回双 bank 并返回文本列表。供 hindsight_recall 工具调用。"""
|
||||
user_results = self._recall_bank(self._user_bank, query)
|
||||
work_results = self._recall_bank(self._work_bank, query)
|
||||
return self._merge_results(user_results, work_results)
|
||||
return self._recall_both(query)
|
||||
|
||||
def retain_to_user_bank(self, content: str) -> None:
|
||||
"""主动写入 user bank。供 hindsight_retain 工具调用。"""
|
||||
|
||||
+11
-2
@@ -27,7 +27,7 @@ from langgraph.config import get_config
|
||||
from langgraph.runtime import Runtime
|
||||
|
||||
from deerflow.agents.memory.manager import build_memory_manager
|
||||
from deerflow.agents.memory.message_processing import filter_messages_for_memory
|
||||
from deerflow.agents.memory.message_processing import count_user_turns, filter_messages_for_memory
|
||||
from deerflow.config.memory_config import get_effective_memory_config, get_memory_config
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
@@ -221,6 +221,10 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
|
||||
if not user_text or not assistant_text:
|
||||
return None
|
||||
|
||||
# 轮次序号按对话历史算出 —— provider 每轮被重建、无法自行计数,
|
||||
# retain_every_n_turns 的节流必须靠这个外部传入的值。
|
||||
turn_index = count_user_turns(filtered_messages)
|
||||
|
||||
thread_id = self._resolve_thread_id(runtime)
|
||||
try:
|
||||
manager = build_memory_manager(
|
||||
@@ -229,7 +233,12 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
|
||||
thread_id=thread_id,
|
||||
config=effective_config,
|
||||
)
|
||||
manager.sync_all(user_text, assistant_text, thread_id=thread_id or "")
|
||||
manager.sync_all(
|
||||
user_text,
|
||||
assistant_text,
|
||||
thread_id=thread_id or "",
|
||||
turn_index=turn_index,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
|
||||
logger.warning("Hindsight retain 失败:%s", exc)
|
||||
|
||||
|
||||
Reference in new issue
Block a user