docs: README 与实现对齐；experiment: 繁简转换实验（负面结果） - #3
Open
EtheXReal wants to merge 4 commits into
Open
Conversation
Ubuntu 22.04 起 apt 安装会触发 needrestart 的「Daemons using outdated libraries」全屏对话框，等待人工选择要重启哪些服务——自动化脚本会直接卡死在这里。 设置 DEBIAN_FRONTEND=noninteractive 禁掉 debconf 问答， NEEDRESTART_MODE=a 让受影响的服务自动重启而不弹窗。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
起因：线上观察到部分查询的重排分数异常低（0.2 量级），而另一些高达 0.93。
假设是语料为繁体、用户输简体造成的字形不匹配。
假设验证成立。同一段原文四种问法的重排分：
简问+繁文 0.197 | 繁问+繁文 0.657 | 简问+简文 0.231 | 繁问+简文 0.223
扩到 8 条真实测试样本的平均：
简问+繁文 0.564 | 繁问+繁文 0.768 | 简问+简文 0.680
转繁体确实让正确答案分数提升约 36%，且优于把文档转简体
（t2s 会归并 發/髮 等字，丢失信息）。
但评测指标反而变差：
Hit@1 0.764 -> 0.727，MRR 0.810 -> 0.791（关闭开关后复现 0.764/0.810，非波动）
逐题分析 54 道有效题：仅 8 题排名变化（4 好 4 坏），46 题不变。
Hit@1 的下降完全来自 2 道从第 1 位掉到第 2 位的题。
结论：效应在噪声范围内，55 题的测试集不足以检出。不采纳——
不引入没有证据支持的复杂度。开关保留但默认关闭，用于记录这次实验。
教训：重排模型的绝对分数是未标定的，分数普遍抬高不等于排序变好。
检索质量必须用排序指标衡量，不能看分数。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
原 README 描述的是重构前的状态，多处与代码不符，照抄无法运行。 修正的事实错误 - 克隆地址写的是 EtheXReal/DocChat，实际仓库为 basiclaw-rag - 文本嵌入维度写 1536，text-embedding-v4 实测为 1024 - 元数据存储写死 Redis，实际已改为 Protocol + Redis/SQLite 可插拔， Redis 不再是必需依赖（未安装时自动回退 SQLite） - 环境变量配置写的是 set/export，实际通过 .env 读取 - 架构图缺少重排环节 新增内容 - 线上体验地址 docchat.xreal.cc - 检索质量评测表（baseline vs 重排），并说明评测可复现 - 两阶段检索架构图，及「为什么是两阶段」「为什么不做混合召回」 - 评测体系说明：测试集构造的三个易忽略细节、为何同时看 Hit@k 与 MRR、 严格指标在语料内容重复时的系统性低估及 LLM 裁判甄别方案 - 项目结构补上 reranker.py、eval/、deploy/ - 「已知限制」章节：CLIP 中文效果差、无单元测试、全量重建无增量索引、 Gradio 全局单例并发不安全、切块未利用文档结构、Docker 未实测 口径调整 CLIP 原描述为「支持图片跨模态检索」，未说明其为英文模型、文本侧 77 token 上限、 本语料仅 5 张图片，且线上部署已关闭。改为如实说明并给出改进方向。 截图更新 原截图为旧界面（无 AI 回答标题、显示已废弃的伪相似度百分比、存在 Textbox 字面量）， 改用 Playwright 从线上环境重新截取，2x 高分辨率。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
上一版为解释设计取舍写得过长（257 行，原版 139 行），信息密度反而下降。 本次压回 140 行，与原版持平： - 「为什么两阶段」「为什么不做混合召回」由整节压缩为各两句 - 评测体系的方法论细节移出 README（保留在评测代码注释中）， 只保留结果表与复现命令 - 「已知限制」由逐条展开改为一段话带过 - 补回 Docker 部署章节（原版有，上一版误删）： docker compose 全栈、单容器 + SQLite 两种方式， 并说明镜像已预装 Tesseract 中文包与 CLIP 权重、数据走命名卷持久化 - 其余界面截图收进 details 折叠块 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
内容
四个提交，分文档、实验、修复三类。
一、README 与实际实现对齐
原 README 描述的是重构前的状态，多处与代码不符，照抄跑不通：
EtheXReal/DocChat.gitbasiclaw-ragtext-embedding-v4实测 1024 维set/export.env读取补充内容：线上体验地址、检索质量评测表、两阶段架构说明、已知限制。
CLIP 原描述为「支持图片跨模态检索」，未说明其为英文模型、文本侧上限 77 token、
本语料仅 5 张图片且线上已关闭。改为如实说明并给出改进方向。
截图从线上环境用 Playwright 重新截取（原截图为旧界面，含已废弃的伪相似度百分比）。
第二次提交将篇幅压回 140 行（与原版 139 行持平），并补回上一版误删的 Docker 章节。
二、繁简转换实验（负面结果）
线上观察到部分查询重排分数异常低（0.2 量级），另一些高达 0.93。
假设是语料为繁体、用户输简体导致的字形不匹配。
假设验证成立——同一段原文四种问法的重排分：
扩到 8 条真实样本，平均 0.564 / 0.768 / 0.680，转繁体让正确答案分数提升约 36%。
但评测指标反而变差：Hit@1 0.764 → 0.727，MRR 0.810 → 0.791
（关闭开关后复现 0.764/0.810，确认非波动）。
逐题分析 54 道有效题：仅 8 题排名变化（4 好 4 坏），46 题不变，
Hit@1 的下降完全来自 2 道从第 1 位掉到第 2 位的题。
结论：效应在噪声范围内，55 题的测试集不足以检出。不采纳——
不引入没有证据支持的复杂度。开关保留但默认关闭，代码注释完整记录了实验过程。
教训：重排模型的绝对分数是未标定的，分数普遍抬高不等于排序变好。
检索质量必须用排序指标衡量，不能看分数。
三、部署脚本修复
Ubuntu 22.04 起 apt 安装会触发 needrestart 的「Daemons using outdated libraries」
全屏对话框等待人工选择，自动化脚本直接卡死。
设置
DEBIAN_FRONTEND=noninteractive与NEEDRESTART_MODE=a解决。验证