通義靈碼知識庫問答增強：知識庫構建與管理指南

通義靈碼能夠結合企業知識庫的私域資料，生成貼合企業特點的回答。充分發揮檢索增強技術的優勢，構建高質量的企業知識資料以及合理的知識庫許可權管理是必不可少的。本文將為您詳細介紹如何構造與管理一個高質量的企業知識庫。

前提條件

適用版本： 通義靈碼企業標準版、通義靈碼企業專屬版。
適用人員： 通義靈碼管理員、組織內全域性管理員（專屬版）。

場景介紹

通義靈碼雖然具備廣泛的通用知識，但缺乏企業獨有的專業知識和資料。透過引入企業知識庫，可以幫助模型更精準地理解私域知識，以便生成更加貼合企業特色的個性化回答。通義靈碼能夠基於知識庫進行自由問答，程式碼最佳化與生成，廣泛應用於企業規範檢查、技術支援等多個場景。

例如：

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》