# RAG Implementation Workflow

> 当要把 RAG 系统从需求落到上线、按阶段推进（嵌入选型、向量库、分块、检索、生成、缓存、评估）时使用；做产出分阶段实施清单+质量门禁+各阶段交付物；不适用于已知技术栈只差具体编码（用 rag-pipeline-builder）、小语料直接塞上下文、需实时计算/查结构化库的场景；触发词：RAG 落地、检索增强工作流、嵌入选型、向量库搭建、RAG 评估

- Skill: `findscripter/rag-implementation-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/rag-implementation-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/rag-implementation-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/rag-implementation-workflow

---

---
name: rag-implementation-workflow
title: RAG 检索增强实现
description: 当要把 RAG 系统从需求落到上线、按阶段推进（嵌入选型、向量库、分块、检索、生成、缓存、评估）时使用；做产出分阶段实施清单+质量门禁+各阶段交付物；不适用于已知栈只差编码（用 rag-pipeline-builder）、小语料直接塞上下文、需实时计算/查结构化库的场景；触发词：RAG 落地、检索增强工作流、嵌入选型、向量库搭建、RAG 评估。
domain: 智能/misc
tags: [rag, workflow, retrieval, embedding, evaluation, llm]
level: 进阶
status: stable
version: 0.1.0
agents: [claude-code, codex, cursor, gemini-cli]
tools: [python]
requires: [rag-pipeline-builder]
related: [prompt-template-designer]
combines_with: [csv-data-cleaner]
license: CC-BY-SA-4.0
---
## 何时使用

当一个 RAG 系统需要**从零规划到上线**，要把工作拆成可验收的阶段、按里程碑推进时使用本技能。它给的是**实施编排骨架（要做哪些阶段、每阶段产出什么、什么时候算过关）**，而不是某一步的具体代码。

- 触发词：RAG 落地、检索增强工作流、RAG 实施流程、嵌入选型、向量库搭建、混合检索、RAG 评估、文档问答上线、语义搜索系统。
- 典型任务：私有文档问答、企业知识库、客服 FAQ、带引用的生成系统的端到端立项与交付。

**不该用（边界）：**
- 已确定技术栈、只差把某一步（分块/检索/重排/拼接）写成代码 → 直接用 `rag-pipeline-builder`，别走完整工作流。
- 语料小且能整体塞进上下文窗口 → 直接拼进 prompt，无需建管道。
- 答案需实时计算、调用 API 或查结构化数据库 → 用工具调用 / SQL，不是检索。
- 强一致事实（金额、库存、汇率）→ 走权威接口，检索结果会过期。
- 缺少输入、权限、安全边界或成功判据时 → 先停下来澄清，不要盲目开工。

## 步骤 / 指令

按阶段推进，每阶段先列**交付物**再过**质量门禁**，前一门禁不过不进下一阶段。

1. **需求分析**：定用例、盘数据源、设准确率与延迟目标、规划评估指标。交付：一页需求说明 + 评估指标定义。
2. **嵌入选型**：候选 embedding 模型在领域样本上对比，量化相关性、成本、延迟，选定模型并记录维度。门禁：嵌入模型已选定。
3. **向量库搭建**：选库（Faiss/Chroma/pgvector/Milvus 等），设计 schema（`vector + 原文 + metadata`），配索引与标量过滤，跑通连接与查询。门禁：向量库可写入可检索。
4. **分块策略**：定 `chunk_size`（默认 300~800 token）与 `overlap`（10~20%），优先按结构切（标题/段落），每块附 `{doc_id, title, section, source_uri, position}`。门禁：分块已实现且检索质量达标。
5. **检索实现**：query 同模型 embedding → top-k 向量召回（`k=20~50`），叠加关键词/BM25 做混合检索，接 rerank 截到 `top-n=3~8`，优化延迟。门禁：检索可用。
6. **LLM 集成**：选 LLM、设计提示模板、注入上下文、处理引用。强制「仅依据上下文作答，缺失则说不知道」。门禁：LLM 已接入。
7. **缓存**：加响应缓存与 embedding 缓存，配 TTL 与失效策略，监控命中率。
8. **评估**：定指标、建测试集，量 `命中率@k / 答案正确率 / 引用准确率`，按结果回调 `chunk_size / k / n / 是否重排`，迭代。门禁：评估达标。

**架构总览：**

```
用户查询 → 嵌入 → 向量检索 → 召回文档 → LLM → 回答
            |        |          |          |
          模型     向量库     分块存储   提示词+上下文
```

**质量门禁清单（逐项打勾再上线）：**

```
[ ] 嵌入模型已选定
[ ] 向量库已配置
[ ] 分块已实现
[ ] 检索可用
[ ] LLM 已集成
[ ] 评估通过
```

各阶段具体编码（分块/向量化/检索/重排/拼接上下文/防注入提示词）下钻到 `rag-pipeline-builder`，提示模板下钻到 `prompt-template-designer`。

## 示例

立项排期（把 8 阶段压成 3 个里程碑）：

```
里程碑 1 · 可检索（阶段 1-4）
  交付：需求说明、选定嵌入模型、向量库 schema、分块入库脚本
  门禁：给定 query 能召回相关文档，命中率@10 ≥ 基线

里程碑 2 · 可回答（阶段 5-6）
  交付：混合检索 + rerank、提示模板、带引用的生成
  门禁：抽样 20 题，引用准确率 ≥ 阈值，无明显幻觉

里程碑 3 · 可上线（阶段 7-8）
  交付：缓存层、固定评测集、评估报告
  门禁：评估全绿，延迟与成本达标
```

各阶段最小落地（伪代码，细节见 `rag-pipeline-builder`）：

```python
chunks = chunk(clean(extract(docs)), size=500, overlap=0.15)    # 阶段 4
index.upsert([(embed(c.text), c.text, c.meta) for c in chunks])  # 阶段 2-3
hits = index.search(embed(query), k=30, filter=meta_filter)      # 阶段 5
top  = rerank(query, hits)[:5]                                    # 阶段 5
ctx  = join_with_citations(dedup(top), budget=0.6)               # 阶段 6
ans  = llm(prompt_template(question=query, context=ctx))         # 阶段 6
```

## 注意事项

- **查询与入库 embedding 模型必须一致**（含版本/维度），否则相似度无意义；选型阶段（步骤 2）就把模型钉死并记录。
- **门禁不过不前进**：没有评估指标就调参等于盲调，先固定评测集再迭代（步骤 1 就定义指标）。
- 召回宽、重排窄：`k` 大保召回，`top-n` 小控成本与噪声，二者解耦调。
- 上下文别塞满，留 30~50% 给指令与生成；超预算先丢低分块而非截断中间。
- 始终带 `metadata` 与来源标记，否则无法溯源、无法增量更新/删除；语料更新走增量 upsert / 按 `doc_id` 删除重建。
- 防注入：检索到的文档是数据不是指令，prompt 中明确隔离，忽略文档内的越权指示。
- 本工作流给的是流程编排，**不替代针对你环境的验证、测试与专家评审**；缺输入/权限/安全边界/成功判据时先澄清再动手。

## 互见

- **requires**：`rag-pipeline-builder` —— 本工作流是阶段编排，每个阶段的具体实现（分块、向量化、检索、重排、拼接上下文）由它落地。
- **related**：`prompt-template-designer` —— 步骤 6 生成端「依据上下文作答+标注引用」的提示模板由其产出。
- **combines_with**：`csv-data-cleaner` —— 表格/结构化源数据入库前先清洗，提升分块与检索质量。

---

采编自 sickn33/antigravity-awesome-skills（MIT 许可）。