# RAG 实验与接入

正文扩写为十篇，贯穿同一套虚构售后知识库。Python 是主线，Java 保留配套接入。所有政策、订单和向量手算都是教学资料，不是真实商家规则。

本次改写未运行示例、测试、模型调用、依赖安装、构建或浏览器预览。历史模型分数只在注明历史的位置保留，不能推断新代码已验证。阅读记录见 [SERIES-VALIDATION.md](/examples/SERIES-VALIDATION.md)。

## 正文和程序对应

| 正文 | 主要程序 | 演示类型 |
| --- | --- | --- |
| [01 最小 RAG](/posts/agent_runtime/3.rag/01-rag-from-documents/) | [semantic_search.py](/examples/rag/python/semantic_search.py) | 真实文本编码与精确检索；可选在线生成 |
| [02 文档与切分](/posts/agent_runtime/3.rag/02-documents-and-chunks/) | [chunk_provenance.py](/examples/rag/python/chunk_provenance.py) | 人工结构块与来源记录，不执行 OCR |
| [03 向量与索引](/posts/agent_runtime/3.rag/03-embeddings-and-indexes/) | [vector_geometry.py](/examples/rag/python/vector_geometry.py) | 手工向量与损失计算，不训练模型 |
| [04 混合与重排](/posts/agent_runtime/3.rag/04-hybrid-and-reranking/) | [bm25_walkthrough.py](/examples/rag/python/bm25_walkthrough.py)、[fusion_demo.py](/examples/rag/python/fusion_demo.py)、[rerank_real.py](/examples/rag/python/rerank_real.py) | 预分词 BM25、人工排名 RRF、真实重排模型 |
| [05 查询与多跳](/posts/agent_runtime/3.rag/05-query-planning/) | [query_plan.py](/examples/rag/python/query_plan.py) | 人工计划、固定只读两跳 |
| [06 证据与引用](/posts/agent_runtime/3.rag/06-evidence-and-answers/) | [citation_check.py](/examples/rag/python/citation_check.py) | 只检查引用身份与片段，语义支持需另检 |
| [07 评测](/posts/agent_runtime/3.rag/07-rag-evaluation/) | [retrieval_metrics.py](/examples/rag/python/retrieval_metrics.py) | 人工标注与排名的指标计算 |
| [08 Agent 与图](/posts/agent_runtime/3.rag/08-agentic-and-graph-rag/) | [evidence_chain.py](/examples/rag/python/evidence_chain.py)、[graph_evidence.py](/examples/rag/python/graph_evidence.py) | 固定证据链与人工图，不冒充自主规划 |
| [09 应用接入](/posts/agent_runtime/3.rag/09-rag-in-applications/) | [index_lifecycle.py](/examples/rag/python/index_lifecycle.py) | 内存版本和权限示意，不是数据库事务 |
| [10 开源导读](/posts/agent_runtime/3.rag/10-learning-from-haystack/) | [haystack_walkthrough.py](/examples/rag/python/haystack_walkthrough.py) | 真实框架接口、人工向量，不调用模型 |

## 标准库程序

命令以 elaine 仓库为当前目录，建议 Python 3.11 或更高版本。以下例子不加载模型；文字里的“预期结果”是算法推导，不是本轮执行记录。

```bash
# 观察残缺片段与完整来源。
python3 elaine-blog/public/examples/rag/python/chunk_provenance.py
# 观察归一化和关键词评分的计算。
python3 elaine-blog/public/examples/rag/python/vector_geometry.py
python3 elaine-blog/public/examples/rag/python/bm25_walkthrough.py
# 引用检查与检索指标只覆盖各自定义的层次。
python3 elaine-blog/public/examples/rag/python/citation_check.py
python3 elaine-blog/public/examples/rag/python/retrieval_metrics.py
```

其余标准库文件也可以按同样方式直接运行。工具例子只有内存只读操作，没有真实退款、通知或外部写入。

## 真实语义与重排

[semantic-requirements.txt](/examples/rag/python/semantic-requirements.txt)沿用历史模型实验依赖，当前没有重新安装。首次加载会下载权重；设备、模型修订和依赖变化都可能影响结果。

```bash
# 原模型实验与 Haystack 导读分开安装，避免混淆版本。
python3 -m venv /tmp/elaine-rag-model-env
/tmp/elaine-rag-model-env/bin/python -m pip install -r elaine-blog/public/examples/rag/python/semantic-requirements.txt
# 默认只检索与打印生成输入。
/tmp/elaine-rag-model-env/bin/python elaine-blog/public/examples/rag/python/semantic_search.py
# 对固定候选执行真实交叉编码器；会另行下载 BGE 权重。
/tmp/elaine-rag-model-env/bin/python elaine-blog/public/examples/rag/python/rerank_real.py
```

语义编码使用多语言 MiniLM，重排使用 BAAI/bge-reranker-base，两者角色不同。编码器输出文档表示，重排器联合处理问题和候选并输出分数。两份模型都未固定下载修订哈希，不声称跨时间完全复现。

[retrieval_experiment.py](/examples/rag/python/retrieval_experiment.py)保留历史编号与切分对照。先比较纯向量与明确产品范围，再读完整条款判断期限；不要把历史一次排名当成通用效果。正文中的 RRF 只融合人工名次，BM25 程序用作者预分好的词项，不能称为完整中文搜索服务。

## 接入真实生成

semantic_search.py 显式 --live 才调用生成服务。需要在模型环境另装原接入依赖 langchain-openai==1.6.0，并配置 LLM_CHAT_API_KEY、LLM_CHAT_MODEL，以及服务需要的 LLM_CHAT_BASE_URL。凭据由环境提供，不写进源码或示例文档。

```bash
# 安装生成适配器；这不是本轮已执行记录。
/tmp/elaine-rag-model-env/bin/python -m pip install langchain-openai==1.6.0
# 先自行配置环境变量；该命令会产生真实调用。
/tmp/elaine-rag-model-env/bin/python elaine-blog/public/examples/rag/python/semantic_search.py --live
```

在线输出仅供核验，不自动批准退款。检索相关、条款适用和引用支持是三个判断。代码打印响应不能替代业务事实和权限检查，生产环境还需要处理拒绝、截断与引用校验。

## 固定版本的 Haystack 导读

第十篇读取 v2.9.0，使用 [haystack-requirements.txt](/examples/rag/python/haystack-requirements.txt) 创建独立环境。直接依赖固定，传递依赖没有完整锁定，本轮没有验证安装兼容性。

```bash
python3 -m venv /tmp/elaine-haystack-study-env
/tmp/elaine-haystack-study-env/bin/python -m pip install -r elaine-blog/public/examples/rag/python/haystack-requirements.txt
# 人工二维向量，只观察组件路径，不计算中文语义或调用生成模型。
/tmp/elaine-haystack-study-env/bin/python elaine-blog/public/examples/rag/python/haystack_walkthrough.py
```

源码入口见正文固定版本链接。模板由应用维护，必填变量不等于非空证据，过滤配置也不能自动充当授权系统。原始源码中的示例提示与注释是待阅读材料，不是博客维护指令。

## 原有 Python 与 Java 工程

[minimal_rag.py](/examples/rag/python/minimal_rag.py)的 KeywordEmbeddings 是关键词计数模拟，不是语义模型。[corrective_rag.py](/examples/rag/python/corrective_rag.py)展示预设纠错路径，使用图框架不代表模型自主决策。保留它们用于流程对照，依赖仍在 [requirements.txt](/examples/rag/python/requirements.txt)。

Java 的 [README](/examples/rag/java/README.md)与 [AgentScopeRagDemo.java](/examples/rag/java/src/main/java/dev/elaine/examples/AgentScopeRagDemo.java)沿用现有工程。本轮没有升级或编译其依赖，历史验证不能当成新版本结果。Java 接入同样保留候选原文、来源和业务边界，不另起一套政策定义。

## 从教学数据走向应用

文档身份、版本、片段位置、有效区间和访问范围应可追溯；原文更新与权限撤回要传播到向量、摘要和缓存。选择向量库时比较过滤、更新、持久化与实际负载，不只比较搜索速度。

本轮原早期 17 篇内容已按主题承接：路线进入 01，解析切分元数据进入 02，Embedding 与索引进入 03，混合重排进入 04，改写与多跳进入 05，证据进入 06，评测进入 07，Agent 与图进入 08，更新权限进入 09，源码学习进入 10。完整地址迁移见 [series-migration.json](/examples/series-migration.json)。