知识库与RAG
一、功能介绍
知识库用于把平台文档、协议资料、数据语义和二开说明整理成可被 AI 调用的知识。AI 在回答平台使用问题、解析协议、执行智能问数时，会优先使用已发布的知识库内容，减少凭空猜测。
RAG 可以理解为“先检索资料，再让模型回答”。资料越结构化、版本越清晰，AI 回答越稳定。
二、操作路径
AI 赋能 > 知识库不同版本菜单名称可能略有差异，以实际管理端为准。
三、知识库类型
| 类型 | 用途 | 典型内容 |
|---|---|---|
| 平台文档知识库 | 支撑平台助手回答菜单、功能、配置、排错和使用说明 | 用户手册、FAQ、操作步骤、注意事项 |
| 协议知识库 | 支撑协议解析和协议适配任务 | 协议术语、报文结构、字段说明、编解码规则、样例报文 |
| NL2SQL 语义知识库 | 支撑智能问数理解表、字段、指标和查询口径 | 表含义、字段语义、枚举、指标口径、数据范围 |
| 源码导航知识库 | 支撑二开人员理解模块、类、接口和页面入口 | 模块说明、接口说明、页面路径、源码摘要 |
信息
当前管理端知识导入以模板方式为主。平台文档、协议知识和 NL2SQL 语义通常通过下载 Excel 模板、填写后上传解析；源码导航知识库更多用于系统自动构建或专用入口维护。
四、整体流程
五、创建知识库
| 字段 | 说明 | 使用建议 |
|---|---|---|
| 知识库编码 | 系统内部识别编码 | 建议稳定、唯一，不要频繁变更 |
| 知识库名称 | 页面展示名称 | 按业务域命名，如 平台使用手册、JT808协议知识 |
| 知识库类型 | 决定模板、解析方式和调用场景 | 按实际用途选择，避免混放不同类型资料 |
| 向量存储类型 | 知识检索使用的存储方式 | 以系统配置和页面选项为准 |
| 发布状态 | 当前是否已有可用版本 | 新建后通常需要构建并发布版本 |
| 启用状态 | 每种类型唯一启用，是否参与运行态调用 | 禁用后不应继续被业务能力使用 |
| 备注 | 知识范围说明 | 写清楚资料来源、版本、适用项目 |
建议一个知识库只服务一个清晰场景。例如平台操作文档和设备协议资料不要混在同一个知识库中。
六、模板下载与上传
1. 下载模板
进入知识库详情后，按知识库类型下载模板：
| 知识库类型 | 模板内容 |
|---|---|
| 平台文档知识库 | 功能、菜单、页面、问题、答案、来源等平台知识 |
| 协议知识库 | 协议总览、报文类型、字段、编解码规则、样例报文等 |
| NL2SQL 语义知识库 | 表、字段、枚举、指标、查询提示和业务口径 |
部分版本支持生成预填模板，例如从本地文档或官网文档提取平台知识。预填内容仍需人工检查后再发布。
2. 填写模板
填写模板时请注意：
- 一行只描述一个明确知识点、字段、报文或查询语义。
- 名称、标识符、枚举值、单位和倍率要与系统实际保持一致。
- 能提供来源、版本、适用范围时尽量填写，方便后续排查。
- 过期内容不要和新内容同时启用，避免 AI 引用旧资料。
3. 上传解析
当前模板上传支持 .xls 和 .xlsx，源码导航是.json。上传后系统会保存为知识文档，解析成功后会生成快照和分段结果。
如果上传失败，通常是文件格式、必填列、枚举值、重复编码或内容校验不通过。请根据页面提示修改模板后重新上传。
警告
NL2SQL 语义不再建议通过 SQL 文件直接上传，应使用语义模板维护表、字段、枚举和指标口径。
七、文档状态
知识库中的每次模板上传都会形成一条文档记录。常见状态含义如下：
| 状态 | 含义 | 处理方式 |
|---|---|---|
| 待解析 | 文档已上传但尚未解析完成 | 等待任务完成或手动重试 |
| 解析成功 | 已生成可构建的知识快照 | 可以参与版本构建 |
| 解析失败 | 文件格式或内容校验异常 | 查看错误信息，修正后重新上传 |
| 已禁用 | 暂不参与版本构建 | 适用于旧资料、测试资料或不再使用的资料 |
构建版本时，通常只会使用启用且解析成功的文档。
八、版本构建、发布与回滚
知识库采用版本方式管理，目的是让资料变更可追踪、可发布、可回滚。
- 上传或更新模板。
- 确认文档解析成功。
- 构建知识库版本，生成草稿快照。
- 查看质量检查结果。
- 发布版本，成为当前运行态版本。
- 如果新版本效果异常，可回滚到历史归档版本。
| 版本状态 | 含义 |
|---|---|
| 草稿 | 已构建但未对业务生效 |
| 已发布 | 当前业务可调用的版本 |
| 已归档 | 历史版本，可用于回滚 |
发布后，平台助手、协议适配、智能问数等能力才会读取新版本。只上传模板但不发布，线上问答通常不会发生变化。
九、运行态重建
某些知识库发布后还需要刷新运行态缓存或语义索引，尤其是 NL2SQL 语义知识库。页面提供运行态查看和重建能力时，可以在以下场景使用：
- 发布新版本后，智能问数仍使用旧字段或旧口径。
- 语义内容修正后，需要立即让业务生效。
- 运行态缓存异常，需要手动刷新。
重建前请确认当前发布版本质量正常，避免把错误语义同步到业务查询中。
十、问答质量优化
| 问题 | 可能原因 | 优化方式 |
|---|---|---|
| 回答泛泛而谈 | 知识点不够具体，缺少操作步骤或示例 | 补充菜单路径、字段含义、错误示例和处理步骤 |
| 引用旧内容 | 旧模板仍启用，或新版本未发布 | 禁用旧文档，重新构建并发布版本 |
| 协议解析不准确 | 报文方向、字节序、校验、倍率或样例缺失 | 补充字段表、样例报文和编解码规则 |
| 智能问数口径错误 | 字段语义、枚举、指标定义不完整 | 补充 NL2SQL 语义模板，重建运行态 |
| 回答无法命中知识 | 知识库未启用、版本未发布或内容描述过少 | 检查知识库状态、版本状态和关键词覆盖 |
| 响应较慢 | 资料过多、召回范围过大或模型较慢 | 拆分知识库，减少无关内容，优化模型配置 |
十一、维护建议
- 正式知识库建议按版本维护，不要直接把测试资料发布到生产环境。
- 每次资料更新后记录来源、版本和修改原因。
- 平台文档知识尽量写成用户能直接执行的步骤，而不是只写功能名称。
- 协议知识尽量结构化，字段、类型、倍率、单位、枚举和样例要完整。
- NL2SQL 语义要写清楚查询边界，避免用户用自然语言问出越权或歧义查询。
- 重要知识发布前，建议先用 AI 对话或专用验证入口抽样测试。