最近帮一家公司搭了一套企业内部知识库智能问答系统技术选型敲定用 Python TypeScript FastAPI React。这个组合确实是目前做 AI 应用落地比较顺手的全栈方案Python 负责文档解析、向量检索和模型调用这些 AI 核心逻辑FastAPI 把 AI 能力包装成接口React 和 TypeScript 撑起上传、管理、对话这些前端交互。整套系统上线后员工直接通过浏览器提问就能从散落几十个部门的知识文档里拿到答案不用再靠问人大海捞针。今天把它的设计思路、核心实现、联调踩坑从头到尾整理一遍给正准备做类似 AI 全栈项目的朋友一个参考。1. 项目整体设计与技术选型解读1.1 为什么用 Python FastAPI React TS 这套组合先说说技术栈怎么定的。Python 在 AI 生态里的地位几乎没有争议不管是做文本分块、Embedding 向量化还是调用大模型接口、接 LangChain 这类框架Python 的工具链最全。项目里我用了不少 Python 库像文档解析、向量计算、openai SDK 之类的换成其他语言会别扭很多。FastAPI 作为 API 层是后补的但它天然支持异步正好匹配大模型流式响应这种长连接场景而且自带 Swagger 文档前端和后端联调时直接打开 /docs 就能看到所有接口的请求响应结构省了来回对文档的沟通成本。React TypeScript 则是前端工程化的稳妥选择组件生态丰富类型系统能让后端返回的数据结构在前端提前暴露问题像 messages 数组里每个字段是什么类型、可能为空的情况编译阶段就能发现不用等运行时报错再排查。有朋友问我为什么不直接用 Django 或者 Flask。不是不能用而是这个场景里 FastAPI 的异步能力更实用。大模型接口动辄几十秒才返回完如果用 Flask 同步处理一个请求占着一个线程并发稍微上来服务就扛不住。FastAPI 的 async 配合异步 HTTP 客户端可以在等待模型返回时释放线程处理其他请求性能和管理成本都更理想。前端为什么不用 Vue也不是不行只是 React 在 AI 交互组件这块更成熟比如流式渲染、虚拟列表、状态管理这些都有现成方案团队上手也快。1.2 从“文档入库”到“问答生成”的整体架构整个系统的核心是 RAG检索增强生成逻辑上分成两条管道。一条是入库管道用户上传文档后端先解析出纯文本接着把长文档切分成小块把每一块做向量化最后连同原文一起存入向量数据库。另一条是问答管道用户提问后先把问题也做向量化在向量库里找与问题最相关的若干文档块把这些文档块和问题一起组装成 Prompt交给大模型生成回答回答再流式返回给前端。这样设计的好处是模型不需要“记住”整本知识库每次回答只要从库里捞出相关的片段即可既绕开了上下文窗口有限的问题又能把信息来源追溯到具体文档块用户看到答案时可以反查原文可信度比直接问大模型高得多。系统里除了这两条管道还有用户认证、文件管理、对话历史这些常规功能模块它们围绕 RAG 管道组成完整的业务闭环。为了把职责理清楚我把系统按后端模块分成了五个部分模块职责关键实现点auth登录认证与会话管理JWT 签发与校验documents文档上传、列表、删除、内容解析支持 PDF/Word/Markdown/TXTchat对话接口、引用来源返回、流式输出SSEServer-Sent Eventsvector_store分块、向量化、检索、向量持久化FAISS 本地索引llm_adapter大模型接口适配与 Prompt 组装统一模型调用封装1.3 功能模块怎么拆前端按页面拆成三块登录页、知识库管理页、对话页。登录页走标准账号密码签发 JWT token 存到本地后续请求自动带上。知识库管理页负责文档列表展示、上传、删除上传后后端返回每个文档的分块数量方便用户确认入库是否成功。对话页则支持连续多轮提问保留上下文记忆并且展示每条回答对应的知识来源。这个拆法最大的好处是前后端可以并行开发。只要先定好接口协议我这边写 FastAPI 的同时前端同事可以照着 Swagger 文档先把页面搭起来。等到联调阶段大家手里的代码都已经成熟接口一对接就能跑通全流程后面我们聊到联调效率时还会再提到这一点。2. 知识库的核心链路文档处理、向量化与检索调优2.1 文档分块chunk_size 和 overlap 怎么定知识库质量的关键不在模型在文档分块。这个观点我每次做 RAG 都要强调。分块太粗一块里面塞了多个主题问题只命中其中的一小段检索召回的噪音就大分块太细语义又被切碎比如一句话被拦腰截断向量化出来的效果会很差。我实际测试下来中文场景下 chunk_size 取 500 到 800 个字符比较合适overlap 取 50 到 100 个字符。overlap 是分块之间重叠的部分用来保住边界信息的关联性否则一段结论正好被切到块尾下一块的提问就检索不到它。举个例子一份 3000 字的制度文档按 500 字符一块、overlap 80 来切大概能切出 7 块其中每相邻两块共享一段重叠文本。这相当于用一点索引空间换召回率。如果是像合同、规章这种标题层级明显的文档我建议优先按标题和段落切分而不是死板固定长度。我在实现里做了一层混合策略先用正则识别 Markdown/文档的标题层级再按标题块切分块超长时才启用固定长度切分。这样分出来的块语义完整性更好测试下来检索准确率能有明显提升。2.2 向量化与向量库选型FAISS 还是 Chroma向量化这块是 Embedding 模型的选择。系统初期访问量不大我直接用开源的 bge-small-zh 中文 Embedding 模型本地跑推理一条文档分块向量化平均不到几十毫秒。如果是英文资料为主或者对效果要求很高再考虑商业 API。用 Embedding 模型时有一点必须做向量归一化。不归一化直接做内积相似度长文档块的分数会天然偏高归一化之后内积等价于余弦相似度检索更公平。实现就三行代码import numpy as np embeddings model.encode(chunks) embeddings embeddings / np.linalg.norm(embeddings, axis1, keepdimsTrue)向量库选型我对比过 FAISS 和 Chroma。Chroma 优点是有元数据过滤可以按文档 ID、标签过滤后检索开发体验好但它是嵌入式服务依赖和文件结构要多维护一层。FAISS 是纯库直接加载到内存建索引、写入本地文件适合百万以内级别的向量性能足够部署成本也低。国内很多内部知识库的体量其实都够用 FAISS 了所以我在这里选 FAISS。如果未来文档量到千万级别、需要分布式横向扩展再迁移到 Milvus 也不迟接口层面我做的数据访问抽象能平滑替换。2.3 检索参数top_k、相似度阈值与重排序检索是 RAG 的命门。top_k 我默认取 5也就是每次检索返回最相关的 5 个文档块。取太小召回内容可能覆盖不全取太大Prompt 塞进去一堆无关内容既浪费上下文窗口又干扰模型判断。除了 top_k还要设置相似度阈值。即使 top_k5如果第 5 个块的相似度已经滑到 0.25 以下说明它跟问题基本无关宁可直接丢掉也不要硬塞给模型。我实践中阈值设在 0.3 到 0.5 之间具体数值需要结合 Embedding 模型的性质微调。还有一个能明显提升效果的手段是重排序Rerank。在向量检索拿回 20 个候选块之后用一个排序模型对它们做精细打分再取前 5 个进 Prompt。虽然多了一次模型调用但命中率提升非常显著尤其是在文档库里主题相近内容多的场景。如果项目预算有限可以先用 Embedding 相似度硬选 top_k 起步跑通之后再慢慢加重排序。3. FastAPI 后端落地接口设计、任务处理与流式问答3.1 FastAPI 工程目录与依赖清单后端工程结构我按功能纵向切分目录如下backend/ ├── app/ │ ├── main.py # 应用入口注册路由与中间件 │ ├── config.py # 配置项读取环境变量 │ ├── db.py # SQLite 连接与初始化 │ ├── routers/ │ │ ├── auth.py # 登录与 token 相关接口 │ │ ├── documents.py # 文档上传、列表、删除 │ │ └── chat.py # 问答与流式接口 │ ├── services/ │ │ ├── parser.py # 文档解析 │ │ ├── splitter.py # 分块逻辑 │ │ ├── embedder.py # 向量化 │ │ ├── retriever.py # 向量检索 │ │ └── llm_client.py # 大模型调用封装 │ └── models/ │ └── schemas.py # Pydantic 请求与响应模型依赖我用 requirements.txt 管理不追求 poetry 是因为团队成员已经熟悉 pip 工作流。核心依赖fastapi、uvicorn[standard]、python-multipart解析上传文件用、pydantic-settings读取配置、faiss-cpu、numpy、openai模型接口、python-jose 或 PyJWTJWT 认证。特别注意 python-multipart 一定要装否则 FastAPI 解析 multipart 表单的时候直接报 500。3.2 文档上传接口从文件到向量库的完整链路文档上传接口是入管道的第一步。整个流程接收文件 → 保存原始文件 → 解析纯文本 → 分块 → 向量化 → 写入 FAISS 索引和 SQLite 元数据表 → 返回文档 ID 和分块数。核心代码大概是这样的router.post(/documents) async def upload_document( file: UploadFile File(...), user: User Depends(get_current_user), ): content await read_and_parse(file) chunks split_document(content) vectors embed(chunks) doc_id save_vector_and_meta(file.filename, chunks, vectors) return {doc_id: doc_id, chunk_count: len(chunks)}注意文档解析不能写进同步代码直接跑。PDF 解析和长文本分块可能耗时数秒放在请求线程里会让整个接口阻塞前端体验就是上传后转圈几十秒没反应。我这里的处理是先同步解析中小文件再借助 FastAPI 的 BackgroundTasks 做向量化入库接口立即返回“已接收处理中”的状态前端再轮询查询处理结果。如果以后文档量大了可以升级成 Celery 任务队列但初期 BackgroundTasks 完全够用。另外解析 PDF 时中文编码容易出问题实测 PyMuPDF 对中文 PDF 的抽取效果比 PyPDF2 好得多建议直接用前者。3.3 问答流式接口基于 SSE 让 AI“边说边显示”问答接口是整个系统里体验最敏感的一环。如果等大模型完整生成几十秒再一次性返回用户会有明显的等待焦虑用流式返回让内容像打字机一样逐字出现等待感会大幅降低。推荐用 SSEServer-Sent Events它比 WebSocket 更适合这种场景。SSE 是单向服务端推送浏览器原生支持断线自动重连前端处理逻辑简单WebSocket 适合双向频繁交互这里反而显得杀鸡用牛刀。FastAPI 实现流式接口非常直接用 StreamingResponse 配合异步生成器from fastapi.responses import StreamingResponse import json router.post(/chat/stream) async def chat_stream(req: ChatRequest): context retrieve_context(req.question) messages build_prompt(req.history, req.question, context) async def generate(): async for delta in llm_stream(messages): yield fdata: {json.dumps({delta: delta}, ensure_asciiFalse)}\n\n yield data: [DONE]\n\n return StreamingResponse(generate(), media_typetext/event-stream)需要特别说明的是 ensure_asciiFalse 这个细节。如果忘了加Python 的 json.dumps 会把中文转成 \uXXXX 序列前端拿到的是转义后的 Unicode 而不是文字虽然也能渲染出来但调试时看着头疼而且网络传输体积会变大。我一开始就因为这个排查了大半天后来养成了习惯所有 AI 相关接口返回 JSON 全部带上 ensure_asciiFalse。4. React TypeScript 前端知识库管理与 AI 对话交互4.1 用 Vite 初始化前端与目录规划前端我直接用 Vite 初始化 React TypeScript 模板命令是npm create vitelatest frontend -- --template react-ts。Vite 在本地开发时冷启动和热更新都很快相比老牌 CRA 或者自己手写 Webpack 配置省事得多。初始化好后我把代码按模块组织src/ ├── components/ # 通用组件比如上传、文档卡片 ├── pages/ # 登录页、知识库页、对话页 ├── api/ # 后端接口封装 ├── types/ # 全局 TS 类型定义 ├── hooks/ # 自定义 Hooks比如 useChat └── utils/ # token 存储、SSE 解析等工具这种目录组织对团队协作友好新加入的成员看目录结构就能知道某个功能应该在哪个文件里改。types 单独抽出来的好处是后端接口返回的数据结构变动时只需要改一处类型定义所有引用它的页面都会同时报错提醒比运行时才发现要靠谱得多。4.2 知识库管理页上传、列表、删除知识库管理页的功能不算复杂但工程上的坑不少。上传组件我先用 Ant Design 的 Upload 组件包一层限制文件类型为 PDF、Word、Markdown、TXT并且在前端做文件大小预校验超过 50MB 的直接拦截避免把压力打到后端。列表页用 Ant Design Table展示文件名、上传时间、分块数和解析状态。解析状态在后端是异步的我做了两种处理上传后立即显示“处理中”同时前端定时轮询后端状态接口状态变成“已入库”后自动刷新表格。关于删除还有一个容易忽略的点前端删除文档的同时后端必须把该文档在 FAISS 索引里的向量一并删除否则向量库里留着“幽灵向量”检索结果里会出现已经被删除的文档内容。我在后端元数据表里记录了每个文档分块对应的 FAISS 索引范围删除时定位这块范围重建索引。这个逻辑单独写了个服务函数每次删文档都会先调它再删元数据顺序不要反否则索引清理就会遗漏。4.3 对话页SSE 流式渲染与 Hooks 设计对话页是用户感知最直观的部分。我封装了一个 useChat 自定义 Hook把消息状态和流式请求逻辑集中管理function useChat() { const [messages, setMessages] useStateMessageItem[]([]); const [loading, setLoading] useState(false); async function send(question: string) { setMessages((prev) [...prev, { role: user, content: question }]); setLoading(true); const res await fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ question, history: messages.slice(-6) }), }); if (!res.body) return; const reader res.body.getReader(); 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 }); const lines buffer.split(\n); buffer lines.pop() ?? ; for (const line of lines) { if (!line.startsWith(data: )) continue; const data JSON.parse(line.slice(6)); if (data.delta) { setMessages((prev) { const copy [...prev]; const last copy[copy.length - 1]; if (last.role assistant) { last.content data.delta; } else { copy.push({ role: assistant, content: data.delta }); } return copy; }); } } } setLoading(false); } return { messages, send, loading }; }这个 Hook 有几个值得注意的点。历史消息只截取最后 6 条传给后端是避免上下文过长造成 token 浪费流式更新消息时要在回调里复制数组再更新不要直接改 state 引用的对象这是 React 不可变数据的硬性要求否则界面不会刷新。SSE 数据是按行传输的底层 TCP 分片可能把一条 data 拆成多段所以必须用 buffer 等换行符再解析我见过不少新手在这里直接 parse 一段不完整 JSON 然后整个程序崩溃这个细节非常关键。聊天区域自动滚动到最新消息也是体验必备项我拿一个 ref 挂在消息列表底部每次 messages 变化时调用el.scrollIntoView({ behavior: smooth })。输入框按回车发送、ShiftEnter 换行这个小交互很多人一开始想不到但做了之后日常使用会顺手很多。5. 联调与上线过程中的常见问题实录5.1 前后端跨域问题排查本地开发时前端跑在 5173 端口后端跑在 8000 端口浏览器默认跨域拦截这是项目的第一个拦路虎。解法是在 FastAPI 里加 CORSMiddleware把前端地址加进 allow_origins。注意生产环境不要图省事用allow_origins[*]因为这意味着任何网站都能调用你的接口配合 JWT 一旦出现泄漏风险是放大的。生产环境我直接在 Nginx 同域名反向代理前端请求 /api 前缀走后端完全绕开跨域。开发环境才保留 CORS 配置。5.2 SSE 流式返回被 Nginx 缓冲本地联调时 SSE 一切正常一上生产就发现回答不是逐字出现而是等几十秒后一次性全部渲染出来。问题几乎都出在 Nginx 默认开启了缓冲流式数据被攒在代理缓冲区里直到断开才一次性发给浏览器。处理方式在 Nginx 配置里加三行location /api/chat/stream { proxy_pass http://backend:8000; proxy_buffering off; proxy_cache off; proxy_http_version 1.1; }另外后端响应头里最好显式加X-Accel-Buffering: no这是给 Nginx 看的指令双保险。我后来排查这个问题时发现如果用了 Uvicorn 多 worker还要保证同一个用户的连接尽量落到同一个 worker 上否则流式过程中换了个进程处理连接可能直接被切断。5.3 中文文档检索效果差答非所问系统刚上线时用户反馈中文问题经常找不到对的内容。排查后发现是 Embedding 模型选了一个偏英文优化的通用模型对中文语义支持很弱。换用 bge-small-zh 这类中文专项 Embedding 模型后召回效果立刻改善。这是任何中文 RAG 项目都要提前想清楚的事Embedding 模型语言适配性直接决定整个检索链路的基线质量。如果已经用了好的中文模型还是有偏差那就要检查分块策略看看是不是 chunk_size 太大导致块内主题混乱或者知识库里本身存在大量相似文档让检索难以区分。5.4 上传大 PDF 直接超时有用户上传一份几百页的 PDF前端等了半分钟后端接口直接 502。原因很直接解析、分块、向量化全部同步执行占住了 worker上游代理等待超时。我的解法是分三步前端限制单文件大小并给出提示后端接口先保存文件、把处理任务放进 BackgroundTasks 立刻返回前端轮询处理状态处理完成后再刷新列表。这样即便大文档用户也只有上传过程等待处理过程是异步的体验不会断掉。如果以后要处理超大文档或者批量导入再上任务队列也不迟现阶段这个设计复杂度刚刚好。5.5 版本兼容问题速查表我整理了一份容易踩的版本兼容清单方便直接对照现象常见原因处理方式FastAPI 上传接口 500缺少 python-multipart安装 python-multipartOpenAI SDK 调用报错v0.x 与 v1.x 接口差异大统一锁版本不要混用FAISS 加载崩溃安装的是 GPU 版或 CPU 版混淆统一 faiss-cpuTS 类型定义与后端不一致接口改版后类型未同步后端改接口后同步改 types/Python 3.10 以下启动异常Pydantic v2 依赖新特性使用 Python 3.11版本问题看起来琐碎但最消耗时间。我的习惯是项目初期就把核心依赖版本写死进 requirements.txt 和 package.json而不是用最新版或者通配符宁可后续手动升级也不要默默踩到不兼容的坑。6. 部署要点与后续扩展建议6.1 Docker 化部署与反向代理配置部署我用 Docker 前后端分别打包再用 docker-compose 串起来。后端镜像基于 python:3.11-slim装依赖后跑 uvicorn前端镜像基于 node 构建产物再用 nginx 提供静态文件服务。docker-compose 简化版长这样services: backend: build: ./backend volumes: - ./data:/app/data environment: - EMBEDDING_MODELbge-small-zh - DATABASE_URLsqlite:///./data/kb.db restart: always frontend: build: ./frontend ports: - 80:80 depends_on: - backend前端 Nginx 配置里把 /api/ 路径反向代理到 backend 容器其余路径服务静态文件。这里有一点要注意SSE 接口的代理一定要关闭缓冲并且建议线上用 TLS因为 JWT token 和对话内容涉及企业内部信息明文传输很危险。容器化还有一个隐形好处是数据目录可以挂载到宿主机我把它单独放到 ./data 下备份、迁移、回滚都简单。6.2 跑通后的体验复盘与后续扩展整个系统上线后第一批测试用户反馈比我预期的好。几百份制度文档、几十个并发问题答案的中文可读性和来源追溯都过关。但我也清楚这个版本离“生产就绪”还有距离。企业客户接下来大概率会提这几个需求按部门隔离知识库并做细粒度权限控制、文档增量更新而不必全部重新入库、引用回答时支持定位到具体页数和段落、对话历史支持导出审计。如果后续要做多知识库隔离我会把向量库改成按租户分索引并在检索入口加上严格的权限过滤增量更新的关键是文档内容指纹比对解析后先算哈希只有变更的部分才重新分块入库。我实际测试中还发现系统在回答“知识库里没有的信息”时模型可能会一本正经地编造内容这种情况在核心业务场景里是致命的。所以我建议在最终 Prompt 里明确约束“如果上下文没有相关内容请直接说明不知道”并在前端回答底部标注“本次回答基于以下 X 个文档片段”让用户自行判断可信度。有人会觉得这个提示词太保守但企业场景里宁可少说也不能说错这是做内部知识库和大模型泛聊最大的区别。最后再分享一个小技巧这套系统的接口协议是先定义的前后端从第一天就照着同一份文档开发。我个人的体会是AI 项目迭代速度太快今天定完的接口明天可能就要加参数如果等后端全写完再让前端切入联调阶段必定爆炸。先把 RAG 链路用最简单的代码跑通一个最小闭环再逐步补权限、补流式、补重排序比一开始就铺开整个架构要稳得多。希望这篇完整的技术复盘能给你接下来的项目省一点绕路的功夫。