Vincentwei1021/anything2explainer

given-names: Yihao     alias: Vincentwei1021 repository-code: "https://github.com/Vincentwei1021/anything2explainer"

alias: Vincentwei1021 repository-code: "https://github.com/Vincentwei1021/anything2explainer" url: "https://github.com/Vincentwei1021/anything2explainer"

repository-code: "https://github.com/Vincentwei1021/anything2explainer"

url: "https://github.com/Vincentwei1021/anything2explainer"

Required Notice: Copyright (c) 2026 Vincent Wei (https://github.com/Vincentwei1021/anything2explainer)

<https://polyformproject.org/licenses/noncommercial/1.0.0>

> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)

[![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-D97757?logo=anthropic&logoColor=white)](https://claude.com/claude-code)

[![Codex](https://img.shields.io/badge/Codex-skill-000000)](https://openai.com/codex)

[![Remotion](https://img.shields.io/badge/Remotion-4.0-0B84F3)](https://remotion.dev)

[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial-informational)](LICENSE)

**Topic in, narrated explainer video out.** anything2explainer is a [Claude Code](https://claude.com/claude-code) / [Codex](https://openai.com/codex) skill that turns any topic into a black-canvas motion-graphics explainer video with TTS vo

https://github.com/user-attachments/assets/e2771c68-a28c-4459-ac5a-a5b685181eeb

https://github.com/user-attachments/assets/5c213990-cbba-439e-8371-fbb3aa348e05

git clone https://github.com/Vincentwei1021/anything2explainer.git

sudo apt install zsh espeak-ng                 # scripts are #!/bin/zsh; espeak-ng for kokoro/piper G2P

sudo apt install chromium                       # or chromium-browser

The toolkit: [PolyForm Noncommercial 1.0.0](LICENSE) — free for noncommercial use; commercial use requires prior authorization from the author. **Videos you make with it are yours.** The four bundled fonts (Noto Sans SC / Orbitron / Exo 2 /

Remotion itself has its own license terms for companies — see [remotion.dev/license](https://remotion.dev/license).

<a href="https://www.star-history.com/?type=date&repos=Vincentwei1021%2Fanything2explainer">

<picture>    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&theme=dark&legend=top-left" />    <source media="(prefers-color-scheme: light)" srcset="h

<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&theme=dark&legend=top-left" />

<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&legend=top-left" />

<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&legend=top-left" />

[![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-D97757?logo=anthropic&logoColor=white)](https://claude.com/claude-code)

[![Codex](https://img.shields.io/badge/Codex-skill-000000)](https://openai.com/codex)

[![Remotion](https://img.shields.io/badge/Remotion-4.0-0B84F3)](https://remotion.dev)

[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial-informational)](LICENSE)

**给一个主题，产出一条带配音的科普讲解视频。** anything2explainer 是一个 [Claude Code](https://claude.com/claude-code) / [Codex](https://openai.com/codex) skill：输入任意主题，输出一条黑底 MG（motion graphics）风格的讲解视频，带 TTS 配音、字幕和章节进度条，中文或英文都行。画面全部由 [Remotion](https://remotion.de

https://github.com/user-attachments/assets/5c213990-cbba-439e-8371-fbb3aa348e05

https://github.com/user-attachments/assets/e2771c68-a28c-4459-ac5a-a5b685181eeb

git clone https://github.com/Vincentwei1021/anything2explainer.git

sudo apt install zsh espeak-ng                 # 脚本是 #!/bin/zsh；espeak-ng 供 kokoro/piper 的 G2P

sudo apt install chromium                       # 或 chromium-browser

工具包本身：[PolyForm Noncommercial 1.0.0](LICENSE)——非商业使用免费，商业使用需事先获得作者授权。**用它做出来的视频归你自己**。 模板内四款字体（Noto Sans SC / Orbitron / Exo 2 / Audiowide）按 SIL OFL 1.1 单独授权，版权与许可全文见 [`template/public/fonts/LICENSE.md`](template/public/fonts/LICENSE.md)。 R

Remotion 自身对公司用户另有授权要求，见 [remotion.dev/license](https://remotion.dev/license)。

<a href="https://www.star-history.com/?type=date&repos=Vincentwei1021%2Fanything2explainer">

<picture>    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&theme=dark&legend=top-left" />    <source media="(prefers-color-scheme: light)" srcset="h

<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&theme=dark&legend=top-left" />

<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&legend=top-left" />

<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Vincentwei1021/anything2explainer&type=date&legend=top-left" />

- 每个镜头至少出 **6 张 still**：入场首帧+1、入场中段、入场完成、中间关键帧、离场中段、末帧。命令：`RAG/script/still.sh RagGn <帧号,逗号分隔> <输出目录> gN`（**tag 固定为本组 gN，一个组只留一个 bundle**；改代码后 `rm -rf remotion/build_dev_gN` 再跑；bundle 已精简为 ≈110MB，仍不要堆多个）。**禁止**直接 `npx remotion still src/ind

**定义与出处** - RAG = Retrieval-Augmented Generation（检索增强生成）。术语来自 Lewis 等人的论文《Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks》，Facebook AI Research（Meta），发表于 **NeurIPS 2020**。核心思想：把"参数化记忆"（预训练 seq2seq 语言模型，原文用 BART）与"非参数化记忆"（维基

- RAG = Retrieval-Augmented Generation（检索增强生成）。术语来自 Lewis 等人的论文《Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks》，Facebook AI Research（Meta），发表于 **NeurIPS 2020**。核心思想：把"参数化记忆"（预训练 seq2seq 语言模型，原文用 BART）与"非参数化记忆"（维基百科的稠密向量索引，

- 长上下文的"分界线"参考：Anthropic 在 Contextual Retrieval 博文中给出经验阈值——知识库 **< 20 万 token（约 500 页）** 时，可直接把整个知识库放进 prompt（配合 prompt caching），不必上 RAG；超过则需要 RAG。来源：https://www.anthropic.com/news/contextual-retrieval（2024）

- 长上下文并非"免费"：Liu 等人《Lost in the Middle》（TACL 2023/2024）发现模型对上下文**开头和结尾**信息利用最好，**中间**显著变差（U 形曲线），即使是专门的长上下文模型也如此。来源：https://arxiv.org/abs/2307.03172（2023）

- **难点**：PDF 没有"段落"概念，多栏排版、页眉页脚、跨页表格、扫描件都需要**版面分析（layout analysis）+ OCR**。 - **工具举例**：   - **Docling**（IBM 开源，LF AI & Data 基金会项目，MIT 许可）：支持 PDF/DOCX/PPTX/XLSX/HTML/图片/音频，做版面检测、阅读顺序、表格结构识别、OCR，可直接接 LangChain/LlamaIndex。来源：https://github.com/

- **工具举例**：   - **Docling**（IBM 开源，LF AI & Data 基金会项目，MIT 许可）：支持 PDF/DOCX/PPTX/XLSX/HTML/图片/音频，做版面检测、阅读顺序、表格结构识别、OCR，可直接接 LangChain/LlamaIndex。来源：https://github.com/docling-project/docling（2025–2026）   - **MinerU**（上海 AI Lab / OpenDataLab）：

- **Docling**（IBM 开源，LF AI & Data 基金会项目，MIT 许可）：支持 PDF/DOCX/PPTX/XLSX/HTML/图片/音频，做版面检测、阅读顺序、表格结构识别、OCR，可直接接 LangChain/LlamaIndex。来源：https://github.com/docling-project/docling（2025–2026）

- **MinerU**（上海 AI Lab / OpenDataLab）：PDF→Markdown/JSON，公式转 LaTeX、表格转 HTML，OCR 支持 109 种语言；当前版本 3.x，采用 MinerU2.5-Pro VLM 模型，页面自报 OmniDocBench 约 86.47%。来源：https://github.com/opendatalab/MinerU（2026）

| 策略 | 做法 | 典型参数 / 出处 | |---|---|---| | 固定长度 | 按 token/字符数切，可设 overlap | 常见 256–1024 token；LlamaIndex 默认 chunk_size=1024、overlap=20。来源：https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（2025） |

|---|---|---| | 固定长度 | 按 token/字符数切，可设 overlap | 常见 256–1024 token；LlamaIndex 默认 chunk_size=1024、overlap=20。来源：https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（2025） | | 递归分割 | 按分隔符层级（段→句→词）递归切

| 固定长度 | 按 token/字符数切，可设 overlap | 常见 256–1024 token；LlamaIndex 默认 chunk_size=1024、overlap=20。来源：https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（2025） |

| 递归分割 | 按分隔符层级（段→句→词）递归切，尽量不切断段落/句子 | LangChain RecursiveCharacterTextSplitter；Chroma 实测建议分隔符加上句号/问号。来源：https://www.trychroma.com/research/evaluating-chunking（2024） |

| 语义分块 | 计算相邻句子 embedding 相似度，在"话题跳变"处切 | LlamaIndex SemanticSplitter，breakpoint_percentile_threshold 默认 95；思路源自 Greg Kamradt。来源：https://developers.llamaindex.ai/python/examples/node_parsers/semantic_chunking/（2025） |

| 父子块（小块检索、大块返回） | 用小块做 embedding 匹配，命中后返回其父块给 LLM | LangChain ParentDocumentRetriever 示例：父块 2000 字符、子块 400 字符；LlamaIndex AutoMergingRetriever 默认三层 2048/512/128。来源：https://github.com/langchain-ai/langchain（源码 docstring，2025）；https://develop

| Late Chunking | 先把**整篇**送入长上下文 embedding 模型，再在 token 向量层面切块并池化，让每块向量"带着全文语境" | Jina AI，Günther 等，arXiv 2409.04701（2024，修订 2025）。来源：https://arxiv.org/abs/2409.04701 |

| Contextual Retrieval | 索引前让 LLM 为每个块生成 50–100 token 的"上下文说明"（如"本块来自 ACME 公司 2023 Q2 财报"）再一起 embedding / 建 BM25 | Anthropic 2024-09-19。**实测数字**：Contextual Embeddings 单独把 top-20 检索失败率降低 **35%**（5.7%→3.7%）；+ Contextual BM25 降低 **49%**（→2.9%）

| 树状摘要（RAPTOR） | 递归聚类 + 摘要成树，检索时可在不同抽象层取材 | Sarthi 等，arXiv 2401.18059（2024）；配 GPT-4 在 QuALITY 上绝对提升 20%。来源：https://arxiv.org/abs/2401.18059 |

- **块大小的实证**：   - Chroma 技术报告（2024-07）：在 text-embedding-3-large 上，递归分割 **200 token、无重叠**表现很好；不同策略召回率差距可达 9%；OpenAI 助手默认的 800 token / 400 overlap 表现"略低于平均"。来源：https://www.trychroma.com/research/evaluating-chunking（2024）

- Chroma 技术报告（2024-07）：在 text-embedding-3-large 上，递归分割 **200 token、无重叠**表现很好；不同策略召回率差距可达 9%；OpenAI 助手默认的 800 token / 400 overlap 表现"略低于平均"。来源：https://www.trychroma.com/research/evaluating-chunking（2024）

- NVIDIA 博客（2025-06）：**页级分块**平均准确率 0.648 最高且最稳定；128 与 2048 token 两个极端最差；中等 512–1024 token 普遍较好，但随数据类型变化。来源：https://developer.nvidia.com/blog/finding-the-best-chunking-strategy-for-accurate-ai-responses/（2025）

- Pinecone 建议测试区间：128–256 token（细粒度）到 512–1024 token（保留更多上下文）。来源：https://www.pinecone.io/learn/chunking-strategies/（2025）

### 2.4 元数据与权限 - 每个块携带元数据：来源文件、页码、标题路径、更新时间、作者、**ACL（允许访问的用户/组）**、租户 ID。查询时先按元数据**预过滤**再做向量相似度，避免"先查到再删"带来的泄露与 top-k 不足。来源：LlamaIndex 元数据过滤说明 https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（20

- 每个块携带元数据：来源文件、页码、标题路径、更新时间、作者、**ACL（允许访问的用户/组）**、租户 ID。查询时先按元数据**预过滤**再做向量相似度，避免"先查到再删"带来的泄露与 top-k 不足。来源：LlamaIndex 元数据过滤说明 https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（2025）

- 多租户：Weaviate 为每个租户分配独立分片与向量索引，单节点可承载 5 万+活跃租户。来源：https://docs.weaviate.io/weaviate/concepts/data（2025）

- Qdrant 的"可过滤 HNSW"：为已建 payload 索引的字段在 HNSW 图上增加额外边，使过滤与向量搜索同步进行；建议先建 payload 索引再灌数据。来源：https://qdrant.tech/documentation/concepts/indexing/（2025）

- 安全视角：OWASP LLM Top 10（2025 版）单列 **LLM08 "向量与嵌入弱点"**，明确多租户环境下"一组的 embedding 可能被另一组的查询检出"，要求"细粒度访问控制与权限感知的向量库"。来源：https://genai.owasp.org/llmrisk/llm082025-vector-and-embedding-weaknesses/（2025）

### 2.5 Embedding（把文本变成向量） - **原理一句话**：用神经网络（多为 Transformer 双编码器）把一段文本映射为固定长度的实数向量，使语义相近的文本在向量空间中距离近（余弦相似度/点积）。稠密检索的奠基工作 DPR（Karpukhin 等，EMNLP 2020）报告 top-20 检索准确率比 BM25 高 9–19 个百分点。来源：https://arxiv.org/abs/2004.04906（2020）

- **原理一句话**：用神经网络（多为 Transformer 双编码器）把一段文本映射为固定长度的实数向量，使语义相近的文本在向量空间中距离近（余弦相似度/点积）。稠密检索的奠基工作 DPR（Karpukhin 等，EMNLP 2020）报告 top-20 检索准确率比 BM25 高 9–19 个百分点。来源：https://arxiv.org/abs/2004.04906（2020）

- **维度范围**：从 384 维（all-MiniLM-L6-v2，Hugging Face 月下载 2.5 亿次量级）到 4096 维（Qwen3-Embedding-8B）；主流 1024–3072。来源：https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2（2026 抓取）；https://qwenlm.github.io/blog/qwen3-embedding/（2025）

| 模型 | 维度 | 上下文 | 语言 | 备注 / 来源 | |---|---|---|---|---| | BAAI bge-m3（开源） | 1024 | 8192 token | 100+ | 同时支持稠密/稀疏/多向量三种检索。https://arxiv.org/abs/2402.03216（2024） |

|---|---|---|---|---| | BAAI bge-m3（开源） | 1024 | 8192 token | 100+ | 同时支持稠密/稀疏/多向量三种检索。https://arxiv.org/abs/2402.03216（2024） | | Qwen3-Embedding 0.6B/4B/8B（开源，Apache 2.0） | 1024/2560/4096，支持 MRL | 32k token | 100+ | 8B 版发布时（2025-06-05）以 **

| BAAI bge-m3（开源） | 1024 | 8192 token | 100+ | 同时支持稠密/稀疏/多向量三种检索。https://arxiv.org/abs/2402.03216（2024） |

| Qwen3-Embedding 0.6B/4B/8B（开源，Apache 2.0） | 1024/2560/4096，支持 MRL | 32k token | 100+ | 8B 版发布时（2025-06-05）以 **70.58** 分居 MTEB 多语言榜首。https://qwenlm.github.io/blog/qwen3-embedding/（2025）；https://arxiv.org/abs/2506.05176 |

| OpenAI text-embedding-3-small / -large | 1536 / 3072，可截短 | 8192 token | — | 官方页 MTEB 分数 62.3% / 64.6%（2024 年口径）。https://developers.openai.com/api/docs/guides/embeddings |

| Google gemini-embedding-001 / gemini-embedding-2 | 默认 3072，可截 768/1536 | 2048 / 8192 token | 100+ | 001 版 2025-07 GA，官方称自 3 月实验版起"稳居 MTEB 多语言榜前列"，$0.15/百万 token；embedding-2 为多模态。https://developers.googleblog.com/en/gemini-embedding-availa

| Voyage voyage-4 系列（voyage-4-large/4/4-lite，含开源 voyage-4-nano） | 默认 1024，可选 256–2048 | 32k token | — | 另有代码/金融/法律领域模型。https://docs.voyageai.com/docs/embeddings（2026）；Voyage 于 2025 年并入 MongoDB【待核 官方公告链接】 |

- **MTEB 榜单地位**：MTEB（Muennighoff 等，2022）最初含 8 类任务、58 个数据集、112 种语言；2025 年扩为 **MMTEB**（ICLR 2025）：500+ 任务、250+ 语言。榜单排名月度变动大，视频中只宜说"某模型在发布时登顶"，勿说"当前第一"。来源：https://arxiv.org/abs/2210.07316（2022）；https://arxiv.org/abs/2502.13595（2025）。**2026-09 

- **为什么要近似**：暴力比对（Flat）是 O(N·d)，百万级向量每次查询都要算百万次距离；ANN 用少量精度换几十到几百倍速度。 - **三类核心结构（一句话原理）**：   - **HNSW**（Malkov & Yashunin，arXiv 2016，后刊于 IEEE TPAMI【待核 期刊卷期】）：多层"可导航小世界图"，上层稀疏用于快速定位、下层稠密用于精确逼近，作者称查询复杂度达到**对数级**。关键参数 M（每点边数）、ef_construction、e

- **三类核心结构（一句话原理）**：   - **HNSW**（Malkov & Yashunin，arXiv 2016，后刊于 IEEE TPAMI【待核 期刊卷期】）：多层"可导航小世界图"，上层稀疏用于快速定位、下层稠密用于精确逼近，作者称查询复杂度达到**对数级**。关键参数 M（每点边数）、ef_construction、ef_search；Qdrant 默认 m=16、ef_construct=100。来源：https://arxiv.org/abs/1603

- **HNSW**（Malkov & Yashunin，arXiv 2016，后刊于 IEEE TPAMI【待核 期刊卷期】）：多层"可导航小世界图"，上层稀疏用于快速定位、下层稠密用于精确逼近，作者称查询复杂度达到**对数级**。关键参数 M（每点边数）、ef_construction、ef_search；Qdrant 默认 m=16、ef_construct=100。来源：https://arxiv.org/abs/1603.09320（2016）；https://qd

- **IVF**（倒排文件）：先 k-means 把向量分到 nlist 个"格子"（Voronoi 单元），查询时只搜最近的 nprobe 个格子。来源：https://github.com/facebookresearch/faiss/wiki/Faiss-indexes

- **PQ**（乘积量化）：把 d 维向量切成 M 段，每段用 8 bit 码本近似，内存从每向量 4d 字节压到 M 字节量级（如 768 维 float32 ≈ 3 KB → PQ 后几十字节）。来源：同上；FAISS 起源论文 Johnson 等《Billion-scale similarity search with GPUs》，arXiv 1702.08734（2017） - **常见向量数据库/引擎**（均支持 HNSW）：FAISS（Meta 开源库，非服务）

- **常见向量数据库/引擎**（均支持 HNSW）：FAISS（Meta 开源库，非服务）；Milvus（Zilliz 发起，LF AI & Data 项目，支持 HNSW/IVF/DiskANN/GPU CAGRA，自称支撑"百亿级"向量，文档当前为 3.0.x）；Qdrant；Weaviate；**pgvector**（Postgres 扩展，支持 HNSW 与 IVFFlat，vector 类型最高 16000 维，普通索引 ≤2000 维，当前 0.8.x）；Ela

### 2.7 混合检索（Hybrid Search） - **BM25**（Robertson、Spärck Jones 等 1970–80 年代概率检索框架，Okapi 系统得名）：基于词频、逆文档频率、文档长度归一化的词袋打分；典型参数 k1∈[1.2, 2.0]，b=0.75。擅长精确词、型号、人名、代码符号。来源：https://en.wikipedia.org/wiki/Okapi_BM25

- **BM25**（Robertson、Spärck Jones 等 1970–80 年代概率检索框架，Okapi 系统得名）：基于词频、逆文档频率、文档长度归一化的词袋打分；典型参数 k1∈[1.2, 2.0]，b=0.75。擅长精确词、型号、人名、代码符号。来源：https://en.wikipedia.org/wiki/Okapi_BM25

- **向量检索**擅长同义改写、跨语言、模糊描述；两者互补。BEIR 基准（NeurIPS 2021）指出 BM25 是"稳健基线"，零样本下不少稠密模型反而不如它。来源：https://arxiv.org/abs/2104.08663（2021）

- **RRF 融合公式**（Cormack、Clarke、Büttcher，SIGIR 2009）：   `RRFscore(d) = Σ_r 1 / (k + rank_r(d))`，原文 k=60，作者称"k=60 接近最优，但取值并不关键"；RRF 平均比最佳单系统高 4–5%。来源：http://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf（2009）。Elasticsearch 的 rank_constant 默认也是 6

`RRFscore(d) = Σ_r 1 / (k + rank_r(d))`，原文 k=60，作者称"k=60 接近最优，但取值并不关键"；RRF 平均比最佳单系统高 4–5%。来源：http://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf（2009）。Elasticsearch 的 rank_constant 默认也是 60。来源：https://www.elastic.co/docs/reference/elasticsear

- Weaviate 另提供 relativeScoreFusion（归一化分数加权，alpha 控制两路权重），自 v1.24 起为默认，内部测试召回率约提升 6%。来源：https://weaviate.io/blog/hybrid-search-fusion-algorithms（2023）

- Anthropic 实测：在 contextual embedding 之上叠加 contextual BM25，失败率再从 3.7% 降到 2.9%。来源：https://www.anthropic.com/news/contextual-retrieval（2024）

### 2.8 增量更新与新鲜度 - 以 doc_id + 内容哈希跟踪每篇文档，变更时只重嵌入受影响的块（LlamaIndex `refresh_ref_docs` 即"同 id、不同内容才更新"）。来源：https://developers.llamaindex.ai/python/framework/module_guides/indexing/document_management/（2025）

- 以 doc_id + 内容哈希跟踪每篇文档，变更时只重嵌入受影响的块（LlamaIndex `refresh_ref_docs` 即"同 id、不同内容才更新"）。来源：https://developers.llamaindex.ai/python/framework/module_guides/indexing/document_management/（2025）

- 注意 HNSW 删除代价高（FAISS 的 IndexHNSWFlat 不支持删除，需标记删除/重建）。来源：https://github.com/facebookresearch/faiss/wiki/Faiss-indexes

- 时效性问题不只在文档侧：FreshLLMs（Google，2023）显示"所有模型（无论大小）在快速变化的知识和错误前提问题上都表现糟糕"，且"检索证据的数量与顺序都关键"。来源：https://arxiv.org/abs/2310.03214（2023）

- 图结构方案的更新成本是分歧点：GraphRAG 需重建社区摘要，LightRAG（2024）主打"增量更新算法，无需全量重建索引"。来源：https://arxiv.org/abs/2410.05779（2024）

### 3.1 查询改写（Query Transformation） - **Query Rewriting**：用 LLM 把口语化/含上下文指代的问题改写成适合检索的查询。代表工作 Ma 等《Query Rewriting for Retrieval-Augmented LLMs》提出 Rewrite-Retrieve-Read 框架（EMNLP 2023）。来源：https://arxiv.org/abs/2305.14283（2023）

- **Query Rewriting**：用 LLM 把口语化/含上下文指代的问题改写成适合检索的查询。代表工作 Ma 等《Query Rewriting for Retrieval-Augmented LLMs》提出 Rewrite-Retrieve-Read 框架（EMNLP 2023）。来源：https://arxiv.org/abs/2305.14283（2023）

- **Multi-query**：让 LLM 生成同一问题的多个变体分别检索，取并集，缓解"一种表述查不到"的问题。LangChain MultiQueryRetriever 默认生成 **3** 个版本。来源：LangChain 源码 docstring https://github.com/langchain-ai/langchain（2025）

- **HyDE**（Hypothetical Document Embeddings，Gao 等 2022）：先让 LLM"编"一段可能的答案文档，用它的向量去检索真实文档——"以答找答"比"以问找答"更贴近文档分布。来源：https://arxiv.org/abs/2212.10496（2022）

- **Step-back prompting**（Google DeepMind，ICLR 2024）：先问一个更抽象的"退一步"问题（原理/背景），再回到具体问题；原文在物理/化学 QA 上提升 7–11%，时间推理提升 27%，多跳提升 7%。来源：https://arxiv.org/abs/2310.06117（2023）

- **路由 / 自适应**：Adaptive-RAG（NAACL 2024）用分类器按问题复杂度分流到"不检索 / 单步检索 / 多步检索"。来源：https://arxiv.org/abs/2403.14403（2024）

### 3.2 检索 top-k 的典型值 - 框架默认值：LlamaIndex similarity_top_k 默认 **2**（文档建议块变小则加倍到 4）；LangChain 向量检索器默认 **k=4**。来源：https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（2025）；LangChain 源码 https://github

- 框架默认值：LlamaIndex similarity_top_k 默认 **2**（文档建议块变小则加倍到 4）；LangChain 向量检索器默认 **k=4**。来源：https://developers.llamaindex.ai/python/framework/optimizing/basic_strategies/basic_strategies/（2025）；LangChain 源码 https://github.com/langchain-ai/lang

- 生产实践是"**两阶段**"：先粗召回 20–100 条，再重排取 3–10 条。Anthropic 实验比较 5/10/20 块，**20 块最好**；Pinecone 示例取 top-25 再重排到 top-3。来源：https://www.anthropic.com/news/contextual-retrieval（2024）；https://www.pinecone.io/learn/series/rag/rerankers/

### 3.3 重排 Rerank - **为什么需要**：Embedding 双编码器把整段压成一个向量，会丢信息；**Cross-encoder** 把"问题+候选段"拼在一起过一遍 Transformer，直接打相关分，更准但慢——Pinecone 估算：用小 BERT 重排 4000 万条记录在 V100 上要 50+ 小时，而向量检索 <100 ms，因此只能对少量候选重排。来源：https://www.pinecone.io/learn/series/rag/re

- **为什么需要**：Embedding 双编码器把整段压成一个向量，会丢信息；**Cross-encoder** 把"问题+候选段"拼在一起过一遍 Transformer，直接打相关分，更准但慢——Pinecone 估算：用小 BERT 重排 4000 万条记录在 V100 上要 50+ 小时，而向量检索 <100 ms，因此只能对少量候选重排。来源：https://www.pinecone.io/learn/series/rag/rerankers/

- **模型举例**：   - **bge-reranker-v2-m3**（BAAI，开源，基于 bge-m3，约 0.6B 参数）：输入问题-段落对，直接输出相关分，多语言。来源：https://huggingface.co/BAAI/bge-reranker-v2-m3（2024）   - **Qwen3-Reranker 0.6B/4B/8B**（2025-06，Apache 2.0）。来源：https://arxiv.org/abs/2506.05176（2025）

- **bge-reranker-v2-m3**（BAAI，开源，基于 bge-m3，约 0.6B 参数）：输入问题-段落对，直接输出相关分，多语言。来源：https://huggingface.co/BAAI/bge-reranker-v2-m3（2024）

- **Qwen3-Reranker 0.6B/4B/8B**（2025-06，Apache 2.0）。来源：https://arxiv.org/abs/2506.05176（2025）

- **Cohere Rerank**：rerank-v3.5（2024-12-02 发布）、rerank-v4.0-pro / -fast，单一多语言模型，100+ 语言。来源：https://docs.cohere.com/docs/rerank-overview（2026）；https://cohere.com/blog/rerank-3pt5（2024）

- **ColBERT 晚交互（late interaction）**（Khattab & Zaharia，SIGIR 2020）：文档与查询各自编码成**每个 token 一个向量**，查询时用 MaxSim 做细粒度匹配——介于双编码器与 cross-encoder 之间：可离线预计算，又保留词级交互。来源：https://arxiv.org/abs/2004.12832（2020）。BEIR 也发现"重排与晚交互模型平均零样本效果最好"。来源：https://arxiv

- Anthropic 实测：在混合检索之上再加重排，top-20 失败率从 2.9% 降到 1.9%。来源：https://www.anthropic.com/news/contextual-retrieval（2024）

### 3.4 上下文组装 - **去重与合并**：同一父块的多个子块合并、近重复块去掉（父子块/AutoMerging 机制，见 2.3）。 - **排序与位置**：《Lost in the Middle》（Liu 等，TACL 2023）：模型对**开头和结尾**的信息利用最好、**中间**明显变差，呈 U 形；即便专门的长上下文模型也如此。工程上因此把最相关的块放两端，或直接少放。来源：https://arxiv.org/abs/2307.03172（2023）

- **去重与合并**：同一父块的多个子块合并、近重复块去掉（父子块/AutoMerging 机制，见 2.3）。 - **排序与位置**：《Lost in the Middle》（Liu 等，TACL 2023）：模型对**开头和结尾**的信息利用最好、**中间**明显变差，呈 U 形；即便专门的长上下文模型也如此。工程上因此把最相关的块放两端，或直接少放。来源：https://arxiv.org/abs/2307.03172（2023） - **Context rot**

- **排序与位置**：《Lost in the Middle》（Liu 等，TACL 2023）：模型对**开头和结尾**的信息利用最好、**中间**明显变差，呈 U 形；即便专门的长上下文模型也如此。工程上因此把最相关的块放两端，或直接少放。来源：https://arxiv.org/abs/2307.03172（2023）

- **Context rot**（Chroma，2025-07）：测试 18 个模型（含 GPT-4.1、Claude 4、Gemini 2.5、Qwen3），即使简单任务，可靠性也随输入长度非均匀下降；干扰项的负面影响在长输入下被放大。结论：**并非塞得越多越好**。来源：https://www.trychroma.com/research/context-rot（2025）

- Anthropic 对"上下文工程"的表述：目标是找到"**最小的高信号 token 集合**"。来源：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents（2025）

### 3.5 带引用的生成（Citation / Grounding） - 做法：给每个块编号或带元数据（文件名、页码、URL），要求模型在句末标注引用；或使用模型原生引用能力。 - Anthropic **Citations** 功能：让模型引用源文档中的具体句子/段落；官方称比多数自建方案"召回准确率最高提升 15%"；客户 Endex 报告"来源幻觉与格式问题从 10% 降到 0%，每次回答引用数增加 20%"。来源：https://claude.com/blog/i

- 做法：给每个块编号或带元数据（文件名、页码、URL），要求模型在句末标注引用；或使用模型原生引用能力。 - Anthropic **Citations** 功能：让模型引用源文档中的具体句子/段落；官方称比多数自建方案"召回准确率最高提升 15%"；客户 Endex 报告"来源幻觉与格式问题从 10% 降到 0%，每次回答引用数增加 20%"。来源：https://claude.com/blog/introducing-citations-api（2025，首发 2025

- Anthropic **Citations** 功能：让模型引用源文档中的具体句子/段落；官方称比多数自建方案"召回准确率最高提升 15%"；客户 Endex 报告"来源幻觉与格式问题从 10% 降到 0%，每次回答引用数增加 20%"。来源：https://claude.com/blog/introducing-citations-api（2025，首发 2025-01【日期待核】）

- 可核查的引用本身就是 RAG 相对纯生成的核心卖点（Lewis 2020 把"提供出处 provenance"列为关键问题）。来源：https://arxiv.org/abs/2005.11401

- **先引原文再作答**："让 Claude 先摘出相关引文，再执行任务，有助于聚焦相关内容、忽略其余部分"。 - 明确"**只依据给定资料回答；资料不足时说不知道**"。 来源：https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices（2026，Long context prompting 小节）

来源：https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices（2026，Long context prompting 小节）

### 3.7 护栏（Guardrails） - **拒答/兜底**：检索分数低于阈值或重排后无高分候选时，返回"知识库中没有相关信息"而不是硬答；CRAG 论文正式化了这一思路——用检索评估器判"正确/错误/模糊"，错误时转外部搜索。来源：https://arxiv.org/abs/2401.15884（2024）

- **拒答/兜底**：检索分数低于阈值或重排后无高分候选时，返回"知识库中没有相关信息"而不是硬答；CRAG 论文正式化了这一思路——用检索评估器判"正确/错误/模糊"，错误时转外部搜索。来源：https://arxiv.org/abs/2401.15884（2024）

- **权限过滤**：在检索层按 ACL 预过滤（见 2.4），而不是让 LLM"自觉"不说。OWASP 明确要求"权限感知的向量与嵌入存储"。来源：https://genai.owasp.org/llmrisk/llm082025-vector-and-embedding-weaknesses/（2025）

### 4.1 RAGAS 四个核心指标（官方定义） RAGAS（Es 等，2023；框架强调"无需人工标注的参考答案"也能评估）。来源：https://arxiv.org/abs/2309.15217（2023）

RAGAS（Es 等，2023；框架强调"无需人工标注的参考答案"也能评估）。来源：https://arxiv.org/abs/2309.15217（2023）

来源：https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/faithfulness/ 、.../answer_relevance/ 、.../context_precision/ 、.../context_recall/（2025–2026）

- 类似框架：TruLens 的 **RAG Triad**（Context Relevance、Groundedness、Answer Relevance）。来源：https://www.trulens.org/getting_started/core_concepts/rag_triad/

### 4.2 检索指标（经典 IR） - **Recall@k**：正确文档是否出现在前 k 条（RAG 最常看的指标，因为生成只能用到检索出的内容）。 - **MRR**（平均倒数排名）：每个查询取"第一条相关结果的排名倒数"再平均，只关心第一条命中。来源：https://en.wikipedia.org/wiki/Mean_reciprocal_rank

- **Recall@k**：正确文档是否出现在前 k 条（RAG 最常看的指标，因为生成只能用到检索出的内容）。 - **MRR**（平均倒数排名）：每个查询取"第一条相关结果的排名倒数"再平均，只关心第一条命中。来源：https://en.wikipedia.org/wiki/Mean_reciprocal_rank - **nDCG**（归一化折损累计增益，Järvelin & Kekäläinen 2002）：按位置以 log2(i+1) 折损求相关度累计，再除以理想

- **MRR**（平均倒数排名）：每个查询取"第一条相关结果的排名倒数"再平均，只关心第一条命中。来源：https://en.wikipedia.org/wiki/Mean_reciprocal_rank

- **nDCG**（归一化折损累计增益，Järvelin & Kekäläinen 2002）：按位置以 log2(i+1) 折损求相关度累计，再除以理想排序的 DCG，范围 0–1；适合多级相关性。来源：https://en.wikipedia.org/wiki/Discounted_cumulative_gain

- Anthropic 博文使用的是"**top-20 检索失败率**"（= 1 − Recall@20）。来源：https://www.anthropic.com/news/contextual-retrieval（2024）

### 4.3 常见 Benchmark - **BEIR**（NeurIPS 2021 数据集赛道）：18 个数据集的零样本检索基准；结论"BM25 是稳健基线"。来源：https://arxiv.org/abs/2104.08663（2021）

- **BEIR**（NeurIPS 2021 数据集赛道）：18 个数据集的零样本检索基准；结论"BM25 是稳健基线"。来源：https://arxiv.org/abs/2104.08663（2021）

- **MTEB / MMTEB**：Embedding 模型综合榜（MMTEB 500+ 任务、250+ 语言，ICLR 2025）。来源：https://arxiv.org/abs/2502.13595（2025）

- **RAGBench**（Friel 等，2024）：10 万条样例、5 个行业领域（用户手册等真实语料），提出 TRACe 评估框架；发现微调的 RoBERTa 评估器可胜过 LLM 评估器。来源：https://arxiv.org/abs/2407.11005（2024）

- **HotpotQA**（EMNLP 2018）：11.3 万条多跳问答，检验"需要跨多篇文档推理"的能力。来源：https://arxiv.org/abs/1809.09600（2018）

- **ViDoRe**：ColPali 提出的视觉文档检索基准。来源：https://arxiv.org/abs/2407.01449（2024）

- **FreshQA**：考察时效性知识。来源：https://arxiv.org/abs/2310.03214（2023）

### 4.4 线上指标（工程通识，无单一出处） - 用户显式反馈（👍/👎）、追问率/改写率、引用点击率、"无法回答"占比、人工抽检的幻觉率、P95 延迟、每次问答成本。 - Barnett 等提醒："RAG 系统的验证只有在运行中才可行"，鲁棒性是"演进出来的，而非一开始设计好的"。来源：https://arxiv.org/abs/2401.05856（2024）

- Barnett 等提醒："RAG 系统的验证只有在运行中才可行"，鲁棒性是"演进出来的，而非一开始设计好的"。来源：https://arxiv.org/abs/2401.05856（2024）

- 论文《From Local to Global: A Graph RAG Approach to Query-Focused Summarization》（Edge 等，arXiv 2024-04，v2 2025-02）；微软研究院博文 2024-02-13。 - **核心思路**：用 LLM 从文档抽取实体与关系构成知识图 → 用 **Leiden 算法**分层做社区检测 → 为每个社区预生成摘要 → 回答"全局性问题"（如"这批文档的五大主题是什么"）时，让每个社区摘

- **核心思路**：用 LLM 从文档抽取实体与关系构成知识图 → 用 **Leiden 算法**分层做社区检测 → 为每个社区预生成摘要 → 回答"全局性问题"（如"这批文档的五大主题是什么"）时，让每个社区摘要各出一段部分答案再汇总。 - **实测**：在约 100 万 token（播客）与 170 万 token（新闻）语料上，相对朴素向量 RAG，**全面性胜率 72–83%**、**多样性胜率 62–82%**。来源：https://arxiv.org/abs/2

- **实测**：在约 100 万 token（播客）与 170 万 token（新闻）语料上，相对朴素向量 RAG，**全面性胜率 72–83%**、**多样性胜率 62–82%**。来源：https://arxiv.org/abs/2404.16130 ；https://arxiv.org/html/2404.16130（2024）；https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-d

- **适用/代价**：适合"要把整批文档串起来理解"的全局问题；代价是建图与社区摘要成本高、更新慢。LightRAG（2024）主打图 + 双层检索 + 增量更新，作为更轻的替代。来源：https://arxiv.org/abs/2410.05779（2024）

### 5.2 Agentic RAG / Deep Research - **从"一次检索"到"多轮检索 + 自我反思"**：   - ReAct（ICLR 2023）：推理轨迹与动作（如查维基）交替进行。来源：https://arxiv.org/abs/2210.03629

- **从"一次检索"到"多轮检索 + 自我反思"**：   - ReAct（ICLR 2023）：推理轨迹与动作（如查维基）交替进行。来源：https://arxiv.org/abs/2210.03629   - Self-Ask（2022）：模型先自问自答一串后续问题，再合成答案，可接搜索引擎；提出"组合性鸿沟"。来源：https://arxiv.org/abs/2210.03350

- ReAct（ICLR 2023）：推理轨迹与动作（如查维基）交替进行。来源：https://arxiv.org/abs/2210.03629

- Self-Ask（2022）：模型先自问自答一串后续问题，再合成答案，可接搜索引擎；提出"组合性鸿沟"。来源：https://arxiv.org/abs/2210.03350

- **Self-RAG**（Asai 等，ICLR 2024）：训练模型输出"反思 token"，按需决定是否检索、并对检索结果与自身生成打分批判。来源：https://arxiv.org/abs/2310.11511（2023）

- **CRAG**（Yan 等，2024）：轻量检索评估器给出置信度 → 正确/错误/模糊三种动作，错误时转网页搜索；对文档做"分解-再重组"去噪。来源：https://arxiv.org/abs/2401.15884（2024）

- Agentic RAG 综述（Singh 等，2025）：把"反思、规划、工具使用、多智能体协作"嵌入 RAG 流水线。来源：https://arxiv.org/abs/2501.09136（2025）

- **Deep Research 产品化**：Google Gemini Deep Research 2024-12-11 上线（生成多步研究计划→反复搜索→带引用报告）；OpenAI Deep Research 2025-02 上线，自主浏览网页 5–30 分钟后输出带引用报告。来源：https://blog.google/products/gemini/google-gemini-deep-research/（2024）；https://en.wikipedia.org

### 5.3 多模态 RAG - **ColPali**（Faysse 等，ICLR 2025）：用视觉语言模型直接把**文档页面图像**编码成多向量（ColBERT 式晚交互），跳过 OCR/版面解析，保留表格、图表、版式信息；配套 ViDoRe 基准。后续 ColQwen2 基于 Qwen2-VL。来源：https://arxiv.org/abs/2407.01449（2024）；https://huggingface.co/vidore/colqwen2-v1.0

- **ColPali**（Faysse 等，ICLR 2025）：用视觉语言模型直接把**文档页面图像**编码成多向量（ColBERT 式晚交互），跳过 OCR/版面解析，保留表格、图表、版式信息；配套 ViDoRe 基准。后续 ColQwen2 基于 Qwen2-VL。来源：https://arxiv.org/abs/2407.01449（2024）；https://huggingface.co/vidore/colqwen2-v1.0

- 多模态 embedding：Gemini Embedding 2 支持文本+图像等多模态输入（8192 token）。来源：https://ai.google.dev/gemini-api/docs/embeddings（2026）

- 表格是老大难：TableRAG（Google，NeurIPS 2024）指出整表塞入 prompt 不可扩展，改为"schema 检索 + 单元格检索"处理百万 token 级表格。来源：https://arxiv.org/abs/2410.04739（2024）

### 5.4 长上下文 vs RAG：当前共识与分歧 - **上下文窗口现状**：Gemini 自称"首个 1M token 模型"；Claude Sonnet 4 于 2025-08-12 开放 1M token（"75,000 行代码"或"几十篇论文"）。来源：https://ai.google.dev/gemini-api/docs/long-context ；https://claude.com/blog/1m-context（2025）

- **上下文窗口现状**：Gemini 自称"首个 1M token 模型"；Claude Sonnet 4 于 2025-08-12 开放 1M token（"75,000 行代码"或"几十篇论文"）。来源：https://ai.google.dev/gemini-api/docs/long-context ；https://claude.com/blog/1m-context（2025）

- **对比研究**：Li 等（Google，EMNLP 2024 Industry）：资源充足时长上下文平均更准，但 RAG **成本显著更低**；两者在 63% 的问题上给出完全相同的答案，因此提出 **Self-Route**（先 RAG，模型自判"答不了"再走长上下文），成本降低 65%（Gemini-1.5-Pro）/ 39%（GPT-4o）而效果接近长上下文。来源：https://arxiv.org/abs/2407.16833 ；https://arxiv.or

- Databricks（2024-08，2000+ 次实验、13 个模型）：多给文档先涨后跌，多数模型在 32k–64k 后性能下滑，仅少数（GPT-4o、Claude 3.5 Sonnet 等）保持；失败形态各异（拒答、答错、复读）。来源：https://www.databricks.com/blog/long-context-rag-performance-llms（2024）

### 5.5 上下文工程（Context Engineering，2025） - 出处：2025 年 6 月 Shopify CEO Tobi Lütke 推文主张用"context engineering"取代"prompt engineering"——"核心技能是为任务提供全部上下文，使其能被 LLM 合理解决"；Andrej Karpathy 随后附议："上下文工程是把恰到好处的信息填进上下文窗口以供下一步使用的精妙艺术与科学"。来源（二手引用）：https://si

- 出处：2025 年 6 月 Shopify CEO Tobi Lütke 推文主张用"context engineering"取代"prompt engineering"——"核心技能是为任务提供全部上下文，使其能被 LLM 合理解决"；Andrej Karpathy 随后附议："上下文工程是把恰到好处的信息填进上下文窗口以供下一步使用的精妙艺术与科学"。来源（二手引用）：https://simonwillison.net/2025/Jun/27/context-engi

- LangChain 博文（2025-06-23）定义："构建动态系统，以正确格式提供正确信息与工具，使 LLM 能合理完成任务"。来源：https://www.langchain.com/blog/the-rise-of-context-engineering

- Anthropic 工程博文（2025-09-29）：上下文工程 = "在推理时为 LLM 策划并维护最优 token 集合的策略"；核心原则"最小的高信号 token 集合"；提出 **just-in-time 检索**——智能体只保留轻量标识（文件路径、查询、链接），运行时按需用工具加载，而非预先全部检索塞入。来源：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-ag

### 5.6 Memory 与 RAG - **MemGPT**（Packer 等，2023）：借鉴操作系统虚拟内存，把对话/文档在"主上下文"与"外部存储"间分层分页调度。来源：https://arxiv.org/abs/2310.08560（2023）

- **MemGPT**（Packer 等，2023）：借鉴操作系统虚拟内存，把对话/文档在"主上下文"与"外部存储"间分层分页调度。来源：https://arxiv.org/abs/2310.08560（2023）

- **Mem0**（2025-04）：从对话中抽取并存储要点，按需检索；报告比 OpenAI 记忆方案 LLM-judge 分数相对提升 26%，比全量上下文 p95 延迟低 91%、token 成本省 90%+；图记忆变体再高约 2%。来源：https://arxiv.org/abs/2504.19413（2025）

### 5.7 MCP 与工具化检索 - **MCP**（Model Context Protocol，Anthropic 2024-11-25 开源）："连接 AI 应用与外部系统的开放标准"，官方比喻为"**AI 应用的 USB-C 接口**"；首批预置服务器含 Google Drive、Slack、GitHub、Postgres 等；现已被 Claude、ChatGPT、VS Code、Cursor 等支持。来源：https://www.anthropic.com/ne

- **MCP**（Model Context Protocol，Anthropic 2024-11-25 开源）："连接 AI 应用与外部系统的开放标准"，官方比喻为"**AI 应用的 USB-C 接口**"；首批预置服务器含 Google Drive、Slack、GitHub、Postgres 等；现已被 Claude、ChatGPT、VS Code、Cursor 等支持。来源：https://www.anthropic.com/news/model-context-pr

学术依据：Barnett 等《Seven Failure Points When Engineering a RAG System》（2024）归纳的七类失败点：内容缺失、相关文档未排进 top-k、在候选中但未进上下文、在上下文中但未被提取、格式错误、具体程度不对、答案不完整。来源：https://arxiv.org/abs/2401.05856（2024）

1. **分块切断语义**：固定长度把一句话、一张表切成两半，任一半都无法独立回答问题 → 用递归/语义分块、父子块、contextual retrieval 补语境（Anthropic 实测失败率降 35–67%）。来源：https://www.anthropic.com/news/contextual-retrieval

2. **检索召回不到**：用户用的词和文档不一样、缩写/型号/人名 → 上混合检索（BM25 + 向量）+ 查询改写 + 多查询。来源：BEIR https://arxiv.org/abs/2104.08663

3. **检索到但没用上**（"Not extracted"）：相关块在上下文中间被忽略，或被噪声块淹没 → 重排、少而精、把关键块放两端、先引原文再答。来源：Lost in the Middle https://arxiv.org/abs/2307.03172 ；Barnett FP4

4. **多跳问题**：答案需要串联多篇文档，一次检索拿不全 → 多轮/智能体式检索（Self-Ask、Self-RAG、CRAG）、GraphRAG。来源：HotpotQA https://arxiv.org/abs/1809.09600

5. **表格与数字**：表格被打平成文字后行列对应关系丢失，数字被错读 → 保留表格结构（HTML/Markdown）、schema+单元格检索、或走视觉检索。来源：TableRAG https://arxiv.org/abs/2410.04739 ；ColPali https://arxiv.org/abs/2407.01449

6. **过期文档**：旧版本与新版本同时在库，模型引用了作废内容 → 元数据带版本/时间、去重、增量刷新、时效性优先排序。来源：FreshLLMs https://arxiv.org/abs/2310.03214 ；LlamaIndex refresh_ref_docs

7. **权限泄露**：多租户共用索引、先查后过滤 → 检索前按 ACL 预过滤、租户物理隔离。来源：OWASP LLM08:2025 8. **评估缺失**：上线前只看 demo，不知道召回率与忠实度 → 建 100–300 条黄金问答集，跟踪 Recall@k、Faithfulness 等。来源：RAGAS https://arxiv.org/abs/2309.15217 ；Barnett（"验证只能在运行中进行"） 9. **成本/延迟**：每问都过大模型重排 + 长上

8. **评估缺失**：上线前只看 demo，不知道召回率与忠实度 → 建 100–300 条黄金问答集，跟踪 Recall@k、Faithfulness 等。来源：RAGAS https://arxiv.org/abs/2309.15217 ；Barnett（"验证只能在运行中进行"）

9. **成本/延迟**：每问都过大模型重排 + 长上下文 → 两阶段检索、Self-Route 按需走长上下文（省 39–65%）、prompt caching（contextual retrieval 一次性成本 $1.02/百万 token）。来源：https://arxiv.org/html/2407.16833 ；https://www.anthropic.com/news/contextual-retrieval

| # | 可直接讲的事实 | 出处 | 可信度 | |---|---|---|---| | 1 | RAG 一词来自 2020 年 Meta（Facebook AI）的 NeurIPS 论文，最初是"语言模型 + 维基百科向量索引" | https://arxiv.org/abs/2005.11401 | ★★★ |

|---|---|---|---| | 1 | RAG 一词来自 2020 年 Meta（Facebook AI）的 NeurIPS 论文，最初是"语言模型 + 维基百科向量索引" | https://arxiv.org/abs/2005.11401 | ★★★ | | 2 | Anthropic 实测：给每个块补 50–100 token 的"上下文说明"，top-20 检索失败率降 35%；再叠加 BM25 降 49%；再加重排降 67%（5.7%→1.9%） | htt

| 1 | RAG 一词来自 2020 年 Meta（Facebook AI）的 NeurIPS 论文，最初是"语言模型 + 维基百科向量索引" | https://arxiv.org/abs/2005.11401 | ★★★ |

| 2 | Anthropic 实测：给每个块补 50–100 token 的"上下文说明"，top-20 检索失败率降 35%；再叠加 BM25 降 49%；再加重排降 67%（5.7%→1.9%） | https://www.anthropic.com/news/contextual-retrieval（2024） | ★★（Anthropic 自有数据集） |

| 3 | 知识库不到 20 万 token（≈500 页）时，可以不用 RAG，直接整个塞进 prompt | 同上 | ★★ | | 4 | Lost in the Middle：模型对上下文开头和结尾记得最牢，中间最容易漏——U 形曲线 | https://arxiv.org/abs/2307.03172（2023） | ★★★ | | 5 | Context rot：2025 年测 18 个前沿模型，输入越长越不可靠，哪怕任务很简单 | https://www.try

| 4 | Lost in the Middle：模型对上下文开头和结尾记得最牢，中间最容易漏——U 形曲线 | https://arxiv.org/abs/2307.03172（2023） | ★★★ |

| 5 | Context rot：2025 年测 18 个前沿模型，输入越长越不可靠，哪怕任务很简单 | https://www.trychroma.com/research/context-rot（2025） | ★★ |

| 6 | 典型 chunk 大小 256–1024 token；LlamaIndex 默认 1024；Chroma 实测 200 token 无重叠效果好；NVIDIA 实测"按页切"最稳 | LlamaIndex 文档；Chroma 2024；NVIDIA 2025 | ★★ | | 7 | HNSW 查询复杂度是对数级：百万向量也只需几十步"跳跃"即可逼近最近邻 | https://arxiv.org/abs/1603.09320（2016） | ★★★（"几十步"为对

| 7 | HNSW 查询复杂度是对数级：百万向量也只需几十步"跳跃"即可逼近最近邻 | https://arxiv.org/abs/1603.09320（2016） | ★★★（"几十步"为对数级的口语化，非原文数字） |

| 8 | RRF 融合公式 1/(60+排名)，k=60 来自 2009 年 SIGIR 论文的试验，作者说"取值不关键" | http://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf | ★★★ |

| 9 | 稠密检索开山作 DPR：top-20 准确率比 BM25 高 9–19 个百分点（2020）；但 BEIR（2021）发现零样本下 BM25 仍是难以击败的基线 | https://arxiv.org/abs/2004.04906 ；https://arxiv.org/abs/2104.08663 | ★★★ |

| 10 | Embedding 维度从 384（MiniLM）到 4096（Qwen3-8B）；Qwen3-Embedding-8B 发布时以 70.58 分登顶 MTEB 多语言榜 | https://qwenlm.github.io/blog/qwen3-embedding/（2025） | ★★★（"发布时"限定） |

| 11 | 重排很贵：小 BERT 重排 4000 万条要 50+ 小时，向量检索 <100 ms——所以只能"粗召回 25 条，精排留 3 条" | https://www.pinecone.io/learn/series/rag/rerankers/ | ★★ |

| 12 | GraphRAG 在 100 万 token 语料上，回答全局性问题时全面性胜率 72–83% | https://arxiv.org/abs/2404.16130（2024） | ★★★（LLM 评审） |

| 13 | RAG vs 长上下文：63% 的问题两者答案完全一样；先 RAG、答不了再长上下文，可省 39–65% 成本 | https://arxiv.org/abs/2407.16833（2024） | ★★★ |

| 14 | Weaviate 单节点可跑 5 万+ 租户，各自独立索引——权限隔离靠架构而非靠模型"自觉" | https://docs.weaviate.io/weaviate/concepts/data | ★★ |

| 15 | OWASP 2025 把"向量与嵌入弱点"列为 LLM 十大风险之一（LLM08） | https://genai.owasp.org/llmrisk/llm082025-vector-and-embedding-weaknesses/ | ★★★ |

| 16 | pgvector 让 Postgres 直接存向量：vector 类型最高 16000 维，支持 HNSW/IVFFlat | https://github.com/pgvector/pgvector | ★★★ |

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

6. 工程层面：`build_dev_<tag>` 原每个 ~820 MB，8 组并行 + `$TMPDIR/remotion-webpack-bundle-*` 曾把磁盘撑满（ENOSPC）。主会话已改 still.sh 为精简 bundle（`--public-dir public_rag`，≈117 MB）并定规则：本组只用 tag `g2`，改代码后 `rm -rf remotion/build_dev_g2` 再跑；不要直接 `npx remotion still 

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

const x0 = cx - w / 2, y0 = cy - h / 2;   const hw = w / 2;   const curl = h * 0.08; // 页面上缘弧度

const hw = w / 2;   const curl = h * 0.08; // 页面上缘弧度   const spineTop = y0 + curl + 6, spineBot = y0 + h;

const curl = h * 0.08; // 页面上缘弧度

const spineTop = y0 + curl + 6, spineBot = y0 + h;

const left = `M${cx},${spineTop} Q${cx - hw * 0.5},${y0 + curl - 4} ${x0},${y0} L${x0},${y0 + h - curl} Q${cx - hw * 0.5},${y0 + h - curl + 6} ${cx},${spineBot} Z`;

const right = `M${cx},${spineTop} Q${cx + hw * 0.5},${y0 + curl - 4} ${x0 + w},${y0} L${x0 + w},${y0 + h - curl} Q${cx + hw * 0.5},${y0 + h - curl + 6} ${cx},${spineBot} Z`;

const lineNodes: React.ReactNode[] = [];   const innerTop = y0 + curl + 26, innerBot = y0 + h - curl - 18;   const step = (innerBot - innerTop) / Math.max(1, lines - 1);

const innerTop = y0 + curl + 26, innerBot = y0 + h - curl - 18;

{lineNodes}         {/* 底部书脊厚度 */}         <path d={`M${x0 + 4},${y0 + h - curl + 2} L${x0 + 4},${y0 + h + 8} Q${cx - hw * 0.5},${y0 + h + 14} ${cx},${spineBot + 8} Q${cx + hw * 0.5},${y0 + h + 14} ${x0 + w - 4},${y0 + h + 8} L${x0 + w - 4}

{/* 底部书脊厚度 */}         <path d={`M${x0 + 4},${y0 + h - curl + 2} L${x0 + 4},${y0 + h + 8} Q${cx - hw * 0.5},${y0 + h + 14} ${cx},${spineBot + 8} Q${cx + hw * 0.5},${y0 + h + 14} ${x0 + w - 4},${y0 + h + 8} L${x0 + w - 4},${y0 + h - curl + 2

<path d={`M${x0 + 4},${y0 + h - curl + 2} L${x0 + 4},${y0 + h + 8} Q${cx - hw * 0.5},${y0 + h + 14} ${cx},${spineBot + 8} Q${cx + hw * 0.5},${y0 + h + 14} ${x0 + w - 4},${y0 + h + 8} L${x0 + w - 4},${y0 + h - curl + 2}`} fill="none" stroke=

- `still.sh` 每次 `npx remotion still` 都会在 `$TMPDIR` 留一份 ~200–340 MB 的 `remotion-webpack-bundle-*`，八组并行时很快写满磁盘（本次 168 份 ≈30 GB，触发 ENOSPC）。建议在脚本末尾追加 `find $TMPDIR -maxdepth 1 -name 'remotion-webpack-bundle-*' -mmin +3 -type d -prune -exec rm -

- 自检：`npx tsc --noEmit` 通过；tag x34（`rm -rf build_dev_x34` 后重 bundle）出 20 张 still 到 `RAG/stills/X34/G3/`（每处改动 f0+4 / f0+12：1542/1550、1618/1626、1667/1675、1823/1831、1929/1937、2008/2016、2067/2075、2177/2185、2502/2510、2610/2618），Read 核对：中段半透明 + 略

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

- 旧 bundle 已由主会话统一清除。后续复现 still/测渲请按新规则：`rag/script/still.sh RagG4 <帧> rag/stills/G4 g4`（tag 固定 `g4`，改代码后先 `rm -rf remotion/build_dev_g4`），测渲输出 `/tmp/rag_test_g4` 看完即删；不要直接 `npx remotion still src/index.ts`。

- `still.sh` 每次 bundle 会在 `$TMPDIR` 留一份 `remotion-webpack-bundle-*`（22–66 MB），本次并行构建累计 105 份 + 各组 `build_dev_*`（每份 ~820 MB）把磁盘写满一次（ENOSPC）。建议 still.sh 末尾加 `find $TMPDIR -maxdepth 1 -name 'remotion-webpack-bundle-*' -mmin +3 -exec rm -rf {} 

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

4. 渲染中途遇到 **磁盘满（ENOSPC）**：`$TMPDIR/remotion-webpack-bundle-*` 累积 6+ GB，已清理（>3 分钟的）；各组 `build_dev_*` 也各 0.8 GB，建议主会话定期清理。按主会话新规则：still 只用 `rag/script/still.sh`，tag 固定 `g5`（精简 bundle ≈117 MB），改代码后 `rm -rf remotion/build_dev_g5` 再跑；旧的 `build_d

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

- still 规则（主会话 18:57 更新）：只用 `still.sh`，tag 固定 `g6`，改代码先 `rm -rf remotion/build_dev_g6`；清盘后用新 bundle 复出 4918/5160/5660 三帧，与此前一致。

Executable file

Executable file

const T_TRAP_IN = B_TAG + 2; // 灰梯形占位 slideUp const T_PAIR_OUT = 4882; // 配对卡 / 相关分 8 帧淡尽 const NC = 25, CW = 38, CH = 50, PITCH = 41, ROW_Y = 205;

const T_PAIR_OUT = 4882; // 配对卡 / 相关分 8 帧淡尽 const NC = 25, CW = 38, CH = 50, PITCH = 41, ROW_Y = 205; const cardCx = (i: number) => 148 + PITCH * i;

const NC = 25, CW = 38, CH = 50, PITCH = 41, ROW_Y = 205;

Executable file

Executable file

const nc = N - T_CTX_IN;

<div style={{position: 'absolute', inset: 0, opacity: opAll}}>       {/* ===== 左：上下文条 ===== */}       {nc >= 0 ? (

{/* ===== 左：上下文条 ===== */}       {nc >= 0 ? (         <div style={{position: 'absolute', inset: 0, transform: `translateY(${ctxDy.toFixed(2)}px)`, opacity: ctxOp}}>

{nc >= 0 ? (

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

const nc = N - T_CARD;

<AbsoluteFill style={{pointerEvents: 'none', opacity: op}}>       {/* 答复卡 */}       {nc >= 0 ? (

{/* 答复卡 */}       {nc >= 0 ? (         <div style={{position: 'absolute', inset: 0, transform: `translateY(${cardDy.toFixed(2)}px)`, opacity: cardOp}}>

{nc >= 0 ? (

Executable file

Executable file

Executable file

Executable file

Executable file

- 磁盘：构建期间磁盘一度只剩 118 MiB（15 个 build_dev bundle ≈11 GB），已通知主会话。按新规则本组 bundle 固定 tag `g8`（`remotion/build_dev_g8`，精简 bundle ≈110 MB），改码后 `rm -rf remotion/build_dev_g8` 再跑 still.sh；已用新版脚本复验 7600/8148 两帧正常。

Executable file

Executable file

Executable file

const N = useCurrentFrame() + F0;   const nIcon = N - 7176;   const nc = N - CNT0;

const nIcon = N - 7176;   const nc = N - CNT0;   const val = nc < 0 ? 0 : Math.round(1e6 * easeOutCubic(clamp01(nc / CNT_LEN)));

const nc = N - CNT0;

const val = nc < 0 ? 0 : Math.round(1e6 * easeOutCubic(clamp01(nc / CNT_LEN)));

</CText>       </SoftIn>       {nc >= 0 ? (

</SoftIn>       {nc >= 0 ? (         <div style={{position: 'absolute', inset: 0, opacity: fadeIn(nc, 10), transform: `translateY(${slideUp(nc, 120).toFixed(2)}px)`}}>

{nc >= 0 ? (

Executable file

Executable file

Executable file

Executable file

Executable file

export const SC44: React.FC = () => {   const N = useCurrentFrame() + F0;   const nC = N - 8061;

const N = useCurrentFrame() + F0;   const nC = N - 8061;   const castleDy = slideUp(nC, 170); // QC v1：Δ300→170，起点城堡底 y≈590 不穿字幕带

const nC = N - 8061;

return (     <>       {nC >= 0 ? (

<>       {nC >= 0 ? (         <svg width={1280} height={720} viewBox="0 0 1280 720" style={{position: 'absolute', left: 0, top: 0, overflow: 'visible', filter: 'drop-shadow(0 0 3px rgba(255,255,255,0.45))', opacity: fadeIn(nC, 10), transfor

{nC >= 0 ? (

Executable file

Executable file

Executable file

- 每个镜头至少出 **6 张 still**：入场首帧+1、入场中段、入场完成、中间关键帧、离场中段、末帧。命令：`<项目根>/scripts/still.sh Gn <帧号,逗号分隔> <输出目录绝对路径> gN`（**tag 固定为本组 gN，一个组只留一个 bundle**；改代码后 `rm -rf <项目根>/build_dev_gN` 再跑；bundle ≈40MB，仍不要堆多个）。**禁止**直接 `npx remotion still src/index.ts

- `public/` 只放本片资产（模板 18MB，bundle ≈38MB）；出 still 只用 `scripts/still.sh`，每组一个固定 tag，改码后 `rm -rf build_dev_<tag>` 再建；不要直接 `npx remotion still src/index.ts …`（会在 $TMPDIR 留临时 bundle，脚本已自动清理）。

Executable file

| 文件 | 字体 | 版权声明 | |---|---|---| | `NotoSansSC.ttf` | Noto Sans SC | (c) 2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. |

|---|---|---| | `NotoSansSC.ttf` | Noto Sans SC | (c) 2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. | | `Orbitron[wght].ttf` | Orbitron | Copyright 2018 The Orbitron Project Authors (https://github.com/theleague

| `NotoSansSC.ttf` | Noto Sans SC | (c) 2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. |

| `Orbitron[wght].ttf` | Orbitron | Copyright 2018 The Orbitron Project Authors (https://github.com/theleagueof/orbitron), with Reserved Font Name: "Orbitron". |

| `Exo2-Italic.ttf` | Exo 2 | Copyright 2013 The Exo 2 Project Authors (https://github.com/googlefonts/Exo-2.0) |

This Font Software is licensed under the SIL Open Font License, Version 1.1. This license is copied below, and is also available with a FAQ at: https://openfontlicense.org

https://openfontlicense.org

Executable file

#!/usr/bin/env python3

#!/usr/bin/env python3

#!/bin/zsh

# portable in-place edit: `-i.bak` + rm works on both BSD/macOS and GNU/Linux sed

sed -i.bak "s/slug: 'demo'/slug: '$SLUG'/" "$DEST/src/config.ts" && rm -f "$DEST/src/config.ts.bak"

#!/bin/zsh

[ "${SKIP_BUNDLE:-0}" = 1 ] && [ -d build_prev ] || { rm -rf build_prev && npx remotion bundle src/index.ts --out-dir build_prev --log=error; }

[ "${KEEP_BUNDLE:-0}" = 1 ] || rm -rf build_prev

#!/bin/zsh

[ "${SKIP_BUNDLE:-0}" = 1 ] && [ -d build_full ] || { rm -rf build_full && npx remotion bundle src/index.ts --out-dir build_full --log=error; }

rm -rf fin_frames && mkdir -p fin_frames

[ "${KEEP_BUNDLE:-0}" = 1 ] || rm -rf build_full

#!/usr/bin/env python3

#!/usr/bin/env python3

#!/usr/bin/env python3

#!/bin/zsh

# ⚠ 每个构建组只用一个 tag（如 g3），改代码后 rm -rf build_dev_<tag> 再跑；不要每次换新 tag（每个 bundle ≈40MB）。

[ "${CLEAN_TMP:-1}" = 1 ] && find "${TMPDIR:-/tmp}" -maxdepth 1 -name 'remotion-webpack-bundle-*' -mmin +240 -exec rm -rf {} + 2>/dev/null

#!/bin/zsh

trap 'rm -rf "$OUT"' EXIT

#!/usr/bin/env python3

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

Executable file

Executable file

Executable file

export const DOT_STEP = 36, DOT_X0 = 24, DOT_Y0 = 18; // 设计坐标网格（frame_metrics.py 用同一组常量还原屏幕坐标） const GRAIN_URL =   "url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence 

"url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='.9' numOctaves='2' stitchTiles='stitch'/><feColorMatrix values='0 0 0 0 0  0 0 0

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file

Executable file