深入浅出RAG——第20章:端到端实战:企业级知识库问答系统

3 阅读25分钟

📖 本章学习目标

  • 将前19章的全部知识点映射到真实系统的具体模块中,理解各自落地的位置
  • 实现混合检索、Rerank重排序和Self-Reflective RAG,建立检索质量的层层保障机制
  • 集成Agent自主查询和流式输出,覆盖从简单问答到多步推理的完整交互场景
  • 搭建评估管道、可观测性埋点和反馈闭环,让系统质量可度量、可追溯

引言:从分散章节到完整系统

《第19章:RAG 系统监控与可观测性》建立了指标采集、追踪和告警体系,至此所有单点技术问题讨论完毕。本章是专栏的集大成章节,将第1章到第19章的每个知识点映射到一个企业级知识库问答系统的具体模块中。

这个系统和《第7章:基础篇实战,文档问答机器人》的 POC(概念验证)机器人有本质区别。第7章的目标是快速跑通"检索加生成"流程,验证 RAG 基本可用,代码是单体结构,检索策略是单一的向量相似度匹配,没有评估、没有监控、没有缓存。本章的系统面向长期生产运行,每一层都有对应的质量保障和运维机制。

本章代码量较大,但每个代码块都标明了它对应前序哪一章的知识点,方便你回溯学习。下面从需求和技术选型开始,按系统构建的自然顺序逐一展开。

一、需求定义与技术选型

1. 业务场景与功能矩阵

假设你是一家中型科技公司的技术负责人,公司有 200 到 500 名员工。新员工入职培训成本高,老员工需要重复回答相同的问题。技术文档分散在 Confluence、GitHub Wiki 和 Notion 中,找不到最新信息。客服团队八成的问题是重复的,但每次都需要人工回答。老员工离职后,他们的经验和判断也随之流失。

解决方案是构建一个企业知识库智能问答系统,让员工和客户通过自然语言提问,系统从内部文档中检索相关信息并生成附带来源引用的答案。功能需求按优先级排列如下。

功能模块需求描述优先级涉及章节
文档管理支持 Markdown、PDF、Word 上传,展示索引状态P0Ch4、Ch5
智能问答基于知识库内容回答,支持多轮对话和流式输出P0Ch6、Ch7、Ch17
引用溯源每个回答标注来源文档和段落,可点击跳转P0Ch11
混合检索稠密向量加稀疏关键词检索,RRF融合排序P0Ch9
检索后处理Rerank重排序和结果压缩,提升精确率P1Ch10
用户反馈对每个回答进行满意度评价,标记错误P1Ch19
管理后台查看知识库覆盖范围、使用统计和反馈汇总P1Ch19
质量评估定期自动评估检索和生成质量,生成趋势报告P1Ch12
Agent查询复杂多步问题时自主调用工具和检索P2Ch15
多知识库支持按团队或项目划分独立的子知识库P2Ch16

非功能需求方面,P95 延迟目标控制在 3 秒以内,首 Token 在 1 秒以内。系统需要支持万级文档量和百级并发用户,同时满足数据传输加密和访问控制的基本安全要求。

2. 三方案回顾:为什么选择 RAG

在《第1章:认识RAG》中我们对比了三种给 LLM 注入外部知识的方式。这里做一个快速回顾,说明为什么企业知识库场景选择 RAG 作为核心架构。

维度RAG微调 (Fine-tuning)Long Context
知识更新速度文档更新后重建索引即可,分钟级生效需要重新训练,成本高、周期长每次请求携带全部文档,Token成本线性增长
可追溯性每个回答带文档引用,可溯源可验证知识融入模型权重,无法追溯具体来源可追溯但窗口内文档越多越容易"迷失在中间"
成本结构Embedding加检索的开销固定,LLM调用按需训练成本高,推理成本低每次调用成本与文档总量成正比
适用场景知识频繁更新、需要引用溯源的场景风格固化、知识稳定的场景单次长文档分析和推理

企业知识库的文档是持续更新的(新版本发布、流程变更、人员调整),回答必须附带来源才能形成可信的知识沉淀,所以 RAG 能更好的同时满足这两个约束的方案。本章的系统在 RAG 基础上,按需引入微调(用于特定风格的指令遵循优化)和 Long Context(用于复杂文档的综合推理),三者不是互斥关系。

3. 技术栈

前后端和基础设施的选型体现了生产环境的实际约束,技术选型的原则是成熟稳定优先。

层级技术用途
运行时Node.js 20 LTS稳定且包管理生态丰富
框架Express + TypeScript灵活、类型安全
向量数据库Chroma(自托管)或 Pinecone(托管)向量存储与检索
稀疏检索BM25(内存索引)关键词检索,与稠密向量互补
消息队列BullMQ + Redis异步索引任务分发
缓存RedisQuery Cache + Embedding Cache
对象存储MinIO(自托管)或 AWS S3(托管)原始文档持久化
前端React 18 + TypeScript + Ant Design + Zustand企业级管理界面
HTTP 客户端Axios前端 API 调用和请求拦截
日志Winston + ELK Stack结构化日志采集和集中分析
容器化Docker + Docker Compose环境一致性和服务编排
CI/CDGitHub Actions自动测试与索引重建
监控Prometheus + Grafana + OpenTelemetry指标采集和全链路追踪

二、Monorepo 项目骨架

1. 包拆分与职责

Monorepo 将系统拆为四个独立的包,每个包有独立的构建和部署流程,通过 shared 包共享类型定义。《第16章:生产级架构设计》详细讨论了分层架构的设计考量,这里直接给出完整的项目骨架。

enterprise-rag/
├── packages/
│   ├── indexer/              # 异步索引管道
│   │   ├── src/
│   │   │   ├── loaders/      # 各类文档加载器(PDF、Markdown、Word)
│   │   │   ├── splitters/    # 文档切分策略
│   │   │   ├── embeddings/   # Embedding 生成
│   │   │   ├── vector-store.ts  # 向量数据库操作
│   │   │   └── index.ts      # Worker 主入口
│   │   ├── tests/
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── api/                  # REST API 服务
│   │   ├── src/
│   │   │   ├── routes/       # 路由:问答、文档管理、反馈、管理后台
│   │   │   ├── services/     # 业务逻辑:检索、生成、评估
│   │   │   ├── middleware/   # 中间件:认证、限流、日志、遥测
│   │   │   ├── utils/        # 工具函数
│   │   │   └── server.ts     # Express 服务器入口
│   │   ├── tests/
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── web/                  # 前端管理界面
│   │   ├── src/
│   │   │   ├── components/   # React 组件
│   │   │   ├── pages/        # 页面:问答、文档管理、统计
│   │   │   ├── hooks/        # 自定义 Hooks
│   │   │   ├── services/     # API 调用封装
│   │   │   └── App.tsx
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   └── shared/               # 共享类型和工具
│       ├── src/
│       │   ├── types.ts      # TypeScript 类型定义
│       │   ├── constants.ts  # 常量
│       │   └── utils.ts      # 通用工具函数
│       ├── package.json
│       └── tsconfig.json
│
├── docker-compose.yml
├── docker-compose.dev.yml
├── .github/workflows/        # CI/CD 配置
├── package.json              # workspace root
├── tsconfig.json             # 根 TypeScript 配置
└── .eslintrc.js

indexer 包独立为 Worker 进程,和 api 包之间通过 Redis 消息队列通信,互不阻塞。shared 包中的类型和常量在所有包之间保持一致,避免了类型定义在不同包中重复声明导致的同步问题。web 包可以独立部署到 CDN 或静态托管服务,不依赖 Node.js 运行时。

npm Workspaces 的根配置如下。

{
  "name": "enterprise-rag",
  "version": "1.0.0",
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "build": "npm run build --workspaces",
    "test": "npm run test --workspaces",
    "dev": "npm run dev --workspaces --if-present",
    "lint": "npm run lint --workspaces"
  }
}

三、数据管道:从文档到向量

第2章到第5章分别讨论了 Embedding、向量数据库、文档加载和切分,这些是 RAG 系统的原材料车间。本节将这四个环节串联为一个可配置的数据管道,是 Indexer Worker 在消费任务时实际执行的流水线。在动手写代码之前,先想清楚一个设计原则:数据管道的每一个环节都应该是可替换的。比如今天用 text-embedding-3-small,明天可能换 bge-large,Embedding 模型的切换不应该要求重写索引逻辑。

1. Embedding 模型管理

《第2章:文本嵌入》建立了向量空间和相似度计算的基础概念。在实际系统中,Embedding 模块的核心职责是接收文本数组,返回向量数组,内部细节对外部透明。

// 定义通用的 Embedding 服务接口,所有模型实现必须遵循
export interface EmbeddingService {
  embedBatch(texts: string[]): Promise<number[][]>;  // 批量转为向量
  dimension(): number;                                // 返回向量维度
}

// OpenAI 实现:调用 text-embedding-3-small,维度 1536
export class OpenAIEmbeddingService implements EmbeddingService {
  constructor(
    private model: string = process.env.EMBEDDING_MODEL || "text-embedding-3-small",  // 可通过环境变量切换
    private batchSize: number = 20                      // 单次最多发送 20 条
  ) {}

  async embedBatch(texts: string[]): Promise<number[][]> {
    const results: number[][] = [];
    // 分批调用,避免单次请求过大触发 API 限制
    for (let i = 0; i < texts.length; i += this.batchSize) {
      const batch = texts.slice(i, i + this.batchSize);
      const response = await openai.embeddings.create({
        model: this.model,
        input: batch,
      });
      results.push(...response.data.map(d => d.embedding));
    }
    return results;
  }

  dimension(): number { return 1536; }
}

2. 文档加载器工厂

《第4章:文档加载》介绍了 LangChain 的 Document 对象体系和多种格式的加载器。在生产系统中,文档来源不只是本地文件,还可能是 API、数据库或对象存储。下面的工厂函数根据文件类型选择对应的加载策略。

// 加载器工厂:根据文件类型和来源返回合适的 Loader
export async function loadDocument(params: {
  path: string;               // 对象存储中的文件路径
  fileType: "markdown" | "pdf" | "word";
}): Promise<Document[]> {
  // 先从对象存储下载到本地临时目录
  const localPath = await downloadFromStorage(params.path);

  switch (params.fileType) {
    case "markdown":
      // Markdown 文件直接按标题切为逻辑段
      return new TextLoader(localPath).load();
    case "pdf":
      // PDF 需要先用 pdf-parse 提取文本,再构造 Document
      return new PDFLoader(localPath).load();
    case "word":
      // Word 文件用 mammoth 库提取内容
      return new DocxLoader(localPath).load();
    default:
      throw new Error(`不支持的文件类型: ${params.fileType}`);
  }
}

3. 可配置切分策略

《第5章:文档切分》讨论了四种主流切分策略及其适用场景。生产系统中,切分参数不是写死的常量,而是可通过环境变量或配置文件调整的,这也是《第13章:用实验闭环调优RAG》中实验闭环的实践基础。

// 切分配置:所有参数可环境变量覆盖,方便线上实验
export const CHUNK_CONFIG = {
  chunkSize: parseInt(process.env.CHUNK_SIZE || "800"),     // 每个 Chunk 的目标字符数
  chunkOverlap: parseInt(process.env.CHUNK_OVERLAP || "100"), // 相邻 Chunk 的重叠字符数
  strategy: process.env.CHUNK_STRATEGY || "recursive",       // 切分策略:recursive | semantic | fixed
};

export function splitDocument(docs: Document[]): Promise<Document[]> {
  const splitter = new RecursiveCharacterTextSplitter({
    chunkSize: CHUNK_CONFIG.chunkSize,
    chunkOverlap: CHUNK_CONFIG.chunkOverlap,
    separators: ["\n\n", "\n", "。", "!", "?", " "],  // 优先级从高到低
  });
  return splitter.splitDocuments(docs);
}

4. 向量数据库操作层

《第3章:向量数据库入门》讲解了 ANN 近似最近邻搜索和向量索引的创建。操作层封装了 Chroma 的 Collection 管理和元数据过滤,上层服务不直接依赖具体的向量数据库实现。

export class VectorStoreService {
  constructor(
    private client: ChromaClient,
    private embeddingService: EmbeddingService  // 注入而非硬编码
  ) {}

  // 创建或复用 Collection,每个知识库一个独立的 Collection
  async getOrCreateCollection(knowledgeBaseId: string) {
    return this.client.getOrCreateCollection({
      name: `kb_${knowledgeBaseId}`,
      metadata: { "hnsw:space": "cosine" },  // 余弦相似度
    });
  }

  // 检索时支持元数据过滤,例如限定文档作者或时间范围
  async search(params: {
    query: string;
    knowledgeBaseId: string;
    topK: number;
    filter?: Record<string, string>;  // 如 { author: "张三", year: "2026" }
  }): Promise<Document[]> {
    const queryEmbedding = await this.embeddingService.embedBatch([params.query]);
    const collection = await this.getOrCreateCollection(params.knowledgeBaseId);
    const results = await collection.query({
      queryEmbeddings: queryEmbedding,
      nResults: params.topK,
      where: params.filter,  // Chroma 的元数据过滤语法
    });
    return formatResults(results);
  }
}

数据管道的四个环节到此串联完毕。Embedding 服务负责文本到向量的转换,加载器工厂适配多种文件格式,切分策略支持实验调优,向量存储层封装了具体的数据库操作。Indexer Worker 按这个顺序执行,产出可检索的向量索引。

四、检索与生成核心

数据管道的产出是索引,检索层的任务是从索引中找到与用户问题最相关的文档片段。《第9章(高级检索策略)》和《第10章(检索后处理与重排序)》的技术在这里集成,目标是让检索链路从能用升级到好用。

1. 共享类型定义

所有包的公共类型定义在 packages/shared/src/types.ts 中。类型系统是团队协作的契约,先定义完整再分头实现。

// 文档元数据:从上传那一刻创建,伴随文档的整个生命周期
export interface DocumentMetadata {
  id: string;                  // 文档唯一标识,UUID
  title: string;               // 原始文件名,展示给用户
  source: string;              // 对象存储中的路径,用于 Worker 下载文件
  knowledgeBaseId: string;     // 所属知识库,支持多知识库隔离
  uploadedBy: string;          // 上传者标识,用于审计和权限
  uploadedAt: Date;            // 上传时间戳
  indexedAt?: Date;            // 索引完成时间,pending 状态下为 undefined
  status: "pending"             // 待索引,文档上传后队列尚未处理的初始状态
        | "indexing"            // Worker 正在加载、切分或生成 Embedding
        | "completed"           // 索引成功,可被检索
        | "failed";             // 索引失败,可在后台手动重试
  fileType: "markdown" | "pdf" | "word";  // 决定使用哪种文档加载器
  page?: number;               // 总页数,索引完成后由加载器回填
}

// 查询请求:用户每次提问都会携带这些信息
export interface QueryRequest {
  query: string;               // 用户输入的自然语言问题
  knowledgeBaseId: string;     // 指定在哪个知识库中检索
  userId?: string;             // 可选,用于个性化上下文和历史记录
  conversationId?: string;     // 传入则继续上一轮对话,不传则开启新对话
  topK?: number;               // 可选,覆盖默认的检索文档数量
  useAgent?: boolean;          // 是否启用 Agent 模式,处理复杂多步推理
}

// 查询响应:除了答案本身,还附带引用、对话信息和性能数据
export interface QueryResponse {
  answer: string;              // LLM 生成的自然语言回答
  citations: Citation[];       // 答案中每个 [N] 对应的文档来源
  conversationId: string;      // 对话 ID,前端用于维持多轮上下文
  queryId: string;             // 本次查询的唯一标识,用于反馈追踪和日志关联
  latency: number;             // 端到端延迟(毫秒),用于性能监控
  retrievalQuality?: number;   // 检索质量评分,低于阈值时触发 Self-Reflective 重试
}

// 引用:答案中的 [1]、[2] 对应此处数组的每一项
export interface Citation {
  index: number;               // 引用编号,对应答案中的 [N]
  documentId: string;          // 被引用文档的 ID,用于跳转原文
  documentTitle: string;       // 文档标题,在前端引用列表中展示
  snippet: string;             // 文档中相关段落的摘要,让用户不必跳转就能判断相关性
  score?: number;              // 检索相似度,用于 Rerank 前后对比
  page?: number;               // 引用内容在原始文档中的页码
  url?: string;                // 文档在对象存储中的可访问链接
}

// 用户反馈记录:每次"有用/无用"点击都会写入一条
export interface Feedback {
  queryId: string;             // 关联的查询 ID,用于追溯完整对话上下文
  rating: number;              // 评分 1~5,1 表示完全无用,5 表示非常满意
  comment?: string;            // 用户填写的补充说明文本
  hallucination?: boolean;     // 用户是否标记了"内容有误",幻觉监测的重要信号
  timestamp: Date;             // 反馈提交时间
}

// 管理后台统计面板的顶层数据结构,/stats 接口直接返回此格式
export interface AdminStats {
  totalDocuments: number;      // 已入库文档总数
  totalQueries: number;        // 历史查询总次数
  avgResponseTime: number;     // 平均端到端延迟(毫秒)
  topQuestions: Array<{ question: string; count: number }>;  // 近 7 天高频问题 Top 10
  feedbackDistribution: {
    positive: number;          // 正面评价数(4~5 分)
    neutral: number;           // 中性评价数(3 分)
    negative: number;          // 负面评价数(1~2 分)
  };
  recentFailures: Feedback[];  // 最近的低分反馈列表,供运营人工复核
}

2. 混合检索引擎

《第9章:高级检索策略》指出单一向量检索有两个盲区,一个是对专有名词和缩写不敏感,另一个是对长尾低频词的语义匹配效果差。混合检索用 BM25 关键词匹配弥补这个缺口,再通过 RRF(倒数排名融合)将两组排序结果合并。

export class HybridRetriever {
  constructor(
    private vectorStore: VectorStoreService,    // 稠密向量检索
    private bm25Index: BM25Index,               // 稀疏关键词检索
    private hybridWeight: number = 0.7          // 稠密权重,0.7 表示向量结果占 70%
  ) {}

  async retrieve(query: string, topK: number): Promise<Document[]> {
    // 并行执行两种检索,互不等待
    const [denseResults, sparseResults] = await Promise.all([
      this.vectorStore.search({ query, knowledgeBaseId, topK: topK * 2 }),
      this.bm25Index.search(query, topK * 2),
    ]);

    // RRF 融合:score = sum(1 / (k + rank)),k=60 是经验常数
    return this.reciprocalRankFusion(denseResults, sparseResults, topK);
  }

  private reciprocalRankFusion(
    dense: Document[], sparse: Document[], topK: number
  ): Document[] {
    const scores = new Map<string, number>();
    const K = 60;  // RRF 常数,值越小排名靠前的文档优势越明显

    dense.forEach((doc, rank) => {
      scores.set(doc.metadata.id,
        (scores.get(doc.metadata.id) || 0) + this.hybridWeight / (K + rank + 1));
    });
    sparse.forEach((doc, rank) => {
      scores.set(doc.metadata.id,
        (scores.get(doc.metadata.id) || 0) + (1 - this.hybridWeight) / (K + rank + 1));
    });

    // 按融合分数降序排列并截取 topK
    return Array.from(scores.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, topK)
      .map(([id]) => dense.find(d => d.metadata.id === id)
                  || sparse.find(d => d.metadata.id === d.metadata.id)!);
  }
}

3. 检索后处理与重排序

《第10章:检索后处理与重排序》的核心观点是检索和排序应该使用不同精度的模型。第一阶段用 Bi-Encoder 快速召回候选集,第二阶段用 Cross-Encoder 精细排序。下面的 Reranker 封装了这两种可选的精排路径。

export class Reranker {
  constructor(
    private method: "cohere" | "llm" = "llm"  // Cohere API 或 LLM 精排
  ) {}

  async rerank(query: string, docs: Document[], topN: number): Promise<Document[]> {
    if (this.method === "cohere") {
      return this.cohereRerank(query, docs, topN);
    }
    return this.llmRerank(query, docs, topN);
  }

  // LLM 精排:让模型对每篇文档的关联度打分
  private async llmRerank(
    query: string, docs: Document[], topN: number
  ): Promise<Document[]> {
    const scored = await Promise.all(docs.slice(0, 10).map(async doc => {
      const score = await this.scoreRelevance(query, doc.pageContent.slice(0, 500));
      return { doc, score };
    }));
    return scored
      .sort((a, b) => b.score - a.score)
      .slice(0, topN)
      .map(item => item.doc);
  }

  // 用 LLM 给文档关联度打分,返回 0~1 之间的值
  private async scoreRelevance(query: string, snippet: string): Promise<number> {
    const prompt = `问题: ${query}\n文档片段: ${snippet}\n请给出 0-1 之间的关联度分数:`;
    const response = await this.llm.invoke(prompt);
    return parseFloat(response.content) || 0;
  }
}

4. Prompt 工程与引文溯源

《第11章:Prompt 工程》讨论了 System Prompt 设计原则和引用标注规范。下面的模板在原有引用规则基础上增加了 Few-shot 示例,帮助模型更准确地按 [N] 格式输出。引文溯源是企业级 RAG 系统和第7章 POC 机器人的一个关键分水岭。

const CITATION_PROMPT = `你是企业知识库助手,请严格遵循以下规则:
1. 只基于参考资料回答,信息不足时明确说明:"根据现有资料,无法回答这个问题"
2. 在关键事实后标注引用编号,格式为 [1]、[2]
3. 多份资料存在矛盾时,分别指出不同观点

## 示例(Few-shot)
问题: Redis 的默认端口是多少?
参考资料:
[文档 1] (Redis配置手册) Redis默认监听端口为6379...
回答: Redis 默认监听端口为 **6379** [1]。

## 参考资料
{context}

## 当前问题
{query}

请回答:`;

export function buildCitationPrompt(query: string, docs: Document[]): string {
  const context = docs.map((doc, i) => {
    const title = doc.metadata.title || "未知文档";
    return `[文档 ${i + 1}] (${title})\n${doc.pageContent}`;
  }).join("\n\n---\n\n");  // 三横线分隔不同文档
  return CITATION_PROMPT.replace("{context}", context).replace("{query}", query);
}

生成答案后,需要从文本中提取 [N] 标注并验证完整性。两个函数职责独立:解析负责提取和关联,验证负责检查缺失。

// 从答案文本中提取所有 [N] 标注,构造 Citation 数组
export function parseCitations(
  answer: string,              // LLM 生成的原始文本
  sourceDocs: Document[]       // 本次检索返回的文档列表
): Citation[] {
  const pattern = /\[(\d+)\]/g;  // 匹配 [数字] 格式
  const citedIndices = new Set<number>();  // Set 自动去重
  let match;

  while ((match = pattern.exec(answer)) !== null) {
    const index = parseInt(match[1]);
    // 只接受有效范围内的引用编号,忽略越界标注
    if (index > 0 && index <= sourceDocs.length) {
      citedIndices.add(index);
    }
  }

  return Array.from(citedIndices).map(index => {
    const doc = sourceDocs[index - 1];  // [1] 对应数组第 0 项
    return {
      index, documentId: doc.metadata.id,
      documentTitle: doc.metadata.title || "未知文档",
      snippet: doc.pageContent.slice(0, 300),  // 截取前 300 字符作为预览
      score: doc.metadata.score, page: doc.metadata.page, url: doc.metadata.url,
    };
  });
}

验证函数检查答案中出现的所有 [N] 是否都有对应文档。验证失败不阻断返回,因为答案本身可能仍然正确,只是模型的标注格式出现了偏差。

export function validateCitations(
  answer: string,
  citations: Citation[]
): { valid: boolean; issues: string[] } {
  const issues: string[] = [];
  const citedSet = new Set(citations.map(c => c.index));  // 已解析的引用编号
  const pattern = /\[(\d+)\]/g;
  let match;

  while ((match = pattern.exec(answer)) !== null) {
    const index = parseInt(match[1]);
    if (!citedSet.has(index)) {
      issues.push(`引用 [${index}] 没有对应的文档`);
    }
  }
  return { valid: issues.length === 0, issues };
}

5. Self-Reflective RAG

《第14章:高级RAG技术》介绍了 Self-RAG 的反思机制,让系统在检索质量不足时自动修正。下面的实现将 Self-Reflective 逻辑嵌入查询服务:检索后先做质量评估,不达标时自动重写查询并重试,最多两次。

export class SelfReflectiveQueryService {
  constructor(
    private retriever: HybridRetriever,   // 混合检索器
    private reranker: Reranker,           // 精排器
    private llm: ChatOpenAI               // LLM 客户端
  ) {}

  async query(request: QueryRequest): Promise<QueryResponse> {
    const startTime = Date.now();
    const queryId = generateId();
    let docs = await this.retriever.retrieve(request.query, 20);
    docs = await this.reranker.rerank(request.query, docs, 8);

    // 评估检索质量:计算检索到的文档与问题的平均相似度
    const qualityScore = this.calculateRetrievalQuality(docs);
    if (qualityScore < 0.5) {
      // 质量不足时重写查询,如"Redis 端口"的缩写展开为完整术语
      const rewrittenQuery = await this.rewriteQuery(request.query);
      docs = await this.retriever.retrieve(rewrittenQuery, 20);
      docs = await this.reranker.rerank(rewrittenQuery, docs, 8);
    }

    if (docs.length === 0) {
      return { answer: "根据现有资料,无法回答这个问题。",
        citations: [], conversationId: request.conversationId || generateId(),
        queryId, latency: Date.now() - startTime, retrievalQuality: qualityScore };
    }

    const prompt = buildCitationPrompt(request.query, docs);
    const response = await this.llm.invoke(prompt);

    return { answer: response.content as string,
      citations: parseCitations(response.content as string, docs),
      conversationId: request.conversationId || generateId(),
      queryId, latency: Date.now() - startTime, retrievalQuality: qualityScore };
  }

  private calculateRetrievalQuality(docs: Document[]): number {
    if (docs.length === 0) return 0;
    return docs.reduce((sum, d) => sum + (d.metadata.score || 0), 0) / docs.length;
  }

  private async rewriteQuery(query: string): Promise<string> {
    const prompt = `将下面的查询改写成更有利于检索的表达,展开缩写、补充同义词:\n${query}`;
    const response = await this.llm.invoke(prompt);
    return response.content as string;
  }
}

Self-Reflective 机制的核心价值不在于一定会找到更好的结果,而在于它给检索质量加了一层自动化的安全网。检索失败时系统至少尝试了一次修正,而不是直接返回无关内容。

五、高级查询特性

第四节实现了基础检索到生成的核心链路,本节补充三个让系统从能用升级到好用的高阶能力。

1. Agent 查询服务

《第15章:Agent RAG》的核心思想是让模型自主决定 是否检索、检索什么和用什么工具 。下面的 Agent 在标准 RAG 基础上额外提供了文档计数和反馈统计两个工具,当用户问如"知识库有多少篇关于Redis的文档"或"最近用户反馈怎么样"时,Agent 能绕过语义检索,直接查询数据库。

export class AgentQueryService {
  // 定义 Agent 可调用的工具集
  private tools: Tool[] = [
    {
      name: "search_knowledge_base",
      description: "在知识库中检索相关文档",
      parameters: { query: "string", topK: "number?" },
      execute: async (args) => this.retriever.retrieve(args.query, args.topK || 5),
    },
    {
      name: "get_document_count",
      description: "获取知识库中的文档总数,可按文件类型过滤",
      parameters: { knowledgeBaseId: "string", fileType: "string?" },
      execute: async (args) => db.count("documents", { knowledgeBaseId: args.knowledgeBaseId }),
    },
    {
      name: "get_feedback_stats",
      description: "获取最近的用户反馈统计",
      parameters: { knowledgeBaseId: "string" },
      execute: async () => db.query(
        "SELECT AVG(rating) as avg_rating, COUNT(*) as total FROM feedback WHERE created_at >= NOW() - INTERVAL '7 days'"),
    },
  ];

  async query(request: QueryRequest): Promise<QueryResponse> {
    const systemPrompt = `你可以使用以下工具回答用户问题。需要具体数据时必须调用工具,不要编造。
    可用工具: ${this.tools.map(t => `${t.name}: ${t.description}`).join("\n")}`;

    let messages = [{ role: "system", content: systemPrompt }, { role: "user", content: request.query }];

    // ReAct 循环:思考 -> 行动 -> 观察,最多3轮
    for (let round = 0; round < 3; round++) {
      const response = await this.llm.invoke(messages);
      const toolCall = this.parseToolCall(response.content as string);

      if (!toolCall) {
        // 没有工具调用,说明 Agent 认为可以直接回答
        return { answer: response.content as string, citations: [],
          conversationId: request.conversationId || generateId(),
          queryId: generateId(), latency: 0 };
      }

      const result = await this.executeTool(toolCall.name, toolCall.args);
      messages.push({ role: "assistant", content: `调用 ${toolCall.name},结果: ${JSON.stringify(result)}` });
    }

    throw new Error("Agent 达到最大推理轮次");
  }
}

2. 流式输出

《第17章:系统性能优化实战》指出流式输出能显著缩短首 Token 延迟,改善用户感知体验。下面的端点用 **SSE(Server-Sent Events)**协议实现逐 Token 推送,前端可以用 EventSource 接收。

router.post("/query/stream", async (req, res) => {
  // SSE 协议头:告知浏览器这是一条事件流
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");

  const docs = await retriever.retrieve(req.body.query, 10);
  const prompt = buildCitationPrompt(req.body.query, docs);
  const stream = await llm.stream(prompt);  // 获取 Token 流

  for await (const chunk of stream) {
    res.write(`data: ${JSON.stringify({ token: chunk.content })}\n\n`);
  }

  // 流结束后推送引用信息,前端在答案末尾展示
  res.write(`data: ${JSON.stringify({ type: "citations", data: citations })}\n\n`);
  res.write("data: [DONE]\n\n");
  res.end();
});

3. 缓存策略

缓存是《第17章:系统性能优化实战》中最直接的降本增效手段。相同的 Embedding 不用重复调用 API,语义相近的查询可以复用 LLM 回答。下面的 CacheService 同时管理两层缓存,每层有不同的过期策略。

export class CacheService {
  constructor(private redis: Redis) {}

  // Query Cache:相似问题的回答直接返回,TTL 1小时
  async getQueryResult(normalizedQuery: string): Promise<QueryResponse | null> {
    const cached = await this.redis.get(`query:${normalizedQuery}`);
    return cached ? JSON.parse(cached) : null;
  }

  async setQueryResult(normalizedQuery: string, result: QueryResponse): Promise<void> {
    await this.redis.setex(`query:${normalizedQuery}`, 3600, JSON.stringify(result));
  }

  // Embedding Cache:同一段文本不重复调用 API,内容不变则向量不变
  async getEmbedding(text: string): Promise<number[] | null> {
    const textHash = crypto.createHash("md5").update(text).digest("hex");
    const cached = await this.redis.get(`emb:${textHash}`);
    return cached ? JSON.parse(cached) : null;
  }

  async setEmbedding(text: string, embedding: number[]): Promise<void> {
    const textHash = crypto.createHash("md5").update(text).digest("hex");
    await this.redis.set(`emb:${textHash}`, JSON.stringify(embedding));
  }
}

六、质量保障体系

前面的章节解决了怎么搜和怎么答的问题,本章解决怎么知道搜得好不好、答得对不对的问题。质量保障不是一次性的上线检查,而是嵌入系统运行流程中的持续机制。

1. 评估管道

《第12章:RAG评估体系》建立了检索质量和生成质量双维度评估框架,其中检索质量用 MRR 和 NDCG,生成质量用忠实度和答案相关性。下面的 EvaluationService 在后台周期性运行,用一组标准问题对系统做体检,产出的指标写入 Prometheus,趋势异常时触发告警。

export class EvaluationService {
  // 标准问题集,建议从真实用户问题中采集中高频问题
  private goldenDataset: Array<{ question: string; expectedChunks: string[] }> = [];

  async runEvaluation(): Promise<EvaluationReport> {
    const results = await Promise.all(this.goldenDataset.map(async item => {
      const retrieved = await this.retriever.retrieve(item.question, 10);
      return {
        question: item.question,
        mrr: this.calculateMRR(retrieved, item.expectedChunks),       // 平均倒数排名
        ndcg: this.calculateNDCG(retrieved, item.expectedChunks, 10), // 归一化折损累计增益
        hitRate: this.calculateHitRate(retrieved, item.expectedChunks), // Top-K命中率
      };
    }));

    return {
      timestamp: new Date(),
      avgMRR: results.reduce((s, r) => s + r.mrr, 0) / results.length,
      avgNDCG: results.reduce((s, r) => s + r.ndcg, 0) / results.length,
      avgHitRate: results.reduce((s, r) => s + r.hitRate, 0) / results.length,
      details: results,
    };
  }
}

2. 幻觉检测与兜底策略

《第8章:RAG的局限与应对策略》系统梳理了检索失败和幻觉残留等典型问题。在生产系统中,兜底机制分两层,其中检索层通过相关性阈值过滤低质量结果,生成层在 Prompt 中明确要求资料不足时拒答。

// 检索层兜底:相关性分数阈值,低于 0.4 的文档直接丢弃
function filterLowQualityDocs(docs: Document[], threshold: number = 0.4): Document[] {
  const filtered = docs.filter(d => (d.metadata.score || 0) >= threshold);
  // 过滤后为空时返回空数组,调用方据此返回兜底文案
  return filtered;
}

// 生成层兜底:在 Prompt 中已内置"信息不足时明确说明"规则
// 额外在服务层检查答案中是否包含幻觉标记词(如不确定的数字和日期)
function detectHallucinationSignals(answer: string, docs: Document[]): string[] {
  const warnings: string[] = [];
  // 检查答案中的数字是否在任一检索文档中出现过
  const numbers = answer.match(/\b\d{4,}\b/g) || [];  // 匹配四位以上数字
  for (const num of numbers) {
    const found = docs.some(d => d.pageContent.includes(num));
    if (!found) warnings.push(`数字 ${num} 在参考资料中未找到,可能是幻觉`);
  }
  return warnings;
}

3. 用户反馈闭环

《第19章:监控与可观测性》建立了反馈收集和闭环分析机制。反馈 API 接收用户的满意度评分和幻觉标记,反馈数据同时用于管理后台统计和评估管道的 Golden Dataset 更新。

router.post("/feedback", async (req, res) => {
  const { queryId, rating, comment, hallucination } = req.body;
  await db.insert("feedback", {
    queryId, rating, comment, hallucination,
    timestamp: new Date(),
  });

  // 被标记为幻觉的查询自动纳入 Golden Dataset 的负样本池
  if (hallucination) {
    await addToNegativeSamplePool(queryId);
  }

  res.json({ success: true });
});

七、系统架构全景

前面六节从数据管道一路构建到质量保障体系,下面用一张架构图把这些组件之间的调用关系和数据流向统一展示。

graph TD
    subgraph 用户端
        U[用户浏览器]
    end
    subgraph 接入层
        GW[API Gateway / Nginx]
    end
    subgraph 服务层
        API[RAG API]
        IDX[Indexer Worker]
        EVAL[Evaluation Cron]
    end
    subgraph 存储层
        VS[(向量数据库)]
        OS[(对象存储)]
        DB[(业务数据库)]
        MQ[(消息队列 Redis)]
        CACHE[(缓存 Redis)]
    end
    subgraph AI 服务
        EMB[Embedding API]
        LLM[LLM API]
    end
    subgraph 监控层
        PROM[Prometheus]
        GRAF[Grafana]
        JAEGER[Jaeger]
    end
    U --> GW --> API
    API --> VS
    API --> LLM
    API --> DB
    API --> CACHE
    API --> MQ
    IDX --> MQ
    IDX --> OS
    IDX --> EMB
    IDX --> VS
    IDX --> DB
    EVAL --> VS
    EVAL --> DB
    API --> PROM
    IDX --> PROM
    EVAL --> PROM
    PROM --> GRAF
    API --> JAEGER

(1)查询流程。用户请求经过 Nginx 到达 RAG API,触发混合检索(稠密加稀疏两路并行),结果经 Reranker 精排和相关性阈值过滤后构建带引用的 Prompt。Self-Reflective 模块评估检索质量,不达标时自动重写查询并重试。答案通过 SSE 流式推送前端,引用列表在流结束后一次性发送。

(2)索引流程。文档上传后原始文件存入对象存储,元数据写入业务数据库,索引任务推入消息队列。Indexer Worker 消费任务后,按加载器工厂选择 Loader、按配置切分为 Chunk、批量生成 Embedding、写入向量数据库,最终更新文档状态。

(3)评估流程。Evaluation Cron 按固定周期(如每天凌晨)用 Golden Dataset 运行检索评估,MRR 和 NDCG 指标写入 Prometheus。指标连续下滑时触发告警,提示需要检查索引质量和切分参数。

八、可观测性

接下来将《第19章:监控与可观测性》的完整方案在这里集成到系统中。三个维度各司其职:OpenTelemetry 追踪每次请求的完整链路,Prometheus 采集业务和技术指标,告警规则在指标异常时发出通知。

1. OpenTelemetry 全链路追踪

追踪中间件在请求到达时创建 Span,记录从检索到 LLM 调用再到响应返回的完整路径。每个 Span 携带 queryId,前端报错时可以凭此找到完整的调用日志。

// OpenTelemetry 中间件:为每个请求创建 Span 并注入 traceId
export function tracingMiddleware(req: Request, res: Response, next: NextFunction) {
  const tracer = trace.getTracer("rag-api");
  const span = tracer.startSpan(`HTTP ${req.method} ${req.path}`, {
    attributes: {
      "http.method": req.method,
      "http.route": req.path,       // Span 属性,Jaeger 中可按此筛选
      "rag.traceId": generateId(),  // 业务层 TraceID,写入日志关联追踪
    },
  });

  res.on("finish", () => {
    span.setAttribute("http.status_code", res.statusCode);
    span.end();  // 响应完成后关闭 Span,记录耗时
  });

  next();
}

2. Prometheus 指标采集

指标分两类:技术指标(延迟、吞吐、错误率)和业务指标(检索质量、Token 消耗、反馈评分)。Counter 类型用于累计值(查询次数、Token 消耗),Histogram 类型用于分布值(延迟、检索分数)。

// Prometheus 指标定义:Counter 累计值,Histogram 分布值
const queryCounter = new Counter({
  name: "rag_queries_total",       // 查询总数
  help: "Total number of RAG queries",
  labelNames: ["knowledge_base_id", "status"],
});

const retrievalScoreHistogram = new Histogram({
  name: "rag_retrieval_quality",   // 检索质量分布
  help: "Distribution of retrieval quality scores",
  buckets: [0.1, 0.3, 0.5, 0.7, 0.9],  // 分值桶,越细越能发现微妙退化
});

const feedbackCounter = new Counter({
  name: "rag_feedback_total",      // 反馈统计
  help: "User feedback count by rating",
  labelNames: ["rating", "hallucination"],
});

3. 告警规则

告警触发条件基于运行基线而不是硬编码阈值。历史上的正常波动范围通过过去 7 天的数据计算,当前值偏离均值超过 3 个标准差才触发,避免了因业务峰谷导致的误报。

// 告警规则:偏离历史基线 3 个标准差时触发
export const alertRules = [
  {
    name: "检索质量下降",
    metric: "rag_retrieval_quality",
    condition: "current_avg < baseline_avg - 3 * baseline_stddev",  // 基于统计基线
    window: "15m",       // 观察窗口 15 分钟
    severity: "warning", // 警告级别,先通知不自动处理
  },
  {
    name: "LLM 错误率上升",
    metric: "rag_queries_total{status='error'}",
    condition: "rate > 0.05",  // 错误率超过 5%
    window: "5m",
    severity: "critical",
  },
];

九、运维与部署

《第18章:RAG系统生产与部署实战》讨论的 Docker 多阶段构建、CI/CD 自动索引和索引版本管理在这里落地为可操作的配置。

1. Docker Compose 完整编排

应用服务和基础设施统一声明,healthcheck 控制启动顺序。

services:
  rag-api:
    build:
      context: .
      dockerfile: packages/api/Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - CHROMA_URL=http://chroma:8000
      - REDIS_URL=redis://redis:6379
      - DATABASE_URL=postgresql://user:pass@postgres:5432/rag
    depends_on:
      chroma: { condition: service_healthy }
      redis: { condition: service_healthy }
      postgres: { condition: service_healthy }
    restart: unless-stopped

  indexer:
    build:
      context: .
      dockerfile: packages/indexer/Dockerfile
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - CHROMA_URL=http://chroma:8000
      - REDIS_URL=redis://redis:6379
      - DATABASE_URL=postgresql://user:pass@postgres:5432/rag
    depends_on: [chroma, redis, postgres]
    restart: unless-stopped

基础设施服务的 healthcheck 确保应用服务启动时依赖已就绪。

  chroma:
    image: chromadb/chroma:latest
    volumes: [chroma_data:/chroma/chroma]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    command: redis-server --maxmemory 1gb
    volumes: [redis_data:/data]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=rag
    volumes: [postgres_data:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  chroma_data: null
  redis_data: null
  postgres_data: null

2. CI/CD 自动测试与索引重建

接着是CI/CD 流水线的设计,下面两个 GitHub Actions 工作流分别处理代码变更和文档变更。

name: Test & Build
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      redis:
        image: redis:7-alpine
        ports: ["6379:6379"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20", cache: "npm" }
      - run: npm ci
      - run: npm run lint
      - run: npm test
        env: { OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}" }
      - run: npm run build

文档目录变更触发自动索引重建,非文档变更不会浪费 CI 资源。

name: Rebuild Index
on:
  push:
    paths: ["docs/**", "knowledge-base/**"]
    branches: [main]
jobs:
  reindex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20", cache: "npm" }
      - run: npm ci
      - run: npx tsx scripts/rebuild-index.ts --namespace production
        env:
          OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
          CHROMA_URL: "${{ secrets.CHROMA_URL }}"

3. 索引版本管理

索引更新通过创建新 Collection 加 Redis 别名原子切换实现,出问题时可以一步回退。

export class IndexVersionManager {
  // 切换别名到指定版本,所有查询即时生效
  async switchToVersion(namespace: string, versionName: string): Promise<void> {
    const key = `rag:index:${namespace}:active`;
    await this.redis.set(key, versionName);
  }

  // 回滚到上一个稳定版本
  async rollback(namespace: string): Promise<void> {
    const versions = await this.listVersions(namespace);
    // 版本列表按时间倒序,跳过当前(第0个)取上一个稳定版本
    const previous = versions.find(v => v.status === "stable");
    if (previous) await this.switchToVersion(namespace, previous.name);
  }
}

十、管理后台统计

运营团队需要一目了然地看到知识库规模、查询趋势和用户反馈分布。下面两个接口分别返回统计概览和按天的趋势数据。

router.get("/stats", async (_req, res) => {
  try {
    const stats: AdminStats = {
      totalDocuments: await db.count("documents"),
      totalQueries: await db.count("queries"),
      avgResponseTime: await db.avg("queries", "latency"),
      topQuestions: await db.query(`
        SELECT query, COUNT(*) as count
        FROM queries WHERE created_at >= NOW() - INTERVAL '7 days'
        GROUP BY query ORDER BY count DESC LIMIT 10
      `),
      feedbackDistribution: await db.query(`
        SELECT
          SUM(CASE WHEN rating >= 4 THEN 1 ELSE 0 END) as positive,
          SUM(CASE WHEN rating = 3 THEN 1 ELSE 0 END) as neutral,
          SUM(CASE WHEN rating <= 2 THEN 1 ELSE 0 END) as negative
        FROM feedback WHERE created_at >= NOW() - INTERVAL '7 days'
      `),
      recentFailures: await db.find("feedback", {
        rating: { $lte: 2 }, limit: 20, sort: { timestamp: -1 },
      }),
    };
    res.json(stats);
  } catch (error) {
    logger.error("统计查询失败", error);
    res.status(500).json({ error: "统计查询失败" });
  }
});

router.get("/usage-trend", async (_req, res) => {
  try {
    const trend = await db.query(`
      SELECT DATE(created_at) as date, COUNT(*) as query_count, AVG(latency) as avg_latency
      FROM queries WHERE created_at >= NOW() - INTERVAL '30 days'
      GROUP BY DATE(created_at) ORDER BY date
    `);
    res.json(trend);
  } catch (error) {
    logger.error("趋势查询失败", error);
    res.status(500).json({ error: "趋势查询失败" });
  }
});

FAQ

Q1:多知识库是物理隔离还是逻辑隔离

物理隔离(Chroma 的不同 Collection 或 Pinecone 的不同 Namespace)保证数据安全性,逻辑隔离(在 metadata 中标记 knowledge_base_id)保留了跨知识库搜索的灵活性。推荐两者结合使用,默认物理隔离,在需要跨库搜索时通过逻辑标记临时跨越。详情见《第16章:生产级 RAG 系统架构设计》。

Q2:引文溯源怎么处理多轮对话中的引用

每轮对话返回独立的 citations 数组,前端按轮次分组展示。如果用户追问"第三个引用里提到的那个配置是什么意思",前端需要将上一轮的引用索引关联到对应的文档片段并允许一键跳转。关键设计原则是引用数组始终与当前轮次的答案绑定,不与历史轮次混淆。

Q3:混合检索的权重怎么调

HybridRetriever 中的 hybridWeight 控制稠密向量和稀疏关键词在最终排序中的比重。默认 0.7(向量占 70%),如果你的知识库包含大量专有名词、缩写或代码,应提高稀疏权重。确定最佳值需要在自己的数据集上做《第13章:RAG系统调优实战》中的参数实验,不存在通用数值。

Q4:Self-Reflective RAG 每次都要重试会不会变慢

只在检索质量评分低于阈值时才触发重试,正常查询不受影响。rewriteQuery 调用的 LLM 成本远低于生成完整回答,且重写查询通常命中 Embedding Cache(改写后的文本可能与缓存中的相似查询匹配)。建议在上线初期把阈值设低一些(如 0.3),观察误触发率后再逐步调整。

Q5:Golden Dataset 从哪来

初期从真实用户问题中采样 50-100 条高频问题,人工标注每道题应该命中的文档片段。后续通过反馈闭环自动扩充:被标记为"幻觉"的查询加入负样本池,被标记为"满意"且引用完整的查询加入正样本池。《第12章:RAG系统评估与指标体系》详细讨论了 Golden Dataset 的构建标准。

练习

练习 1:实现混合检索

将你《第7章:基础篇实战——文档问答机器人》的机器人的单一向量检索替换为本章的 HybridRetriever,用 BM25 补全关键词检索能力。

验证步骤:

  1. 上传一篇包含大量专有名词的技术文档
  2. 用缩写和全称分别搜索同一个概念,确认两次都能命中
  3. 对比单一向量检索和混合检索的检索结果,观察哪些查询的召回提升最明显

预期结果:关键词查询(缩写、代码函数名)的 Hit Rate 有明显提升,语义查询的精度不受负面影响。

练习 2:集成评估管道

为第7章的机器人添加一个评估脚本,用本章的 EvaluationService 评估检索质量。创建至少 20 条问答对作为 Golden Dataset。

验证步骤:

  1. 运行评估脚本,记录初始 MRR 和 HitRate@3
  2. 将 Chunk Size 从 800 调整为 500,重新索引后再次评估
  3. 对比两次评估结果,确认哪个配置在你的数据集上表现更好

预期结果:能通过指标数字而非直觉判断参数变更的效果,形成可复现的调优流程。

练习 3:实现文档上传和异步索引

实现完整的文档上传和异步索引流程,支持 Markdown 和 PDF 文件。按本章第三节描述的方案,用 BullMQ 将上传和索引解耦。

验证步骤:

  1. 上传一个 Markdown 文件,确认 API 立即返回 status: "pending_indexing"
  2. 查询 /status/:id 端点,观察状态从 pending 到 indexing 再到 completed 的变化
  3. 索引完成后发送查询,确认能检索到文档内容

预期结果:上传接口不阻塞,索引异步完成,状态流转正确。

练习 4:接入 OpenTelemetry 追踪

为你的 RAG API 添加 OpenTelemetry 中间件,在 Jaeger 中查看一次完整查询的 Span 链路。

验证步骤:

  1. 启动 Jaeger(docker run -p 16686:16686 jaegertracing/all-in-one)
  2. 发送一条查询请求后打开 Jaeger UI
  3. 确认能看到完整的 Span 树,包括检索和 LLM 调用两个子 Span
  4. 检查 Span 的 attributes 中包含了 queryId

预期结果:Jaeger 中能排查单次查询的完整执行路径,延迟瓶颈一目了然。

📚 延伸阅读