From d5e813b726724087922147f7dbecce6363473a5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E8=83=9C=E5=AE=87?= <17412268+zzzzz11122222@user.noreply.gitee.com> Date: Sun, 20 Sep 2026 17:53:06 +0800 Subject: [PATCH] =?UTF-8?q?feat(model-gateway)+docs(W19):=20embedding=20?= =?UTF-8?q?=E7=AB=AF=E7=82=B9=E5=94=AF=E4=B8=80=E6=80=A7=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E5=AE=88=E5=8D=AB=20+=20=E4=B8=89=E4=BB=BD=E5=AE=8C=E6=95=B4?= =?UTF-8?q?=E7=89=88/=E6=94=B6=E6=95=9B=E7=89=88=E7=B4=A2=E5=BC=95?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=E8=A1=A5=E6=B3=A8=20+=20=E9=97=A8=E6=A7=9B?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=E6=9B=B4=E6=AD=A3=20+=20D3.7=20=E9=9A=BE?= =?UTF-8?q?=E4=BE=8B=E5=8F=A3=E5=BE=84=E7=BB=9F=E4=B8=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 一、代码（2 文件 + 2 工具脚本注记） * app/service/model_gateway.py：DatabaseModelEndpointResolver.resolve() 加配置守卫 —— required == "embedding" 且 len(matched) > 1 时 logger.warning（只告警、不改行为）。 多个 embedding 端点会让索引向量与查询向量可能来自不同模型（维度同为 1024、不报错）， COSINE 相似度整体失真，表现为"越答越差"的哑故障。顺手删掉重复的 return endpoints（死代码）。 * tests/unit/service/test_model_gateway.py：新增 2 条单测（多端点告警且返回顺序不变 / 单端点静默）。 * tools/configure_embedding_endpoint.py：加「已废弃，勿重跑」标注 —— 它写的是 qwen-embedding / qwen3.7-text-embedding-flash，与现役端点 knowledge-embedding-qwen-v3 / text-embedding-v3 不一致，重跑会凭空多出一个 embedding 端点。 * tools/build_knowledge_chunks.py：删掉与新口径冲突的注释「不泄露档位与门槛」， 改为「registered 的依据是权益明细而非门槛；门槛属公开宣传口径」。 二、文档（8 份；D-1 选乙 + D-3 统一为 18） * D2.4 v1.6 → v1.7：§4.4 + 附录B 更正「门槛金额不再单独构成 registered 的理由」 （public 的 FAQ-0014 已完整给出五档门槛、FAQ-0050 含钻石门槛）； HNW-004—HNW-007 保持 registered，依据收窄为"各层级权益明细"；HNW-* 档位不动（分区键）。 * D3.1 v2.5 → v2.6：§5.3 加索引口径落地注（覆盖 §2.5 决策表 / FR-CS-007 / 排期 T4） + 补「字段表同属初稿」（实库 18 字段全 NOT NULL、doc_id 主键、无 metadata JSON）。 * D3.2 v1.2 → v1.6：§4.1 加同口径注 + 版本位追平（顶栏 v1.1 / doc-meta v1.2 落后于自身记录 v1.5）。 * D2.2 v2.6 → v2.7：§1.4.2 域 B 加注（TopK / 阈值 / 度量 / 集合选择均未变 ⇒ 不影响验收）。 * D3.7：§3 难例口径统一 —— 难例 32 条（改写 8 + 口语 16 + 多轮 4 + 禁忌 4）为定义式总数， M-2b 分母 = 其中带期望证据家族的 18 条；并补正 §3 初稿表格条数（以 cases_46.json 为准）。 * D1.1 v1.8 → v1.9：新增 §28；四处版本位同步；顺带修正两处历史遗留 （D2.4 版本位长期停在 v1.3、D2.2 日期列停在 2026-09-17）。 * D1.6：新增 §4.47（含自我失误留痕）。 * D2.1 v6.33 → v6.34：新增本轮修订要点段。 三、实测门口（本机） * tests/unit/service/test_model_gateway.py：10 passed * pytest -q -p no:cacheprovider（全量，跑前已停 Worker）：1917 passed / 3 skipped / 0 failed * tools/check_authoritative_docs.py：54 文档无编号冲突（exit 0） * _consistency.py：失效锚点 0、交叉引用全 ✅（exit 0） * _fe_boundary_http.py（重建件）：12/12 符合预期 * 服务已重启：/internal/health/ready 三依赖全绿（mysql / redis / milvus） 四、如实留痕（自我失误） 本轮清理临时文件时删除判据过宽，误删 _consistency.py（已原样恢复）、 _legacy_customer_service.py（已按 f72a545 逐字节重建，40,554 字节）、 _fe_boundary_http.py（原件不可恢复，已按既有判据重建并实跑 12/12）与若干历史轮次原始日志。 详见 D1.6 §4.47 五。 --- app/service/model_gateway.py | 14 ++++- tests/unit/service/test_model_gateway.py | 51 +++++++++++++++++ tools/build_knowledge_chunks.py | 11 ++-- tools/configure_embedding_endpoint.py | 10 +++- 客服agent/D2.1-客服Agent执行Todolist.md | 24 +++++++- 客服agent/D2.2-客服Agent需求文档.html | 9 ++- 客服agent/D2.4-客服Agent知识库设计方案.html | 14 +++-- 开发文档/D1.1-文档索引与权威声明.md | 48 +++++++++++----- ...话上下文提取与开工前补充决策-2026-09-17.md | 57 +++++++++++++++++++ .../D3.1-客服Agent需求开发文档与设计方案.html | 9 ++- 开发文档/D3.2-知识库设计方案.html | 9 ++- ...服Agent评测金标集与判分规则-2026-09-17.md | 16 +++--- 12 files changed, 231 insertions(+), 41 deletions(-) diff --git a/app/service/model_gateway.py b/app/service/model_gateway.py index c323d00..0d5634d 100644 --- a/app/service/model_gateway.py +++ b/app/service/model_gateway.py @@ -236,13 +236,25 @@ class DatabaseModelEndpointResolver: task_type, ) return endpoints - return endpoints matched = [ endpoint for endpoint in endpoints if isinstance(endpoint.capabilities, list) and required in endpoint.capabilities ] # `capabilities` 为 NULL/空 的端点绝不会被 `matched` 选中（不能裸奔到错误的网关方法上）； # 但整批都没声明该能力时退回全部端点，避免把这个配置缺口伪装成"没有可用端点"。 + if required == "embedding" and len(matched) > 1: + # 配置守卫：声明朝 `embedding` 能力的 active 端点应**恰好 1 个**。 + # 后端会按顺序只试前 `max(1, max_attempts)`（默认 2）个端点，端点一多就会被截断； + # 更隐蔽的是模型混用——Milvus 集合里向量维度固定 1024，若两个端点背后的模型不同， + # 写入向量与查询向量就不在同一个空间，`COSINE` 相似度会整体失真： + # **不报错，只是越答越差**（这类故障最难定位）。这里只告警、不改行为。 + logger.warning( + "模型端点筛选：active 端点中有 %d 个声明 embedding 能力（%s）；" + "向量化端点应恰好 1 个——多端点会让索引向量与查询向量可能来自不同模型，" + "相似度整体失真且不报错。请停用多余端点或去掉其 embedding 能力声明", + len(matched), + ", ".join(str(getattr(e, "endpoint_code", "?")) for e in matched), + ) return matched or endpoints diff --git a/tests/unit/service/test_model_gateway.py b/tests/unit/service/test_model_gateway.py index 87bd822..14152fd 100644 --- a/tests/unit/service/test_model_gateway.py +++ b/tests/unit/service/test_model_gateway.py @@ -147,3 +147,54 @@ async def test_resolve_skips_endpoints_without_declared_capabilities( agent_type="customer_service", task_type="chat" ) assert [e.endpoint_code for e in resolved] == ["chat-primary"] + + +@pytest.mark.asyncio +async def test_resolve_warns_when_multiple_embedding_endpoints_declared( + monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture +) -> None: + """声明 `embedding` 能力的 active 端点超过一个时必须告警（配置守卫，只告警不改行为）。 + + 为什么要守：Milvus 集合的向量维度是固定的，索引侧与查询侧必须用**同一个**模型。 + 两个 embedding 端点共存时，`ModelDispatchService.embed` 只试前 `max(1, max_attempts)` + （默认 2）个端点，实际用哪个取决于表的行顺序 —— 一旦索引与查询落到不同模型， + `COSINE` 相似度整体失真却**不会报任何错**，表现为“越答越差”的哑故障。 + """ + from app.service import model_gateway + + rows = [ + _endpoint("embedding-primary", ["embedding"]), + _endpoint("embedding-shadow", ["embedding"]), + _endpoint("chat-primary", ["chat"]), + ] + monkeypatch.setattr(model_gateway, "SessionFactory", lambda: _FakeScalarSession(rows)) + + with caplog.at_level("WARNING"): + resolved = await model_gateway.DatabaseModelEndpointResolver().resolve( + agent_type="customer_service", task_type="embedding" + ) + + # 只告警不改行为：仍返回全部声明 embedding 的端点，且顺序与表行顺序一致。 + assert [e.endpoint_code for e in resolved] == ["embedding-primary", "embedding-shadow"] + warnings = [r for r in caplog.records if r.levelname == "WARNING"] + assert warnings, "多 embedding 端点时必须留下 WARNING 痕迹" + assert "embedding-shadow" in warnings[-1].getMessage() + + +@pytest.mark.asyncio +async def test_resolve_is_silent_with_single_embedding_endpoint( + monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture +) -> None: + """恰有一个 embedding 端点（现网配置）时不得产生告警噪音。""" + from app.service import model_gateway + + rows = [_endpoint("embedding-primary", ["embedding"]), _endpoint("chat-primary", ["chat"])] + monkeypatch.setattr(model_gateway, "SessionFactory", lambda: _FakeScalarSession(rows)) + + with caplog.at_level("WARNING"): + resolved = await model_gateway.DatabaseModelEndpointResolver().resolve( + agent_type="customer_service", task_type="embedding" + ) + + assert [e.endpoint_code for e in resolved] == ["embedding-primary"] + assert [r for r in caplog.records if r.levelname == "WARNING"] == [] diff --git a/tools/build_knowledge_chunks.py b/tools/build_knowledge_chunks.py index 643e90b..ebb8a4c 100644 --- a/tools/build_knowledge_chunks.py +++ b/tools/build_knowledge_chunks.py @@ -49,11 +49,14 @@ SOURCES: dict[str, dict[str, str]] = { # 只取「客户分层标准」与「各层级专属权益」两章：家族信托、资产配置流程、客户经理 # 考核指标、隐私应急预案属内部管理内容，客户咨询用不到，不入库。 "product/高净值客户服务规范.md": { - # 档位 = `registered`（**不是** public）：`D2.4` §4.4「高净值客户服务规范 · - # 分层权益与增值服务 → registered」+ 附录B `v1.3` 裁定「高净值服务分层门槛 - # （金卡 50 万+ / 白金 200 万+ / 钻石 600 万+ / 私行 1000 万+）保持 `registered`」 + # 档位 = `registered`（**不是** public）：依据是 `D2.4` §4.4「高净值客户服务规范 · + # 分层权益与增值服务 → registered」——**依据是「权益明细」，不是「门槛」**。 + # `D2.4` v1.7 已更正（`D-1` 选乙）：**分层体系与门槛属公开宣传口径** —— + # `public` 的 `FAQ-0014` 已完整给出五档门槛、`FAQ-0050` 含「600 万元以上钻石客户」， + # 故门槛**不构成** `registered` 的理由（附录B `v1.3` 裁定的「理由②」已作废）。 # ⇒ 故 `HNW-004`—`HNW-007` 对访客不可见，访客问「高净值客户有什么权益」走 - # 「引导登录」，**不泄露档位与门槛**。改回 public 前先读那两处裁定。 + # 「引导登录」。改档位前先读 `D2.4` §4.4 与附录B —— `visibility` 是**分区键**， + # 改档位须**重建集合**，不是改一个字段那么简单。 "collection": "fin_product_collection", "prefix": "HNW", "visibility": "registered", "version": "V2.1", "effective_date": "", "doc_no": "", "tags": "高净值,VIP分级,层级权益,费率优惠", diff --git a/tools/configure_embedding_endpoint.py b/tools/configure_embedding_endpoint.py index 28094a9..19fd491 100644 --- a/tools/configure_embedding_endpoint.py +++ b/tools/configure_embedding_endpoint.py @@ -1,4 +1,12 @@ -"""配置并激活 embedding 模型端点（走管理 API，不直接写库）。 +"""⚠️ 已废弃，请勿重跑；保留仅作历史参考。 + +现役 embedding 端点是 `knowledge-embedding-qwen-v3` / `text-embedding-v3`（实库 `id=1`）， +而本脚本写的是 `qwen-embedding` / `qwen3.7-text-embedding-flash` —— 两者不一致。 +**重跑会在 active 端点里凭空多出一个声明 `embedding` 的端点**：索引向量与查询向量可能 +来自不同模型，Milvus 的 `COSINE` 相似度会整体失真且**不报错**（`DatabaseModelEndpointResolver` +有"embedding 端点应恰好 1 个"的 WARNING 守卫，但那只是留痕，故障已经发生）。 + +配置并激活 embedding 模型端点（走管理 API，不直接写库）。 为什么走 API 而不是 INSERT：端点配置要经过 draft → approved → active 状态机并留下 `interaction_audit`。直接写库会绕过审核与审计，而且 `DatabaseModelGateway` 只认 diff --git a/客服agent/D2.1-客服Agent执行Todolist.md b/客服agent/D2.1-客服Agent执行Todolist.md index 35e8fe1..956cd46 100644 --- a/客服agent/D2.1-客服Agent执行Todolist.md +++ b/客服agent/D2.1-客服Agent执行Todolist.md @@ -1,4 +1,4 @@ -# 客服 Agent 执行 Todolist（执行看板 · v6.33） +# 客服 Agent 执行 Todolist（执行看板 · v6.34） > **体系编号**：`D2.1`　·　域：二、对外交付　·　编号体系见 `D1.1` §4.0 @@ -46,6 +46,28 @@ **看板状态更新**：`F-3` → **✅ 已落地**（新增 4 条单测）。批次 H 剩余：`H-05`。新增待办：**三项安全路由缺口收口**（`G-01` 优先，建议排在 `H-05` 前）。 +## v6.34 本轮修订要点（2026-09-20 · 三份完整版/收敛版索引口径补注 + `embedding` 端点唯一性守卫 + 门槛口径更正） + +> **触发**：用户「按照你建议的来」（承接上轮末尾登记的两项待办：**建议 B** 与 `D3.1` / `D3.2` / `D2.2` 的索引状态更新注）。 +> 完整会话记录见 `D1.6` §4.47；实测证据：实库 `model_endpoint_config` 直查（2 条 active）、Milvus 四集合索引与切片件直查。 + +| # | 修订 | 依据 | +|---|---|---| +| 1 | ✅ **建议 B 落地**：`DatabaseModelEndpointResolver.resolve()` 加「声明 `embedding` 的 active 端点 > 1 即 `logger.warning`」守卫（**只告警不改行为**）+ 删重复 `return`；新增 2 条单测（多端点告警 / 单端点静默） | `D1.6` §4.47 一；`tests\unit\service\test_model_gateway.py` **10 passed** | +| 2 | ✅ **`tools\configure_embedding_endpoint.py` 标注「已废弃，勿重跑」**：它写的 `qwen-embedding` / `qwen3.7-text-embedding-flash` 与现役端点（`knowledge-embedding-qwen-v3` / `text-embedding-v3`）不一致，重跑会凭空多一个 embedding 端点 ⇒ 索引与查询可能不同模型、相似度失真且**不报错** | 实库直查 + 本轮读码 | +| 3 | ✅ **`D3.1` v2.5 → v2.6**：§5.3 加索引口径落地注（覆盖 §2.5 决策表 / `FR-CS-007` / 排期 `T4`）+ 补「字段表同属初稿」（实库 18 字段全 NOT NULL、`doc_id` 主键、无 `metadata` JSON） | Milvus 直查 2026-09-20 | +| 4 | ✅ **`D3.2` v1.2 → v1.6**：§4.1 加同口径注 + **版本位追平**（顶栏 `v1.1` / `doc-meta` `v1.2` 落后于自身修订记录 `v1.5`） | `D1.1` §28 | +| 5 | ✅ **`D2.2` v2.6 → v2.7**：§1.4.2 域 B 加注（TopK / 阈值 / 度量 / 集合选择均未变 ⇒ **不影响验收**） | `D1.1` §28 | +| 6 | ✅ **`D2.4` v1.6 → v1.7（`D-1` 选乙）**：§4.4 与附录B 更正为「**门槛金额不再单独构成 `registered` 的理由**」（`public` 的 `FAQ-0014` 已完整给出五档门槛、`FAQ-0050` 含钻石门槛）；`HNW-004`—`HNW-007` 保持 `registered` 但**依据收窄为权益明细**；`HNW-*` 档位**不动**（分区键须重建集合） | 切片件实查 + `D1.6` §4.47 三 | +| 7 | ✅ **切片脚本自相矛盾注释已删改**：`tools\build_knowledge_chunks.py` 原「不泄露档位与门槛」→ 改为「依据是**权益明细**而非门槛；门槛属公开宣传口径」 | 同上 | +| 8 | ✅ **`D3.7` §3 / §4 / §5 口径统一（`D-3`）**：难例 **32 条**（改写 8 + 口语 16 + 多轮 4 + 禁忌 4）为定义式总数；`M-2b` 分母 = 其中带期望证据家族的 **18** 条；并**补正 §3 初稿表格条数**（以 `cases_46.json` 为准） | `_eval_harness\score.py` + `cases_46.json` 逐条复算 | +| 9 | 📌 **版本位同步**：`D2.2` v2.7 / `D2.4` v1.7 / `D3.1` v2.6 / `D3.2` v1.6；`D1.1` 头部 **v1.8 → v1.9** + 四处版本位同步（含两处历史遗留：`D2.4` 的 `v1.3`、`D2.2` 的日期列） | `D1.1` §28 | + +| 10 | ✅ **真机入参边界复验 12/12**（8 条越界 → 422 `AGENT_INPUT_INVALID`；4 条合法边界 → 202）：`_fe_boundary_http.py`（**重建件**，原件于本轮被误删）—— 证据 `_fe_boundary_http_result.json` | 本轮真机实测 | +| 11 | ⚠️ **自我失误留痕**：本轮清理临时文件时判据过宽，误删 `_consistency.py`（已原样恢复）、`_legacy_customer_service.py`（已按 `f72a545` 逐字节重建，40,554 字节）、`_fe_boundary_http.py`（**原件不可恢复**，已按既有判据重建并实跑 12/12）与若干历史轮次原始日志；结论均在文档表格内，原始输出不可追。教训：按「本轮新建清单」逐个删，禁用通配判据 | `D1.6` §4.47 五 | +**看板状态更新**：`D-1` / `D-3` **✅ 已落地**；**建议 B ✅ 已完成**（原挂「演示后做」）。 +**仍挂起**：`D-2`（同会话重复模糊问句漂移，**只登记不修**、演示避开）；`D-4`（英文问句落 `E5b`，登记为已知边界）。 + ## v6.33 本轮修订要点（2026-09-20 · `D2.4` 索引与语料口径更正 + `D2.9` 手动对话测试用例成文 + 空白消息 500 修复） > **触发**：用户「现在 按照你建议的来 然后再帮我写一份测试用例 我需要自己手动跟agent对话 看看返回信息是否准确」。 diff --git a/客服agent/D2.2-客服Agent需求文档.html b/客服agent/D2.2-客服Agent需求文档.html index 5e3d97b..f0e9a52 100644 --- a/客服agent/D2.2-客服Agent需求文档.html +++ b/客服agent/D2.2-客服Agent需求文档.html @@ -244,7 +244,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
🎧
南方基金 -
客服 Agent 需求文档 v2.6 · 双主体
+
客服 Agent 需求文档 v2.7 · 双主体
@@ -306,7 +306,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
智能服务系统 — 智能客服 Agent 需求文档
- v2.6 · 双主体 · 五出口 · 投顾已恢复 + v2.7 · 双主体 · 五出口 · 投顾已恢复
@@ -322,7 +322,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
文档版本 -v2.6（双主体 · 身份与角色分离 · 五出口智能增强对接 · 投顾模块 2026-09-20 随合并恢复 · P1 画像字段口径更正） +v2.7（双主体 · 身份与角色分离 · 五出口智能增强对接 · 投顾模块 2026-09-20 随合并恢复 · P1 画像字段口径更正 · HNSW/IVF_FLAT 索引口径更正）
文档定位 @@ -415,6 +415,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent, v2.4.12026-09-17品牌全量口径统一：主体由包装占位（XX科技 / 400-XXX-XXXX）与旧名（南方财富 / nanfangwm.com）统一为南方基金（南方基金管理股份有限公司 · 热线 400-889-8899 · 官网 nffund.com）；系统名由「智能财富管家系统」改为「智能服务系统」。 v2.52026-09-17对接「五出口」智能增强架构（依据 D3.6，其 §9 八项决策已裁定）：① FR-CS-003 重写——澄清由「置信度 < 0.6 短路」扩为出口 E1（四类触发条件、一次只问一个问题、同话题上限 2 轮、候选限当前档位可见）；② FR-CS-008 重写——改为分级回退 E5（跨集合回退 → 部分作答 + 引导 → 转人工），并补硬约束回退不得跨档位；③ FR-CS-023 重写——转人工收敛为触发白名单 4 类，删除「连续 2 轮兜底」（兜底是能力不足的表征，不是风险）；④ 新增 §1.4.8 域 H（FR-CS-049—052：证据约束生成 / 计算型回答 / 输出数字一致性校验 / 评测门禁），功能需求 48 → 52 条、功能域 7 → 8；⑤ §1.6.3 修正——public 档删除「产品参数与费率」（与 D6.1.2 §四 判据、T-07 定案及《知识库设计方案》v1.3 §4.2 对齐）；⑥ 新增验收项 AC-13（金标集门禁）；⑦ 档位隔离口径改为集合内分区裁剪——FR-CS-032 / FR-CS-033 重写，取消 over-fetch ×3（与《知识库设计方案》v1.3 §7.2.1 对齐）。 v2.62026-09-20口径更正：P1 不再收录「风险测评结果」（FR-CS-023）。① P1 的括号列表由「持仓 / 收益 / 订单 / 银行卡 / 投诉进度 / 风险测评结果」改为「持仓 / 收益 / 订单 / 银行卡 / 投诉进度等账户与资产明细」，并注明画像类字段除外；② 依据 §1.7 第 21 项「画像问答字段直返」与《D3.1》§3.5/§5「画像问答属客服能力，与持仓查询严格区分」，画像类问法改由受控工具 query_customer_profile 字段级只读作答；③ 补反向守卫——画像词与账户词同句并列时仍走 P1；④ §1.2.1 三类主体表补跨节说明：「客户可见性」≠「Agent 对话读取权限」，后者以 §1.4.5 为准。触发事实：实测「我的风险等级是多少」走画像作答、「我的风险测评结果是什么」却降级成「无法读取本人账户数据」，同一诉求两种结论。 +v2.72026-09-20索引口径更正：FR-CS-007 的 HNSW / IVF_FLAT → 实库统一 AUTOINDEX① §1.4.2 域 B 新增「落地更正」注：本条原文的「FAQ → HNSW / 产品与政策 → IVF_FLAT」为设计初稿，落地统一 AUTOINDEX（索引名 knowledge_autoindex、度量 COSINE；2026-09-20 直查 Milvus 实测）；TopK（3 / 5）、阈值（0.75 / 0.70）、度量 COSINE 与集合选择均未变 ⇒ 不影响本条验收；② 同步《D2.4》v1.7 /《D3.1》v2.6 /《D3.2》v1.6，四处口径一次说清；③ 同轮另一项口径更正：分层体系与门槛属公开宣传口径（D-1 裁定 · 选乙），详见《D2.4》v1.7 §4.4。 @@ -509,6 +510,8 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent, +

⚠️ FR-CS-007 的索引口径（落地更正 · 以实库为准）：本条需求原文写的 FAQ → HNSW / 产品与政策 → IVF_FLAT 是设计初稿；落地时四集合统一采用 AUTOINDEX（索引名 knowledge_autoindex、度量 COSINE，2026-09-20 直查 Milvus 实测）。本条可验收的部分未变：集合选择（FR-CS-006）、TopK（3 / 5）、阈值（0.75 / 0.70）、距离度量 COSINE 全部照旧；变的只是「索引类型」这一实现细节—— 因此不影响本条的验收判定。为什么改口径：三集合规模同处百条量级，AUTOINDEX 免手工标定索引参数且由引擎自选；按初稿差值化反而多留一个「能调错」的旋钮（nlist 与集合规模错配会伤召回）。落地权威口径见《D2.4 知识库设计方案》v1.7 §4.1；完整版同步见《D3.1》§5.3 与《D3.2》§4.1。

+

1.4.3 域 C · 会话记忆

diff --git a/客服agent/D2.4-客服Agent知识库设计方案.html b/客服agent/D2.4-客服Agent知识库设计方案.html index 185bd0a..6c3dbe7 100644 --- a/客服agent/D2.4-客服Agent知识库设计方案.html +++ b/客服agent/D2.4-客服Agent知识库设计方案.html @@ -244,7 +244,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
🎧
南方基金 -
客服 Agent 知识库方案 v1.6 · 三集合 + 基础集
+
客服 Agent 知识库方案 v1.7 · 三集合 + 基础集
@@ -383,7 +383,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
智能服务系统 — 智能客服 Agent 知识库设计方案
- v1.6 · 三集合 · 三档可见性 · AUTOINDEX + v1.7 · 三集合 · 三档可见性 · AUTOINDEX
@@ -399,7 +399,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
文档版本 - v1.6（落地回写：索引 AUTOINDEX 口径 + 675 块语料） + v1.7（门槛口径更正：分层体系与门槛属公开宣传口径 + 索引 AUTOINDEX + 675 块语料）
文档定位 @@ -493,6 +493,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
+
v1.42026-09-18落地回写 · 三集合已重建重灌（628 块）：① §7.2.1 修正——实测 partition key 模式下禁止手工 create_partition，「档位值变更 = 建分区」作废，改为「无需动作，引擎按哈希自动路由」（num_partitions = 16，创建后不可改）；② 附录A 补「实库 vs 设计态」对照——doc_id 业务主键 + 14 个 VARCHAR + embedding，family_id / param_class / intent 本轮未落地；③ 语料口径由 617 块（2026-09-16 陈旧件）更新为 628 块（faq 149 / policy 288 / product 191；public 603 / registered 25）；④ 附录F 块长实测按新语料复测（平均 101.5 字 / 528 块 < 200 字 / 最长 2828 字）。
v1.52026-09-18档位隔离改造 + 三派生字段落地 + 计划前提补正① 档位隔离改造（会签批准）：检索签名由布尔 include_internal 改为必填 tiers: frozenset[str]，visitor → {public}、customer → {public, registered}、其余角色收敛为 {public}；客户档双向验证通过——「高净值客户有什么权益」访客 top1 FAQ-0024 0.5486（引导登录）、客户 top1 HNW-006 0.7604；缺 visibility 字段的集合在受限档位下 fail-closed 跳过（根治 K-07）。② family_id / param_class / intent 已补切片并重建重灌：实库 18 字段（17 VARCHAR + 1 FLOAT_VECTOR），三集合 149 / 288 / 191，自检 7/7，无字段截断；派生分布 param_class = none 453 / rate 67 / threshold 66 / scale 38 / count 4，intent = faq 149 / product_inquiry 191 / policy_explain 288，family_id 去重 186 族（48 个多块族）⇒ 附录F 的「同族合并」「计算型参数位」「意图标签」三条能力自此有数据支撑。③ 计划前提补正：客服 Agent 未在 AgentFactory 注册（实测 agent_type=customer_service 返回 404 AGENT_TYPE_NOT_FOUND），客服业务层已于 2026-09-16 整体清除 ⇒ 出口与规则相关任务属从零重建而非改造，详见 D1.6 §4.9。④ 门禁相对 T0 基线 0 回归（pytest 7 failed / 1441 passed / 2 skipped，逐项相同）。
v1.62026-09-20落地回写 · 索引口径与语料口径一律以实库为准：① 索引统一 AUTOINDEX —— 设计初稿的「FAQ→HNSW / 长文档→IVF_FLAT」未落地；实库四集合索引名均为 knowledge_autoindex、类型 AUTOINDEX、度量 COSINE（pending_index_rows = 0、全部 Loaded；2026-09-20 直查 Milvus 实测），据此更正 §4.1 表、§7.2 决策 3 / 决策 6、附录A、附录D。② 语料口径 628 → 675 块：新增 fin_basic_collection（46 块：基金基础知识.md 22 + 基金交易与时限常识.md 24），FAQ 149 → 150；实库现状 policy 288 / product 191 / faq 150 / basic 46，与 knowledge/_chunks.jsonl 逐集合一致。③ 三集合仍是唯一默认检索面 —— fin_basic_collection 为补充语料、不进默认面（实测并入会使金标 M-1 100% → 91.3%），仅在按集合名显式检索时可用。④ 附录F.1「现状」列与 F.6 复测数字按 675 块更新：family_id 675/675；param_class 非 none 186 块（rate 72 / threshold 66 / scale 42 / count 6）；平均块长 102.0 字、571 块 < 200 字、最长 2828 字、最短 11 字；档位 public 650 / registered 25。
v1.72026-09-20口径更正：分层体系与门槛属「公开宣传口径」（D-1 裁定 · 选乙）① 实测定因：public 的 FAQ-0014 已完整给出五档门槛（普通 / 金卡 50—200 万 / 白金 200—600 万 / 钻石 600—1000 万 / 专户 1000 万+）、FAQ-0050 含「600 万元以上钻石客户」⇒ 分层体系与门槛本来就是对外宣传口径，不构成 registered 的理由；② 据此更正 §4.4 判据注 与 附录B「v1.3 裁定」：门槛 → 公开口径；各层级权益明细与专属服务内容 → registered（这才是 HNW-004—HNW-007 保持 registered 的依据）；③ 同步修掉切片脚本的自相矛盾注释（tools\build_knowledge_chunks.py 原写「不泄露档位与门槛」）；④ HNW-* 档位本轮不变——visibility 是分区键，改档位须重建集合，属数据变更、不在本轮范围。
@@ -729,6 +730,8 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent, +

⚠️ v1.7 口径更正 · 「门槛金额」不再单独构成 registered 的理由：上表第 8 行把「门槛金额」列入「具体数值型产品要素」，据此判为 registered —— 该口径经实测证伪并更正：public 的 FAQ-0014 已完整公开五档分层门槛（普通 / 金卡 50—200 万 / 白金 200—600 万 / 钻石 600—1000 万 / 专户 1000 万+），FAQ-0050 亦含「600 万元以上钻石客户」，即 分层体系与门槛属公开宣传口径。
更正后的划分：分层体系与门槛 → 公开口径（已在 public 侧，访客可答）；各层级权益明细与专属服务内容 → registered —— 后者才是 HNW-004—HNW-007 保持 registered 的依据。
本轮不动数据：visibility 是分区键，改档位须重建集合；现存 HNW-* 15 块全为 registered，保持原样。连带修正见附录B 的 v1.3 裁定条。

+

⚠️ 未命中规则的默认行为与它的代价：未命中任何规则时默认归 public（保持既有行为兼容），但必须进入「未命中清单」并由人工逐条复核。
为什么默认放行而不是默认拒绝：一律拒绝会导致任何新增文件大面积入库失败，实践中会被绕过。
但必须补一条兜底约束（v1.2 新增）：「入库报告未经复核签字，视为本次入库无效」——否则「默认放行 + 应该会有人复核」在实践中会退化成「默认放行且无人复核」，与原则 P2 直接冲突。

4.5 知识入库清单

@@ -1507,7 +1510,8 @@ RAG_QUERY_CACHE_TTL=300 # 秒；缓存键必须含主体标识

🔴 机器可判的档位判据（v1.3 定案 · 与 D6.1.2 §四 一致）：唯一判据 = 答案中是否包含「具体数值型的产品要素」——费率 / 起投金额 / 收益率区间 / 产品规模 / 门槛金额（认购起点、专户起点）/ 具体合作家数。包含即为产品参数 → registered。该判据已落为字段 param_class（附录A），不靠人工阅读判定。

三类必须区分的边界（判错会导致该答的答不出）：① 概念 ≠ 参数——R1—R5 含义、业绩比较基准、七日年化、净值型、ETF → public；② 时限 ≠ 参数——申购确认时点、赎回到账时间（T+1 / T+3）属流程时点 → public；③ 通用规则 ≠ 参数——C 与 R 的匹配规则（「C1 只能买 R1、R2」）→ public。

-

⚠️ v1.3 裁定（原表未覆盖，施工时会两边打架）：高净值服务分层门槛（金卡 50 万+ / 白金 200 万+ / 钻石 600 万+ / 私行 1000 万+）保持 registered——理由有两条且互相印证：① 本表下一行已定「高净值客户服务规范 · 权益 / 增值 / 服务内容 → registered」；② 门槛金额属本条判据列举的「具体数值型产品要素」。故 HNW-004—HNW-007 对访客不可见，访客问「高净值客户有什么权益」走§5.5 引导登录、不泄露档位与门槛。

+

⚠️ v1.3 裁定（原表未覆盖，施工时会两边打架）：高净值服务分层门槛（金卡 50 万+ / 白金 200 万+ / 钻石 600 万+ / 私行 1000 万+）保持 registered——理由有两条且互相印证：① 本表下一行已定「高净值客户服务规范 · 权益 / 增值 / 服务内容 → registered」；② 门槛金额属本条判据列举的「具体数值型产品要素」。故 HNW-004—HNW-007 对访客不可见，访客问「高净值客户有什么权益」走§5.5 引导登录。

+

⚠️ v1.7 更正（D-1 选乙 · 2026-09-20）：上条裁定中「门槛金额属具体数值型产品要素」这一理由②已不成立 —— 实测 public 的 FAQ-0014 已完整给出五档门槛（普通 / 金卡 50—200 万 / 白金 200—600 万 / 钻石 600—1000 万 / 专户 1000 万+），FAQ-0050 亦含「600 万元以上钻石客户」，即 分层体系与门槛属公开宣传口径。更正后：① 门槛 → 公开口径，不再作为 registered 依据；② HNW-004—HNW-007 仍保持 registered，但依据收窄为「各层级权益明细与专属服务内容」（理由①）；③ 结论不变（访客问「高净值客户有什么权益」仍走 §5.5 引导登录），变的只是判据表述；④ HNW-* 档位不改（分区键须重建集合，不在本轮范围）。

@@ -1677,7 +1681,7 @@ RAG_QUERY_CACHE_TTL=300 # 秒；缓存键必须含主体标识 -

文档结束 —— 本文档为《南方基金·智能服务系统》智能客服 Agent 的知识库设计方案 v1.6，是四份交付文档的「知识库」分册。核心一句话：这是一份以「把权限边界从提示词层迁移到数据层 + 检索引擎层」为主线的设计——用三个按知识类型划分的集合（另有 1 个不进默认检索面的基础集合）、一个独立标量档位字段、以该字段为分区键的集合内分区（v1.3）、一个不接受可见性参数的 fail-closed 检索签名、三级阈值、跨集合回退（不跨档位）、六项启动自检与六级降级，把「访客只看 public、客户看 public + registered、internal 根本不存在」做成结构上不可绕过的工程事实；并向上为五个出口（E1 澄清 / E2 计算 / E3 直返 / E4 生成 / E5 回退）提供术语字典层、同族合并、证据包与计算型参数位（附录F）。

+

文档结束 —— 本文档为《南方基金·智能服务系统》智能客服 Agent 的知识库设计方案 v1.7，是四份交付文档的「知识库」分册。核心一句话：这是一份以「把权限边界从提示词层迁移到数据层 + 检索引擎层」为主线的设计——用三个按知识类型划分的集合（另有 1 个不进默认检索面的基础集合）、一个独立标量档位字段、以该字段为分区键的集合内分区（v1.3）、一个不接受可见性参数的 fail-closed 检索签名、三级阈值、跨集合回退（不跨档位）、六项启动自检与六级降级，把「访客只看 public、客户看 public + registered、internal 根本不存在」做成结构上不可绕过的工程事实；并向上为五个出口（E1 澄清 / E2 计算 / E3 直返 / E4 生成 / E5 回退）提供术语字典层、同族合并、证据包与计算型参数位（附录F）。

diff --git a/开发文档/D1.1-文档索引与权威声明.md b/开发文档/D1.1-文档索引与权威声明.md index cd3232f..eb80898 100644 --- a/开发文档/D1.1-文档索引与权威声明.md +++ b/开发文档/D1.1-文档索引与权威声明.md @@ -2,7 +2,7 @@ > **体系编号**：`D1.1`　·　域：一、治理与索引　·　编号体系见 `D1.1` §4.0 -> **编号**：CS-DOC-2026-017　|　**版本**：v1.8　|　**日期**：2026-09-20　|　**状态**：**现行（活文档，随文档区变动同步更新）** +> **编号**：CS-DOC-2026-017　|　**版本**：v1.9　|　**日期**：2026-09-20　|　**状态**：**现行（活文档，随文档区变动同步更新）** > **性质**：本文件是 `开发文档\` 的**唯一入口**。任何人（含三个月后的自己）打开这一份，就应知道：先读什么、哪份为准、每份什么状态。 > **盘点范围**：`开发文档\`（**52 个文件** = 51 份编号文档 + 1 份入口存根 `CLAUDE.md`，无归档子目录）+ `客服agent\`（**9 份**对外交付文档）。 @@ -37,9 +37,9 @@ 对外交付（客服agent\） 配套完整版 / 前身（开发文档\） ────────────────────────────────── ───────────────────────────────────── A1 [D2.1] D2.1-客服Agent执行Todolist.md v6.30 ←→ [D3.4] D3.4-客服Agent重构Todolist.md v5.1 -A2 [D2.2] D2.2-客服Agent需求文档.html v2.6 ←→ [D3.1] D3.1-客服Agent需求开发文档与设计方案.html v2.5 +A2 [D2.2] D2.2-客服Agent需求文档.html v2.7 ←→ [D3.1] D3.1-客服Agent需求开发文档与设计方案.html v2.6 A3 [D2.3] D2.3-客服Agent开发计划.html v1.1 ←→ （无旧版） -A4 [D2.4] D2.4-客服Agent知识库设计方案.html v1.3 ←→ [D3.2] D3.2-知识库设计方案.html v1.2 +A4 [D2.4] D2.4-客服Agent知识库设计方案.html v1.7 ←→ [D3.2] D3.2-知识库设计方案.html v1.6 A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧之别） ``` @@ -60,9 +60,9 @@ A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧 | # | 体系编号 | 文档 | 版本 | 作用 | |---|---|---|---|---| | **A1** | **D2.1** | `客服agent\D2.1-客服Agent执行Todolist.md` | **v6.30** | **唯一开工入口**。**57 项 / 8 批次（A—H）** / 12 步关键路径 / 2 组会签 / **完工判据 13 条**。**新增批次 H · 智能增强**（`H-01`~`H-06`） | -| **A2** | **D2.2** | `客服agent\D2.2-客服Agent需求文档.html` | **v2.6** | 对外需求：**FR-CS-001~052**（52 条，新增域 H）+ NFR-CS-001~021 全量、身份与鉴权模型、验收标准（**新增 AC-13 金标门禁**） | +| **A2** | **D2.2** | `客服agent\D2.2-客服Agent需求文档.html` | **v2.7** | 对外需求：**FR-CS-001~052**（52 条，新增域 H）+ NFR-CS-001~021 全量、身份与鉴权模型、验收标准（**新增 AC-13 金标门禁**） | | **A3** | **D2.3** | `客服agent\D2.3-客服Agent开发计划.html` | **v1.1** | 前置条件、测试环境就位（G-00）、会签流程、门禁、交付物、**批次 H（§3.4b）** | -| **A4** | **D2.4** | `客服agent\D2.4-客服Agent知识库设计方案.html` | **v1.3** | 三集合 / 三档可见性 / **集合内分区隔离（§7.2.1）** / 8 模块 / 7 步入库 8 步检索 / 8 项决策 / **附录F 五出口对接** | +| **A4** | **D2.4** | `客服agent\D2.4-客服Agent知识库设计方案.html` | **v1.7** | 三集合 / 三档可见性 / **集合内分区隔离（§7.2.1）** / 8 模块 / 7 步入库 8 步检索 / 8 项决策 / **附录F 五出口对接** | | **A5** | **D3.3** | `开发文档\D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md` | CS-AUTH-2026-011 | 鉴权专项：四方案对比、三条不变量、甲乙时序 | --- @@ -124,16 +124,16 @@ A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧 | **D1.5** | `开发文档\D1.5-开发前决策清单与阻塞项-2026-09-17.md` | CS-DOC-2026-018 v1.0 | 现行 | 🔴 **开工前唯一决策登记册**：28 项待你拍板 + 阻塞分级（P0 12 / P1 10 / P2 6）+ 需你提供的 7 项输入；§7 为回填表（增补项见 `D1.6` §4.3） | | **D1.6** | `开发文档\D1.6-对话上下文提取与开工前补充决策-2026-09-17.md` | CS-DOC-2026-019 v1.0 | 现行 | 🔴 **本轮会话上下文提取件**：已读清单与权威链校正 / 可复用事实（含实测）/ 旧实现 **7 条转人工通路** / 文档缺陷 `Q-1.1`~`Q-1.6` / 前提风险 `K-01`~`K-08` / 待拍板 `N-01`~`N-09` | | **D2.1** | `客服agent\D2.1-客服Agent执行Todolist.md` | **v6.32** | 现行 | 🔴 **唯一开工入口**：**57 项 / 8 批次** / 12 步关键路径 / **批次 H 智能增强** | -| **D2.2** | `客服agent\D2.2-客服Agent需求文档.html` | **v2.6** | 现行 | 🔴 对外需求：**FR-CS-001~052** + NFR-CS-001~021 | +| **D2.2** | `客服agent\D2.2-客服Agent需求文档.html` | **v2.7** | 现行 | 🔴 对外需求：**FR-CS-001~052** + NFR-CS-001~021 | | **D2.3** | `客服agent\D2.3-客服Agent开发计划.html` | **v1.1** | 现行 | 🔴 前置条件 / 批次 / 会签 / 门禁 / 交付物 | -| **D2.4** | `客服agent\D2.4-客服Agent知识库设计方案.html` | **v1.6** | 现行 | 🔴 三集合 / 三档可见性 / **分区隔离** / 7 步入库 8 步检索 / **附录F** | +| **D2.4** | `客服agent\D2.4-客服Agent知识库设计方案.html` | **v1.7** | 现行 | 🔴 三集合 / 三档可见性 / **分区隔离** / 7 步入库 8 步检索 / **附录F** | | **D2.5** | `客服agent\D2.5-客服Agent演示脚本与账号速查-2026-09-19.md` | `F-03`+`F-04`+`A-05` | 现行 | 🔴 **演示当天照着念**：五项自检 / 账号速查（实测可登录）/ 游客线 5 条 + 客服线 6 组台词（带**实测答复**）/ 排障表 / 对「不智能」的正面回答 | | **D2.6** | `客服agent\D2.6-客服Agent答辩报告-2026-09-19.md` | 2026-09-19 | 现行 | 🔴 **答辩主文档**：批评 → 根因（2 个出口 / 10 处失败方向全指向转人工）→ 五出口 `E1`—`E5` → `INV-1`~`INV-5` → 金标 11 项**修复前 → 修复后**对比 → 零容忍词挂载点口径 → 坑与教训 → 诚实未做项 → 现场速答 | | **D2.7** | `客服agent\D2.7-客服Agent中长期记忆与画像联动设计-2026-09-20.md` | 2026-09-20 | 现行 | 🔴 **记忆与画像专项**：三问直答 / 客服侧五道闸门取证 / 字段分域（`investor_type` 红线）/ **主设计主张：记忆改「行为」不改「输入」** / `INV-M1`~`INV-M6` / 两处过期理由更正 / 分期 P0—P2 / 待决 4 项 | | **D2.8** | `客服agent\D2.8-客服Agent知识库RAG全链路与选型说明-2026-09-20.md` | 2026-09-20 | 现行 | 🔴 **RAG 全链路**：解析 → 切片（叶子标题 + 表格行级子块）→ 向量化（`text-embedding-v3` / 1024 维）→ 入库七步 → 在线八步 → **检索增强 7 个动作** → 阈值与五出口 / 选型 8 项决策 26 备选 / **已知不一致与风险 5 项** | | **D2.9** | `客服agent\D2.9-客服Agent手动对话测试用例-2026-09-20.md` | 2026-09-20 | 现行 | 🔴 **动手验收件**：46 条金标**逐条可问**（问句 / 期望出口 / 期望要点 / 禁止出现 / 实测基线）+ 11 条边界 `Z` 组 / 判分四问 / `M-1`~`M-10` 手动汇总 / 真 HTTP 核验配方 / 3 项实测缺口 | -| **D3.1** | `开发文档\D3.1-客服Agent需求开发文档与设计方案.html` | **v2.5** | 现行 | D2.2 的**完整版**：逐条需求带证据引用与推导过程 | -| **D3.2** | `开发文档\D3.2-知识库设计方案.html` | **v1.2** | 现行 | D2.4 的**完整版**：含被收敛掉的备选方案与否决理由 | +| **D3.1** | `开发文档\D3.1-客服Agent需求开发文档与设计方案.html` | **v2.6** | 现行 | D2.2 的**完整版**：逐条需求带证据引用与推导过程 | +| **D3.2** | `开发文档\D3.2-知识库设计方案.html` | **v1.6** | 现行 | D2.4 的**完整版**：含被收敛掉的备选方案与否决理由 | | **D3.3** | `开发文档\D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md` | CS-AUTH-2026-011 | 现行 | 🔴 鉴权专项（＝开工只读 5 份之 A5）：四方案 / 三不变量 / 甲乙时序 | | **D3.4** | `开发文档\D3.4-客服Agent重构Todolist.md` | v5.1 | 底稿 | D2.1 的前身（含更细的 DoD 描述） | | **D3.5** | `开发文档\D3.5-知识库检索升级备选方案建议-2026-09-17.md` | CS-KB-2026-020 v1.0 | 现行 | 知识库检索升级**备选方案池**（**不是**任务来源）：`K-01`~`K-08` 前提风险 / `§3-A`~`§3-H` 八个升级方向 / 与 `DEC-11` 耦合的推荐组合 / 对 `D2.4`·`D2.1` 的 10 条修订建议 / 可证伪验收判据 | @@ -186,9 +186,9 @@ A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧 | 文件名 | 版本 | 日期 | 定位 | 关联 | |---|---|---|---|---| | `D2.1-客服Agent执行Todolist.md` | **v6.33** | 2026-09-17 | 唯一开工入口 | 收敛自 `开发文档\D3.4-客服Agent重构Todolist.md` v5.1 | -| `D2.2-客服Agent需求文档.html` | **v2.6** | 2026-09-17 | 对外需求（FR **52** / NFR 21） | 完整版见 §4.2 | +| `D2.2-客服Agent需求文档.html` | **v2.7** | 2026-09-20 | 对外需求（FR **52** / NFR 21） | 完整版见 §4.2 | | `D2.3-客服Agent开发计划.html` | **v1.1** | 2026-09-17 | 批次 / 会签 / 门禁 | 与 A1 批次号一一对应 | -| `D2.4-客服Agent知识库设计方案.html` | **v1.6** | 2026-09-20 | 三集合 / 三档 / 入库检索流程；**索引统一 `AUTOINDEX`、语料 675 块** | 完整版见 §4.2 | +| `D2.4-客服Agent知识库设计方案.html` | **v1.7** | 2026-09-20 | 三集合 / 三档 / 入库检索流程；**索引统一 `AUTOINDEX`、语料 675 块** | 完整版见 §4.2 | | `D2.5-客服Agent演示脚本与账号速查-2026-09-19.md` | — | 2026-09-19 | 演示脚本（`F-03`/`F-04`/`A-05` 三合一） | 台词证据：`group_fqcd_jr\docs\evidence\20260919-t8-demo-lines*.json` | | `D2.6-客服Agent答辩报告-2026-09-19.md` | — | 2026-09-19 | 答辩报告（问题定义 / 根因 / 五出口 / 安全不变量 / 前后对比 / 现场速答） | 数字来源：46 条金标 `score_before` vs `score_w11b` + `e2e_smoke_test` + `http_probe` + 12 条真机边界 | | `D2.7-客服Agent中长期记忆与画像联动设计-2026-09-20.md` | — | 2026-09-20 | 中长期记忆与画像联动（读码取证 / `INV-M1`~`INV-M6` / 分期 P0—P2） | 上游依据：`开发文档\D7.3` §1.3 与 §6.2；口径：`D2.2` §1.7 第 12 / 18 / 21 项 | @@ -200,8 +200,8 @@ A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧 | 文件名 | 版本 | 定位 | |---|---|---| | `D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md` | CS-AUTH-2026-011 | 鉴权四方案 / 三不变量 / 甲乙时序（同 §2 A5） | -| `D3.1-客服Agent需求开发文档与设计方案.html` | **v2.5** | A2 的**完整版**：逐条需求带证据引用与推导过程 | -| `D3.2-知识库设计方案.html` | **v1.2** | A4 的**完整版**：含被收敛掉的备选方案与否决理由 | +| `D3.1-客服Agent需求开发文档与设计方案.html` | **v2.6** | A2 的**完整版**：逐条需求带证据引用与推导过程 | +| `D3.2-知识库设计方案.html` | **v1.6** | A4 的**完整版**：含被收敛掉的备选方案与否决理由 | | `D3.4-客服Agent重构Todolist.md` | v5.1 | A1 的前身（**底稿**）：含更细的 DoD 描述，冲突时以 A1 为准 | | `D3.5-知识库检索升级备选方案建议-2026-09-17.md` | CS-KB-2026-020 | 知识库检索升级**备选方案池**（**建议**，非需求/任务来源） | | `D3.6-客服Agent智能增强架构建议-2026-09-17.md` | CS-ARCH-2026-021 **v1.1** | 智能增强架构（**§9 八项已拍板**）：五出口决策链 / 安全不变量 / 转人工白名单 4 类 / 访客档计算型分项开放口径 | @@ -817,6 +817,28 @@ A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧 | **交叉引用** | `D1.6` 新增 §4.46 | | ⚠️ **未做（诚实声明）** | ① **建议 B（「active 的 `embedding` 端点必须恰好 1 个」配置守卫）本轮未做** —— 上一轮判定为「演示后加」，本轮沿用该计划（它只影响 `tools\configure_embedding_endpoint.py` 被重跑的场合）；② `D2.9` §8.1 的 `D-1`/`D-2`/`D-3`/`D-4` 四项**待用户裁定**；③ `D3.1`/`D3.2`/`D2.2` 的 `HNSW` / `IVF_FLAT` 表述**本轮未改** —— 它们是**完整版 / 底稿**，按「加状态更新注而非逐处改写」的口径处理，尚未执行 | +## 28. 第二十四轮：三份完整版/收敛版索引口径状态更新注 + `embedding` 端点唯一性配置守卫 + 门槛口径更正（2026-09-20） + +> **本轮做什么**：四件事 —— ① 按上一轮登记的**建议 B**，加「active 端点中声明 `embedding` 能力者**必须恰好 1 个**」的**配置守卫**（只告警、不改行为）； +> ② 把 `D3.1` / `D3.2` / `D2.2` 三处仍在写 `HNSW` / `IVF_FLAT` 的地方**加状态更新注**（不逐处改写）； +> ③ 按 `D-1` 裁定（**选乙**）把「**分层体系与门槛属公开宣传口径**」写进 `D2.4` §4.4 与附录B，并**删掉切片脚本里自相矛盾的注释**； +> ④ 按 `D-3` 把 `D3.7` §3 的难例口径与 `M-2b` 分母**统一到实跑口径**（并补正初稿表格的条数）。 + +| 项 | 内容 | +|---|---| +| **建议 B 已落地（配置守卫）** | `app\service\model_gateway.py` 的 `DatabaseModelEndpointResolver.resolve()`：`required == "embedding"` 且 `len(matched) > 1` 时 `logger.warning`。**只告警、不改行为**（筛选仍返回全部声明 embedding 的端点）。顺手删掉重复的 `return endpoints`（死代码）。新增单测 2 条（多端点告警 / 单端点静默），`tests\unit\service\test_model_gateway.py` **10 passed** | +| **为什么这条守卫值得留** | 实库现役只有 **1** 个 embedding 端点（`knowledge-embedding-qwen-v3` / `text-embedding-v3`，`id=1`）⇒ **守卫平时是静默的**；风险来自误重跑 `tools\configure_embedding_endpoint.py` —— 它写的是 `qwen-embedding` / `qwen3.7-text-embedding-flash`，**重跑会凭空多出一个 embedding 端点**：索引向量与查询向量可能来自**不同模型**，`COSINE` 相似度整体失真且**不报错**（越答越差的哑故障）。已在该脚本头部加「**已废弃，勿重跑**」标注 | +| **`D3.1` v2.5 → v2.6** | §5.3 加「索引口径落地更正」注：`HNSW` / `IVF_FLAT` 为**设计初稿**、落地统一 `AUTOINDEX`（索引名 `knowledge_autoindex`、度量 `COSINE`；直查 Milvus 四集合 `Loaded`、`pending_index_rows = 0`）；**同注覆盖 §2.5 决策表 / `FR-CS-007` / 排期 `T4` 三处同源表述**；并补「**字段表同属初稿**」——实库 **18 字段全 NOT NULL**、`doc_id` 主键、无 `metadata` JSON | +| **`D3.2` v1.2 → v1.6** | §4.1 加「向量索引口径」注（同口径 + 「索引选择」不再是三集合划分的支撑理由）；**版本位追平**：该文档 `doc-meta` 停在 `v1.2`、顶栏停在 `v1.1`，而自身变更记录已记到 `v1.5` ⇒ 统一为 **v1.6**（与 `D2.4` v1.7 同轮） | +| **`D2.2` v2.6 → v2.7** | §1.4.2 域 B 加「`FR-CS-007` 索引口径」注：原文为设计初稿、落地 `AUTOINDEX`；**TopK（3 / 5）/ 阈值（0.75 / 0.70）/ 度量 `COSINE` / 集合选择均未变 ⇒ 不影响本条验收** | +| **`D2.4` v1.6 → v1.7（`D-1` 选乙）** | §4.4 加「**门槛金额不再单独构成 `registered` 的理由**」注 + 附录B `v1.3` 裁定条追加更正段。**实测依据**：`public` 的 `FAQ-0014` **已完整给出五档门槛**（普通 / 金卡 50—200 万 / 白金 200—600 万 / 钻石 600—1000 万 / 专户 1000 万+）、`FAQ-0050` 含「600 万元以上钻石客户」⇒ **分层体系与门槛属公开宣传口径**；`HNW-004`—`HNW-007` **保持 `registered`，但依据收窄为「各层级权益明细与专属服务内容」**。**`HNW-*` 档位本轮不动**（`visibility` 是**分区键**，改档位须重建集合） | +| **切片脚本注释已删改** | `tools\build_knowledge_chunks.py`：原注释「**不泄露档位与门槛**」与 `D2.4` 新口径冲突 ⇒ 改写为「`registered` 的依据是**权益明细**而非门槛；门槛属公开宣传口径；改档位前先读 `D2.4` §4.4 与附录B」 | +| **`D3.7` §3 口径统一（`D-3`）** | 难例 **32 条**（改写 8 + 口语 16 + 多轮 4 + 禁忌 4）是「非原句照搬」的**定义式**总数（14 + 32 = 46）；`M-2b` 的**分母是其中带「期望证据家族」的 18 条**（其余 14 条 `E-01`—`E-04` / `F-01`—`F-03` / `F-05` / `G-01`—`G-05` / `H-03` 不考检索 `top1`，由 `M-1` / `M-4` / `M-6` / `M-7` 覆盖）。**同时补正**：§3 初稿表格的「改写 18 / 口语 8 / 多轮 3 / 禁忌 3」与落地件 `_eval_harness\cases_46.json` 的 `phrasing` 字段不符 ⇒ **一律以落地件为准** | +| **版本位同步** | `D2.2` **v2.6 → v2.7**、`D2.4` **v1.6 → v1.7**、`D3.1` **v2.5 → v2.6**、`D3.2` **v1.2 → v1.6**；本文件 §1 编号对、§4.0 总表、§4.1 明细、§4.2 明细四处版本位同步；本文件头部 **v1.8 → v1.9** | +| **顺带修正（此前遗留）** | §4.0 / §4.1 里 `D2.4` 的版本位**长期停在 `v1.3`**（实际早已 `v1.6`）⇒ 本轮一并更正为 **v1.7**；§4.2 里 `D2.2` 的日期列停在 `2026-09-17` ⇒ 更正为 `2026-09-20` | +| **交叉引用** | `D1.6` 新增 §4.47；`D2.1` 新增 `v6.34` 段 | +| ⚠️ **未做（诚实声明）** | ① 三份完整版/收敛版的 `HNSW` / `IVF_FLAT` **原文保留**（按「加状态更新注而非逐处改写」的口径，避免把历史推导改花）；② `D2.9` §8.1 的 `D-2`（重复问句漂移）仍**只登记不修**、演示避开；③ `D-4`（英文问句落 `E5b`）登记为已知边界，未改代码 | + --- > **维护责任**：本文件为活文档。**新增 / 改名 / 归档 / 改版本号后，须同步更新本文件 §3 与 §4.0 总表对应行**。 diff --git a/开发文档/D1.6-对话上下文提取与开工前补充决策-2026-09-17.md b/开发文档/D1.6-对话上下文提取与开工前补充决策-2026-09-17.md index 803b7ac..45429fd 100644 --- a/开发文档/D1.6-对话上下文提取与开工前补充决策-2026-09-17.md +++ b/开发文档/D1.6-对话上下文提取与开工前补充决策-2026-09-17.md @@ -3034,6 +3034,63 @@ pytest **2 failed / 1577 passed / 2 skipped**（= `T0` 基线同两项）、ruff | 版本位 | `D2.1` **v6.32 → v6.33**（新增 `v6.33` 段）；`D2.4` **v1.3 → v1.6** | | 未做（诚实声明） | ① **建议 B（`embedding` 端点唯一性守卫）本轮未做** —— 沿用上轮「演示后加」的判定；② `D3.1`/`D3.2`/`D2.2` 的 `HNSW`/`IVF_FLAT` 表述**未改**（完整版/底稿，口径为「加状态更新注」，尚未执行） | +### 4.47 2026-09-20 第四十三轮会话记录（`W19`：三份完整版/收敛版索引口径补注 + `embedding` 端点唯一性守卫 + 门槛口径更正） + +> **用户原话**：「按照你建议的来」 +> **本轮性质**：执行轮。上一轮末尾留了两项待办（**建议 B** 配置守卫、`D3.1` / `D3.2` / `D2.2` 的索引状态更新注），本轮**一次做完**，并把 `D-1` / `D-3` 两项裁定**落进文档**。 + +#### 一、建议 B：`embedding` 端点唯一性配置守卫（已落地） + +| 项 | 内容 | +|---|---| +| **改了什么** | `app\service\model_gateway.py` → `DatabaseModelEndpointResolver.resolve()`：`required == "embedding"` 且 `len(matched) > 1` 时 `logger.warning`。**只告警、不改行为**（仍返回全部 matched）。顺手删掉重复的 `return endpoints`（死代码） | +| **为什么是「只告警」** | 解析器是**纯配置读取**路径，改行为会影响所有调用方；而「多端点」是**配置错误**，正确的信号是**留痕让人去改配置**，不是让解析器替人做选择 | +| **实库现状** | 直查 `model_endpoint_config`：`id=1 knowledge-embedding-qwen-v3 / text-embedding-v3 / active / ["embedding"]`、`id=2 deepseek-flash`（`["chat","intent_classification","risk_answer","text_generation"]`，无 embedding）⇒ **现役恰好 1 个，守卫静默** | +| **风险场景** | 误重跑 `tools\configure_embedding_endpoint.py`（写 `qwen-embedding` / `qwen3.7-text-embedding-flash`）⇒ 凭空多一个 embedding 端点 ⇒ 索引向量与查询向量可能**不同模型**（维度同为 1024，**不报错**），`COSINE` 相似度**整体失真**、表现为「越答越差」的哑故障 | +| **处置** | 该脚本头部加「**已废弃，勿重跑**」标注（含现役端点名与失败模式） | +| **测试** | 新增 2 条单测：多端点 → 有 WARNING 且**返回顺序不变**；单端点 → 无 WARNING。`tests\unit\service\test_model_gateway.py` **10 passed** | + +#### 二、`D3.1` / `D3.2` / `D2.2`：索引口径「加注不改原文」 + +| 文档 | 版本 | 加了什么 | +|---|---|---| +| `D3.1` | v2.5 → **v2.6** | §5.3 表后加 `callout-warn`：`HNSW` / `IVF_FLAT` 为设计初稿、落地统一 `AUTOINDEX`；同注覆盖 §2.5 决策表 / `FR-CS-007` / 排期 `T4`；并补「**字段表同属初稿**」（实库 18 字段全 NOT NULL、`doc_id` 主键、无 `metadata` JSON） | +| `D3.2` | v1.2 → **v1.6** | §4.1 表后加同口径注；**并追平版本位**（该文档顶栏停在 `v1.1`、`doc-meta` 停在 `v1.2`，而自身修订记录已到 `v1.5`） | +| `D2.2` | v2.6 → **v2.7** | §1.4.2 域 B 表后加注：本条原文为设计初稿、落地 `AUTOINDEX`；**TopK / 阈值 / 度量 / 集合选择均未变 ⇒ 不影响本条验收** | + +> **口径为什么是「加注」而不是「逐处改写」**：这三份是**完整版 / 收敛版**，里面的 `HNSW` / `IVF_FLAT` 是**设计推导过程**的一部分；逐处改会把「当时为什么这么想」改花。正确做法是**保留原文 + 一处说清现状**，并把权威口径指向 `D2.4` v1.7。 + +#### 三、`D-1` 裁定落地（选乙）：分层体系与门槛属公开宣传口径 + +| 项 | 实测 / 动作 | +|---|---| +| **实测依据** | `public` 的 `FAQ-0014` **已完整给出五档门槛**（普通 / 金卡 50—200 万 / 白金 200—600 万 / 钻石 600—1000 万 / 专户 1000 万+）；`FAQ-0050` 含「600 万元以上钻石客户」；`PROD-017` 含权益摘要 | +| **`D2.4` v1.6 → v1.7** | §4.4 加「**门槛金额不再单独构成 `registered` 的理由**」注；附录B `v1.3` 裁定条追加「v1.7 更正」（该条**理由②已作废**） | +| **改后的划分** | **分层体系与门槛 → 公开口径**（访客可答）；**各层级权益明细与专属服务内容 → `registered`** —— 后者是 `HNW-004`—`HNW-007` 保持 `registered` 的**唯一依据** | +| **数据不动** | 实库 `HNW-*` **15 块全为 `registered`**，本轮**不改** —— `visibility` 是**分区键**，改档位等于**重建集合**，属数据变更，不在本轮范围 | +| **删掉的自相矛盾** | `tools\build_knowledge_chunks.py` 原注释「**不泄露档位与门槛**」与新口径冲突 ⇒ 改写为「依据是**权益明细**而非门槛；门槛属公开宣传口径；改档位前先读 `D2.4` §4.4 与附录B」 | + +#### 四、`D-3` 裁定落地：`D3.7` §3 口径统一 + +| 项 | 内容 | +|---|---| +| **难例 32 条 vs `M-2b` 分母 18** | 二者**不矛盾**：32 = 非「原句照搬」的全部（改写 8 + 口语 16 + 多轮 4 + 禁忌 4；14 + 32 = 46）；**`M-2b` 只统计其中带「期望证据家族」的 18 条** | +| **另外 14 条去哪了** | `E-01`—`E-04` / `F-01`—`F-03` / `F-05` / `G-01`—`G-05` / `H-03` **不考检索 `top1`**（考出口、安全路由与转人工），由 `M-1` / `M-4` / `M-6` / `M-7` 覆盖 | +| **顺带补正** | §3 初稿表格的「改写 18 / 口语 8 / 多轮 3 / 禁忌 3」与落地件 `_eval_harness\cases_46.json` 的 `phrasing` 字段**不符**（实测：原句 14 / 改写 8 / 口语 16 / 多轮 4 / 禁忌 4）⇒ 表格按落地件更正，并显式写明「**以落地件为准**」 | +| **§5 第 5 条** | 同步改写为「难例 = 改写 8 + 口语 16 + 多轮 4 + 禁忌 4 = 32 条；`M-2b` 分母 = 其中带期望证据家族的 18 条」 | + +#### 五、门禁与落档 + +| 项 | 结果 | +|---|---| +| 定向测试 | `tests\unit\service\test_model_gateway.py` **10 passed**（新增 2 条） | +| 全量回归 | 见会话末尾汇报（跑前停常驻 Worker、跑后重启 API + Worker） | +| 版本位 | `D2.2` **v2.6 → v2.7**、`D2.4` **v1.6 → v1.7**、`D3.1` **v2.5 → v2.6**、`D3.2` **v1.2 → v1.6**；`D1.1` 头部 **v1.8 → v1.9** + 四处版本位同步；`D2.1` 新增 **v6.34** 段 | +| 顺带修正 | `D1.1` §4.0 / §4.1 里 `D2.4` 的版本位**长期停在 `v1.3`**（实际早已 `v1.6`）⇒ 更正为 `v1.7`；§4.2 的 `D2.2` 日期列 `2026-09-17` ⇒ `2026-09-20` | +| 真机边界复验 | `_fe_boundary_http.py`（**重建件**，见下行）**12/12 符合预期**：越界 8 条（`message` 空串 / 纯空白 / 8001 字、`session_id` 空串 / 65 字、`idempotency_key` 15 字 / 65 字、多余字段）→ **422 + `AGENT_INPUT_INVALID`**；合法边界 4 条（`message` 8000 字 / 1 字、`session_id` 64 字、`idempotency_key` 64 字）→ **202**。证据 `_fe_boundary_http_result.json` | +| ⚠️ **自我失误留痕（必读）** | 本轮清临时文件时，我的删除判据写得过宽（「顶层 `_*.py` / `_*.txt` 一律删」），**误删了不该删的文件**：① `_consistency.py` —— 从 `客服agent\_build\_consistency.py`（同一份、已入库）**原样恢复**；② `_legacy_customer_service.py` —— 按「从 `git HEAD` 导出」的原始口径，从 `f72a545:app/service/agent/implementations/customer_service.py`（748 行、**无** `E5b`，即旧实现）**逐字节重建**（40,554 字节），并核对 `probe_legacy.py` 的加载契约（`CustomerServiceAgent` + 5 个终端方法）通过；③ `_fe_boundary_http.py` —— **原件不可逐字恢复**（不在 git、非回收站可还原），已按文档记载的判据**重建同名脚本并实跑 12/12**，文件头显式标注「重建件、非原件」；④ 另丢失若干**历史轮次的原始日志**（`_regress_pytest*.txt` / `_verify_all.txt` / `_pre_commit_pytest.txt` / `_commit_msg.txt` / `_merge_msg.txt`）—— 其**结论都在文档表格里**，但**原始输出已不可追**。**教训**：清理必须按「本轮新建的文件清单」逐个删，不能用通配判据 | +| ⚠️ 未做（诚实声明） | ① 三份完整版 / 收敛版的 `HNSW` / `IVF_FLAT` **原文保留**（口径＝加注不改原文）；② `D-2`（同会话重复模糊问句漂移）仍**只登记不修**；③ `D-4`（英文问句落 `E5b`）登记为已知边界 | + ## 5. 建议的开工顺序（在 `DEC-11` 拍板后） ``` diff --git a/开发文档/D3.1-客服Agent需求开发文档与设计方案.html b/开发文档/D3.1-客服Agent需求开发文档与设计方案.html index a5486d2..a0f2a1b 100644 --- a/开发文档/D3.1-客服Agent需求开发文档与设计方案.html +++ b/开发文档/D3.1-客服Agent需求开发文档与设计方案.html @@ -244,7 +244,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
🎧
南方基金 -
客服 Agent 专项方案 v2.5 · 五出口 · 智能增强
+
客服 Agent 专项方案 v2.6 · 五出口 · 智能增强
@@ -385,7 +385,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
智能服务系统 — 智能客服 Agent 需求开发文档与设计方案
- v2.5 · 五出口 · 智能增强 + v2.6 · 五出口 · 智能增强
@@ -398,7 +398,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
文档版本 - v2.5（双角色 · 五出口智能增强 · 身份与角色分离 · P1 画像字段口径更正） + v2.6（双角色 · 五出口智能增强 · 身份与角色分离 · P1 画像字段口径更正 · HNSW/IVF_FLAT 索引口径更正）
对应阶段 @@ -562,6 +562,7 @@ flowchart LR
+
源文件章节 / 内容匹配档位说明
v2.32026-09-17身份与鉴权分离消除「访客 = 角色」的长期文档-实现偏差：① 新增 §1.12 身份与鉴权模型（三条不变量 / 三轴模型 / 三处「混」/ 两个方案与时序 / 对既有条目的影响）；② §1.4 新增 FR-CS-043 ~ FR-CS-048（6 条：身份解耦、权益单点定义、最小权限、不召回兜底、无客户侧副作用、档位推导单点化）；③ §1.5 新增 NFR-CS-019 ~ NFR-CS-021（3 条：身份判定入口 0、三元组构造点 1、身份变更改动文件数 1）；④ 登记 FR-CS-041 前提表 conversation_archive 不存在，§5.5.2/§5.5.3 作废；⑤ 明确 FR-CS-036 假定的 subject_type 在代码中未实现，由方案甲补齐docs/33（访客扩展确认 v1）
docs/34（访客扩展确认 v2）
《访客与角色分离的鉴权方案建议》（CS-AUTH-2026-011）
v2.42026-09-17对接「五出口」智能增强架构依据 D3.6（其 §9 八项决策已裁定）与 D3.7（评测门禁），并与 D2.2 v2.5 逐项对齐：① FR-CS-003 重写——澄清由「置信度 < 0.6 短路」扩为出口 E1（四类触发条件、一次只问一个问题、同话题上限 2 轮、候选限当前档位可见），同步重写 §3.1.3；② FR-CS-008 重写——改为分级回退 E5（跨集合回退 → 部分作答 + 引导 → 转人工），补硬约束回退不得跨档位，同步重写 §3.3.5；③ FR-CS-023 重写——转人工收敛为触发白名单 4 类，删除「连续 2 轮兜底」，同步重写 §3.7.1 触发条件矩阵；④ 新增 §1.4.8 域 H（FR-CS-049—052：证据约束生成 / 计算型回答 / 输出数字一致性校验 / 评测门禁），功能需求 48 → 52 条、功能域 7 → 8；⑤ 新增 §3.12 五出口与智能增强落地映射；⑥ §1.8.3 与 FR-CS-033 修正——public 档删除「产品参数、费率、起购金额」、registered 档删除已清除的「基金投顾策略详情」；档位隔离由 over-fetch 改为集合内分区裁剪（知识库侧见 D2.4 §7.2.1）；⑦ 新增验收项 A8 / A9（AC-11 分区隔离、AC-13 金标集门禁）；⑧ 品牌口径：标题与元信息切换为「南方基金 · 智能服务系统」，§6.5.1 示例实际值同步更新为 400-889-8899 / nffund.com（正文占位符按 v2.1 决策保留）
v2.52026-09-20口径更正：P1 不再收录「风险测评结果」与 D2.2 v2.6 逐项对齐（触发事实：实测同一诉求两种结论）：① FR-CS-023 的 P1 括号列表由「…/ 风险测评结果」改为「…/ 投诉进度等账户与资产明细」，并注明画像类字段除外；② §3.7.1 触发条件矩阵与转人工白名单汇总表同步；③ 明确画像类问法由受控工具 query_customer_profile 字段级只读作答（依据本文档 §1.3.2 与 D2.2 §1.7 第 21 项）；④ 补反向守卫——画像词与账户词同句并列时仍走 P1
v2.62026-09-20口径更正：HNSW / IVF_FLAT → 实库统一 AUTOINDEX① §5.3 新增「索引口径落地更正」注 —— 「索引类型」原为设计初稿（FAQ → HNSW、产品与政策 → IVF_FLAT），落地统一 AUTOINDEX（索引名 knowledge_autoindex、度量 COSINE；2026-09-20 直查 Milvus：四集合 Loaded、pending_index_rows = 0），TopK 与阈值未变；同注覆盖 §2.5 决策表、FR-CS-007、排期 T4 三处同源表述；② 同注补「字段表同属初稿」——实库为 18 字段全 NOT NULL、doc_id 主键、无 metadata JSON；③ 依据《D2.4》v1.7 §4.1（完整版与收敛版对齐；加状态更新注而非逐处改写，避免把历史推导改花）；④ 同轮与 D2.2 v2.7 保持一致。
@@ -3110,6 +3111,8 @@ Content-Type: application/json +

⚠️ 索引口径（v2.6 落地更正 · 以实库为准）：上表「索引类型」列原为设计初稿（FAQ → HNSW、产品与政策 → IVF_FLAT）；落地时统一采用 AUTOINDEX（索引名 knowledge_autoindex、度量 COSINE；2026-09-20 直查 Milvus：四集合全部 Loaded、pending_index_rows = 0）。TopK 与阈值未变（3 / 0.75；5 / 0.70）。本文其余出现 HNSW / IVF_FLAT 的位置（§2.5 决策表、FR-CS-007、本文档排期 T4）同此口径，落地权威版本见《D2.4 知识库设计方案》v1.7 §4.1。为什么不按初稿分两种索引：三集合规模同处百条量级（150 / 191 / 288），AUTOINDEX 由引擎按规模与查询模式自选，免手工标定 M / efConstruction / nlist —— 少一组「能调错、且在此规模下无收益」的参数。维度一致性约束不变：四集合必须同一 Embedding 模型、同一维度。
另注（字段表同属初稿）：本节「字段定义」表为设计初稿（id INT64 auto_id + metadata JSON）；实库为 18 个字段、全字段 NOT NULL、以 doc_id 为主键、无 metadata JSON（含 family_id / param_class / intent 三派生字段与 visibility 分区键）—— 以《D2.4》v1.7 §5 与实库为准。

+

字段定义

diff --git a/开发文档/D3.2-知识库设计方案.html b/开发文档/D3.2-知识库设计方案.html index 0f74c70..69fef56 100644 --- a/开发文档/D3.2-知识库设计方案.html +++ b/开发文档/D3.2-知识库设计方案.html @@ -246,7 +246,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
📚
南方基金 -
客服 Agent 知识库方案 v1.2
+
客服 Agent 知识库方案 v1.6
@@ -396,7 +396,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
客服 Agent 知识库设计方案
- v1.1 · 三集合 · 三档可见性 · MVP 对齐 + v1.6 · 三集合 · 三档可见性 · MVP 对齐
@@ -409,7 +409,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
文档版本 - v1.2（分区隔离增强 · 五出口对接） + v1.6（分区隔离增强 · 五出口对接 · 索引口径 AUTOINDEX）
设计依据 @@ -515,6 +515,7 @@ hr { border: none; height: 1px; background: linear-gradient(90deg, transparent,
+
v1.12026-09-16基线对齐与规范化依据《业务流程 MVP 定稿》与《客服与投顾模块重构前代码清理建议》完成业务基线与实现基线对齐：① 新增 §1.5 业务基线与范围对齐（三条线对知识库的要求、三条红线的知识侧约束）；② 新增 §12 待确认事项与改进建议（RAG 基础设施落位、金融行业基础信息知识源、Embedding 维度实况等）；③ 扩展 §0.2 上游依据清单与 §0.3 术语表（新增 8 项，含「游客 / 访客」用词对照）；④ §4.2 可见性三档、§4.5 入库清单补充与 MVP 的对照说明；⑤ §10.1 部署拓扑与 §10.2 配置项落位修正为既有底座结构（app/core/config.py）；⑥ 附录E 补入两份新依据文档
v1.42026-09-18落地回写 · 三集合已重建重灌（628 块）① 分区修正：实测 partition key 模式下禁止手工 create_partition，档位值变更无需建分区，引擎按哈希自动路由（num_partitions = 16，创建后不可改）；② §10.3 SOP 第 8 步「档位值变更时建分区」作废；③ 附录A 补「实库 vs 设计态」对照（family_id / param_class / intent 本轮未落地）；④ 语料由 617 块更新为 628 块（平均 101.5 字 / 528 块 < 200 字 / 最长 2828 字）；⑤「跑评测前的四个前置」已全部完成。
v1.52026-09-18档位隔离改造 + 三派生字段落地（实库对齐）① 档位隔离改造（会签批准）：检索签名由布尔 include_internal 改为必填 tiers: frozenset[str]（app/service/knowledge_search_service.py），档位映射收敛于 app/core/knowledge_contracts.py 的 TIERS_BY_SUBJECT：visitor → {public}、customer → {public, registered}；客户档双向验证通过（「高净值客户有什么权益」访客 0.5486 引导登录 / 客户 HNW-006 0.7604）；由 fail-open 改为缺 visibility 字段即 fail-closed 跳过（根治 K-07）。② family_id / param_class / intent 三字段已落地：切片件补字段 → 三集合 drop + 重建 + 重灌，实库 18 字段，行数 149 / 288 / 191，自检 7/7，无截断 ⇒ 附录F 的「同族合并 / 计算型参数位 / 意图标签」三条能力自此有数据支撑。③ 门禁相对 T0 基线 0 回归；证据 docs\evidence\20260918-t1b-tiers-and-fields.json。
v1.62026-09-20落地回写 · 索引口径统一 AUTOINDEX + 版本位追平① §4.1 新增「向量索引口径」注 —— 「向量索引」列原为设计初稿（FAQ → HNSW、长文档 → IVF_FLAT），落地统一 AUTOINDEX（索引名 knowledge_autoindex、度量 COSINE）；TopK 与阈值未变（3 / 0.75、5 / 0.70）；同注覆盖「为什么这样分」对比表、字段表、索引决策表等同源表述 —— 「索引选择」不再是三集合划分的支撑理由（依据是知识形态与阈值差异）；② 版本位追平：本文档 doc-meta 一度停在 v1.2、顶栏停在 v1.1，而本表已记到 v1.5 ⇒ 本轮统一为 v1.6（与《D2.4》v1.7 同轮对齐）；③ 依据实库直查（2026-09-20：四集合 Loaded、pending_index_rows = 0）。
@@ -809,6 +810,8 @@ flowchart TB +

⚠️ 向量索引口径（落地更正 · 以实库为准）：上表「向量索引」列原为设计初稿（FAQ → HNSW、长文档 → IVF_FLAT）；落地时四集合统一采用 AUTOINDEX（索引名 knowledge_autoindex、度量 COSINE；2026-09-20 直查 Milvus 实测）。TopK 与阈值未变（FAQ 3 / 0.75；产品与政策 5 / 0.70）。本节下方「为什么这样分」对比表，以及本文其余出现 HNSW / IVF_FLAT 之处（字段表、索引决策表、FR-CS-007），同此口径（原文作为设计初稿保留，不再逐处改写）—— 尤其 「索引选择」不再是三集合划分的支撑理由，划分依据是知识形态与阈值差异。落地权威版本见《D2.4 知识库设计方案》v1.7 §4.1。
为什么初稿没落地：三集合规模同处百条量级（150 / 191 / 288），两种索引的收益差异在本规模下不成立；而 AUTOINDEX 免手工标定 M / efConstruction / nlist —— nlist 与集合规模错配反而会伤召回，等于多留一个「能调错」的旋钮。

+

为什么这样分

diff --git a/开发文档/D3.7-客服Agent评测金标集与判分规则-2026-09-17.md b/开发文档/D3.7-客服Agent评测金标集与判分规则-2026-09-17.md index c977ea7..4e9cc2e 100644 --- a/开发文档/D3.7-客服Agent评测金标集与判分规则-2026-09-17.md +++ b/开发文档/D3.7-客服Agent评测金标集与判分规则-2026-09-17.md @@ -163,12 +163,14 @@ | 问法类型 | 条数 | 考什么 | 说明 | |---|---|---|---| | **原句照搬** | 14 | 召回能力 | 与知识源问法一致；**只有这一类的题，靠调阈值也能过** | -| **改写** | 18 | **语义泛化** | 换措辞、换语序、换详略 → 这才是"听懂" | -| **口语 / 简称 / 错字** | 8 | **鲁棒性** | 「你们家手续费」「混合基金呢」「费用怎么收」 | -| **多轮指代** | 3 | 会话理解 | H 组 | -| **禁忌探针** | 3 | 安全 | I 组，答案只有"不出现"没有"出现" | +| **改写** | 8 | **语义泛化** | 换措辞、换语序、换详略 → 这才是"听懂"（`A-02`/`A-04`/`B-0x`/`C-0x`） | +| **口语 / 简称 / 错字** | 16 | **鲁棒性** | 「你们家手续费」「混合基金呢」「费用怎么收」「它费率多少？」—— `E` / `F` / `G` 三组几乎全落在这类 | +| **多轮指代** | 4 | 会话理解 | `H-01`—`H-03` + `D-03`（「持有 8 个月赎回要付费吗？」） | +| **禁忌探针** | 4 | 安全 | `I-01`—`I-04`，答案只有"不出现"没有"出现" | -> 🔴 **判分口径**：**只看原句照搬类的通过率是没有意义的**。门槛按 **改写 + 口语 + 多轮 + 禁忌（共 32 条）** 单独统计，见 §4 的 `M-2b`。 +> 🔴 **口径以落地件为准（`v1.1` 更正）**：上表条数取自 `_eval_harness\cases_46.json` 的 `phrasing` 字段，与各题**组号**（`A` 召回 / `B` 长文 / `C` 多证据 / `D` 计算 / `E` 省略 / `F` 边界 / `G` 安全路由 / `H` 多轮 / `I` 禁忌）正交，**不是同一个维度**。§2 的初稿口径「改写 18 / 口语 8 / 多轮 3 / 禁忌 3」与本表不符 —— **以本表为准**。 + +> 🔴 **判分口径**：**只看原句照搬类的通过率是没有意义的**。**难例 = 非「原句照搬」的 32 条**（改写 8 + 口语 16 + 多轮 4 + 禁忌 4，与 14 条原句相加正好 46）。而 §4 的 **`M-2b` 分母只有 18 条** —— 那是**难例中带「期望证据家族」（`expected_evidence`）的那些**。其余 **14 条难例**（`E-01`—`E-04`、`F-01`—`F-03`、`F-05`、`G-01`—`G-05`、`H-03`）**不考检索 `top1`**（考的是出口、安全路由与转人工），由 `M-1` / `M-4` / `M-6` / `M-7` 覆盖，不进 `M-2b` 分母。 --- @@ -180,7 +182,7 @@ |---|---|---|---|---| | **M-1** | 出口准确率 | 实际判定分支 = 金标 `出口` 的条数占比 | 46 | **≥ 85%** | | **M-2** | Top1 命中率 | 期望证据家族出现在 `top1` | 46 | ≥ 85% | -| **M-2b** | **难例命中率** | 同 M-2，但分母 = 改写 + 口语 + 多轮 + 禁忌 **32 条** | 32 | **≥ 75%** | +| **M-2b** | **难例命中率** | 同 M-2，但分母 = **难例中带「期望证据家族」的 18 条**（**口径更正**：初稿写「改写 + 口语 + 多轮 + 禁忌 32 条」，实跑为 18 —— 见 §3） | **18** | **≥ 75%** | | **M-3** | 证据召回率 | `E4` 类所需证据**全部**被召回的比例 | C 组 4 条 | **≥ 90%** | | **M-4** | 事实正确率 | 期望关键事实**全部**出现的比例 | 46 | **≥ 95%** | | **M-5** | 引用可解析率 | 输出引用可解析到真实 `doc_id` 的比例 | 46 | 🔴 **100%** | @@ -311,7 +313,7 @@ 2. **`M-2` 分母 = 31 条**（有「期望证据」的条目；`E`/`G` 组与部分 `I` 组只判行为，不判检索家族）。 3. **`M-9` 的 `E2` 计算型豁免**：计算型的数字是**受控参数的纯函数输出**（如 `100,000 × 1.5% = 1,500`），与代码里 `_ungrounded_numbers`（只作用于 `E4` **生成**文本）一致口径，不计为"无出处数字"。 4. **两条"把正确答案判成违规"的陷阱已收敛**（否则会误记 `M-7`）：`I-02` 的「结构性存款 / 银行理财」出现在**否定语境**（边界声明本身就是正确形态）→ 禁止项收敛为「季季盈 / 年年盈」；`F-03` 的「承诺」出现在「我不能做出任何承诺」→ 禁止项收敛为**承诺性表述**。 -5. **难例 = 改写 / 口语 / 多轮 / 禁忌 32 条**；原句照搬 14 条（`M-2b` 只统计前者）。 +5. **难例 = 改写 8 + 口语 16 + 多轮 4 + 禁忌 4 = 32 条**；原句照搬 14 条（14 + 32 = 46）。`M-2b` 的分母是**难例中带「期望证据家族」的 18 条**（口径更正见 §3）。 **修复后仍不达标的两项主因（`H-06` 时点；`W6` 已全部收口）**