设计决策与方案取舍
本节记录本项目在架构、模型、产品化方向上的关键设计决策与权衡，帮助读者理解“为什么这样做”以及未来可替换空间。决策按照 背景 → 选项 → 评估 → 结论 → 可替代路径 的模板呈现。
为什么选择 Qwen 大模型
背景：需要一个在中英文技术文档、指令遵循、成本与可用性之间平衡的主力 LLM。
候选：GPT-4 系列、Claude、DeepSeek、Qwen、Gemini。
评估维度：中文技术语义、指令稳定性、上下文对齐、延迟、成本、可用性（网络/合规）、配套嵌入一致性。
| 维度 | GPT-4 | Claude | DeepSeek | Gemini | Qwen |
|---|---|---|---|---|---|
| 中文技术语义 | 高 | 中高 | 中 | 中 | 高 |
| 指令稳定性 | 高 | 高 | 中 | 中 | 高 |
| 成本 | 高 | 高 | 低 | 中 | 中低 |
| 延迟 | 中 | 中 ~ 偶高 | 中 | 中 | 中 |
| 可用性/网络 | 变量 | 变量 | 稳定 | 需梯子 | 稳定 |
| 嵌入协同性 | 中 | 中 | 中 | 中 | 高 |
结论：Qwen 在中文语义与嵌入一致性方面具备优势，性价比适合个人与中小规模试验；通过轻量接口抽象保留未来切换余地。
可替代路径：引入“多模型路由”组件，对分类、生成、代码、翻译分流不同模型；或使用蒸馏策略降低高端模型成本。
为什么不直接使用 SaaS（如 kapa.ai）
| 目标 | SaaS 适配情况 | 自研价值 |
|---|---|---|
| 深度检索控制 | 限制（不可自由组合 pipeline） | 可自由混合多路召回/重排/裁剪 |
| 数据主权 & 合规 | 需信任第三方 | 全链自控，可本地化部署 |
| 快速迭代 | 受厂商发布节奏限制 | 任意模块热替换/灰度 |
| 监控细粒度 | 黑盒指标有限 | 可暴露相似度分布、引用命中率、拒答率 |
| 成本策略 | 固定阶梯 | 按需选模型/缓存分层/降级策略 |
| 创新实验 | 受限 | 引入 rerank、反思链、知识图谱更灵活 |
结论：自研建立“知识基础设施”能力，长期复利 > 短期集成速度；SaaS 可作为 baseline/对照组存在。
补充：仍可引入通用托管能力（如 API 网关、安全）而不放弃核心检索与生成链路控制权。
自研初衷与核心优势
- 知识资产沉淀：个人/社区文档、手册、博客统一结构化 → 可检索、可演化。
- 可验证性：答案引用原文块，杜绝“不可追溯权威”。
- 迭代弹性：Embedding / Retriever / Reranker / Prompt / LLM 各层可独立优化。
- 成本可控：逐步引入缓存、多级模型、动态上下文裁剪。
- 教育示范：输出工程化、透明、可复制范式，降低他人入门门槛。
- 反馈驱动：基于失败会话回放构建“持续运营”机制。
版本策略与开源差异
发布基线：手册基于仓库 tag v1.0.0 进行讲解，确保内容稳定、步骤可重放。
线上版本：网站运行 main 分支，包含迭代增强（检索调参、结构化日志、Prompt 优化、多语言增强等）。
选择原因：main 快速试错降低创新滞后；v1.x 系列维持学习稳定性。
未来可替换模块
| 模块 | 当前实现 | 可替换方向 | 触发条件 |
|---|---|---|---|
| Embedding | Qwen + 维度规整 | bge-m3 / jina / 自训练 | 召回率瓶颈 |
| 检索 | 单向量 + rerank | 混合 BM25 / MMR / Graph | 相关性不足或重复高 |
| 生成 | Qwen 主模型 | 多模型路由 / 反思链 | 复杂任务失败率高 |
| 约束 | 引用 + 阈值 | 事实回查 / 知识图谱 | 误导性回答残留 |
| 监控 | 结构化日志 | 专用指标聚合服务 | 指标规模增长 |
| 部署 | Cloudflare Workers | Regional Edge / 混合本地 | SLA / 合规提升需求 |
决策记录模板（建议团队化使用）
# DR-2025-08-XX: <决策标题>
## 背景
<问题描述> + <约束条件>
## 目标
<成功标准>
## 选项
| 方案 | 描述 | 优点 | 缺点 |
|------|------|------|------|
## 评估结论
<做出决策的理由>
## 决策
<选定方案> + <生效时间> + <Owner>
## 回滚条件
<哪些观测指标触发回滚>
## 后续行动
- [ ] <Task1>
- [ ] <Task2>
小结
设计决策透明化让系统演进具备“认知可追溯性”。通过最小可替换接口 + 版本分层 + 度量驱动，我们将 RAG 系统从一次性交付转向持续改进平台。读者可据此裁剪或扩展，构建符合自身约束的解决方案。