通义灵码知识库问答增强：知识库构建与管理指南

作者：垚佳、汐遥

通义灵码能够结合企业知识库的私域数据，生成贴合企业特点的回答。充分发挥检索增强技术的优势，构建高质量的企业知识数据以及合理的知识库权限管理是必不可少的。本文将为您详细介绍如何构造与管理一个高质量的企业知识库。

前提条件

• 适用版本： 通义灵码企业标准版、通义灵码企业专属版。
• 适用人员： 通义灵码管理员、组织内全局管理员（专属版）。

场景介绍

通义灵码虽然具备广泛的通用知识，但缺乏企业独有的专业知识和数据。通过引入企业知识库，可以帮助模型更精准地理解私域知识，以便生成更加贴合企业特色的个性化回答。通义灵码能够基于知识库进行自由问答，代码优化与生成，广泛应用于企业规范检查、技术支持等多个场景。

例如：

1）智能自由问答场景： 企业技术新人入职问答、企业安全合规规范问答、产品运维故障排查咨询、企业内部平台、API 使用问答等。

2）代码优化与生成场景： 根据企业编码规范，确保代码风格的一致性与规范性；根据安全规范文档检查代码漏洞，并提出修复建议等。

为了最大程度发挥生成的效果，需要从两个方面进行实践。一方面是构建高质量的知识库，确保知识数据的质量；另一方面是清晰的知识库权限分配，确保知识库的可见范围符合预期。为此知识库管理员需要：

• 提供 AI 友好的、高质量的知识数据，如文档或代码等，陈旧或不准确的信息不仅无法带来增益，反而可能会误导模型，影响回答的准确性；
• 构建一个结构合理、权限隔离的知识库。这不仅保障了数据的隐私和隔离，还保障了知识库的易管理性和可维护性。权限管理混乱的知识库可能会引发数据安全等问题。

构建高质量知识库

通义灵码的企业知识库问答功能，目前已支持通过文档上传的形式，将其转化为检索增强的知识数据，本章节将重点介绍文档类知识数据的准备原则和方法。如需了解代码类请参见《企业代码补全增强使用实践》 [ 1] 。

文档格式要求

• 格式： 支持 PDF、CSV、DOCX、TXT、Markdown 格式，优先推荐使用 Markdown 格式。
• 大小： 每次最多上传 10 个文件，单文件大小不超过 10MB。

单个文档规范

单个文档需要从名称、标题、格式、内容方面检查是否符合文档规范。

详细说明与示例如下：

文档类型与命名

• 类型： 推荐使用 Markdown 格式。相较于 Word 和 PDF，我们推荐使用 Markdown 格式以获得更佳的文档处理效果。
• 编码： 推荐使用 UTF-8 编码，以确保字符兼容性最佳。
• 文档命名： 文档名用词简洁明了，不同命名之间应有明显差异，便于模型理解。避免使用含义不明的英文缩写、数字或符号。

反例： 《编码规范》、《安全规范1》、《安全规范2》、《SR3》这些命名缺乏具体性，不易区分，且可能造成混淆。

正例： 《Java语言编程规范》：明确指出了编程语言和文档性质。

《API数据安全管理规范》：指出了文档内容和目的。

《云账号安全使用管理规范》：清晰地表达了文档的主题和适用范围。

文档结构

• 层级结构： 需采用多级标题来组织文档内容，避免将信息堆砌在单一段落。特别是对于专有名词的释义，每个专有名词建议单独成行。
• 各级标题： 各层级标题含义清晰用词简洁明了，不同标题之间有明显差异。避免使用含义不明的英文缩写、数字或符号。避免罗列文章关键词，会对模型造成干扰。

反例：

《AK安全使用规范》
【目录】
关键词：AK、安全规范、Access Key
一、 定义
Access Key（简称AK），是用于身份验证的一种密钥对，由Access Key ID 和 Access Key Secret 组成。它允许用户通过API调用安全地访问系统服务。本规范旨在明确AK的使用规则，确保系统的安全性与稳定性。Access Key ID是代表用于标识用户的身份。Access Key Secret是代表用于加密签名，保证请求的唯一性和不可抵赖性。
二、 使用原则
确保Access Key Secret的保密性，不得泄露给任何未经授权的第三方。遵循最小权限原则授予API调用权限，仅授予完成任务所必需的权限。定期每90天更换Access Key Secret。记录AK的使用情况，并定期审查使用日志，确保没有异常行为，以及在不需要时及时撤销其权限。
三、 安全实践
为确保访问密钥（AK）的安全，我们实施了以下简化的安全实践：在生产环境中，我们优先使用环境变量存储AK，避免硬编码；通过配置管理系统统一管理AK，防止其在代码中的直接暴露。同时，我们对日志进行过滤，确保AK的Secret信息不会被记录。我们还定期进行权限审查，确保AK仅拥有执行必要操作所需的最低权限。此外，建立了异常检测机制，以便快速识别并响应任何可疑的AK使用活动。这些措施共同保障了AK的安全和合理使用。
四、 API调用示例
● 示例1
Node.js中使用AK/SK进行API调用：在Node.js中，可以使用axios库来发送API请求，并在请求头中包含AK和SK。例如，使用AK和SK进行签名认证的API请求可能如下所示：
【示例代码块】
● 示例2
Python中使用AK/SK调用API：在Python中，可以使用requests库来发送带有AK和SK的API请求。以下是一个示例代码，展示了如何构建请求并添加签名：
【示例代码块】

正例（注释为优化说明）：

《AK安全使用规范》
/*
去除干扰元素：文章开头的目录、关键词等无需召回的内容可以删除，以减少干扰。
专业名词解释：专业名词及其解释应以条目形式列出，以便于模型更好地查找和理解。
 */
一、 定义
● Access Key（简称AK）：是用于身份验证的一种密钥对，由Access Key ID 和 Access Key Secret 组成，它允许用户通过API调用安全地访问系统服务。
● Access Key ID：用于标识用户的身份。
● Access Key Secret：用于加密签名，保证请求的唯一性和不可抵赖性。
/*
避免使用大段落陈述，建议采用分点陈述的方式，以便模型更容易理解
 */
二、 使用原则
● 保密性：Access Key Secret 必须严格保密，不得泄露给任何未经授权的第三方。
● 最小权限：授予API调用的权限应遵循最小权限原则，仅授予完成任务所必需的权限。
● 定期轮换：定期更换Access Key Secret，推荐每90天更换一次。
● 监控与审计：记录AK的使用情况，并定期审查使用日志，确保没有异常行为。
● 及时撤销：当不再需要使用某个AK时，应及时撤销其权限。
三、 安全实践
● 环境变量：在生产环境中，使用环境变量而非硬编码的方式存储AK。
● 配置管理：使用配置管理系统来管理AK，避免直接在代码中出现。
● 日志过滤：确保日志记录中不会出现Access Key Secret。
● 权限审查：定期检查AK的权限设置，确保符合最小权限原则。
● 异常检测：建立异常检测机制，及时发现并处理可疑活动。
/*
关于API调用示例部分，示例层级的名字不清晰，其中“示例1”和“示例2”，需要修改为某个示例的具体名字
*/
四、API调用示例
● Node.js中使用AK/SK进行API调用示例
 在Node.js中，可以使用axios库来发送API请求，并在请求头中包含AK和SK。例如，使用AK和SK进行签名认证的API请求可能如下所示：
【示例代码块】
● Python中使用AK/SK调用API示例
在Python中，可以使用requests库来发送带有AK和SK的API请求。以下是一个示例代码，展示了如何构建请求并添加签名：
【示例代码块】

文档章节和段落

• 将相关性强的内容尽量聚集在同一段落或章节内，以确保数据处理文档切片的准确性和相关内容的连续性。
• 避免指代或缩略关键信息。如果遇到内容相同，避免“同上”或“与某个模块相同”这样的表述，应该具体写明内容。
• 避免无意义的空行。
• 建议利用项目符号（如 Markdown 中的“-”或“*”）和有意义的缩进来分点阐述，可以在一定程度上辅助模型更准确地理解。

反例：

1）无意义的空行

6.3 方法的接收器
推荐以类名第一个英文首字母的小写作为接收器的命名。

接收器的命名在函数超过`20行`的时候不要用单字符。

命名不能采用 `me`，`this`，`self` 这类易混淆名称。

2）使用省略描述或指代描述

4.6 Go语言的接口命名规则
命名规则和结构体命名规则一致。
或
同3.2章《命名规则和结构体命名规则》

正例：

1）去掉无意义的空行

6.3 方法的接收器
● 推荐以类名第一个英文首字母的小写作为接收器的命名。
● 接收器的命名在函数超过`20行`的时候不要用单字符。
● 命名不能采用 `me`，`this`，`self` 这类易混淆名称。

2）需要详细阐述具体内容，避免使用同上、缩写或指代词

4.6 Go语言的接口命名规则
● 采用驼峰命名方式，首字母根据访问控制采用大写或者小写。
● 结构体名应该是名词或名词短语，如 Customer、WikiPage、Account、AddressParser，它不应是动词。
● 避免使用 Data、Info 这类意义太宽泛的结构体名。

特殊内容与媒体处理

当文档段落中出现图片、表格时，应该对应注意以下几点：

文档中关于表格的处理：

• 表格格式要求：表格的第一行应为表头，不要将表格名称作为表格的第一行内容。
• 表格结构说明：对于表格结构没有特别的要求。可以根据内容的需要自由设计列和行。
• 保持样式简洁：建议去除所有不必要的格式，如背景色、字体样式等。表格线条应保持清晰，使用默认的线条样式。

• 补充说明：

  • 企业标准版，由于表格处理能力仍在持续优化，建议在文档中尽量减少表格，或考虑比如文本列表等替代方式来展示表格数据。
  • 企业专属版与私有化版本，通义灵码已经具备了更高级的表格处理能力，可确保表格数据的准确性。

文档中关于图片的处理：

• 优先使用文字：尽可能地使用文字表达信息，如果图像中的文字比较少且包含重要信息，建议将信息转录成文字的形式。
• 添加图示说明：确保所有核心图都有图示说明（即图解或说明），图示说明应清晰地解释图中的主题。

其他通用注意事项：

• 特殊字符：避免包含表情包的特殊字符，以免造成解析问题。
• 页眉页脚、水印、批注：避免包含批注、页眉、页脚或水印，以免造成不必要的干扰。
• 文档背景：文档每页尽可能无背景，复杂背景容易造成干扰。
• 统一文字方向：确保文档中所有文字的方向一致。
• 音视频：避免包含音视频等多媒体内容。

不同类型文档的处理准则：

Markdown： 建议优先使用 Markdown 格式。

Word：

• 使用更新格式：优先采用 2007 版或之后的 Word 格式。
• 使用全局样式：统一使用全局标题和段落样式。
• 避免字符样式：不要使用字符样式，如特殊字体格式、边框和底纹。
• 使用段落样式：应使用段落样式来保持文档格式的一致性。

PDF：

• 避免使用图片：不要直接将图像转换成 PDF 文件。应该将图像中的重要信息转录成文本，并按照本文中的文档规范要求进行组织。
• 不包含嵌入压缩文件： 请确保文件中不包含嵌入的压缩文件。
• 保持文档单栏布局：避免双栏并排形式，以确保内容被正确解析。

CSV：

• 避免使用图片：不插入图片，以确保文档的文本可搜索性。
• 不嵌入压缩文件：不要在文档中嵌入压缩文件。
• 表头作为第一行：在表格中，将表头放在第一行，不要将表格名称作为表格的第一行内容。

• 特别说明：

  • 推荐用法：保存 FAQ（常见问题解答）中的问答对。FAQ 的问题表述清晰明确，答案简洁易懂，使用用户熟悉的术语，突出关键词，以提高检索召回准确度。例如：

-   不推荐：在 CSV 中上传复杂的关系型数据表。可能会导致数据处理时间超长，导致数据处理失败。

多文档规范

在编写文档时，确保多个文档之间做到知识独立、知识聚合、规范统一以及覆盖全面，这样做能够显著提高知识的召回准确度，从而提升整体效果。你可以参考以下准则来进行多文档组织与整理：

知识独立： 每个文档应包含独特且非冗余的信息。

• 在撰写文档内容时，如介绍特性或功能时，检查是否存在与其他文档重叠的内容，并尽量减少重复。
• 尽量保证每个文档都是自成一体的知识单元，能够独立提供完整而准确的信息。

知识聚合： 尽量将与同一主题相关的所有信息整合到一起。

尽量将同一主题的相关知识聚类在一起，避免相关知识过于分散，尽量实现文档内高内聚。

规范统一： 确保同类信息在不同文档间保持一致性和标准化。

• 确保所有文档遵循一致的风格和术语标准。
• 制定详细的风格指南和术语表，并对文档编写者进行培训，确保他们能够正确应用这些规则。

覆盖全面： 确保文档的完整性、及时性、准确性。

• 确保知识库覆盖问答所需的高频知识。针对需要高精确度回答的问题，知识无遗漏， 如对于某个 API 的咨询，需确保包含了所有相关的接口、参数。
• 定期对知识库进行审核和更新，补充缺失的知识点，淘汰过时的内容。

遵循上述原则，不仅能帮助企业知识库管理员创建高质量的产品文档，还能提升用户的满意度和体验。通过系统化的方法来组织和维护文档，确保了信息的准确性、易用性和完整性，为用户提供了一个更加可靠的知识资源库。

知识库权限管理

知识库的划分，通常是根据内容主题和可见成员对象来确定。

一方面，可以创建企业内所有已授权开发者可见的通用型知识库，用于共享企业内的规范性文档和指南，如企业代码规范、安全标准等；另一方面，也可以为特定团队或部门创建垂直型知识库，如具体业务的开发文档、培训材料和运维指南，或面向企业新人的技术指南等。

新建知识库

在通义灵码的企业管理台，选择知识管理模块，单击新建知识库，选择智能问答场景，可见范围选择私有-仅知识库成员。

说明： 可见范围选择公开则企业内所有已授权使用通义灵码的开发者均对知识库可见，选择私有则可以自定义可见成员的范围，推荐选择私有。

管理知识库可见成员

在通义灵码的企业管理台，选择知识管理模块，选择需要操作的知识库，在知识库的可见成员管理列表中选择添加开发者或移除。如需了解知识库更多操作请参见《企业知识库问答》 [ 2] 。

说明： 在管理知识库的可见成员时，需确保每位成员仅访问与其职责和工作相关的知识内容。这不仅保护了数据隔离和隐私安全，还减少了不必要的信息干扰，提升了用户的专注度和知识检索的效率。

相关链接：

[1] 企业代码补全增强使用实践

https://help.aliyun.com/zh/lingma/use-cases/enterprise-code-c...

[2] 企业知识库问答

https://help.aliyun.com/zh/lingma/user-guide/enterprise-knowl...

推荐阅读： 《5 大场景上手通义灵码企业知识库 RAG》

---

更多活动推荐

1）通义灵码一周年： 灵码新功能有奖测评火热开启！参与有机会获得机械键盘、华为手环等精美好礼：https://developer.aliyun.com/topic/lingma-one-year

2）手把手带你体验通义灵码企业 RAG，让问答和代码补全更贴合企业规范和业务特点。赢通义灵码超大鼠标垫 1000 份， 领完为止：https://developer.aliyun.com/topic/lingma/202409

点击此处，下载使用通义灵码！