修复长期记忆向量链路:投影入队 + 集合名三侧同源 + 召回按客户过滤

语义召回"恒空"的根因分四层,本提交修掉投递层与读取层(另两层——重试计数
门禁、episode 不投 rebuild 事件——已在前两个提交修复)。

R2 投递层:dispatch_profile_rebuild 只做图投影,没有任何 Milvus 投递,
  长期记忆的向量从未被写入过(实测客户 9001 在 memory_sync_outbox 里 0 行)。
  新增 _enqueue_memory_vector_projection(),在画像重建后投
  MemorySyncOutbox(target_store="milvus")。走事件而不是同步写,是为了拿
  Outbox 的重试/退避/死信,且不把 embedding 的网络等待拖进事务。
  ⚠️ payload 必须带 version(正整数):适配器 _coerce_profile_version 缺它
  直接抛 ValueError(实测踩到,事件立刻 failed)。

R4 读取层:写的集合与读的集合不是同一个 ——
  写(MilvusProfileProjection)用 "user_long_term_memory_v1",
  读(bootstrap.get_vector_memory_adapter)与删(projection_cleanup_service)
  却用 settings.milvus_collection = "jr_memory",而该集合从未被创建。
  ⇒ 召回:MilvusClient 构造不校验集合存在,适配器"构造成功"但每次 search
     抛异常被 VectorMemoryAdapter 吞成 degraded → 召回恒
     degraded_reasons=('milvus_unavailable',)、向量命中恒 0 条;
  ⇒ 清理:jr_memory 不在集合列表 → 走 vector_collection_absent 分支 →
     报清理成功但一个向量都没删,陈旧向量永久留存。
  修法:PROFILE_COLLECTION 成为唯一常量,读/删两侧直接引用它;
  并删除 Settings.milvus_collection 配置项、清掉 .env.example 的
  MILVUS_COLLECTION —— 写侧从来没读过它,一个只在契约一侧生效的配置项
  比没有配置项更危险(Settings 的 extra="ignore" 会让其他环境残留的该
  变量被安全忽略)。

顺带:
- 语义检索把客户过滤下推到 Milvus(filter="customer_id == N")。此前不带
  过滤,别家客户的命中会白占 limit 名额,稀释本客户的召回条数。
- upsert 在 sources 为空时先返回,不再无条件 load_collection ——
  "本来就没有可写内容"不该被记成投递失败(10001/10002 那两条事件即如此
  重试 5 次进死信)。

回归守卫:tests/unit/infrastructure/test_memory_vector_collection_consistency.py
  断言读侧与删侧用的都是 PROFILE_COLLECTION,且被删掉的配置项不得回归。
  这个缺陷能活下来,正是因为两侧单测全绿而接缝无人守。

验证(走生产装配、进程内调用,未重启你正在跑的 API 窗口):
  读侧集合打印 user_long_term_memory_v1(修前为 jr_memory);
  召回 degraded=False / reasons=() / sources 含 milvus,且排序随 query 语义
  变化(投资期限→horizon 0.288 > risk_level 0.201;风险偏好→risk_level 0.287);
  query="进取型" 双通道合并且 vector_score=0.9987;query=None 走 mysql 全量。
  pytest tests/unit tests/contract → 1432 passed, 2 skipped, 1 failed
  (唯一失败是同事正在改的投顾页面,与记忆链路无关)。

文档:docs/演示用/记忆召回恒空-根因与修复-2026-09-14.md(新增,四层根因+证据)、
  docs/37-记忆投影链路实现说明.md(补集合名三侧契约)。
This commit is contained in:
2026-09-14 21:26:03 +08:00
parent 3a1065ca1e
commit 0c642133d4
12 changed files with 515 additions and 11 deletions
+53
View File
@@ -8,6 +8,7 @@ from typing import Any, Protocol, cast
from uuid import uuid4
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.config import Settings, get_settings
from app.core.contracts import AgentRequest, AgentRequestMetadata, AgentResult, RequestContext
@@ -15,6 +16,7 @@ from app.core.errors import AgentError, RecoverableAgentError, RunLeaseLostError
from app.infrastructure.db import SessionFactory
from app.model.audit import InteractionAudit
from app.model.conversation import ConversationMessage
from app.model.memory import MemorySyncOutbox
from app.model.platform import (
AgentRun,
DomainEventOutbox,
@@ -292,6 +294,11 @@ class WorkerRuntime:
if result.degraded:
logger.warning("graph projection degraded customer_id=%s reason=%s",
customer_id, result.reason)
# ★ 向量投影:图投影在上面同步做完了,**向量侧此前完全没做** ——
# 这个方法里只有图投影,没有任何 milvus 投递,后果是长期记忆的向量
# 从未写入过,`memory_recall_service._vector()` 永远搜不到东西
# (实测:`memory_sync_outbox` 里客户 9001 有 0 行)。
self._enqueue_memory_vector_projection(session, int(customer_id))
async def dispatch_handover_queue_ready(payload: dict[str, Any]) -> None:
"""记录转人工队列已就绪;不向客户承诺已接单或处理时限。"""
@@ -631,6 +638,52 @@ class WorkerRuntime:
handled += 1
return handled
@staticmethod
def _enqueue_memory_vector_projection(session: AsyncSession, customer_id: int) -> None:
"""把该客户的长期记忆投递到向量集合 `user_long_term_memory_v1`。
**为什么需要它**:`dispatch_profile_rebuild` 此前只做**图**投影
(`ProfileGraphProjectionService`),**向量侧完全没做** —— 于是长期记忆的向量
从未被写入过,`memory_recall_service._vector()` 永远搜不到任何东西。
实测:客户 9001 的记忆在 09-13、09-14 都更新过,而 `memory_sync_outbox`
里它**一行都没有**(表里仅有的 4 行是 10001/10002 开户测评的画像投影)。
**为什么走事件而不是在这里直接投影**:写向量要跑一次 embedding 网络调用。
放进 outbox 才有重试/退避/死信,也不会把网络等待拖进本事务。
**为什么不调 `ProfileGenerationService.generate()`**:上面
`ProfileAssemblyService.rebuild()` 已经写过 `profile_snapshots`(自带
version / is_current / hash)。两套生成器并行会让每次重建写两条快照、
互相清 `is_current`、版本跳号。这里**只投事件**,不碰快照。
**payload 只带 `customer_id`**:消费侧 `_with_memory_sources` 会回退查
`memory_unit` 里该客户的 active 记忆。语义上成立 —— 长期记忆是**客户级**的,
不是画像版本级的;每条记忆自带 `version`,适配器按 `memory_uuid + version`
做幂等,所以"用的是哪一版"仍然确定。
"""
now = datetime.now(UTC).replace(tzinfo=None)
session.add(MemorySyncOutbox(
event_uuid=str(uuid4()),
aggregate_type="profile",
aggregate_uuid=str(customer_id),
aggregate_version=1,
target_store="milvus",
operation="upsert",
# ⚠️ `version` 不能省:适配器的 `_coerce_profile_version`
# (`milvus_profile_projection.py:140-145`)要求 payload 里
# `profile_version` 或 `version` 是**正整数**,缺失直接抛 `ValueError`
# (实测踩到:只带 customer_id 时第 43 行投影立刻 failed/ValueError)。
# 它只用于日志 —— 真正的幂等靠每条记忆自己的 `version`
# (适配器按 `memory_uuid + version` 去重),所以固定 1 是安全的。
payload={"customer_id": str(customer_id), "version": 1},
status="pending",
retry_count=0,
next_retry_at=None,
last_error=None,
created_at=now,
processed_at=None,
))
async def _with_memory_sources(self, payload: dict[str, Any]) -> dict[str, Any]:
"""保证 payload 带 `memory_sources`;缺失时回退为查询当前有效记忆。