RAG Jev
September 20, 2026 · View on GitHub
国服《英雄联盟》版本更新公告的本地 RAG 问答，加上一个 Jev（TypeSafe System One）决策层。
回答里的数字全部来自官方公告的结构化抽取结果，不经过生成模型；Jev 只负责「在候选里选哪一个」这类可校验的判断。
为什么不是"又一个 RAG demo"
| 维度 | 常见作品集项目 | 本项目 |
|---|---|---|
| 数字来源 | 让模型写数值 | 模板渲染，数值只来自公告 chunk（_render） |
| 版本处理 | 纯相似度检索 | 元数据过滤先于排名；26.17 / 16.17 / 15.13 三套版本号自动归一 |
| 评估 | 无，或自己写几条同源问题 | 38 题独立盲测（出题方被禁止读语料）+ 48 条解析盲测 + 18 条陷阱题；同源与盲测分开报 |
| 负面结论 | 不写 | 三种排序在过滤后打平、门槛测量后不采用、Jev 曾把答案挤到 @2（已加置信闸门）——都留在报告里 |
| 模型定位 | 全流程交给 LLM | 解析用确定性正则（48/48 盲测全过、零延迟）；Jev 只做重排与自检，$0.0001/次 |
| 拒答 | 靠提示词祈祷 | 关键词黑名单 + 覆盖边界 + 「最近一次改动」回退 + 其它服务器边界，盲测拒答 10/10 |
| 工程 | 一个 notebook | 89 项单元测试 + GitHub Actions + 进程 Job Object + 索引指纹 + 公告原文不入库 |
一、语料规模
python scripts/corpus_stats.py 生成，完整表格见 docs/语料统计.md。
| 指标 | 最近 10 个版本（26.9—26.18） | 全部 30 个版本（15.13—26.18） | 倍数 |
|---|---|---|---|
| 版本数 | 10 | 30 | ×3.0 |
| chunk 总数 | 1176 | 4995 | ×4.25 |
| 结构化数值改动 | 503 | 2212 | ×4.40 |
| 公告叙述段 | 673 | 2783 | ×4.14 |
| 英雄（去重） | 86 | 156 | ×1.81 |
| 装备（去重） | 29 | 58 | ×2.00 |
| 带技能归属的改动 | 265 | 832 | ×3.14 |
解析质量：结构化占比 44.3%，字段归一率 91.0%（未归一的行保留原文但不参与字段过滤）， 带技能归属的结构化改动 832/2212。逐版本明细与字段分布见统计报告。
二、评测结果（三套口径分开记账）
全部由 scripts/evaluate_patch.py / evaluate_parse.py 跑出，页面与报告只读取 docs/*.json。
盲测 38 题（Codex 依官方公告出题，出题时禁止读语料）
| 指标 | 无版本上下文 | 界面选中版本 |
|---|---|---|
| 单点数值正确 | 19/20 | 20/20 |
| 检索命中@1 / @5 | 18/20 · 19/20 | 20/20 · 20/20 |
| 版本正确（12 条写了版本） | 12/12 | 12/12 |
| 汇总含预期对象 | 7/8 | 8/8 |
| 无记录 / 越界拒答 | 10/10 | 10/10 |
| Jev 回答自检（支持度 ≥ 0.5） | 13/13 | 20/20 |
同源 76 例（作者按语料编写，非盲测，用于回归）
| 指标 | bm25 | vector | hybrid | hybrid + Jev |
|---|---|---|---|---|
| 单点命中@1（28 条） | 25 | 25 | 26 | 26 |
| 定点命中@1（15 条，候选歧义） | 14 | 14 | 14 | 15 |
| 汇总含预期对象（4 条） | 4 | 4 | 4 | 4 |
| 跨版本聚合（4 条，多跳） | 4 | 4 | 4 | 4 |
| 无记录/越界拒答（7 条） | 7 | 7 | 7 | 7 |
| 陷阱题（18 条，规则定义） | 18 | 18 | 18 | 18 |
| 回答自检 | — | — | — | 47/47 |
| Jev 开销 | — | — | — | $0.0028 / 32 次 · 1147ms |
查询理解盲测 48 条（期望只看解析结果）
48/48：主体 37/37、版本 10/10、技能 14/14、字段 19/19、模式 3/3、意图与守卫 9/9。
三、Jev 的净贡献（含负面结论）
| 结论 | 证据 | |
|---|---|---|
| ＋ | 候选歧义时把正确行捞回来 | 定点命中@1 14/15 → 15/15（问题用词与字段标签不一致的场景） |
| ＋ | 回答自检，没有替代品 | 逐条核对回答与证据：同源 47/47、盲测 20/20 最低支持度 ≥ 0.5 |
| ＋ | 成本可忽略 | $0.0001/次、约 1.2s；无 key 时自动降级并写进轨迹 |
| ＋ | 置信闸门 | noul 分差 < 0.15 时不改顺序（两条无法区分的候选同样正确），盲测命中@1 由 19/20 回到 20/20 |
| － | 三种排序在同源案例上打平 | 元数据过滤后候选常只剩 1–6 条，BM25/向量/混合没有差别——这是过滤先于排名的必然结果 |
| － | 解析层没有用 Jev | 字段与意图识别用确定性正则，48 条盲测全过且零延迟 |
快速开始
# 1. 依赖：Python 3.12+ 与 numpy
python -m pip install numpy
# 2. 模型（约 1.7 GB，脚本按 SHA-256 校验）
python scripts/download_runtime.py
python scripts/download_models.py
# 3. 语料（需要联网：Data Dragon + 国服公告）
python scripts/build_aliases.py
python scripts/ingest_qq.py --count 30 --pages 90 # 想快就 --count 10
# 4. 启动（首次会构建向量索引）
python launch.py
# 浏览器打开 http://127.0.0.1:18890
停止：python launch.py --stop，或运行 停止服务.cmd。
Jev（可选）
$env:TYPESAFE_API_KEY = "sk-..." # 或写入 runtime/jev-key.txt
没有 key 时系统照常工作，只是不做重排与自检（/api/health 会显示 jev.enabled=false）。
能问什么
| 问法 | 行为 |
|---|---|
26.17 亚索改了什么 | 该版本该英雄的全部结构化改动 |
16.17 岚切怎么调整的 | Data Dragon 版号自动换算到公告版号 26.17 |
15.13 希瓦娜 W 冷却 | 2025 赛季两套版本号（15.x / 25.x）都能落到正确版本 |
26.17 薇恩 W 真实伤害是多少 | 先按字段过滤，再由 Jev 选出最匹配的一条 |
26.17 有哪些英雄被削弱 | 该版本改动清单（默认只看召唤师峡谷） |
赛娜从 26.13 到 26.18 一共改了几次 | 跨版本聚合：逐版本时间线 + 方向统计 + 最常被改的字段，并说明其它模式被略过多少条 |
沃利贝尔历次被削弱的记录 | 不带版本范围时按全部收录版本聚合，可再按方向收窄 |
娜美 E 每次伤害改成多少了 | 未写版本且最新版没有 → 回退到最近一次改动并标注历史版本 |
26.17 亚索为什么被调整 | 附上公告里的设计说明（叙述语料） |
26.18 阿卡丽改了什么 | 该版本没有记录时，提示其它版本里有记录 |
命令
python -m unittest discover -s tests # 89 项，不需要模型与网络
python scripts/ingest_qq.py --offline # 用已缓存公告重建语料
python scripts/corpus_stats.py # 语料统计表（docs/语料统计.md）
python scripts/build_aliases.py --offline # 重建英雄/装备别名表
python scripts/evaluate_parse.py # 查询理解盲测（不需要模型）
python scripts/evaluate_patch.py # 四口径 A/B（需模型在跑；Jev 需要 key）
python scripts/calibrate.py --report # 门槛测量（结论：不采用）
python scripts/ingest_en.py --offline # 与英文公告对照核验
python scripts/review_feedback.py # 复核页面反馈，产出 docs/反馈复核.md
# 盲测（先按 docs/盲测集提示词.md 出题）：
python scripts/evaluate_patch.py --cases tests\cases\blind_cases.json --out docs\盲测报告.md
数据边界（请按此引用本项目）
- 主语料是国服官方公告正文，覆盖英雄、装备与系统数值改动；皮肤、炫彩、云顶、模式机制不在抽取范围。
- 公告里没有写的版本内热修不在语料中，系统会明确提示而不是猜。
- 公告只记录改动，因此「最近一次调整」不等于「当前实际数值」。
- 国服公告数值与其它服务器可能不同，本项目以国服为准，不做跨服务器断言。
- 解析可能漏项：
docs/解析覆盖率.md记录每个版本的解析量与未识别字段。
版权
公告原文只保存在本地 data/patch/（已被 .gitignore 排除），仓库里只有抓取解析脚本、统计与少量测试样例。
数据来源与许可见 THIRD_PARTY_NOTICES.md。
目录
config.py 端口与路径的单一来源
engine.py BM25 + 向量 + RRF 检索内核与门槛
patch_engine.py 版本解析、元数据过滤、答案渲染、Jev 接入点
patch_schema.py 字段键、箭头/技能行解析、句子的唯一定义处
jev.py TypeSafe System One 客户端（重排 / 分类 / 自检）
server.py 本地 HTTP API 与静态页面
launch.py 三进程监督（Windows Job Object，退出即回收）
scripts/ ingest_qq / build_aliases / corpus_stats / evaluate_* / calibrate / ingest_en / review_feedback
tests/ 89 项单元测试 + 手写样例语料 + 盲测集
web/ 单页工作台（问答 / 结构 / 数据 / 版本对比）
docs/ 评测报告、盲测报告、语料统计、门槛校准、对照核验、交接文档