RAG，给 Agent 补充外部知识

用户问题 -> 检索相关资料 -> 把资料放进上下文 -> 让模型基于资料回答

用户问题 -> 模型 -> 回答

pnpm example examples/07-rag/rag-agent.ts

pnpm example examples/07-rag/rag-agent.ts "为什么 RAG 不等于把整篇文档塞进 prompt？"

OPENAI_MODEL=gpt-5-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# TypeScript Agent Assistant Knowledge Base
 
这份知识库模拟一个项目内部文档。第 07 章会把它当作模型参数之外的外部知识来源。
 
## Context Engineering
 
Context Engineering 负责决定模型每一轮应该看到什么信息。它会把系统规则、用户目标、当前状态、历史消息、工具观察和外部知识组织成清楚的上下文层。
 
好的上下文不是越长越好，而是要让模型知道当前任务是什么、任务执行到哪一步、回答依据来自哪里，以及哪些旧信息已经不再重要。
 
## RAG
 
RAG 是 Retrieval-Augmented Generation 的缩写。它的重点不是让模型永久记住新知识，而是在回答前从外部知识库里检索当前问题需要的片段，再把这些片段作为上下文提供给模型。
 
在 Agent 里，RAG 通常不是一个独立终点，而是 Context Engineering 的一个知识来源。检索结果需要带上来源、片段内容和相关性信息，然后进入上下文里的 external knowledge 层。
 
## Chunking
 
文档切块会直接影响检索质量。如果 chunk 太大，里面会混入很多和问题无关的内容；如果 chunk 太小，模型可能看不到完整语义。
 
一个适合入门示例的做法是按 Markdown 二级标题切块。这样每个 chunk 通常对应一个完整主题，既比整篇文档更聚焦，也比单句切分更容易保留上下文。
 
## Embedding Retrieval
 
Embedding 会把文本转换成向量。查询和文档片段都转换成向量后，可以用 cosine similarity 计算它们的相似度。
 
最小 RAG 可以只做 top-k retrieval：把所有 chunk 按相似度排序，取最相关的几个片段。真实系统还可能继续加入 reranking、权限过滤、增量索引和向量数据库。
 
## Grounded Answering
 
RAG 检索到片段以后，Agent 不应该直接把它们当作最终答案。系统需要把片段注入上下文，并要求模型只根据给定资料回答。
 
回答中最好带上来源引用。引用不是装饰，它让用户和系统都能检查结论是否真的来自检索结果。
 
## When To Use A RAG Framework
 
LangChain、LlamaIndex 和向量数据库适合生产系统，尤其是文档多、更新频繁、需要权限过滤或复杂检索策略的时候。
 
但在教学和早期原型里，先手写一个最小 RAG 链路更容易理解。读者应该先看清楚文档切块、embedding、相似度排序、top-k 检索和上下文注入分别在做什么，再决定要不要换成框架。

type DocumentChunk = {
  id: string;
  source: string;
  title: string;
  content: string;
};

function chunkMarkdown(source: string, markdown: string): DocumentChunk[] {
  const chunks: DocumentChunk[] = [];
  const lines = markdown.split(/\r?\n/);
  let currentTitle = "Introduction";
  let currentLines: string[] = [];
 
  function flushChunk() {
    const content = currentLines.join("\n").trim();
 
    if (!content) {
      return;
    }
 
    const id = `chunk-${chunks.length + 1}`;
 
    chunks.push({
      id,
      source,
      title: currentTitle,
      content,
    });
  }
 
  for (const line of lines) {
    const heading = line.match(/^##\s+(.+)$/);
 
    if (heading) {
      flushChunk();
      currentTitle = heading[1]?.trim() || "Untitled";
      currentLines = [line];
      continue;
    }
 
    currentLines.push(line);
  }
 
  flushChunk();
 
  return chunks;
}

async function embedChunks(chunks: DocumentChunk[]): Promise<EmbeddedChunk[]> {
  const response = await client.embeddings.create({
    model: embeddingModel,
    input: chunks.map((chunk) => `${chunk.title}\n${chunk.content}`),
  });
 
  return chunks.map((chunk, index) => ({
    ...chunk,
    embedding: response.data[index]?.embedding ?? [],
  }));
}

type EmbeddedChunk = DocumentChunk & {
  embedding: number[];
};

input: chunks.map((chunk) => `${chunk.title}\n${chunk.content}`),

const response = await client.embeddings.create({
  model: embeddingModel,
  input: question,
});
 
const queryEmbedding = response.data[0]?.embedding ?? [];

function cosineSimilarity(left: number[], right: number[]) {
  if (left.length === 0 || left.length !== right.length) {
    return 0;
  }
 
  let dotProduct = 0;
  let leftNorm = 0;
  let rightNorm = 0;
 
  for (let index = 0; index < left.length; index += 1) {
    const leftValue = left[index] ?? 0;
    const rightValue = right[index] ?? 0;
 
    dotProduct += leftValue * rightValue;
    leftNorm += leftValue * leftValue;
    rightNorm += rightValue * rightValue;
  }
 
  if (leftNorm === 0 || rightNorm === 0) {
    return 0;
  }
 
  return dotProduct / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
}

return chunks
  .map((chunk) => ({
    chunk,
    score: cosineSimilarity(queryEmbedding, chunk.embedding),
  }))
  .sort((left, right) => right.score - left.score)
  .slice(0, topK);

function buildRagContext(question: string, results: RetrievalResult[]) {
  const retrievedKnowledge = results
    .map((result, index) => {
      const rank = index + 1;
      const score = result.score.toFixed(3);
 
      return [
        `[${rank}] source: ${result.chunk.source}#${result.chunk.id}`,
        `title: ${result.chunk.title}`,
        `score: ${score}`,
        result.chunk.content,
      ].join("\n");
    })
    .join("\n\n");
 
  return [
    "## task",
    question,
    "",
    "## external knowledge",
    retrievedKnowledge,
  ].join("\n");
}

const response = await client.chat.completions.create({
  model,
  messages: [
    {
      role: "system",
      content:
        "你是一个工程教程助手。只能根据用户提供的 external knowledge 回答；如果资料不足，请说明不知道。回答要简洁，并在关键结论后引用 source。",
    },
    {
      role: "user",
      content: context,
    },
  ],
});

RAG 和 Context Engineering 是什么关系？什么时候需要引入 RAG 框架？

chunk-1: Introduction
chunk-2: Context Engineering
chunk-3: RAG
chunk-4: Chunking
...

1. RAG score=0.62 source=examples/07-rag/knowledge-base.md#chunk-3
2. Context Engineering score=0.55 source=examples/07-rag/knowledge-base.md#chunk-2
3. When To Use A RAG Framework score=0.51 source=examples/07-rag/knowledge-base.md#chunk-7

## task
RAG 和 Context Engineering 是什么关系？什么时候需要引入 RAG 框架？
 
## external knowledge
[1] source: examples/07-rag/knowledge-base.md#chunk-3
title: RAG
score: 0.620
...

const retriever = vectorStore.asRetriever();
const chain = createRetrievalChain(...);

chunk -> embed -> retrieve -> format context -> answer with sources