企业官网建设流程全解析

WeKnora 实战：将《智能家居中控 Pro 产品手册》构建为可检索知识库与 FAQ 问答

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

导读

《智能家居中控 Pro 产品手册》是 WeKnora 仓库 website-docs/sample-data 中提供的示例语料之一，与《Q1 产品会议纪要》《员工手册》《售后知识库 POC 技术方案》和《FAQ 导入样例》共同构成一套完整的演示数据集。本文以这份产品手册为骨架，完整梳理其技术规格、首次配置、场景联动与常见问题，并在此基础上讲解如何利用 WeKnora 的文档入库管线、FAQ 知识库与混合检索能力，把一份静态 Markdown 手册升级为可供一线工程师和客服直接查询、带出处的智能问答系统。读完本文，你将掌握"文档型知识库 + FAQ 标准问答库"双轨建库的完整路径。

一、示例语料定位：产品手册在 RAG 系统中的角色

在 WeKnora 的文档体系里，sample-data目录是一套刻意设计的仿真语料，五个文件相互呼应：

其中产品手册是这套语料的核心，FAQ 导入样例中约一半条目（保修时长、断网语音、账号绑定中控数量、支持协议、Matter 认证计划等）都直接源自手册正文。这意味着：一份产品手册既可以作为文档型知识库的原始语料，也可以被二次提炼成 FAQ 标准问答库，两者互补，正是 WeKnora 多知识库设计的典型用法。

二、语料全解析：智能家居中控 Pro 产品手册

该文档是一份完整的产品手册，包含型号版本信息、产品概述、技术规格、首次配置、场景联动和 FAQ 六个部分，下面逐节继承并展开。

2.1 产品概述

产品型号：HUB-Pro-2024；文档版本：v2.1；适用固件：≥ 3.4.0。

智能家居中控 Pro 是星云科技（NovaTech）推出的家庭物联网中枢，负责统一管理灯光、空调、窗帘、安防传感器等设备，用户可通过手机 App、语音助手或本地触摸屏完成场景联动。核心卖点：

• 本地离线可用：断网后局域网内仍可执行已配置场景；
• 多协议兼容：同时支持 Matter、Zigbee 3.0、Wi-Fi 与蓝牙 Mesh；
• 边缘 AI：内置轻量模型，可识别「我回家了」「准备观影」等口语化指令。

从 RAG 语料的角度看，这些概述性文字中包含了"本地离线""多协议""边缘 AI"等高价值关键词，是回答"这产品有什么能力"类问题的检索入口。

2.2 技术规格

这是整份手册中结构化程度最高的内容。在 04-技术方案-售后知识库POC.md 的验收用例里，"中控 Pro 最多能接多少设备？"这一题的标准答案正是从本表提取的（"256，推荐 ≤ 120"）。表格类内容在分块时尤其需要注意上下文保留——这正是 WeKnora 分块参数中chunk_overlap与父子分块要解决的场景（详见第三节）。

2.3 首次配置

手册给出四条配网步骤：

1. 将设备接通电源，指示灯呈蓝色慢闪表示等待配网。
2. 打开 NovaHome App，选择「添加中控」，扫描机身二维码。
3. 按向导连接家庭 Wi-Fi；若使用有线网络，可跳过 Wi-Fi 步骤。
4. 完成固件检查；如有更新，建议先升级再添加子设备。

注意：首次配网时手机需与中控处于同一 2.4 GHz 频段。5 GHz-only 路由器需先开启 2.4 GHz 兼容模式。

这类"步骤 + 注意事项"的流程型内容，是售后工单的高频查询主题。在 WeKnora 中，它们最适合以父子分块方式入库：检索命中细节子块，生成回答时使用包含完整流程的父块，避免上下文被切断。

2.4 场景联动示例

「回家模式」——触发条件（满足任一即可）：手机 GPS 进入家庭地理围栏；大门指纹锁解锁；语音说「我回来了」。执行动作：客厅主灯调至 70% 暖白光；空调设为 26℃ 制冷（仅夏季模板生效）；关闭安防布防。

「离家模式」——触发条件：所有家庭成员手机离开地理围栏超过 5 分钟。执行动作：关闭全屋灯光、关闭空调、启动安防布防、关闭燃气机械手（如已接入）。

场景联动内容体现了"条件 → 动作"的语义结构，属于典型的多条件段落，验证分块策略时可以用它来观察模型是否能把"触发条件"和"执行动作"完整关联起来。

2.5 手册内 FAQ

这三组问答与 05-常见问题-FAQ导入样例.json 中standard_question为"智能家居中控保修多久？""断网后语音还能用吗？""一个账号能绑几台中控？"的条目一一对应，是手册向 FAQ 库转化的直接素材，第四节将展开讲解这一转化。

三、文档入库：把 Markdown 手册变成可检索的知识

产品手册要能被检索和回答，先要经过 WeKnora 的文档入库管线。整个链路为：上传 → 存储 → 解析 → 分块 → 向量化 → 索引，详见 文档入库流程。

3.1 建库与上传

在 Web 前端创建类型为document的知识库，将本手册的 Markdown 文件上传即可（完整路径参考 快速上手）。Markdown 由独立的 Python 微服务 docreader 解析，其解析器矩阵覆盖 Markdown / HTML / PDF / Office 等多种格式（见 文档解析服务）。

3.2 分块参数：从 POC 方案继承的实践值

04-技术方案-售后知识库POC.md 针对这套语料给出了可直接落地的分块建议：

这组数值的设计意图值得展开：手册正文段落平均长度与 512 字符的切分窗口大致吻合，overlap=64用于把"最大接入设备数"这类紧贴表格下方的结论行与规格表本体关联起来；父子分块则保证回答生成时能拿到完整段落而非被截断的子块。WeKnora 的分块机制本身是自适应的（heading / heuristic / recursive 三种策略），详见 分块机制。

3.3 检索策略：混合检索 + RRF + 可选 Rerank

POC 方案的检索策略同样是现成的实践模板：

• 默认：向量 + BM25 混合检索，RRF 融合，Top-5 送入 LLM；
• 可选：开启 Rerank（bge-reranker-v2-m3）提升多义词场景准确率；
• 暂不启用：知识图谱（Neo4j）与 Wiki 自动生成。

混合检索解决了"产品手册中规格数字靠关键词精确命中、场景描述靠语义召回"的两种需求差异，各检索引擎的能力对比见 检索引擎与向量存储。

四、FAQ 化：从手册问答到标准问答库

产品手册中的 FAQ 是零散排布的，回答质量依赖检索命中。WeKnora 的 FAQ 知识库（KB 类型为faq）把它们转化为结构化条目，检索时直接匹配问题并按策略返回标准答案，详见 FAQ 能力。

4.1 样例 JSON 的结构解析

05-常见问题-FAQ导入样例.json 中的每个条目包含五个字段，与 WeKnora 的 FAQ 条目模型一一对应：

{ "tag_name": "售后", "standard_question": "智能家居中控保修多久？", "similar_questions": ["保修期几年", "质保多长时间"], "negative_questions": [], "answers": ["整机保修 24 个月，电池类配件 12 个月。人为拆解、进水不在保修范围。"] }

注意样例中"保修多久"这条的similar_questions覆盖了"保修期几年""质保多长时间"两种说法，这正是 FAQ 知识库相对纯文档检索的优势：把不同问法收敛到同一标准答案。而negative_questions字段（样例中为空数组）对应检索时的负例过滤机制——例如问"不支持 X 吗"，就不会错误命中"支持 X"的条目。

4.2 数据模型：一个 FAQ 条目 = 一个 Chunk

在 internal/types/faq.go 中，每个 FAQ 条目对应一条ChunkType = "faq"的 Chunk，结构化内容存放在FAQChunkMetadata中：

type FAQChunkMetadata struct { StandardQuestion string `json:"standard_question"` SimilarQuestions []string `json:"similar_questions,omitempty"` NegativeQuestions []string `json:"negative_questions,omitempty"` // 反例问：命中即过滤 Answers []string `json:"answers,omitempty"` AnswerStrategy AnswerStrategy `json:"answer_strategy,omitempty"` // all | random Version int `json:"version,omitempty"` // 每次更新自增 Source string `json:"source,omitempty"` }

其中AnswerStrategy取值为all（返回全部答案）或random（随机返回一个），默认all。条目的分类、启停、推荐位则复用 Chunk 通用字段（TagID、IsEnabled、Flags中的ChunkFlagRecommended）。

4.3 批量导入：append / replace 与 dry_run

FAQ 条目通过POST /knowledge-bases/:id/faq/entries批量导入（实现见 internal/application/service/knowledge_faq_import.go），核心参数：

type FAQBatchUpsertPayload struct { Entries []FAQEntryPayload `json:"entries" binding:"required"` Mode string `json:"mode" binding:"oneof=append replace"` KnowledgeID string `json:"knowledge_id"` TaskID string `json:"task_id"` // 可选，不传自动生成 UUID DryRun bool `json:"dry_run"` // 仅验证不落库 }

• append：按内容哈希匹配已有条目，命中则合并（保留标准问、追加去重后的相似问、覆盖答案），未命中则新增；
• replace：删除全部旧条目，仅保留本批导入内容；
• dry_run：仅运行格式校验、批内去重、DB 查重与内容安全检查，不落库，适合先验证样例 JSON 再正式导入。

导入是异步任务，可通过GET /faq/import/progress/:task_id轮询进度，返回success_count/failed_count/partial_failed_count/skipped_count/merged_count/added_count等统计，以及失败条目明细 CSV。

4.4 检索命中策略：负例过滤与迭代召回

FAQ 检索（internal/handler/faq.go 的SearchFAQ+ internal/application/service/knowledgebase_search_faq.go）的命中流程为：

1. 混合召回：查询文本归一化后做向量检索 + BM25 关键词检索，融合去重；
2. 两级标签优先：FirstPriorityTagIDs命中的条目排最前，其次SecondPriorityTagIDs；
3. 负例过滤：查询文本与某条目的任一反例问完全匹配（小写比较）→ 剔除该条目；
4. 迭代召回：过滤后结果不足match_count且向量结果打满时，最多迭代 5 次、每次 TopK 翻倍，带去重与负例过滤缓存，无新结果提前终止；
5. 结果附带score、match_type、matched_question（实际命中的是标准问还是哪个相似问），答案按answer_strategy返回。

FAQSearchRequest的关键参数：VectorThreshold（默认 0.7）、MatchCount（默认 10，上限 50）、OnlyRecommended。请求参数可通过 FAQ 检索 API 直接调试。

五、端到端演练：从语料到验收的 POC 路径

04-技术方案-售后知识库POC.md 给出了这套语料的完整落地模板，核心要素：

架构链路：Confluence 导出 / Markdown / PDF 手册 → WeKnora（docreader 解析 → 分块 → 向量 + BM25 混合检索）→ 模型层（本地 bge-m3 Embedding + 公司 API 网关的 DeepSeek-V3）→ 售后工单系统 iframe 嵌入（二期）。

首批语料清单与预估分块数：

验收用例（节选）：

这套验收表的设计值得借鉴：每道题同时校验答案要点与期望出处，与 WeKnora"回答必须带出处链接"的要求一致——FAQ 库返回matched_question，文档库通过引用面板给出可追溯的原始段落，二者都能满足"可追溯"这一验收底线。

六、实践要点与注意事项

结合手册内容与 WeKnora 实现，梳理几条落地要点：

1. 文档库与 FAQ 库各司其职：开放式的"怎么配置""支持什么"问题交给文档库混合检索；高频、答案固定的标准问答（保修、限购、报销上限）沉淀为 FAQ 条目。FAQ 库可与文档库一起供 Agent 检索，启用 FAQ 优先并满足直接回答阈值时可直接返回标准答案。
2. 语料过期管理：POC 方案明确列出"语料过期"为首要风险——手册 v2.1 与即将发布的 v2.2 冲突时，需要建立"语料 Owner"机制定期核对，这正是 02-会议纪要-Q1产品规划.md 中提到的售后语料质量参差风险的缓解手段。
3. 幻觉抑制：强制 Prompt 要求"仅根据引用回答；无依据则回复不知道"，避免模型在手册范围外自由发挥。
4. 权限边界：POC 阶段单租户即可；生产环境按区域售后组拆分知识库 ACL，对应 WeKnora 的多租户与知识库访问控制能力（见 租户、用户与认证授权）。

实现参考

以下路径均相对仓库根目录，可按需深入：

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora