构建与管理你的通义灵码知识库：问答增强全攻略！

作者：垚佳、汐遥

通义灵码可以利用企业内部的私域数据，生成符合企业特色的回答。为了充分发挥检索增强技术的优势，构建一个高质量的企业知识库以及合理的权限管理是非常重要的。接下来，我们将详细聊聊如何打造和管理一个高质量的企业知识库。

前提条件

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

场景介绍

虽然通义灵码拥有丰富的通用知识，但在企业特有的专业知识和数据方面还是有所欠缺。引入企业知识库可以帮助模型更精准地理解私域知识，从而生成更符合企业特点的个性化回答。通义灵码可以基于知识库进行灵活的问答、代码优化和生成，广泛应用于企业规范检查、技术支持等多个场景。

比如说：

1）智能问答场景：员工入职时的技术咨询、企业安全合规问题、产品运维故障排查、内部平台使用问答等。

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调用示例● 示例1Node.js中使用AK/SK进行API调用：在Node.js中，可以使用axios库来发送API请求，并在请求头中包含AK和SK。例如，使用AK和SK进行签名认证的API请求可能如下所示：【示例代码块】● 示例2Python中使用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 格式：

• 别放图片：不插入任何图片，这样才能确保文档中的文本可以被搜索。
• 不嵌压缩文件：文档中不要有嵌入的压缩文件。
• 表头置顶：表格的第一行要放表头，表格名称不要放在首行。
• 特别提示：

• 推荐做法：把常见问题解答中的问答整理好。确保问题清晰，答案简洁，使用大家熟悉的术语，突出关键词，这样能提高检索的准确性。

• 不推荐：在 CSV 中上传复杂的关系型数据，这样会导致处理时间过长，甚至可能失败。

多文档规范：

在撰写文档时，要确保多个文档之间做到知识独立、聚合、规范统一和全面覆盖，这样才能显著提高信息的检索准确率，从而提升整体效果。以下是一些整理和组织多文档的准则：

知识独立：每个文档都应该有独特的信息，避免冗余。

• 在撰写内容时，检查是否有与其他文档重复的地方，尽量减少相似内容。
• 确保每个文档都能独立提供完整的信息，成为一个自足的知识单元。

知识聚合：尽量把与同一主题相关的信息整合在一起。

将相同主题的知识聚在一起，避免分散，以实现文档的高内聚性。

规范统一：确保同类型的信息在不同文档间保持一致性。

• 确保所有文档遵循相同的风格和术语标准。
• 制定详细的风格指南和术语表，并对文档撰写人员进行培训，以确保正确使用这些规范。

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

• 确保知识库覆盖所有高频问答所需的信息。针对需要精确回答的问题，确保知识无遗漏，例如关于某个 API 的问题，要涵盖所有相关接口和参数。
• 定期审核和更新知识库，补充缺失的知识点，剔除过时的信息。

遵循这些原则，不仅能帮助管理员编写优质的产品文档，还能提升用户的满意度与体验。通过系统化的方式组织和维护文档，确保信息的准确性、易用性与完整性，为用户提供一个更可靠的知识资源库。

知识库权限管理

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

一方面，可以创建一个所有授权开发者都能访问的通用知识库，用于分享公司内部的规范文档和指南，比如企业代码规范和安全标准等；另一方面，可以为特定团队或部门建立专属知识库，例如开发文档、培训材料和运维指南，或者面向新员工的技术指导等。

新建知识库：

轻松创建和管理你的知识库

在通义灵码的企业管理平台上，首先找到知识管理这个模块，接着点击新建知识库，选择智能问答的场景，这时候你会看到一个可见范围的选项，记得选择“私有-仅知识库成员”哦。

小提示：如果选择“公开”，那么所有已经获得通义灵码授权的开发者都能看到这个知识库；而如果你选择“私有”，就可以自定义哪些成员可以访问，建议你还是选私有比较好。

管理知识库的可见成员

同样在通义灵码的企业管理平台，你需要选择要操作的知识库，然后进入可见成员管理列表，这里可以添加或移除开发者。如果你想知道更多关于知识库的操作，可以参考《企业知识库问答》。

小提示：管理知识库成员的时候，务必要确保每个人只能访问跟自己工作相关的内容。这样不仅能保护数据的隐私，还能减少干扰，提高专注度和信息检索的效率。

相关链接：

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

https://help.aliyun.com/zh/lingma/use-cases/enterprise-code-completion-enhancements-beta-usage-practices

[2] 企业知识库问答

https://help.aliyun.com/zh/lingma/user-guide/enterprise-knowledge-base-q-a