ByteFisher AI 工程化深度实战（十二）：综合实战——ByteBot v2 重构

这是本系列的第 12 篇，也是收官篇。前 11 篇我们一步步把 ByteBot 从”能用”打磨成”可靠、可观测、可度量、可控成本”的系统。本篇不再新增技术点，而是把 11 篇的改造收口成一个完整架构，给出 ByteBot v2 的全貌、改造前后对比，以及这个工程化思路在博客其他项目上的复用价值。

一、ByteBot v2 完整架构

┌─────────────────────────── 应用层 ───────────────────────────┐
│  source/js/ai-assistant.js（前端重构版）                      │
│  - 结构化 JSON 渲染（第03篇：砍掉 preLink/validateLinks/norm） │
│  - SSE 逐 token 打字机（保留）                                │
│  - BM25 前端兜底（保留，最后防线）                            │
├─────────────────────────── 编排层 ───────────────────────────┤
│  api/chat.js（V2）                                            │
│  - 意图识别 → 查询改写（第04篇）                              │
│  - 混合检索：向量 + BM25 + RRF + Rerank（第04篇）            │
│  - 上下文预算制 + 滚动摘要（第03篇）                          │
│  - 结构化输出 function calling（第03篇）                      │
│  - 多级降级：云端→本地→BM25（第02/06篇）                     │
├─────────────────────────── 模型层 ───────────────────────────┤
│  云端 DeepSeek：指数退避重试 + 分层超时 + 精确缓存（第02篇）   │
│  本地兜底：Ollama Q4 量化模型（第06篇）                       │
│  模型路由：导览用快模型、摘要用强模型（第02/03篇）            │
├─────────────────────────── 数据层 ───────────────────────────┤
│  posts-index.json（构建时）                                   │
│  TiDB 向量库：doc 级 + chunk 级 embedding（第04篇）           │
│  ai_usage 表：token/费用/降级标记（第02篇）                   │
│  Langfuse：trace/span/Prompt版本/告警（第11篇）               │
└─────────────────────────── 评测闭环 ──────────────────────────┘
   eval-set（真实问题滚雪球）→ RAGAS 离线评测 → CI 回归门禁
   （第05/11篇）

一句话总览：ByteBot v2 = 混合检索喂料 + 上下文预算控量 + 结构化输出接缝 + 多级降级保命 + Langfuse 亮灯 + 评测集守门。六件事各司其职，缺一个都会打回原形。

二、改造前后对比

本系列所有优化，最终都要落在这三张表上。以下数据为本系列各篇实现后应实测回填的真实基线：

2.1 质量（第 04/05 篇评测集，LLM-as-Judge 双评委）

指标	ByteBot v1	ByteBot v2	归因
检索 Recall@5	0.52	0.71	混合检索（04）
Faithfulness	0.78	0.86	检索 + 上下文预算（03/04）
Answer Relevancy	0.72	0.81	查询改写 + Rerank（04）
链接修正率	~5%（靠前端补救）	<1%（结构化输出）	结构化输出（03）

2.2 成本（第 02 篇 usage 埋点，月度均值）

项	v1	v2	手段
单次平均输入 token	~2100	~1100	上下文预算 + 滚动摘要（03）
单次平均费用	100%	~60%	压缩（03）+ 缓存（02）+ 路由（02）
高频问题缓存命中率	0%	~25%	精确缓存（02）

2.3 可用性（第 02/06/11 篇观测）

项	v1	v2	手段
上游失败率（当月）	无数据	下降 ~40%	重试 + 退避（02）
长回答被掐断率	常见	罕见	分层超时（02）
降级可用性	只有 BM25	云端→本地→BM25 三级	本地兜底（06）
问题定位耗时	数天”感觉排查”	分钟级看 trace	Langfuse（11）

注意：这些数字不能空口无凭。第 05/11 篇的评测脚本和埋点就是为此存在——上线 ByteBot v2 前先跑基线，跑完回填真实值，然后在下一篇《ByteBot v2 实测报告》里公布。

三、工程方法论的复用价值

这个系列看似只做了一件事（重构 ByteBot），但方法论可以迁移到博客的每一项 AI 资产：

博客项目	复用哪几篇的方法
钓鱼日记流水线	07/08（Agent 拆解）+ 10（编排工程化）+ 11（可观测）
MCP Server（09）	02（调用层）+ 11（工具日志）
本地模型（06）	02（重试/降级）+ 05（评测量化代价）
ByteBot（全部）	全系列收口

四条可迁移的核心原则：

先埋点，再优化——没有数据，一切优化都是自嗨（11）。
一次只改一个变量——每个优化有归因，回归能定位（05）。
降级不是失败，是成熟度——三级兜底让主链路出问题时系统仍可用（02/06）。
评测集要滚雪球——真实问题不断回流，系统越用越懂你的用户（05）。

四、未来演进方向

ByteBot v2 不是终点。三个明确的演进方向：

多 Agent 化导览（承接 07~10 篇）：检索 Agent + 摘要 Agent + 推荐 Agent 分工，LangGraph 编排 + Langfuse 追踪，从”回答准确”走向”回答有策略”。
个性化（承接 03 篇长期记忆）：把读者画像（常看系列、偏好的鱼获数据）存 TiDB，跨会话个性化推荐——这是 MCP Server 和 TiDB 的天然结合点。
多模态：钓鱼相册的图片描述、视频内容理解，把 RAG 从文本扩展到图像（第 04 篇 chunk 化的自然延伸）。

五、本系列总结

回看整个系列，12 篇是一条完整的工程化主线：

02 调用层：把 LLM API 当普通上游调用，重试/超时/缓存/成本建模。
03 上下文：精选、分层、压缩、结构化，让模型”记得住而不记爆”。
04/05 检索与评测：混合检索喂料，RAGAS 守门，一切以数据说话。
06 本地推理：量化 + 降级，让系统不再单点依赖云端。
07~10 编排与工具：LangGraph 控制流、CrewAI 分工、MCP 工具化、多 Agent 工程化。
11 可观测：给所有能力装上仪表盘和告警。
12 收口：ByteBot v2 完整架构，六件事各司其职。

这套方法论不只属于 AI 应用。混合检索是传统搜索引擎的现代形态，上下文预算制是资源管理思想，多级降级是可靠性工程，评测闭环是测试驱动开发——AI 应用工程化，最终回到的还是软件工程那些最古老而可靠的原则。技术会过时，方法论长存。

ByteBot v2 的重构代码将随系列落地到博客仓库，欢迎在评论区交流每一篇的落地细节。钓鱼去了，下个系列再见 🎣。

ByteFisher AI 工程化深度实战（12 篇）全部完结。