前端工程师的 RAG 入门实战：从零构建一个知识库问答系统

作者背景：3 年前端开发，金融科技行业，负责公司 KMS（Knowledge Management System）知识管理平台。本文记录我在项目中从零搭建 RAG 知识库问答系统的完整过程。如果你也是前端工程师，想入门 AI 应用开发但不知从何下手，这篇文章就是写给你的。

写在前面：Brainstorming 输出

文章核心看点

1. 前端视角，零门槛入门：不需要 Python/ML 背景，从前端工程师熟悉的"请求-响应"模式出发，一步步理解 RAG 的工作原理和实现方式。
2. 代码驱动，可运行：每个环节都配有完整的代码示例，前端 TypeScript 类型齐全，后端 Python 可复制运行，学完能直接在项目中落地。
3. 真实踩坑经验：所有问题来自 KMS 生产环境实践，每个坑都用"现象-根因-解决"三段式拆解，帮你少走弯路。

章节结构

核心代码示例列表

关键踩坑点（现象 → 根因 → 解决）

一、为什么前端要学 RAG

我们团队的 KMS 知识管理平台，沉淀了三年多的技术文档、业务规范、复盘报告，累计 2000+ 篇。但同事们的反馈很一致：搜索不好用。

关键词匹配搜出来的东西太多了，或者搜不到。你明明记得文档里有"灰度发布回滚流程"，但搜"上线出问题怎么回退"就是找不到。

这就是传统全文检索的局限——它匹配的是字符，不是语义。

2024 年以来，RAG（Retrieval-Augmented Generation，检索增强生成）成了解决这类问题的主流方案。核心思路很简单：先把知识存到向量数据库，用户提问时检索相关内容，再让 LLM 基于这些内容生成回答。

对前端工程师来说，RAG 是一个极好的 AI 切入点。它的技术栈清晰（Embedding + Vector DB + LLM），链路明确（入库 → 检索 → 生成），跟前端熟悉的"请求-响应"模式一脉相承。而且 RAG 的前端部分——对话界面、流式渲染、上下文展示——恰恰是前端擅长的领域。

下面我就以 KMS 项目为例，记录从零搭建一个知识库问答系统的完整过程。

二、RAG 是什么——用前端能懂的方式

先抛开那些论文术语，用前端工程师熟悉的方式来理解 RAG。

想象你有一个巨大的 Markdown 文件夹（就是 KMS 的文档库），你想做一个功能：用户输入问题，系统从文档里找答案，用自然语言回复。

2.1 为什么不直接把所有文档塞给 GPT？

GPT-4o-mini 的上下文窗口是 128K tokens，看起来很大，但 KMS 两千篇文档总共有约 500 万 tokens，远超上限。而且即使能塞进去，成本也极高——每次提问都传 500 万 tokens，按 OpenAI 定价算，一次问答就要几块钱。

RAG 的思路是：只把最相关的几段文档传给 LLM。

2.2 三个核心概念

Embedding（向量化）：把一段文本变成一个固定长度的数字数组（向量）。语义相近的文本，向量之间的距离就近。你可以把它理解为"把文字翻译成数学语言"。OpenAI 的 text-embedding-3-small 模型输出 1536 维向量，效果和成本都很适合入门。

向量检索（Vector Search）：给定一个查询向量，在向量数据库中找出距离最近的 K 个向量。这比传统的关键词匹配强大很多 —— "上线出问题怎么回退"和"灰度发布回滚流程"在字面上完全不同，但在向量空间里距离很近。

Rerank（重排序）：向量检索召回 N 条结果后，用更精准的模型再做一次排序。这步是可选的，但对中文场景效果提升明显。我们用的是 Cohere 的 Rerank API。

三、技术选型：为什么选这套组合

选型原则：入门阶段优先选"开箱即用"的方案。Chroma 不用单独部署服务器，一个 pip install chromadb 就能跑起来。等系统成熟了再考虑换 Milvus 这类生产级方案。

四、环境搭建：30 分钟跑起来

4.1 项目初始化

# 创建项目目录
mkdir kms-rag && cd kms-rag

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install langchain langchain-openai langchain-chroma chromadb \
            python-dotenv fastapi uvicorn sse-starlette

4.2 配置环境变量

创建 .env 文件：

OPENAI_API_KEY=sk-your-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small
LLM_MODEL=gpt-4o-mini

4.3 验证环境

# test_env.py
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL"),
)

# 测试 Embedding
response = client.embeddings.create(
    model=os.getenv("EMBEDDING_MODEL"),
    input="你好，测试一下",
)
print(f"Embedding 维度: {len(response.data[0].embedding)}")  # 输出: 1536

# 测试 Chat
response = client.chat.completions.create(
    model=os.getenv("LLM_MODEL"),
    messages=[{"role": "user", "content": "回复'环境正常'"}],
)
print(response.choices[0].message.content)  # 输出: 环境正常

看到"Embedding 维度: 1536"和"环境正常"，说明环境配置成功。

五、文档处理：把知识"喂"给系统

这是 RAG 最关键的环节。文档处理的质量直接决定检索效果。

5.1 文档加载

KMS 的文档以 Markdown 格式存储在本地。LangChain 提供了丰富的文档加载器：

# document_loader.py
from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from typing import List
from langchain_core.documents import Document

def load_kms_documents(docs_path: str) -> List[Document]:
    """
    加载 KMS 文档目录中的所有 Markdown 文件。
    
    Args:
        docs_path: 文档目录路径
    
    Returns:
        Document 对象列表，每个 Document 包含 page_content 和 metadata
    """
    loader = DirectoryLoader(
        docs_path,
        glob="**/*.md",           # 匹配所有 Markdown 文件
        loader_cls=TextLoader,    # 使用文本加载器
        loader_kwargs={"encoding": "utf-8"},
        show_progress=True,       # 显示进度条
    )
    return loader.load()

5.2 文档分块（Chunking）

这是 RAG 里最容易踩坑的环节。分块太大，检索精度低；分块太小，上下文不完整。

# text_splitter.py
from langchain.text_splitter import RecursiveCharacterTextSplitter

def split_documents(
    documents: List[Document],
    chunk_size: int = 800,       # 每个 chunk 的最大字符数
    chunk_overlap: int = 150,    # 相邻 chunk 的重叠字符数
) -> List[Document]:
    """
    使用递归字符分割器将文档切分成小块。
    
    为什么用 RecursiveCharacterTextSplitter？
    - 它会按优先级尝试分隔符：段落 → 句子 → 字符
    - 对中文 Markdown 友好，优先在标题和段落边界切分
    - overlap 确保跨 chunk 的语义连续性
    """
    splitter = RecursiveCharacterTextSplitter(
        separators=[
            "\n## ",    # 二级标题
            "\n### ",   # 三级标题
            "\n\n",     # 段落
            "\n",       # 换行
            "。",        # 中文句号
            ". ",       # 英文句号
            " ",        # 空格
            "",         # 字符级别
        ],
        chunk_size=chunk_size,
        chunk_overlap=chunk_overlap,
        length_function=len,
    )
    
    chunks = splitter.split_documents(documents)
    print(f"文档数: {len(documents)}, 分块数: {len(chunks)}")
    return chunks

5.3 关键参数调优

5.4 生成 Embedding 并存入 Chroma

# embedding_store.py
from langchain_openai import OpenAIEmbeddings
from langchain_chroma import Chroma
import os

def create_vector_store(
    chunks: List[Document],
    persist_dir: str = "./chroma_db",
) -> Chroma:
    """
    为文档块生成 Embedding 并存入 Chroma 向量数据库。
    
    这里用 OpenAIEmbeddings 自动处理批量和速率限制。
    """
    embeddings = OpenAIEmbeddings(
        model=os.getenv("EMBEDDING_MODEL"),  # text-embedding-3-small
        dimensions=1536,                      # 可选，3-small 默认 1536 维
    )
    
    vectorstore = Chroma.from_documents(
        documents=chunks,
        embedding=embeddings,
        persist_directory=persist_dir,        # 持久化到本地磁盘
        collection_name="kms_knowledge",      # 集合名称，用于后续检索
    )
    
    print(f"向量存储完成，持久化目录: {persist_dir}")
    return vectorstore

完整入库流程：

六、检索链路：找到最相关的文档

入库完成后，核心能力就是检索——根据用户问题从向量数据库中找出最相关的文档片段。

6.1 基础检索

# retriever.py
from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings
from typing import List
from langchain_core.documents import Document

def create_retriever(
    persist_dir: str = "./chroma_db",
    k: int = 4,                              # 返回最相关的 K 个文档
) -> callable:
    """
    创建检索器，用于根据查询语句检索相关文档。
    """
    embeddings = OpenAIEmbeddings(
        model="text-embedding-3-small",
    )
    
    vectorstore = Chroma(
        persist_directory=persist_dir,
        embedding_function=embeddings,
        collection_name="kms_knowledge",
    )
    
    # similarity_search_by_vector 返回相似度最高的 K 个文档
    # 也可以设置 similarity_threshold 过滤低相关度的结果
    retriever = vectorstore.as_retriever(
        search_type="similarity",
        search_kwargs={"k": k},
    )
    
    return retriever


def retrieve_relevant_chunks(
    query: str,
    retriever,
    k: int = 4,
) -> List[Document]:
    """
    检索与查询最相关的文档块。
    
    Args:
        query: 用户输入的问题
        retriever: 检索器实例
        k: 返回文档数量
    
    Returns:
        按相似度排序的文档块列表
    """
    docs = retriever.invoke(query)
    
    print(f"查询: {query}")
    for i, doc in enumerate(docs):
        source = doc.metadata.get("source", "unknown")
        print(f"  [{i+1}] 来源: {source}, 相似度: 高")
    
    return docs[:k]

6.2 检索策略选择

对于 KMS 的知识库问答，通常用 similarity 就够。如果发现返回的 4 条结果都来自同一篇文档，可以换成 mmr 增加多样性。

七、问答生成：让 AI 基于知识回答

检索到相关文档后，接下来就是把它们组装成 Prompt，交给 LLM 生成回答。

7.1 Prompt 模板设计

# chain.py
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings
import os

# 中文 Prompt 模板，包含角色设定和输出约束
RAG_PROMPT_TEMPLATE = """
你是一个 KMS 知识管理平台的智能助手。请根据以下知识库内容回答用户的问题。

## 要求
1. 只基于提供的知识库内容回答，不要编造信息
2. 如果知识库中没有相关信息，请明确告知用户"该问题暂未收录，建议查阅相关文档或联系管理员"
3. 回答要结构化，使用 Markdown 格式
4. 在回答末尾列出引用的文档来源

## 知识库内容
{context}

## 用户问题
{question}

## 回答
"""

def create_rag_chain(retriever):
    """
    创建完整的 RAG 链：检索 → 组装 Prompt → LLM 生成 → 输出解析。
    """
    prompt = ChatPromptTemplate.from_template(RAG_PROMPT_TEMPLATE)
    
    llm = ChatOpenAI(
        model=os.getenv("LLM_MODEL"),       # gpt-4o-mini
        temperature=0.3,                     # 低温度保证回答一致性
        streaming=True,                      # 开启流式输出
    )
    
    # 使用 LCEL（LangChain Expression Language）构建链
    def format_docs(docs):
        """将检索到的文档块格式化为上下文字符串"""
        formatted = []
        for i, doc in enumerate(docs):
            source = doc.metadata.get("source", "unknown")
            formatted.append(f"【文档{i+1} - 来源: {source}】\n{doc.page_content}")
        return "\n\n---\n\n".join(formatted)
    
    rag_chain = (
        {
            "context": retriever | format_docs,  # 检索 + 格式化
            "question": RunnablePassthrough(),    # 原样传递用户问题
        }
        | prompt
        | llm
        | StrOutputParser()
    )
    
    return rag_chain

7.2 测试问答

# test_rag.py
def test_rag():
    """端到端测试 RAG 问答"""
    retriever = create_retriever()
    rag_chain = create_rag_chain(retriever)
    
    questions = [
        "上线出问题怎么回退？",
        "KMS 项目的权限模型是什么？",
        "代码审查流程是怎样的？",
    ]
    
    for q in questions:
        print(f"\n{'='*50}")
        print(f"用户: {q}")
        print(f"{'='*50}")
        
        # 流式输出回答
        for chunk in rag_chain.stream(q):
            print(chunk, end="", flush=True)
        print()

if __name__ == "__main__":
    test_rag()

八、前端集成：React Chat 组件实战

后端链路跑通后，前端这步对咱们来说就是主场了。我们给 KMS 加了一个 AI 问答面板，核心是流式对接 LangChain 的 SSE 输出。

8.1 后端：FastAPI SSE 接口

# api.py
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from sse_starlette.sse import EventSourceResponse
from pydantic import BaseModel
import asyncio
import json

app = FastAPI(title="KMS RAG API")

class ChatRequest(BaseModel):
    question: str
    conversation_id: str | None = None

@app.post("/api/chat/stream")
async def chat_stream(request: ChatRequest):
    """
    流式聊天接口，通过 Server-Sent Events 返回生成内容。
    
    前端通过 EventSource 或 fetch + ReadableStream 消费这个接口。
    """
    retriever = create_retriever()
    rag_chain = create_rag_chain(retriever)
    
    async def event_generator():
        # 先发送检索到的文档来源
        docs = retriever.invoke(request.question)
        sources = [
            {"title": doc.metadata.get("source", "unknown"), "snippet": doc.page_content[:200]}
            for doc in docs[:4]
        ]
        yield {
            "event": "sources",
            "data": json.dumps(sources, ensure_ascii=False),
        }
        
        # 流式发送 LLM 生成的内容
        full_text = ""
        async for chunk in rag_chain.astream(request.question):
            full_text += chunk
            yield {
                "event": "message",
                "data": json.dumps({"content": chunk}, ensure_ascii=False),
            }
        
        # 发送完成信号
        yield {
            "event": "done",
            "data": json.dumps({"full_text": full_text}, ensure_ascii=False),
        }
    
    return EventSourceResponse(
        event_generator(),
        headers={
            "Content-Type": "text/event-stream; charset=utf-8",
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
        },
    )

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=5001)

8.2 前端：TypeScript 类型定义

// types/rag.ts

/** 单条聊天消息 */
export interface ChatMessage {
  id: string;
  role: "user" | "assistant" | "system";
  content: string;
  /** 引用文档来源列表，仅 assistant 消息有 */
  sources?: DocSource[];
  /** 消息时间戳 */
  timestamp: number;
  /** 是否正在生成中（流式输出未完成） */
  isStreaming?: boolean;
}

/** 引用文档来源 */
export interface DocSource {
  title: string;
  snippet: string;
}

/** SSE 事件类型 */
export type SSEEventType = "sources" | "message" | "done" | "error";

/** SSE 消息事件数据 */
export interface SSEMessageData {
  content: string;
}

/** SSE 完成事件数据 */
export interface SSEDoneData {
  full_text: string;
}

8.3 前端：流式聊天 Hook

// hooks/useRAGChat.ts
import { useState, useCallback, useRef } from "react";
import { v4 as uuidv4 } from "uuid";
import type { ChatMessage, DocSource } from "@/types/rag";

interface UseRAGChatOptions {
  apiUrl: string;
  onError?: (error: Error) => void;
}

export function useRAGChat({ apiUrl, onError }: UseRAGChatOptions) {
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const abortControllerRef = useRef<AbortController | null>(null);

  const sendMessage = useCallback(
    async (question: string) => {
      if (!question.trim() || isLoading) return;

      // 添加用户消息
      const userMsg: ChatMessage = {
        id: uuidv4(),
        role: "user",
        content: question,
        timestamp: Date.now(),
      };
      setMessages((prev) => [...prev, userMsg]);
      setIsLoading(true);

      // 创建 assistant 消息占位
      const assistantId = uuidv4();
      const assistantMsg: ChatMessage = {
        id: assistantId,
        role: "assistant",
        content: "",
        sources: [],
        timestamp: Date.now(),
        isStreaming: true,
      };
      setMessages((prev) => [...prev, assistantMsg]);

      // 创建 AbortController 用于取消请求
      abortControllerRef.current = new AbortController();

      try {
        const response = await fetch(apiUrl, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ question }),
          signal: abortControllerRef.current.signal,
        });

        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }

        const reader = response.body?.getReader();
        if (!reader) throw new Error("无法获取响应流");

        const decoder = new TextDecoder("utf-8");
        let buffer = "";

        while (true) {
          const { done, value } = await reader.read();
          if (done) break;

          buffer += decoder.decode(value, { stream: true });

          // 解析 SSE 事件（按双换行分割）
          const events = buffer.split("\n\n");
          buffer = events.pop() || ""; // 最后一个可能不完整

          for (const eventStr of events) {
            const eventType = parseSSEEvent(eventStr);
            if (!eventType) continue;

            const { event, data } = eventType;

            if (event === "sources") {
              const sources: DocSource[] = JSON.parse(data);
              setMessages((prev) =>
                prev.map((msg) =>
                  msg.id === assistantId ? { ...msg, sources } : msg
                )
              );
            } else if (event === "message") {
              const { content }: { content: string } = JSON.parse(data);
              setMessages((prev) =>
                prev.map((msg) =>
                  msg.id === assistantId
                    ? { ...msg, content: msg.content + content }
                    : msg
                )
              );
            } else if (event === "done") {
              setMessages((prev) =>
                prev.map((msg) =>
                  msg.id === assistantId
                    ? { ...msg, isStreaming: false }
                    : msg
                )
              );
            }
          }
        }
      } catch (error) {
        if ((error as Error).name === "AbortError") return;
        onError?.(error as Error);
        setMessages((prev) =>
          prev.map((msg) =>
            msg.id === assistantId
              ? { ...msg, content: "抱歉，请求失败，请重试。", isStreaming: false }
              : msg
          )
        );
      } finally {
        setIsLoading(false);
        abortControllerRef.current = null;
      }
    },
    [apiUrl, isLoading, onError]
  );

  const stopGeneration = useCallback(() => {
    abortControllerRef.current?.abort();
  }, []);

  const clearMessages = useCallback(() => {
    setMessages([]);
  }, []);

  return { messages, isLoading, sendMessage, stopGeneration, clearMessages };
}

/** 解析单条 SSE 事件字符串 */
function parseSSEEvent(raw: string): { event: string; data: string } | null {
  const lines = raw.split("\n");
  let event = "";
  let data = "";

  for (const line of lines) {
    if (line.startsWith("event: ")) {
      event = line.slice(7);
    } else if (line.startsWith("data: ")) {
      data = line.slice(6);
    }
  }

  return event && data ? { event, data } : null;
}

8.4 前端：ChatPanel 组件

// components/ChatPanel.tsx
import React, { useRef, useEffect } from "react";
import { Input, Button, Spin, Typography, Tag, Space } from "antd";
import { SendOutlined, StopOutlined, ClearOutlined } from "@ant-design/icons";
import { useRAGChat } from "@/hooks/useRAGChat";
import type { ChatMessage } from "@/types/rag";

const { TextArea } = Input;
const { Text, Paragraph } = Typography;

export const ChatPanel: React.FC = () => {
  const [inputValue, setInputValue] = React.useState("");
  const messagesEndRef = useRef<HTMLDivElement>(null);

  const {
    messages,
    isLoading,
    sendMessage,
    stopGeneration,
    clearMessages,
  } = useRAGChat({
    apiUrl: "/api/chat/stream",
    onError: (err) => console.error("RAG Chat Error:", err),
  });

  // 自动滚动到底部
  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [messages]);

  const handleSend = () => {
    if (!inputValue.trim()) return;
    sendMessage(inputValue.trim());
    setInputValue("");
  };

  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === "Enter" && !e.shiftKey) {
      e.preventDefault();
      handleSend();
    }
  };

  return (
    <div style={styles.container}>
      {/* 顶部标题栏 */}
      <div style={styles.header}>
        <Text strong style={{ fontSize: 16 }}>AI 知识库问答</Text>
        <Button
          type="text"
          icon={<ClearOutlined />}
          onClick={clearMessages}
          disabled={messages.length === 0}
        >
          清空
        </Button>
      </div>

      {/* 消息列表 */}
      <div style={styles.messageList}>
        {messages.length === 0 && (
          <div style={styles.empty}>
            <Text type="secondary">
              你好，我是 KMS 知识库助手，可以问我任何关于项目的问题。
            </Text>
          </div>
        )}

        {messages.map((msg) => (
          <MessageBubble key={msg.id} message={msg} />
        ))}

        {isLoading && !messages[messages.length - 1]?.isStreaming && (
          <div style={styles.loading}>
            <Spin size="small" />
            <Text type="secondary" style={{ marginLeft: 8 }}>
              正在检索知识库...
            </Text>
          </div>
        )}

        <div ref={messagesEndRef} />
      </div>

      {/* 底部输入区 */}
      <div style={styles.inputArea}>
        <TextArea
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          onKeyDown={handleKeyDown}
          placeholder="输入你的问题，按 Enter 发送..."
          autoSize={{ minRows: 1, maxRows: 4 }}
          disabled={isLoading}
          style={{ flex: 1 }}
        />
        <Space style={{ marginLeft: 8 }}>
          {isLoading ? (
            <Button
              danger
              icon={<StopOutlined />}
              onClick={stopGeneration}
            >
              停止
            </Button>
          ) : (
            <Button
              type="primary"
              icon={<SendOutlined />}
              onClick={handleSend}
              disabled={!inputValue.trim()}
            >
              发送
            </Button>
          )}
        </Space>
      </div>
    </div>
  );
};

/** 单条消息气泡 */
const MessageBubble: React.FC<{ message: ChatMessage }> = ({ message }) => {
  const isUser = message.role === "user";

  return (
    <div
      style={{
        ...styles.bubble,
        alignSelf: isUser ? "flex-end" : "flex-start",
        backgroundColor: isUser ? "#1677ff" : "#f5f5f5",
        color: isUser ? "#fff" : "#333",
      }}
    >
      <Paragraph
        style={{ margin: 0, whiteSpace: "pre-wrap", color: "inherit" }}
      >
        {message.content}
        {message.isStreaming && <span style={styles.cursor}>▍</span>}
      </Paragraph>

      {/* 引用来源 */}
      {message.sources && message.sources.length > 0 && (
        <div style={{ marginTop: 8 }}>
          <Text type="secondary" style={{ fontSize: 12 }}>
            参考来源：
          </Text>
          {message.sources.map((source, idx) => (
            <Tag key={idx} style={{ marginTop: 4, fontSize: 11 }}>
              {source.title}
            </Tag>
          ))}
        </div>
      )}
    </div>
  );
};

/** 内联样式 */
const styles: Record<string, React.CSSProperties> = {
  container: {
    display: "flex",
    flexDirection: "column",
    height: "100%",
    border: "1px solid #e8e8e8",
    borderRadius: 8,
    overflow: "hidden",
    backgroundColor: "#fff",
  },
  header: {
    display: "flex",
    justifyContent: "space-between",
    alignItems: "center",
    padding: "12px 16px",
    borderBottom: "1px solid #e8e8e8",
  },
  messageList: {
    flex: 1,
    overflow: "auto",
    padding: 16,
    display: "flex",
    flexDirection: "column",
    gap: 12,
  },
  empty: {
    display: "flex",
    justifyContent: "center",
    alignItems: "center",
    height: "100%",
    textAlign: "center" as const,
  },
  loading: {
    display: "flex",
    alignItems: "center",
    padding: 12,
  },
  inputArea: {
    display: "flex",
    alignItems: "flex-end",
    padding: "12px 16px",
    borderTop: "1px solid #e8e8e8",
    backgroundColor: "#fafafa",
  },
  bubble: {
    maxWidth: "80%",
    padding: "10px 14px",
    borderRadius: 12,
    wordBreak: "break-word" as const,
  },
  cursor: {
    display: "inline-block",
    animation: "blink 1s step-end infinite",
  },
};

九、踩坑清单与性能调优

以下是我们在 KMS 项目中实际踩过的坑，分享出来帮你省时间。

9.1 坑 1：检索结果不相关

现象：用户问"上线出问题怎么回退"，检索返回的却是"版本发布规范"、“代码分支管理”，没有回滚相关内容。

根因：默认的 CharacterTextSplitter 对中文不友好，在字符数处直接截断，导致"灰度发布回滚流程"这个标题和正文被切到了两个不同的 chunk 里。

解决：换成 RecursiveCharacterTextSplitter 并设置中文友好的分隔符优先级，同时在 separator 列表中加入中文标点：

# 关键改动：separators 列表
RecursiveCharacterTextSplitter(
    separators=["\n## ", "\n### ", "\n\n", "\n", "。", ". ", " ", ""],
    chunk_size=800,
    chunk_overlap=150,
)

另外，为了验证分块效果，建议写一个快速预览函数：

def preview_chunks(chunks: list, n: int = 5):
    """预览前 N 个 chunk 的内容，检查切分质量"""
    for i, chunk in enumerate(chunks[:n]):
        print(f"--- Chunk {i+1} ({len(chunk.page_content)} chars) ---")
        print(chunk.page_content[:300])
        print()

9.2 坑 2：API 调用频繁超限

现象：知识库有 2000+ 篇文档，全量入库时 OpenAI API 返回 429 Too Many Requests。

根因：Embedding API 有速率限制（text-embedding-3-small 为每分钟 3000 次请求），LangChain 默认没有做请求间隔。

解决：实现带退避重试和速率控制的批量入库：

import time
from typing import List
from langchain_core.documents import Document

def batch_embed_with_retry(
    chunks: List[Document],
    batch_size: int = 20,
    delay: float = 1.0,
) -> None:
    """分批次入库，批次间加延迟，失败自动重试。"""
    for i in range(0, len(chunks), batch_size):
        batch = chunks[i:i + batch_size]
        retries = 3
        while retries > 0:
            try:
                # 入库操作
                vectorstore.add_documents(batch)
                print(f"进度: {min(i + batch_size, len(chunks))}/{len(chunks)}")
                break
            except Exception as e:
                retries -= 1
                if retries == 0:
                    raise e
                print(f"重试中... ({3 - retries}/3), 错误: {e}")
                time.sleep(5 * (4 - retries))  # 指数退避
        time.sleep(delay)

9.3 坑 3：前端流式输出乱码

现象：前端收到的 SSE 数据中，中文字符偶尔出现乱码，一个汉字被拆成两个 \x 字节输出。

根因：后端 StreamingResponse 未显式设置 charset=utf-8，且前端 TextDecoder 的 stream: true 模式下，UTF-8 多字节字符跨越两次 read() 调用时被错误解码。

解决：双管齐下。

• 后端：Response Header 加上 Content-Type: text/event-stream; charset=utf-8
• 前端：使用 decoder.decode(value, { stream: true })（已在 8.3 节的 Hook 中体现），它会将不完整的多字节字符保留在下一次解码中。

9.4 坑 4：知识库更新后检索不准

现象：新增了 50 篇文档，重新执行入库脚本后，检索效果反而变差——旧文档检索不到了。

根因：Chroma 的 add 方法不会更新已有文档，而是追加。多次执行入库脚本导致同一个文档被重复添加多次，检索结果被旧版本的重复数据污染。

解决：区分"增量更新"和"全量重建"两种模式：

def update_knowledge_base(
    new_chunks: List[Document],
    mode: str = "incremental",  # "incremental" | "full_rebuild"
):
    """知识库更新，区分增量更新和全量重建。"""
    if mode == "full_rebuild":
        # 删除旧 collection，重新创建
        try:
            client.delete_collection("kms_knowledge")
        except Exception:
            pass
        create_vector_store(new_chunks)
    else:
        # 增量模式：使用 upsert 避免重复
        for chunk in new_chunks:
            chunk_id = hash(chunk.page_content[:100])  # 用内容哈希做 ID
            vectorstore.add_documents(
                [chunk],
                ids=[str(chunk_id)],  # 指定 ID，已存在则更新
            )

9.5 坑 5：大文档回答"遗忘"开头内容

现象：当某个文档 chunk 很长（接近 1000 字符），LLM 回答时只用到了后半部分信息，遗漏了开头的重要信息。

根因：虽然 GPT-4o-mini 有 128K 上下文窗口，但当 k=4 且 chunk_size=1000 时，传给 LLM 的内容总量并不大。问题出在 LLM 的"注意力衰减"——越靠后的内容越容易被"关注"，排在 Prompt 中间和前面的内容容易被忽略。

解决：

1. 将 k 控制在 3-5，避免塞太多信息
2. 对检索结果做排序：最相似的 chunk 放在 Prompt 最后面（离问题最近的位置）
3. 对超长 chunk 做二次截断：

def reorder_and_truncate(
    docs: List[Document],
    max_total_chars: int = 3000,
    k: int = 4,
) -> List[Document]:
    """
    重新排序检索结果并截断过长内容。
    最相关的放在最后（最接近用户问题的位置，LLM 关注度最高）。
    """
    docs = docs[:k]
    # 反转顺序：最相关的放最后
    docs = list(reversed(docs))
    
    total_chars = 0
    result = []
    for doc in docs:
        remaining = max_total_chars - total_chars
        if remaining <= 200:
            break  # 剩余空间不够放有意义的内容
        if len(doc.page_content) > remaining:
            doc.page_content = doc.page_content[:remaining] + "..."
        result.append(doc)
        total_chars += len(doc.page_content)
    
    return result

9.6 Embedding 参数调优速查表

十、总结

从零搭建一个 RAG 知识库问答系统，核心链路只有四步：文档加载分块 → 向量化入库 → 相似度检索 → LLM 生成回答。前端工程师完全可以在不深入 ML 原理的情况下，把这个系统跑起来并集成到项目中。

几点建议：

1. 先跑通，再优化。用 Chroma + OpenAI 这套组合最快半天就能看到效果，有了基线再逐步替换组件（比如换成本地部署的 BGE Embedding）。
2. 分块策略是核心。RAG 系统的质量天花板由分块决定。花时间调 chunk_size 和 separators，收益远高于换模型。
3. 前端是体验关键。流式输出、引用来源展示、停止生成、对话历史——这些前端细节决定用户是否愿意用你的 AI 功能。
4. 关注成本。text-embedding-3-small 的价格是 $0.02/1M tokens，GPT-4o-mini 是 $0.15/1M input tokens。以 KMS 2000 篇文档为例，全量入库的 Embedding 成本不到 $0.1，每次问答成本约 $0.002。

RAG 是前端工程师进入 AI 应用开发的最佳入口。它不要求你懂 Transformer 架构，只需要你理解"检索 + 生成"这个模式，然后用你擅长的工程化能力把它变成一个可靠的产品功能。