项目线 A 企业知识库问答 Agent

这条项目线是整套指南里最适合前端工程师切入的 AI Agent 项目之一。 它兼顾了业务价值、工程完整度和求职展示效果，能够把“模型调用、RAG、评测、上线、安全、作品集”串成一个完整闭环。

1. 项目定位

1.1 项目目标

做一个面向企业内部员工的知识库问答 Agent，帮助用户查询制度、流程、产品文档、售后规范、内部 FAQ 等资料。

目标不是做一个“看起来很聪明的聊天框”，而是做一个：

• 有证据引用。
• 能拒答未知问题。
• 可评测、可回归。
• 可上线、可监控。
• 可包装成作品集的完整系统。

1.2 为什么它适合前端转型

因为这个项目能同时复用和展示前端工程师的很多已有能力：

• 信息展示与交互设计。
• API 对接与状态管理。
• 流式响应与异步状态处理。
• 错误兜底与加载反馈。
• 数据埋点与体验优化。

同时它也能补齐 AI Agent 工程师必须具备的新能力：

• 知识切片和检索增强。
• 引用与拒答策略。
• 评测集和发布门禁。
• 安全与权限设计。
• 项目复盘和面试表达。

2. 项目边界

2.1 第一阶段只做一个垂直场景

不要一开始就做“全公司万能助手”。 建议先选一个边界清晰、资料相对规范的场景，例如：

• 人事制度问答。
• 售后 SOP 查询。
• 产品知识库检索。
• 客服答复规范查询。

2.2 推荐的 MVP 范围

MVP 只要覆盖以下能力即可：

• 用户输入问题。
• 系统完成检索与回答。
• 回答附带引用来源。
• 证据不足时拒答。
• 前端展示引用、置信度和反馈入口。

不要在第一版就追求：

• 多 Agent。
• 自动写入系统。
• 多轮复杂记忆。
• 全量企业文档统一接入。

3. 推荐能力地图

这条项目线可以覆盖整套指南中的关键章节：

• 第 2 章：模型调用与输出约束。
• 第 4 章：基础 RAG 链路。
• 第 5 章：查询优化与重排。
• 第 8 章：评测体系建设。
• 第 9 章：工程化上线能力。
• 第 10 章：安全与合规治理。
• 第 11 章：作品集包装。
• 第 12 章：面试表达。

4. 系统架构建议

一个推荐的最小架构如下：

• 前端应用：负责提问、展示答案、展示引用、收集反馈。
• Agent 服务层：负责 Prompt 组织、检索调用、回答生成、输出结构化结果。
• 检索层：负责召回、重排、片段筛选。
• 数据层：知识文档、切片结果、元数据、评测样本、用户反馈。
• 观测层：日志、trace、评测报告、线上指标。

可以把数据流理解为：

1. 用户提出问题。
2. 服务层改写查询并发起检索。
3. 检索层返回高相关证据。
4. 模型基于证据生成回答。
5. 服务层输出结构化结果。
6. 前端渲染答案、引用和风险提示。
7. 用户提交反馈，进入后续评测与优化闭环。

5. 前端需要承担什么

这个项目不是“后端都做好，前端只接个接口”。 前端在这个系统里非常关键，至少要负责以下内容：

5.1 结果展示设计

用户不只需要一个答案，还需要看到：

• 答案正文。
• 引用来源。
• 文档标题。
• 风险提示。
• 置信度。
• 下一步建议。

5.2 状态设计

至少要覆盖这些状态：

• 输入中。
• 检索中。
• 生成中。
• 部分失败。
• 拒答。
• 需要人工帮助。

5.3 反馈闭环

建议设计最小反馈入口：

• 这个回答是否有帮助。
• 引用是否准确。
• 是否需要转人工。
• 用户是否愿意补充上下文。

这些反馈不是 UI 装饰，而是后续优化评测集的重要数据来源。

6. 实施步骤

第一步：盘点资料与定义范围

先做一张资料清单：

• 有哪些文档源。
• 谁负责维护。
• 更新频率如何。
• 哪些内容可信度最高。
• 哪些内容不适合进入知识库。

同时定义项目边界：

• 回答哪些问题。
• 不回答哪些问题。
• 哪些场景必须拒答或转人工。

第二步：完成文档清洗与切片

建议先统一文档结构，再做切片。 重点关注：

• 标题层级是否清晰。
• 是否带版本号和发布日期。
• 是否有失效旧文档。
• 一条制度是否被拆得过碎或过长。

切片策略建议先从简单方案开始：

• 按标题和段落切片。
• 保留文档标题、章节路径、更新时间等元数据。
• 不要一开始就做过度复杂的切片算法。

第三步：建立最小检索链路

第一版检索链路建议尽量简单：

• 输入问题。
• 查询改写或标准化。
• 向量检索或混合检索。
• 返回前若干条证据。
• 生成附带引用的回答。

这一阶段最重要的不是模型有多强，而是链路闭环是否清晰、能否解释。

第四步：做引用与拒答

这是企业知识问答和普通聊天产品的关键差异。 至少要实现：

• 每个答案都能给出引用来源。
• 如果证据不足，就明确说明无法确认。
• 对高风险问题做保守处理。

如果没有这一层，系统很容易从“看起来能用”变成“业务不敢用”。

第五步：建立评测集

建议至少准备三类样本：

• 正常问答样本。
• 边界问题样本。
• 应该拒答的样本。

每条样本建议带这些字段：

• 问题。
• 标准答案或参考结论。
• 允许引用的文档。
• 是否必须拒答。
• 所属场景标签。

第六步：做版本回归

每次调整以下任一项时，都应该跑回归：

• Prompt。
• 检索参数。
• 切片策略。
• 重排策略。
• 模型版本。

不要把“效果好像更好了”当成上线依据。

第七步：加入线上观测

上线前至少加这些观测项：

• 平均响应时间。
• 检索命中率。
• 引用准确率。
• 拒答准确率。
• 用户满意度反馈。
• 单次请求成本。

7. 推荐的验收指标

第一版项目不需要把所有指标做到极致，但至少要有一个清晰基线。 可以参考以下阈值：

• 引用准确率 >= 85%。
• 该拒答场景拒答准确率 >= 90%。
• 关键问题命中率 >= 80%。
• 平均响应时间维持在可接受范围内。
• 结构化输出解析成功率 >= 95%。

你也可以按业务场景自己调整，但重点是必须“先定义，再优化”。

8. 常见坑

8.1 文档质量没处理好，就急着调模型

很多问题其实不是模型不行，而是文档本身混乱、过时、重复或无版本信息。

8.2 只做召回，不做引用验证

如果回答没有可靠引用，业务方很难真正相信系统。

8.3 只看正确率，不看拒答

企业知识问答里，“该不知道时别乱答”往往比“尽量多答”更重要。

8.4 前端只展示文本，不展示证据

这样会让系统失去可解释性，也削弱用户信任。

8.5 没有反馈入口

没有反馈就没有持续优化的数据来源，系统很快会停在“开发者自我感觉良好”的阶段。

9. 建议的阶段性交付物

阶段 1：可跑通 MVP

交付物：

• 一个可提问的前端页面。
• 一个最小 RAG 服务接口。
• 一个基础知识库样本。

阶段 2：可解释版本

交付物：

• 回答引用。
• 拒答策略。
• 反馈入口。
• 错误空态设计。

阶段 3：可评测版本

交付物：

• 评测样本集。
• 自动回归脚本。
• 基线指标表。

阶段 4：可上线版本

交付物：

• 监控指标。
• 发布清单。
• 回滚预案。
• 风险控制说明。

阶段 5：可求职展示版本

交付物：

• 项目卡片。
• 架构图。
• 指标图表。
• 复盘文档。
• 面试讲述稿。

10. 项目卡片应该怎么包装

如果你要把它写进作品集，建议项目卡片至少包含：

• 业务背景：为什么要做这个系统。
• 项目目标：解决什么问题。
• 技术方案：RAG、引用、评测、监控分别怎么做。
• 指标结果：优化前后发生了什么变化。
• 你的职责：你负责了哪些关键环节。
• 复盘总结：你做对了什么，还缺什么。

11. 面试表达

你可以这样讲：

“我做的不是一个通用聊天机器人，而是一个面向企业内部知识查询的 Agent 系统。项目重点不是把模型接起来，而是把知识切片、检索、引用、拒答、评测和上线治理串成一个完整闭环。前端部分我不仅负责界面，还参与了输出结构设计、引用展示和反馈闭环；工程部分我补上了评测基线、回归机制和风险控制。这样项目既能演示，也能经得住面试追问。”

12. 最终验收清单

• 有明确的知识范围和拒答边界。
• 回答结果带可核验引用。
• 前端能展示引用、状态和反馈入口。
• 有基础评测样本与回归流程。
• 有上线指标、风险说明和回滚预案。
• 能沉淀为作品集材料并完成口头讲述。

---

13. 自托管部署变体

🏠 零 API 依赖版本

本项目可完全替换为自托管方案，实现数据不出域。完整自托管项目请参考 项目线 D。

技术栈替换对照

组件	云端版	自托管版
推理模型	GPT-4o / Claude	Ollama + Qwen3-8B
Embedding	text-embedding-3	BGE-M3 via Ollama
向量库	Pinecone / Weaviate	ChromaDB / Qdrant
部署	云服务	Docker Compose

自托管改造要点

1. 模型替换：修改 baseURL 指向本地 Ollama，model 改为 qwen3:8b
2. Embedding 替换：使用 ollama pull bge-m3 + 本地 Embedding API
3. 向量库替换：ChromaDB Docker 一键启动
4. 适用场景：金融合规、医疗数据保护、政务内网

详细实施步骤参考 专题 11：自托管 AI Agent 全栈指南