通義靈碼的企業知識庫問答功能，目前已支持通過文檔上傳的形式，將其轉化為檢索增強的知識數據，本章節將重點介紹文檔類知識數據的準備原則和方法。如需了解代碼類請參見。

文檔格式要求

• 格式：支持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中的“-”或“*”）和有意義的縮進來分點闡述，可以在一定程度上輔助模型更準確地理解。

  反例	正例
  無意義的空行 6.3 方法的接收器 推薦以類名第一個英文首字母的小寫作為接收器的命名。 接收器的命名在函數超過`20行`的時候不要用單字符。 命名不能采用 `me`，`this`，`self` 這類易混淆名稱。	去掉無意義的空行 6.3 方法的接收器 ● 推薦以類名第一個英文首字母的小寫作為接收器的命名。 ● 接收器的命名在函數超過`20行`的時候不要用單字符。 ● 命名不能采用 `me`，`this`，`self` 這類易混淆名稱。
  使用省略描述或指代描述 4.6 Go語言的接口命名規則 命名規則和結構體命名規則一致。 或 同3.2章《命名規則和結構體命名規則》	需要詳細闡述具體內容，避免使用同上、縮寫或指代詞 4.6 Go語言的接口命名規則 ● 采用駝峰命名方式，首字母根據訪問控制采用大寫或者小寫。 ● 結構體名應該是名詞或名詞短語，如 Customer、WikiPage、Account、AddressParser，它不應是動詞。 ● 避免使用 Data、Info 這類意義太寬泛的結構體名。

特殊內容與媒體處理

當文檔段落中出現圖片、表格時，應該對應注意以下幾點：

• 文檔中關于表格的處理：

  • 表格格式要求：表格的第一行應為表頭，不要將表格名稱作為表格的第一行內容。

  • 表格結構說明：對于表格結構沒有特別的要求。可以根據內容的需要自由設計列和行。

  • 保持樣式簡潔：建議去除所有不必要的格式，如背景色、字體樣式等。表格線條應保持清晰，使用默認的線條樣式。

  • 補充說明：

    • 企業標準版，由于表格處理能力仍在持續優化，建議在文檔中盡量減少表格，或考慮比如文本列表等替代方式來展示表格數據。

    • 企業專屬版與私有化版本，通義靈碼已經具備了更高級的表格處理能力，可確保表格數據的準確性。

• 文檔中關于圖片的處理：

  • 優先使用文字：盡可能地使用文字表達信息，如果圖像中的文字比較少且包含重要信息，建議將信息轉錄成文字的形式。

  • 添加圖示說明：確保所有核心圖都有圖示說明（即圖解或說明），圖示說明應清晰地解釋圖中的主題。

• 其他通用注意事項：

  • 特殊字符：避免包含表情包的特殊字符，以免造成解析問題。

  • 頁眉頁腳、水印、批注：避免包含批注、頁眉、頁腳或水印，以免造成不必要的干擾。

  • 文檔背景：文檔每頁盡可能無背景，復雜背景容易造成干擾。

  • 統一文字方向：確保文檔中所有文字的方向一致。

  • 音視頻：避免包含音視頻等多媒體內容。

不同類型文檔的處理準則

• Markdown：建議優先使用Markdown格式。

• Word：

  • 使用更新格式：優先采用2007版或之后的Word格式。

  • 使用全局樣式：統一使用全局標題和段落樣式。

  • 避免字符樣式：不要使用字符樣式，如特殊字體格式、邊框和底紋。

  • 使用段落樣式：應使用段落樣式來保持文檔格式的一致性。

• PDF：

  • 避免使用圖片：不要直接將圖像轉換成PDF文件。應該將圖像中的重要信息轉錄成文本，并按照本文中的文檔規范要求進行組織。

  • 不包含嵌入壓縮文件： 請確保文件中不包含嵌入的壓縮文件。

  • 保持文檔單欄布局：避免雙欄并排形式，以確保內容被正確解析。

• CSV：

  • 避免使用圖片：不插入圖片，以確保文檔的文本可搜索性。

  • 不嵌入壓縮文件：不要在文檔中嵌入壓縮文件。

  • 表頭作為第一行：在表格中，將表頭放在第一行，不要將表格名稱作為表格的第一行內容。

    特別說明：

    • 推薦用法：保存FAQ（常見問題解答）中的問答對。FAQ的問題表述清晰明確，答案簡潔易懂，使用用戶熟悉的術語，突出關鍵詞，以提高檢索召回準確度。例如：

    • 不推薦：在CSV中上傳復雜的關系型數據表。可能會導致數據處理時間超長，導致數據處理失敗。

多文檔規范

在編寫文檔時，確保多個文檔之間做到知識獨立、知識聚合、規范統一以及覆蓋全面，這樣做能夠顯著提高知識的召回準確度，從而提升整體效果。你可以參考以下準則來進行多文檔組織與整理：

知識獨立：每個文檔應包含獨特且非冗余的信息。

• 在撰寫文檔內容時，如介紹特性或功能時，檢查是否存在與其他文檔重疊的內容，并盡量減少重復。

• 盡量保證每個文檔都是自成一體的知識單元，能夠獨立提供完整而準確的信息。

知識聚合：盡量將與同一主題相關的所有信息整合到一起。

• 盡量將同一主題的相關知識聚類在一起，避免相關知識過于分散，盡量實現文檔內高內聚。

規范統一：確保同類信息在不同文檔間保持一致性和標準化。

• 確保所有文檔遵循一致的風格和術語標準。

• 制定詳細的風格指南和術語表，并對文檔編寫者進行培訓，確保他們能夠正確應用這些規則。

覆蓋全面：確保文檔的完整性、及時性、準確性。

• 確保知識庫覆蓋問答所需的高頻知識。針對需要高精確度回答的問題，知識無遺漏，如對于某個API的咨詢，需確保包含了所有相關的接口、參數。

• 定期對知識庫進行審核和更新，補充缺失的知識點，淘汰過時的內容。

遵循上述原則，不僅能幫助企業知識庫管理員創建高質量的產品文檔，還能提升用戶的滿意度和體驗。通過系統化的方法來組織和維護文檔，確保了信息的準確性、易用性和完整性，為用戶提供了一個更加可靠的知識資源庫。