企业官网建设流程全解析

1. 这不是做个“聊天框”那么简单：RAG客户端的本质是人机协作的指挥中枢

很多人看到“给RAG系统写一个聊天界面”，第一反应是：“不就是套个前端模板，接个API，发个请求、收个响应，再渲染出来？”我去年也这么想，用Vue+Axios三小时搭了个带输入框和消息列表的页面，连上自己跑的FastAPI后端，看着文字一行行冒出来，还挺有成就感。直到客户提了第一个真实需求：“能不能让AI在回答里自动标出它引用的是哪份PDF第几页？点一下就跳转到原文？”——那一刻我才意识到，这个“聊天界面”根本不是UI层的装饰品，而是整个RAG系统对外输出的神经末梢，是用户与知识库、检索器、大模型之间所有交互逻辑的聚合点。它要处理的远不止HTTP请求：得管理会话状态防止上下文错乱，得解析流式响应避免卡顿，得把原始检索结果（比如向量相似度、chunk元数据）转化成用户能理解的溯源标记，还得在API返回400错误时，把“this model's maximum context length is 1048576 tokens”这种机器语言翻译成“您上传的文件太大，建议拆分成小于20MB的文档”。所以，这个项目标题里的“客户端开发”，核心不是写多少行HTML或CSS，而是设计一套健壮、可扩展、用户友好的人机协作协议。关键词里反复出现的“FastAPI”“OpenRouter API Key”“DeepSeek API如何调用”，其实都在指向同一个现实：我们面对的不是一个静态的、可控的内部服务，而是一个由多种LLM供应商（OpenRouter、DeepSeek、智谱、百度）、不同RAG框架（LangChain、LlamaIndex、Agentscope 2.0 RAG as Service）构成的异构生态。客户端必须足够“聪明”，能动态适配不同API的鉴权方式（Bearer Token、API Key Header）、响应格式（标准JSON、SSE流式、自定义字段）、错误码语义（400可能是参数错，也可能是token超限），甚至要预判像“api error: 400 this model's maximum context length…”这类高频报错，并给出可操作的修复建议。适合谁来参考？如果你正在用FastAPI搭建RAG后端，正为前端联调焦头烂额；如果你手上有现成的RAG知识库，但缺一个能真正落地给业务部门用的交互入口；或者你是个全栈开发者，想系统性地吃透RAG前后端协同的完整链路——这篇就是为你写的。它不讲抽象概念，只拆解真实世界里每一行代码背后的决策逻辑。

2. 客户端架构设计：为什么不能直接用ChatGPT网页版的思路？

2.1 核心矛盾：通用聊天UI vs RAG专用交互范式

通用大模型聊天界面（比如ChatGPT网页版）的设计哲学是“对话即一切”。它的输入框接收自然语言，输出区展示连续的文本流，上下文管理完全交给后端模型。但RAG客户端面对的是一个分阶段、多角色、强溯源的系统。一次典型的RAG问答流程是：用户提问 → 客户端将问题发送给后端 → 后端执行检索（从本地知识库或向量数据库中找出Top-K相关片段）→ 将问题+检索结果拼装成Prompt → 调用LLM API生成答案 → 返回结构化响应（含答案正文、引用来源、检索置信度等）。如果客户端照搬ChatGPT的UI，就会立刻暴露三个致命缺陷：

• 信息黑洞：用户看不到“AI到底查了哪些资料”，无法判断答案的可靠性。当回答出现偏差时，用户只能干瞪眼，没法反向追溯是检索错了，还是LLM幻觉了。
• 状态失控：RAG的会话状态比纯LLM复杂得多。除了对话历史，还涉及当前激活的知识库ID、检索参数（如top_k=3）、是否启用重排序（rerank）、甚至用户对某次检索结果的手动反馈（比如“这个引用不相关”）。这些状态若只存在后端内存里，刷新页面就全丢了。
• 错误失语：当后端返回{"code":"api_key_required","message":"api key is required in authorization header"}时，一个通用聊天框只会显示“请求失败”，而RAG客户端必须能识别这是认证问题，并引导用户去检查API Key配置，而不是让用户去翻后端日志。

所以我最终采用的架构是“三层驱动”：会话层（Session Layer）管理用户对话历史和RAG特有状态；溯源层（Provenance Layer）专门解析和渲染引用信息；适配层（Adapter Layer）屏蔽不同LLM供应商API的差异。这三层不是凭空设计的，而是被现实逼出来的。比如，当我第一次接入DeepSeek API时，发现它的流式响应格式是data: {"id":"...","choices":[{"delta":{"content":"..."}}]}，而OpenRouter的格式是data: {"choices":[{"delta":{"content":"..."}}]}，少了一层id字段。如果客户端没有适配层，就得为每个供应商写一套解析逻辑，维护成本爆炸。而有了适配层，只需要在配置里声明provider: "deepseek"，客户端就能自动加载对应的解析器，把原始流数据统一转换成标准的{content: string, source: {doc_id: string, page: number, score: number}}对象。

2.2 技术选型逻辑：为什么选React而非Vue或纯HTML？

项目标题里没限定前端框架，但结合热词中高频出现的“FastAPI项目目录结构”“RAG实战”，我默认这是一个需要快速迭代、与Python后端深度协同的工程化项目。Vue固然轻量，但其响应式系统在处理RAG特有的“部分更新”场景时略显笨重。举个例子：当用户提问后，后端先返回检索到的3个文档摘要（非流式），客户端需要立即在消息区下方显示“已检索到相关资料：《XX白皮书》P12、《YY指南》P5…”；几秒后，LLM才开始流式返回答案正文。这时，Vue的v-model绑定容易导致整个消息列表重新渲染，造成卡顿。而React的useReducer配合useEffect能精准控制：reducer只更新sources字段，useEffect监听sources变化并局部刷新溯源区块，答案流则由独立的useState管理。更重要的是，React生态里有大量成熟的RAG相关工具链。比如@langchain/core官方提供了React Hooks封装（useChat），能直接复用LangChain的Message Schema；react-markdown库能安全渲染LLM生成的Markdown内容，自动处理代码块、表格等富文本；react-virtualized则解决了长消息列表的性能瓶颈——当一次RAG问答返回50条引用时，虚拟滚动能让列表保持60fps。相比之下，纯HTML+JS方案虽然启动快，但一旦需要支持“点击引用跳转到PDF高亮位置”“拖拽上传新文档触发知识库增量更新”等功能，代码复杂度会指数级上升。我试过用原生JS写一个基础版本，光是处理SSE流式响应的连接重试、心跳保活、错误恢复，就写了200多行胶水代码，而React生态里一个useSSEHook就能搞定。

2.3 目录结构与模块职责：一个可维护的RAG客户端骨架

一个健康的RAG客户端，目录结构必须清晰反映其“协议驱动”的本质。我摒弃了常见的src/components/ChatBox.vue这种扁平化命名，而是按能力域划分：

src/ ├── api/ # 所有API通信逻辑，与UI彻底解耦 │ ├── clients/ # 不同供应商的SDK封装 │ │ ├── openrouter.ts # OpenRouter API Client，处理key注入、rate limit │ │ ├── deepseek.ts # DeepSeek API Client，处理stream parser、context window校验 │ │ └── local-rag.ts # 本地FastAPI RAG服务Client，支持文件上传、知识库切换 │ ├── adapters/ # 响应适配器，统一输出格式 │ │ ├── openrouter-adapter.ts # 将OpenRouter raw response → StandardRAGResponse │ │ └── deepseek-adapter.ts # 同上，处理其特殊的delta.content嵌套 │ └── index.ts # 对外统一API入口，export const ragApi = { chat, upload, listKb } ├── store/ # 状态管理，使用Zustand（轻量、TypeScript友好） │ ├── chatStore.ts # 核心会话状态：messages[], currentSessionId, activeKbId │ ├── sourceStore.ts # 溯源状态：currentSources[], selectedSourceIndex │ └── configStore.ts # 用户配置：defaultProvider, maxRetries, autoScroll ├── components/ # UI组件，严格遵循单一职责 │ ├── ChatInput.tsx # 输入框，集成文件拖拽、快捷指令（/upload /switch-kb） │ ├── MessageList.tsx # 消息列表，区分user/bot/system message类型 │ ├── SourcePanel.tsx # 独立的溯源面板，显示引用文档缩略图、页码、相似度 │ └── ErrorBoundary.tsx # 全局错误捕获，针对API error code做定制化提示 └── utils/ # 工具函数 ├── markdown.ts # 安全渲染Markdown，过滤危险HTML标签 └── token-calculator.ts # 估算输入文本token数，提前预警context length超限

这个结构的关键在于分离关注点。api/目录下的代码，可以脱离React环境单独单元测试——我用Jest跑过openrouter-adapter.ts的测试用例，模拟各种异常响应（401、429、503），验证适配器能否正确抛出RAGError并附带errorCode: 'AUTH_FAILED'。store/里的状态，通过Zustand的create函数定义，类型安全且调试友好。当我在Chrome DevTools里打开Zustand插件，能实时看到chatStore里每条消息的role、content、sources字段，以及sourceStore里当前选中的引用详情。这种可观察性，是快速定位“为什么用户点了引用没跳转”这类问题的基础。而components/里的每个组件，都只负责渲染，不掺杂任何业务逻辑。比如SourcePanel.tsx只接收sources: Source[]和onSelect: (source: Source) => void两个Props，至于“点击后是跳转PDF还是弹窗预览”，由父组件MessageList.tsx根据configStore里的previewMode配置决定。这种设计让组件复用率极高——我把SourcePanel稍作修改，就用在了知识库管理页的“文档预览”功能里。

3. 核心细节实现：从API调用到用户体验的12个关键点

3.1 API调用：不只是fetch，而是构建RAG专属的通信管道

RAG客户端的API调用，绝不是简单的fetch(url, {method: 'POST', body: JSON.stringify(data)})。它必须是一个有状态、可监控、可重试的通信管道。以最核心的chat接口为例，我定义了StandardRAGRequest类型：

interface StandardRAGRequest { message: string; // 用户输入的原始问题 sessionId?: string; // 会话ID，用于后端上下文管理 knowledgeBaseId?: string; // 指定知识库，支持多库切换 topK?: number; // 检索返回的片段数，默认3 enableRerank?: boolean; // 是否启用重排序，默认true stream?: boolean; // 是否启用流式响应，默认true }

这个类型的设计，直接源于对FastAPI后端/chat路由的深入分析。FastAPI的ChatRequestPydantic模型里，knowledgeBaseId是Optional[str]，意味着客户端必须能处理“未选择知识库”的场景（此时后端应返回可用知识库列表）。topK参数则来自实际业务需求：法务部门要求每次检索必须返回至少5个法律条文供人工复核，而客服部门觉得3个就够了。所以客户端不能硬编码topK=3，而要在UI里提供滑块控件，值实时同步到chatStore。

真正的挑战在于流式响应（SSE）的处理。很多教程教用fetch().then(res => res.body.getReader())，但这在RAG场景下有严重缺陷：当后端因网络抖动短暂断开SSE连接时，getReader()会抛出TypeError: Failed to fetch，而标准fetch没有内置重连机制。我的解决方案是封装一个RAGStreamClient类：

class RAGStreamClient { private controller: AbortController | null = null; async chat(request: StandardRAGRequest): Promise<AsyncIterable<StandardRAGResponse>> { this.controller = new AbortController(); const url = new URL('/chat', API_BASE_URL); url.searchParams.set('stream', 'true'); const response = await fetch(url.toString(), { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${getApiKey()}`, // 从configStore读取 }, body: JSON.stringify(request), signal: this.controller.signal, }); if (!response.ok) { throw new RAGError(`HTTP ${response.status}: ${response.statusText}`); } // 关键：用ReadableStream + pipeThrough构建可重连管道 const reader = response.body?.getReader(); if (!reader) throw new RAGError('No readable stream'); return this.createStreamIterator(reader, request); } private async *createStreamIterator( reader: ReadableStreamDefaultReader<Uint8Array>, request: StandardRAGRequest ): AsyncGenerator<StandardRAGResponse> { let buffer = ''; let retryCount = 0; const maxRetries = 3; while (retryCount < maxRetries) { try { const { done, value } = await reader.read(); if (done) break; // SSE格式解析：data: {...}\n\n buffer += new TextDecoder().decode(value); const lines = buffer.split('\n'); buffer = lines.pop() || ''; // 保留不完整的最后一行 for (const line of lines) { if (line.startsWith('data: ')) { const jsonStr = line.slice(6).trim(); if (jsonStr) { const parsed = JSON.parse(jsonStr); yield adaptResponse(parsed, request.provider); // 调用适配器 } } } } catch (error) { retryCount++; if (retryCount >= maxRetries) throw error; // 模拟退避重连：1s, 2s, 4s await new Promise(r => setTimeout(r, Math.pow(2, retryCount - 1) * 1000)); // 重建连接，携带上次的sessionId确保上下文连续 reader = (await this.reconnect(request)).getReader(); } } } private async reconnect(request: StandardRAGRequest) { // 重连逻辑：重新发起fetch，但带上lastEventId或sessionId const url = new URL('/chat', API_BASE_URL); url.searchParams.set('stream', 'true'); url.searchParams.set('resume_from', request.sessionId || ''); const response = await fetch(url.toString(), { method: 'POST', headers: { 'Authorization': `Bearer ${getApiKey()}` }, body: JSON.stringify(request), signal: this.controller?.signal, }); return response.body?.getReader()!; } }

这段代码的价值在于，它把“网络不可靠”这个客观事实，转化成了客户端可预测的行为。当用户看到消息区顶部出现“连接中断，正在重试…（1/3）”，而不是一片空白或报错弹窗，信任感就建立起来了。而且，adaptResponse函数是适配层的核心，它接收原始JSON，根据request.provider参数，调用openrouter-adapter.ts或deepseek-adapter.ts，将千奇百怪的供应商响应，统一成StandardRAGResponse：

interface StandardRAGResponse { content: string; // LLM生成的文本片段 sources?: Array<{ // 检索到的引用来源 docId: string; // 文档唯一标识 title: string; // 文档标题 page: number; // 页码 score: number; // 相似度分数（0-1） snippet: string; // 在原文中的上下文片段 }>; isFinal?: boolean; // 是否为最终响应（流式结束标志） }

3.2 溯源渲染：让“AI引用了什么”成为用户可操作的资产

RAG的终极价值不在答案本身，而在答案的依据。所以，客户端必须把sources字段，从一个后台调试用的JSON数组，变成用户可点击、可筛选、可导出的交互元素。我设计的SourcePanel组件，有三个核心交互：

• 智能摘要：不直接显示原始snippet（可能包含乱码或公式），而是用utils/markdown.ts进行清洗和截断。例如，snippet是“根据《网络安全法》第21条，“国家实行网络安全等级保护制度…””，清洗后显示为“《网络安全法》第21条：国家实行网络安全等级保护制度…”，并自动加粗关键条款号。
• 精准跳转：点击任一引用，触发window.open(/pdf-viewer?docId=${source.docId}&page=${source.page}#highlight, '_blank')。这里的关键是#highlight锚点，它告诉PDF.js在打开后自动高亮该页的对应段落。这个功能依赖后端在生成sources时，额外计算并返回highlightPosition坐标（基于PDF文本坐标系），客户端只需将其序列化进URL。
• 批量操作：在面板顶部提供“导出引用”按钮，生成一个标准的BibTeX格式文本，方便用户写报告时直接粘贴。BibTeX内容由source的title、author（从文档元数据提取）、year（从文件名或OCR识别）动态生成。

实现这些，需要客户端与后端深度协同。比如，为了支持精准跳转，后端FastAPI的/chat接口，在组装StandardRAGResponse时，必须调用PDF解析服务，获取每个snippet在原文中的精确坐标。客户端拿到坐标后，不是自己画高亮，而是信任PDF.js的getViewport和renderAPI。我踩过的坑是：早期版本直接用canvas绘制高亮矩形，结果在不同DPI屏幕下偏移严重。后来改用PDF.js官方推荐的Page.getViewport方法，传入scale=1.5获取视口，再用viewport.convertToViewportPoint(x, y)转换坐标，终于实现了像素级精准。

3.3 错误处理：把API报错翻译成用户能懂的行动指南

RAG客户端最常见的错误，不是网络不通，而是语义错误。热词里反复出现的api error: 400 this model's maximum context length is 1048576 tokens，就是一个典型。用户看到这个，第一反应是“我的网络坏了？”，而真相是：他上传了一份100页的PDF，RAG后端检索出20个相关片段，拼起来的Prompt总长度超过了DeepSeek模型的1M token上限。一个合格的客户端，必须把这个技术错误，翻译成用户可执行的步骤：

提示：AI模型处理能力已达上限。您的问题及关联资料过大，建议：

1. 缩短问题描述（当前约1200字，目标<300字）
2. 在知识库管理页，为该PDF设置更严格的检索条件（如限定章节范围）
3. 或联系管理员，升级至支持更大上下文的模型（如DeepSeek-VL）

这个提示不是静态文案，而是动态生成的。客户端在捕获到400错误后，会解析响应体里的message字段，用正则匹配maximum context length is (\d+) tokens，提取出1048576，再调用token-calculator.ts估算当前Prompt的token数（基于gpt-4tokenizer），最后计算出“超限比例”，决定提示的严厉程度。如果超限<10%，就只提示“问题稍长，可尝试精简”；如果超限>50%，就弹出上面那个带三条建议的模态框。

另一个高频错误是{"code":"api_key_required","message":"api key is required in authorization header"}。客户端不会简单显示“请检查API Key”，而是主动检测：configStore里是否有apiKey字段？如果有，检查其格式是否符合sk-xxx（OpenRouter）或ds-xxx（DeepSeek）的模式；如果没有，就引导用户去“设置”页填写，并高亮显示AuthorizationHeader的正确写法。这种“诊断式错误处理”，把用户从“猜错因”变成了“跟步骤”，大幅降低支持成本。

4. 实操全流程：从零搭建一个可运行的RAG聊天客户端

4.1 环境准备与依赖安装：避开那些坑人的版本陷阱

开始前，请确保你的Node.js版本≥18.17.0（V18.17.0是React 18.2.0的最低要求，而V18.18.0修复了SSE流式响应的内存泄漏Bug）。我强烈建议用nvm管理Node版本，避免全局污染：

# 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装并切换到Node 18.18.2 nvm install 18.18.2 nvm use 18.18.2 # 创建项目（使用Vite，比Create React App更快） npm create vite@latest rag-client -- --template react-ts cd rag-client npm install # 安装核心依赖 npm install zustand @tanstack/react-query react-markdown remark-gfm rehype-sanitize pdfjs-dist npm install --save-dev @types/pdfjs-dist @types/react-markdown

这里有个关键细节：pdfjs-dist的版本必须锁定在2.16.105。因为2.17.x版本引入了ESM-only模块，与Vite的默认配置冲突，会导致import * as pdfjsLib from 'pdfjs-dist'报错。我在package.json里强制指定了版本：

"dependencies": { "pdfjs-dist": "2.16.105" }

同时，在vite.config.ts里添加别名，解决PDF.js Worker路径问题：

import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], resolve: { alias: { 'pdfjs-dist/build/pdf.worker.entry': 'pdfjs-dist/build/pdf.worker.entry.js' } } })

4.2 FastAPI后端对接：编写第一个可工作的API调用

假设你的FastAPI后端已部署，地址为http://localhost:8000，且/chat接口遵循标准RAG协议。现在，我们编写src/api/clients/local-rag.ts：

// src/api/clients/local-rag.ts import { StandardRAGRequest, StandardRAGResponse } from '../index'; import { adaptLocalRAGResponse } from '../adapters/local-rag-adapter'; const API_BASE_URL = 'http://localhost:8000'; export const localRAGClient = { async chat(request: StandardRAGRequest): Promise<StandardRAGResponse[]> { const response = await fetch(`${API_BASE_URL}/chat`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(request), }); if (!response.ok) { const errorData = await response.json(); throw new Error(`API Error ${response.status}: ${errorData.detail || 'Unknown'}`); } const data = await response.json(); // 注意：本地FastAPI返回的是完整数组，非流式 return data.map((item: any) => adaptLocalRAGResponse(item)); }, async uploadFile(file: File): Promise<{ docId: string; title: string }> { const formData = new FormData(); formData.append('file', file); const response = await fetch(`${API_BASE_URL}/upload`, { method: 'POST', body: formData, }); if (!response.ok) { throw new Error(`Upload failed: ${response.status}`); } return response.json(); } };

对应的适配器src/api/adapters/local-rag-adapter.ts：

// src/api/adapters/local-rag-adapter.ts import { StandardRAGResponse } from '../index'; export function adaptLocalRAGResponse(raw: any): StandardRAGResponse { return { content: raw.answer || '', sources: raw.sources?.map((s: any) => ({ docId: s.doc_id, title: s.title || '未知文档', page: s.page || 1, score: s.score || 0, snippet: s.snippet || '' })), isFinal: true }; }

现在，在src/store/chatStore.ts里初始化状态：

// src/store/chatStore.ts import { create } from 'zustand'; import { localRAGClient } from '../api/clients/local-rag'; interface ChatState { messages: Array<{ role: 'user' | 'assistant' | 'system'; content: string; sources?: any[] }>; sendMessage: (message: string) => Promise<void>; } export const useChatStore = create<ChatState>((set) => ({ messages: [], sendMessage: async (message) => { // 添加用户消息 set((state) => ({ messages: [...state.messages, { role: 'user', content: message }] })); try { // 调用后端 const response = await localRAGClient.chat({ message }); // 添加AI回复 set((state) => ({ messages: [ ...state.messages, { role: 'assistant', content: response[0].content, sources: response[0].sources } ] })); } catch (error) { set((state) => ({ messages: [ ...state.messages, { role: 'system', content: `出错了：${error instanceof Error ? error.message : '未知错误'}` } ] })); } } }));

4.3 构建核心UI：一个最小但完整的聊天界面

创建src/components/ChatInput.tsx：

// src/components/ChatInput.tsx import { useState, useRef, KeyboardEvent } from 'react'; import { useChatStore } from '../store/chatStore'; export default function ChatInput() { const [inputValue, setInputValue] = useState(''); const textareaRef = useRef<HTMLTextAreaElement>(null); const { sendMessage } = useChatStore(); const handleSubmit = async () => { if (!inputValue.trim()) return; await sendMessage(inputValue); setInputValue(''); }; const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); handleSubmit(); } }; return ( <div className="border-t border-gray-200 p-4"> <textarea ref={textareaRef} value={inputValue} onChange={(e) => setInputValue(e.target.value)} onKeyDown={handleKeyDown} placeholder="输入问题，例如：公司最新的差旅报销标准是什么？" className="w-full p-3 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 resize-none" rows={3} /> <div className="mt-2 flex justify-end"> <button onClick={handleSubmit} disabled={!inputValue.trim()} className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors" > 发送 </button> </div> </div> ); }

创建src/components/MessageList.tsx，重点展示如何渲染溯源：

// src/components/MessageList.tsx import { useChatStore } from '../store/chatStore'; import { useEffect, useRef } from 'react'; import remarkGfm from 'remark-gfm'; import rehypeSanitize from 'rehype-sanitize'; import ReactMarkdown from 'react-markdown'; export default function MessageList() { const messages = useChatStore(state => state.messages); const messagesEndRef = useRef<null | HTMLDivElement>(null); // 自动滚动到底部 useEffect(() => { messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' }); }, [messages]); return ( <div className="flex-1 overflow-y-auto p-4 space-y-6"> {messages.map((msg, index) => ( <div key={index} className={`flex ${msg.role === 'user' ? 'justify-end' : 'justify-start'}`}> <div className={`max-w-3xl px-4 py-2 rounded-lg ${ msg.role === 'user' ? 'bg-blue-500 text-white' : msg.role === 'system' ? 'bg-yellow-100 text-yellow-800' : 'bg-gray-100 text-gray-800' }`}> {msg.role === 'assistant' && msg.sources && msg.sources.length > 0 && ( <div className="mb-2 text-xs text-gray-600"> <strong>引用来源：</strong> {msg.sources.map((source, i) => ( <span key={i} className="ml-1"> <a href="#" onClick={(e) => { e.preventDefault(); alert(`跳转到 ${source.title} 第 ${source.page} 页`); }} className="text-blue-600 hover:underline" > {source.title} P{source.page} </a> {i < msg.sources.length - 1 && ' · '} </span> ))} </div> )} <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeSanitize]} className="prose prose-sm max-w-none" > {msg.content} </ReactMarkdown> </div> </div> ))} <div ref={messagesEndRef} /> </div> ); }

最后，在src/App.tsx中组合：

// src/App.tsx import MessageList from './components/MessageList'; import ChatInput from './components/ChatInput'; function App() { return ( <div className="flex flex-col h-screen bg-gray-50"> <header className="bg-white shadow-sm p-4"> <h1 className="text-xl font-bold text-gray-800">RAG知识助手</h1> <p className="text-sm text-gray-600">基于本地知识库的智能问答</p> </header> <main className="flex-1 overflow-hidden"> <MessageList /> </main> <ChatInput /> </div> ); } export default App;

运行npm run dev，一个基础但功能完整的RAG聊天界面就跑起来了。它能发送问题、接收答案、显示引用来源，并支持基本的Markdown渲染。这只是一个起点，后续你可以按需集成文件上传、知识库切换、多会话管理等功能。

5. 常见问题与排查技巧实录：那些只有亲手踩过才知道的坑

5.1 “消息不显示/卡在‘思考中’”——SSE流式响应的隐形杀手

现象：用户发送问题后，界面上一直显示“AI正在思考…”，但没有任何内容返回，控制台也没有报错。

排查思路：

1. 首先确认后端是否真的在发送SSE流。用curl -N http://localhost:8000/chat?stream=true -H "Content-Type: application/json" -d '{"message":"test"}'，看终端是否有data: {...}持续输出。
2. 如果后端正常，问题大概率在客户端的ReadableStream处理。常见原因是TextDecoder().decode(value)在处理二进制流时，遇到不完整的UTF-8字符（比如一个中文字符被截断在两个Uint8Array块之间），导致解码失败，后续split('\n')失效。
3. 终极解决方案：改用TransformStream做流式解码，它能自动缓冲不完整的字符：

// 替换原来的buffer += new TextDecoder().decode(value) const decoder = new TextDecoder('utf-8', { fatal: false }); const transformStream = new TransformStream({ transform(chunk, controller) { const decoded = decoder.decode(chunk, { stream: true }); controller.enqueue(decoded); } }); const reader = response.body?.pipeThrough(transformStream).getReader();

5.2 “引用跳转失效/高亮错位”——PDF坐标系的时空错乱

现象：点击引用后，PDF确实打开了，但高亮位置偏移了几行，或者完全找不到。

根因分析：

• PDF.js的Page.getViewport返回的坐标系，是以页面左上角为原点，单位是CSS像素。
• 而后端OCR或文本提取服务返回的highlightPosition，通常是基于PDF原始坐标系（单位是磅point，原点在左下角）。
• 两者之间存在旋转、缩放、原点偏移三重变换。

实操修复：

1. 后端必须统一输出坐标系。我要求所有PDF解析服务，输出{ x: number, y: number, width: number, height: number }，单位为页面归一化坐标（0-1），即x=0.5表示页面水平中点。
2. 客户端在PDF.js加载完成后，获取当前viewport，然后用viewport.convertToViewportPoint转换：

const viewport = page.getViewport({ scale: 1.5 }); const rect = viewport.convertToViewportRectangle({