15 - 技术文档问答¶

项目背景与目标¶

某开源软件公司维护着十余个技术产品，官方文档累计上万页（API 参考、教程、最佳实践、变更日志），用户与内部支持团队每天产生大量提问。传统搜索只能返回文档列表，用户仍需自行阅读定位答案，且代码示例与版本耦合易出错。企业希望构建技术文档智能问答系统，支持多文档 RAG、代码示例检索、版本感知，让用户用自然语言获得带引用与可运行示例的答案，问答准确率 ≥ 90%，含可运行代码示例。

核心目标： 1. 多文档 RAG，跨产品跨章节检索 2. 代码示例专用检索与版本匹配 3. 答案含引用溯源与可运行示例 4. 问答准确率 ≥ 90%，响应 < 3 秒

预期价值：降低支持成本、提升开发者体验、文档反馈闭环、推广产品采用。

需求分析¶

用户角色与场景 - 开发者用户：查 API 用法、找代码示例、排错 - 内部支持：快速答用户问题、定位文档缺陷 - 文档作者：基于问答数据发现文档缺口

功能需求列表 - 自然语言提问 + 多轮追问 - 多文档 RAG（API 参考、教程、最佳实践、变更日志） - 代码示例专用索引（按语言、版本、功能标签） - 版本感知（答案对应提问者使用版本） - 引用溯源（文档链接 + 锚点） - 可运行示例（标注运行环境与依赖） - 文档缺口发现（高频无答案问题反馈作者） - 多语言文档（中英）

非功能需求 - 性能：P95 < 3 秒 - 准确性：代码示例可运行率 ≥ 85% - 可用性：99.9% - 覆盖：支持 10+ 产品文档

约束条件：需与官方文档站点集成；支持版本切换。

技术选型说明¶

层次	技术选择	选型理由
Agent 框架	LlamaIndex	多文档 RAG 与代码索引强
LLM	Qwen2.5-72B	代码与文本双强
Embedding	bge-m3 + 代码专用模型	文本与代码分库索引
向量库	Milvus	多索引、标量过滤
重排序	bge-reranker	提升召回质量
后端	Python FastAPI	异步
部署	K8s + CDN	全球访问

架构设计¶

flowchart LR
    subgraph 离线
        DOC[多产品文档] --> PARSE[解析+分块]
        PARSE --> TXT[文本索引]
        PARSE --> CODE[代码示例索引]
        TXT --> VEC1[(Milvus 文本)]
        CODE --> VEC2[(Milvus 代码)]
    end
    subgraph 在线
        Q[用户提问+版本] --> REW[查询改写]
        REW --> H1[文本检索]
        REW --> H2[代码检索 版本过滤]
        H1 --> RR[重排序]
        H2 --> RR
        RR --> GEN[生成+引用+示例]
        GEN --> A[答案]
        GEN --> GAP[缺口检测]
    end

核心是「双索引（文本+代码）+ 版本感知检索 + 引用溯源生成」。文档文本与代码示例分库索引，代码索引带语言与版本标签；检索时按用户版本过滤，避免给出过期 API；生成阶段强制引用与示例对齐。

关键模块实现思路¶

模块1：文档与代码双索引¶

思路：文档文本按章节分块入文本索引；代码示例（代码块）单独提取，带「语言、产品、版本、功能标签」元数据入代码索引；两者都用 bge 生成向量。
关键点：代码示例独立索引使其能精确召回可运行片段，而非混在长文中。

模块2：版本感知检索¶

思路：用户提问时识别使用版本（显式指定或从上下文推断）；代码检索用标量过滤 version ∈ 用户版本兼容范围；对已废弃 API，答案标注「此 API 在 vX 废弃，建议用 Y」。

示意：

def search_code(query, lang, version):
    flt = f"lang == '{lang}' and version_compatible contains '{version}'"
    return code_vec_db.search(embed(query), filter=flt, top_k=5)

模块3：引用溯源生成¶

思路：Prompt 强制答案每个要点后标注文档引用（产品-章节-锚点）；代码示例标注来源与版本；后处理校验引用真实存在。

模块4：文档缺口发现¶

思路：对「无高置信召回」或「用户标记无用」的问题聚类，输出高频缺口主题给文档作者，指导文档补充。

核心流程详解¶

流程1：查 API 用法¶

用户「如何在 v2.3 用 Python 批量导入数据」
识别版本 v2.3、语言 Python
文本检索批量导入教程，代码检索 Python 示例（版本过滤）
生成答案：步骤说明 + 可运行代码示例 + 文档链接
代码示例标注「适用于 v2.3+」

流程2：废弃 API 提示¶

用户问某 v1 API 用法，但已 v2 废弃
检索发现该 API 在变更日志标记废弃
答案提示「此 API 已废弃，建议使用 Y，示例：...」

部署与优化建议¶

部署架构：索引离线流水线；在线服务全球多区域 + CDN 缓存高频问答。
性能优化：高频问答答案缓存（带版本失效）；rerank 仅 Top-30。
成本控制：缓存命中不调 LLM；代码与文本检索可合并为一次召回。

常见问题与解决方案¶

代码示例不可运行 → 代码示例入库前做可运行性验证；标注运行环境。
版本混淆 → 严格版本过滤 + 答案标注适用版本。
跨产品答案错位 → 检索带产品标签过滤。

扩展方向¶

在线运行：文档站点内嵌代码运行沙箱。
智能补全：用户写代码时实时推荐对应文档。
多模态：支持架构图与截图问答。