企业官网建设流程全解析

TraceRAG：从功能型 Demo 到面试级项目，我的企业技术文档知识库问答系统设计

很多 RAG 项目都会被概括成一句话：

上传文档，切分文本，写入向量库，再让大模型回答问题。

这类项目可以证明自己会使用 LangChain、Milvus 和大模型 API，但在面试中很容易陷入同质化。因为绝大多数候选人都能完成“文档上传 + 向量检索 + 问答”的基础闭环。

因此，我没有把项目定位为泛化的“知识库问答系统”，而是将其定位为：

TraceRAG：一个面向企业技术文档的可观测、可追踪、可优化的 RAG 知识库问答系统。

系统面向产品手册、技术说明书、论文、复杂 PDF 等非结构化资料，提供从文档导入、解析、切分、混合检索、答案生成到会话历史管理的完整能力，并重点关注 RAG 在企业落地过程中的可维护性、可解释性和可评测性。

一、项目背景

企业内部往往积累了大量 PDF、产品说明书、操作手册、技术规范和历史文档。这些资料存在几个典型问题：

• 文档格式复杂，包含标题、表格、图片和多栏排版；

• 信息分散，员工需要花费大量时间查找；

• 同一产品可能有多个名称、别名或型号；

• 传统关键词搜索难以理解自然语言问题；

• 直接让大模型回答容易出现幻觉，也无法引用知识来源。

因此，项目目标并不是简单“接入一个聊天机器人”，而是构建一套能够将企业文档转化为可检索知识，并通过检索增强生成（RAG）提供可信回答的系统。

二、项目定位与核心特色

相比“功能全面的知识库问答系统”，TraceRAG 的定位更明确：

面向复杂技术文档的、具备检索增强、链路追踪、故障降级和效果评测能力的企业级 RAG 系统。

项目的设计重点可以归纳为三层。

第一层：基础 RAG 能力 文档上传 -> 解析 -> 切分 -> 向量化 -> 入库 -> 问答 第二层：检索增强能力 主体识别 -> 普通检索 -> HyDE -> RRF 融合 -> Reranker 重排 第三层：企业化演进能力 会话历史 -> 资源存储 -> 任务状态 -> 故障降级 -> 观测与评测

其中，第三层是项目区别于普通 RAG Demo 的关键，也是后续重点建设的方向。

三、当前已实现功能

1. 知识导入：将复杂文档转化为可检索数据

目前系统支持 PDF 和 Markdown 文档导入，完整导入链路如下：

上传文档 -> MinerU 解析 PDF -> 转换为 Markdown -> 图片提取并上传 MinIO -> 文档切分为 Chunk -> 识别文档或产品名称 -> 生成 BGE-M3 稠密/稀疏向量 -> 写入 Milvus

已实现能力包括：

• 支持上传 PDF、Markdown 文档；

• 使用 MinerU 将 PDF 解析为 Markdown；

• 解析文档中的图片并上传至 MinIO；

• 将长文档切分为可检索的 Chunk；

• 自动识别文档名、产品名或实体名称；

• 使用 BGE-M3 生成稠密向量和稀疏向量；

• 将知识内容写入 Milvus 的kb_chunks集合；

• 将文档或产品名称写入kb_item_names集合，为后续主体识别和过滤提供支持。

这里的设计并不是直接对 PDF 原文粗暴切分，而是先完成结构化解析，再进行文本处理。这样可以为后续保留标题层级、图片引用和文档来源打下基础。

2. 知识检索：构建多路召回与重排链路

用户提问后，系统不会只做一次向量检索，而是构建了多阶段检索流程：

用户问题 -> 历史上下文改写 -> 文档/产品主体识别 -> 普通向量检索 -> HyDE 增强检索 -> 联网检索（按需） -> RRF 融合 -> Reranker 重排 -> 基于上下文生成答案

已实现的核心能力包括：

• 根据用户问题识别关联文档、产品或实体；

• 根据历史会话改写上下文不完整的问题；

• 使用 BGE-M3 进行普通向量检索；

• 使用 HyDE（Hypothetical Document Embeddings）增强召回；

• 支持多路检索结果通过 RRF 融合；

• 使用 Reranker 对候选文档进行二次排序；

• 基于高相关度 Chunk 生成最终答案；

• 支持在需要时接入 WebSearch MCP 补充外部信息。

这条链路体现了项目对检索质量的关注。普通 RAG 往往是“问题 -> 检索 -> 生成”，而本项目通过主体识别、多路召回、融合和重排，尽量提高进入模型上下文的信息质量。

3. 对话与流式输出能力

系统具备基础会话能力：

• MongoDB 保存用户问题、助手回答、关联文档和图片链接；

• 支持多轮对话上下文；

• 支持会话历史查询与管理；

• 支持 SSE 流式输出；

• 用户无需等待完整答案生成，即可看到回答逐步返回。

在实际体验中，流式输出不一定降低模型总生成耗时，但可以显著改善首字等待时间和交互感受。

4. 外部服务与技术栈

项目当前涉及的核心组件如下：

四、系统主链路如何讲清楚？

面试时不需要从所有代码讲起，而要优先讲清楚两条核心链路。

1. 文档导入链路

上传文档 -> PDF 解析为 Markdown -> 图片资源上传对象存储 -> 文本切分 -> 文档/产品名识别 -> BGE-M3 向量化 -> 写入 Milvus

可以这样描述：

用户上传 PDF 后，系统会调用 MinerU 将复杂 PDF 解析为 Markdown，并将文档中的图片上传到 MinIO。随后按照 Chunk 策略切分文本，提取文档或产品名称，再通过 BGE-M3 生成稠密和稀疏向量，最终写入 Milvus，形成可检索的知识库。

2. 用户问答链路

用户提问 -> 历史上下文改写 -> 主体识别 -> 向量检索 / HyDE 检索 -> RRF 融合 -> Reranker 重排 -> 大模型生成答案 -> 保存会话历史并 SSE 返回

可以这样描述：

用户提问后，系统先结合多轮历史改写问题，再识别问题关联的产品或文档范围。检索阶段同时使用普通向量检索和 HyDE 检索，通过 RRF 融合多个召回通道，再使用 Reranker 进行精排，最后将高相关度上下文交给大模型生成答案，并保存完整对话记录。

五、当前项目与面试级项目之间的差距

目前项目已经具备完整 RAG 主链路，不再是单纯的玩具 Demo。但如果希望在面试中体现更强的工程能力，还需要补齐以下部分。

1. 工程化部署不够完整

当前项目仍较依赖本地环境、模型路径和外部服务地址，新成员启动成本较高。

主要缺口：

• 缺少统一的 Docker Compose；

• 缺少一键启动脚本；

• .env配置项较多且缺少标准示例；

• 本地模型路径、远程服务地址依赖较强；

• 缺少环境检查与依赖健康检查。

优化方向：

Docker Compose -> Milvus -> MongoDB -> MinIO -> API 服务 -> 可选的模型服务 .env.example README 启动手册 健康检查接口 初始化脚本

2. 稳定性与任务治理仍需加强

MinerU、WebSearch、Reranker、LLM 服务都可能发生超时、鉴权异常或临时不可用。

当前项目已具备部分降级思路，但仍可继续完善：

• 为外部服务增加统一超时和重试策略；

• 对可降级能力建立明确的 fallback 路径；

• 为导入任务建立可靠状态机；

• 支持任务失败后的重试、恢复和人工干预；

• 对非幂等写入操作增加幂等控制；

• 记录失败阶段、失败原因和重试次数。

建议的导入任务状态如下：

PENDING -> PARSING -> SPLITTING -> EMBEDDING -> INDEXING -> SUCCESS 任意阶段 -> FAILED -> RETRYING

3. 缺少完整的可观测性体系

目前有日志，但仍缺少真正的全链路观测能力。

理想状态下，每一次问答请求都应该能够追踪：

trace_id -> 问题改写耗时 -> 主体识别耗时 -> 向量检索耗时 -> HyDE 检索耗时 -> RRF 融合耗时 -> Reranker 耗时 -> LLM 首 Token 时间 -> 总 Token 用量 -> 总响应耗时 -> 错误与降级信息

建议后续接入：

• LangSmith：追踪模型调用与 LangGraph 执行路径；

• OpenTelemetry：统一链路追踪协议；

• Prometheus：采集指标；

• Grafana：建立延迟、错误率、Token、任务状态看板。

这是 TraceRAG 最值得强化的个人特色：不仅让系统回答，还能解释系统是如何得出回答的。

4. 缺少数据驱动的 RAG 评测体系

很多 RAG 项目都会说“我加了 HyDE、RRF 和重排”，但面试官通常会继续追问：

这些策略真的有效吗？提升了多少？

如果没有评测集和实验数据，很难给出可信答案。

建议构建 20 到 50 条标准问题，覆盖：

• 精确事实问答；

• 产品型号与参数问题；

• 操作步骤问题；

• 多轮追问问题；

• 无答案问题；

• 易产生幻觉的问题。

评测指标可包括：

后续可以形成这样的实验对比表：

这样项目优化过程就从“凭感觉调参”变成“由数据驱动的检索策略选择”。

5. 知识库管理能力不足

当前系统更接近单知识库原型，距离企业知识资产管理平台还可以继续扩展。

后续可以补充：

• 文档列表与详情页；

• 文档导入进度与任务状态；

• 删除文档及关联向量；

• 文档更新与重新索引；

• 文档版本管理；

• 多知识库隔离；

• 按部门、角色、用户控制权限；

• 检索阶段基于 Metadata 进行权限过滤。

这部分能体现后端工程和企业业务建模能力，而不仅仅是 AI 调用能力。

6. 检索策略还有优化空间

当前系统已经具备普通检索、HyDE、RRF、Reranker 等能力，但检索质量仍值得持续优化。

后续可尝试：

• 父子 Chunk 检索；

• 保留标题层级的 Section-aware Retrieval；

• 多查询扩展（Query Expansion）；

• BM25 与向量检索混合召回；

• 更完善的 Metadata Filter；

• 根据问题类型动态选择检索策略；

• 根据文档类型采用不同 Chunk 策略；

• 降低对item_name精确匹配的强依赖。

例如，技术手册适合按章节结构切分，产品参数表适合按表格或字段切分，长篇论文则可能更适合父子 Chunk 结构。

7. 前端产品体验仍偏原型

当前系统重点在于后端主链路可运行，但企业知识库产品还可以继续完善前端体验：

• 文件上传进度；

• 导入任务状态与失败原因；

• 文档列表和知识库管理；

• 对话历史管理；

• 回答引用来源展示；

• 原始文档定位；

• 图片预览；

• 检索 Chunk 可视化；

• 用户反馈入口，例如“有帮助 / 无帮助”。

前端并不是项目的唯一重点，但“引用来源可见”和“任务状态可见”能显著增强系统可信度。

六、TraceRAG 的面试亮点应该怎么讲？

项目不应被包装成“我做了一个聊天机器人”，而应该突出下面四个亮点。

1. 复杂文档结构化处理

系统面向复杂 PDF、产品手册和技术文档，先通过 MinerU 解析为 Markdown，再处理图片、标题和文本结构，最终进行切分和向量化，而不是直接把 PDF 文本粗暴切块。

2. 多路检索增强

在检索侧，我实现了主体识别、普通向量检索、HyDE 增强检索、RRF 融合和 Reranker 重排，通过多阶段检索提高召回质量与上下文相关性。

3. 可追踪与可降级

我重点关注 RAG 工程落地中的可观测性。后续会为每个 LangGraph 节点记录耗时、失败原因、调用次数和 Token 用量，并对 MinerU、WebSearch、Reranker、LLM 等外部依赖设计超时、重试和降级机制。

4. 数据驱动的效果评测

我不会只凭主观感受调整 RAG 策略，而是通过标准问题集，对比普通检索、HyDE、RRF 和重排的 Recall@K、答案准确率、响应耗时等指标，形成可量化的优化闭环。

七、总结

TraceRAG 已经完成了从文档导入到智能问答的核心闭环：

上传文档 -> 解析 -> 切分 -> 向量化 -> Milvus 入库 用户提问 -> 主体识别 -> 多路检索 -> 融合重排 -> 大模型生成 -> 保存历史与流式输出

它当前已经具备功能型 RAG 项目的完整能力。下一阶段的重点，不是盲目增加更多模型或工具，而是围绕以下方向持续建设：

• 可观测；

• 可评测；

• 可降级；

• 可部署；

• 可管理；

• 可扩展。

当系统能够清楚回答“答案来自哪里、哪一步耗时最多、哪种检索策略提升了多少、外部依赖失败后如何恢复”时，它才真正具备企业级 RAG 项目的说服力。