點選此處，立即下載通義靈碼！https://tongyi.aliyun.com/lingma/
企業程式碼補全增強使用實踐
通義靈碼提供了企業程式碼補全增強的能力，在開發者使用通義靈碼 IDE 外掛的行間程式碼生成時，可以結合企業上傳的程式碼庫作為上下文進行行間程式碼補全，使程式碼補全更加貼合企業程式碼規範、業務特點。本文將分享如何構建高質量的企業程式碼庫，以及開發者在前端和後端開發場景的使用實踐。
適用版本與支援語言
管理員如何準備高質量企業程式碼庫
為確保程式碼資料的有效處理，我們建議您遵循以下指導原則來準備程式碼庫。這將有助於提升檢索的效率與準確性。
準備指南
-
上傳限制僅適用於原始碼檔案，程式碼庫中應僅上傳實際編寫的原始碼檔案。例如，對於Java應上傳.java檔案，對於C#應上傳.cs檔案，對於JavaScript應上傳.js或.jsx檔案等。
-
請避免上傳以下內容。
- 測試資料與程式碼：請勿上傳測試指令碼、測試用例或任何不包含業務邏輯的測試相關程式碼。
- Mock方法：排除所有由模擬方法和工具生成的程式碼，除非這些程式碼包含對業務邏輯的具體實現。
- 構建產物：
- 前端：排除透過構建工具（如Webpack、Gulp等）生成的檔案，這些檔案通常位於dist或build目錄下。
- 後端：排除編譯生成的DLL檔案及其他所有編譯輸出。
- 註釋要求如下。
- 對希望被檢索到的函式，在函式頭部應新增詳盡的註釋。
- 註釋應提供充分的資訊以區分不同的函式，建議參考註釋模板或根據企業規範進行相應調整。
/**
* 更新指定訂單狀態。
*
* @param orderId 訂單的唯一識別符號。
* @param newStatus 新的訂單狀態。
* @return boolean 表示更新是否成功。
*/
- 函式名稱規範要求。
- 如果函式註釋較為簡單，則函式名稱必須能夠準確描述其功能。
- 使用清晰且具描述性的命名方式，例如：exportOrdersToPDF、updateOrderStatus而不是 func1。
上傳指南
- 打包壓縮檔案：將程式碼檔案打包為.zip、.gz或.tar.gz格式。
- 程式碼包大小限制：每個程式碼包的大小不得超過100 MB。
開發者如何使用企業程式碼生成增強
外掛版本要求
僅適用於 VS Code 1.3.9 及以上版本，以及 JetBrains IDEs 1.3.10 及以上版本。
後端場景使用實踐
- 透過自然語言註釋生成程式碼。
a. 企業程式碼庫程式碼上傳：上傳包含所需功能程式碼的壓縮包至企業程式碼庫，例如雪花演算法的程式碼，並確保目標函式遵循註釋規範，註釋位於函式頭部。更詳細程式碼庫準備指南請參見上述管理員如何準備高質量企業程式碼庫。
/**
* 使用雪花演算法生成唯一序列號
* @param workerId
* @return
*/
public synchronized Long getSnowFlowerId(long workerId){
long id = -1L;
if (workerId < 0 || workerId > snowFlowerProperties.getMaxWorkerId()) {
throw new IllegalArgumentException(
String.valueOf("workerID must gte 0 and lte " + snowFlowerProperties.getMaxWorkerId()));
}
// ... 演算法實現程式碼 ...
return id;
}
b. 輸入註釋：在整合開發環境（IDE）中定位到某Java類內，輸入與期望召回的函式相匹配的註釋。註釋格式可以靈活，但應確保含義的準確性和一致性。
第一種方式
//請透過雪花演算法生成唯一編號的程式碼，返回生成的id
第二種方式
/**
* 使用雪花演算法生成唯一序列號
* @param wId
* @return
*/
註釋說明。
- 註釋長度要求：在編寫程式碼時，註釋應儘量避免過於簡短，建議長度至少15個字元，過短的註釋將無法觸發召回。
- 註釋語義要求：確保註釋的語義準確且有意義，最好包含關鍵詞與返回值說明，以便通義靈碼準確地理解和匹配相應的程式碼。
- 多語言支援：支援中英文註釋，程式碼庫中的註釋和實際編碼時的註釋可以使用不同的語言。
- 引數名稱靈活性：引數名稱可以靈活處理，通義靈碼會根據提供的引數自動調整以匹配召回的程式碼。如下反例。
- //雪花演算法問題：沒有提供足夠的資訊，註釋長度過短。
- //生成唯一序列號問題：沒有使用具體關鍵詞，可能會影響理解和匹配效果。
c. 程式碼生成：首次回車後，靈碼將提供基於註釋生成補全建議；再次回車後，靈碼將根據企業程式碼庫中的程式碼進行補全。
說明：
- 如果您的註釋中包含引數，靈碼將自動調整生成程式碼中的引數，確保命名一致性。
- 如果需要重新整理快取獲取新的補全建議，macOS可以使用⌥(option) P 手動觸發行間補全，Windows可以使用Alt P手動觸發。
- 透過函式簽名生成程式碼。
a. 程式碼庫程式碼上傳：上傳包含所需功能程式碼的壓縮包至企業程式碼庫，並確保這些函式具有清晰且獨特的標識，以便於檢索和識別。更詳細程式碼庫準備指南請參見上述管理員如何準備高質量企業程式碼庫。
b. 輸入函式簽名：在整合開發環境（IDE）中定位到某Java類內，鍵入目標函式的簽名部分。引數名稱可以靈活處理，通義靈碼會根據提供的引數自動調整以匹配召回的程式碼。
public List<Object> nextList(String name, int size)
函式簽名說明。
- 函式名稱：使用較為清晰的函式名稱，需要具備一定語義作為相似性依據。
- 引數和返回值：型別和順序需要與目標函式保持一致，但引數名稱可以靈活處理，通義靈碼會根據提供的引數自動調整以匹配召回的程式碼。如下反例。
- public List
- public List
nextList(int orderId)// 問題：引數型別和返回值型別，與目標函式不匹配
c. 程式碼補全：首次回車後，靈碼將提供程式碼補全建議；再次回車後，靈碼將根據企業程式碼庫中的程式碼進行自動補全。
說明：
- 靈碼將根據您提供的引數名，自動調整生成程式碼中的引數名，確保命名一致性。
- 如果需要重新整理快取獲取新的補全建議，macOS可以使用⌥(option) P 手動觸發行間補全，Windows可以使用Alt P手動觸發。
前端場景使用實踐
- 透過標籤補全前端自研元件程式碼。
a. 程式碼庫程式碼上傳：在開始之前，您需要確保所有必要的前端元件程式碼已經上傳到企業程式碼庫中。如下是React框架示例。
<LTable
isReady={isReady}
formInitialValues={formInitialValues}
rowKey="key"
tableRef={tableRef}
toolbarLeft={
<Button type="primary">新增</Button>
}
formItems={formItems}
formRef={formRef}
columns={columns}
request={async (params, requestType) => {
const res: Record<string, any> = await apiGetUserList(params);
return {
data: res.data,
total: res.total,
};
}}
/>
b. 編寫元件程式碼： 在您的IDE中開啟相應的.jsx檔案，並開始編寫程式碼。輸入基礎HTML標籤或自定義元件標籤，例如
c. 程式碼自動補全： 當您輸入的程式碼達到一定長度，並且能夠與企業元件庫中的程式碼匹配時，IDE將自動觸發程式碼補全功能，為您生成完整的元件程式碼。您也可以透過回車，主動觸發程式碼補全。
重要：請在完整的元件標籤內觸發您的補全。
- 透過自然語言註釋生成程式碼。
a. 程式碼庫程式碼上傳：上傳包含所需功能程式碼的壓縮包至企業程式碼庫，並確保每個函式都遵循註釋規範，註釋位於函式頭部。 更詳細程式碼庫準備指南見管理員如何準備高質量企業程式碼庫章節。如下是JavaScript示例。
/**
* 根據報錯資訊生成，以id為鍵值的物件
* @param {Array<validator,Result>} results
* @return {Record<string,string>}
*/
function getErrObj(results) {
// ... 函式實現程式碼 ...
}
b. 輸入註釋：在IDE中，在JavaScript檔案內輸入特定的註釋內容，如下示例。
//根據報錯資訊生成以 id 為鍵值的物件
註釋說明。
- 註釋長度要求：在編寫程式碼時，註釋應儘量避免過於簡短，建議長度至少15個字元，過短的註釋將無法觸發召回。
- 註釋語義要求：確保註釋的語義準確且有意義，最好包含關鍵詞與返回值說明，以便通義靈碼準確地理解和匹配相應的程式碼。
- 多語言支援：支援中英文註釋，程式碼庫中的註釋和實際編碼時的註釋可以使用不同的語言。
- 引數名稱靈活性：引數名稱可以靈活處理，通義靈碼會根據提供的引數自動調整以匹配召回的程式碼。
c. 程式碼生成：首次回車後，靈碼將提供基於註釋生成補全建議；再次回車後，靈碼將根據企業程式碼庫中的程式碼進行補全。
說明：
- 如果您的註釋中包含引數，靈碼將自動調整生成程式碼中的引數名，確保命名一致性。
- 如果需要重新整理快取獲取新的補全建議，macOS可以使用⌥(option) P 手動觸發行間補全，Windows可以使用Alt P手動觸發。
常見問題：在重新安裝外掛後，即便重啟IDE或重新登入，仍無法成功召回知識庫中的程式碼。
解決方案：
- 在macOS系統中，請執行以下命令以重啟程序並清除快取。
ps -ef|grep lingma|grep start|awk '{print $2}'|xargs -I {} kill -9 {}
- 如果是Windows系統，請在程序管理器中結束Lingma程序。
企業知識庫問答使用實踐
知識庫問答增強：知識庫構建與管理指南
通義靈碼能夠結合企業知識庫的私域資料，生成貼合企業特點的回答。充分發揮檢索增強技術的優勢，構建高質量的企業知識資料以及合理的知識庫許可權管理是必不可少的。本文將為您詳細介紹如何構造與管理一個高質量的企業知識庫。
前提條件
- 適用版本：通義靈碼企業標準版、通義靈碼企業專屬版。
- 適用人員：通義靈碼管理員、組織內全域性管理員（專屬版）。
場景介紹
通義靈碼雖然具備廣泛的通用知識，但缺乏企業獨有的專業知識和資料。透過引入企業知識庫，可以幫助模型更精準地理解私域知識，以便生成更加貼合企業特色的個性化回答。通義靈碼能夠基於知識庫進行自由問答，程式碼最佳化與生成，廣泛應用於企業規範檢查、技術支援等多個場景。
例如：
- 智慧自由問答場景：企業技術新人入職問答、企業安全合規規範問答、產品運維故障排查諮詢、企業內部平臺、API使用問答等。
- 程式碼最佳化與生成場景：根據企業編碼規範，確保程式碼風格的一致性與規範性；根據安全規範文件檢查程式碼漏洞，並提出修復建議等。
為了最大程度發揮生成的效果，需要從兩個方面進行實踐。一方面是構建高質量的知識庫，確保知識資料的質量；另一方面是清晰的知識庫許可權分配，確保知識庫的可見範圍符合預期。為此知識庫管理員需要：
- 提供 AI 友好的、高質量的知識資料，如文件或程式碼等，陳舊或不準確的資訊不僅無法帶來增益，反而可能會誤導模型，影響回答的準確性；
- 構建一個結構合理、許可權隔離的知識庫。這不僅保障了資料的隱私和隔離，還保障了知識庫的易管理性和可維護性。許可權管理混亂的知識庫可能會引發資料安全等問題。
構建高質量知識庫
通義靈碼的企業知識庫問答功能，目前已支援透過文件上傳的形式，將其轉化為檢索增強的知識資料，本章節將重點介紹文件類知識資料的準備原則和方法。如需瞭解程式碼類請參見。
文件格式要求
- 格式：支援PDF、CSV、DOCX、TXT、Markdown格式，優先推薦使用Markdown格式。
- 大小：每次最多上傳10個 檔案，單檔案大小不超過 10MB。
單個文件規範
單個文件需要從名稱、標題、格式、內容方面檢查是否符合文件規範矮的
詳細說明與示例如下：
文件型別與命名
- 型別：推薦使用Markdown格式。相較於Word和PDF，我們推薦使用Markdown格式以獲得更佳的文件處理效果。
- 編碼：推薦使用UTF-8編碼，以確保字元相容性最佳。
- 文件命名：文件名用詞簡潔明瞭，不同命名之間應有明顯差異，便於模型理解。避免使用含義不明的英文縮寫、數字或符號。
文件結構
- 層級結構：需採用多級標題來組織文件內容，避免將資訊堆砌在單一段落。特別是對於專有名詞的釋義，每個專有名詞建議單獨成行。
- 各級標題：各層級標題含義清晰用詞簡潔明瞭，不同標題之間有明顯差異。避免使用含義不明的英文縮寫、數字或符號。避免羅列文章關鍵詞，會對模型造成干擾。
反例
《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中的“-”或“*”）和有意義的縮排來分點闡述，可以在一定程度上輔助模型更準確地理解。
特殊內容與媒體處理
當文件段落中出現圖片、表格時，應該對應注意以下幾點：
-
文件中關於表格的處理：
- 表格格式要求：表格的第一行應為表頭，不要將表格名稱作為表格的第一行內容。
- 表格結構說明：對於表格結構沒有特別的要求。可以根據內容的需要自由設計列和行。
- 保持樣式簡潔：建議去除所有不必要的格式，如背景色、字型樣式等。表格線條應保持清晰，使用預設的線條樣式。
- 補充說明：
- 企業標準版，由於表格處理能力仍在持續最佳化，建議在文件中儘量減少表格，或考慮比如文字列表等替代方式來展示表格資料。
- 企業專屬版與私有化版本，通義靈碼已經具備了更高階的表格處理能力，可確保表格資料的準確性。
-
文件中關於圖片的處理：
- 優先使用文字：儘可能地使用文字表達資訊，如果影像中的文字比較少且包含重要資訊，建議將資訊轉錄成文字的形式。
- 新增圖示說明：確保所有核心圖都有圖示說明（即圖解或說明），圖示說明應清晰地解釋圖中的主題。
-
其他通用注意事項：
- 特殊字元：避免包含表情包的特殊字元，以免造成解析問題。
- 頁首頁尾、水印、批註：避免包含批註、頁首、頁尾或水印，以免造成不必要的干擾。
- 文件背景：文件每頁儘可能無背景，複雜背景容易造成干擾。
- 統一文字方向：確保文件中所有文字的方向一致。
- 音影片：避免包含音影片等多媒體內容。
不同型別文件的處理準則
-
Markdown：建議優先使用Markdown格式。
-
Word：
- 使用更新格式：優先採用2007版或之後的Word格式。
- 使用全域性樣式：統一使用全域性標題和段落樣式。
- 避免字元樣式：不要使用字元樣式，如特殊字型格式、邊框和底紋。
- 使用段落樣式：應使用段落樣式來保持文件格式的一致性。
-
PDF：
-
避免使用圖片：不要直接將影像轉換成PDF檔案。應該將影像中的重要資訊轉錄成文字，並按照本文中的文件規範要求進行組織。
-
不包含嵌入壓縮檔案： 請確保檔案中不包含嵌入的壓縮檔案。
-
保持文件單欄佈局：避免雙欄並排形式，以確保內容被正確解析。
-
CSV：
- 避免使用圖片：不插入圖片，以確保文件的文字可搜尋性。
- 不嵌入壓縮檔案：不要在文件中嵌入壓縮檔案。
- 表頭作為第一行：在表格中，將表頭放在第一行，不要將表格名稱作為表格的第一行內容。
特別說明： - 推薦用法：儲存FAQ（常見問題解答）中的問答對。FAQ的問題表述清晰明確，答案簡潔易懂，使用使用者熟悉的術語，突出關鍵詞，以提高檢索召回準確度。例如：矮的 (1)
- 不推薦：在CSV中上傳複雜的關係型資料表。可能會導致資料處理時間超長，導致資料處理失敗。
多文件規範
在編寫文件時，確保多個文件之間做到知識獨立、知識聚合、規範統一以及覆蓋全面，這樣做能夠顯著提高知識的召回準確度，從而提升整體效果。你可以參考以下準則來進行多文件組織與整理：
知識獨立：每個文件應包含獨特且非冗餘的資訊。
- 在撰寫文件內容時，如介紹特性或功能時，檢查是否存在與其他文件重疊的內容，並儘量減少重複。
- 儘量保證每個文件都是自成一體的知識單元，能夠獨立提供完整而準確的資訊。
知識聚合：儘量將與同一主題相關的所有資訊整合到一起。
- 儘量將同一主題的相關知識聚類在一起，避免相關知識過於分散，儘量實現文件內高內聚。
規範統一：確保同類資訊在不同文件間保持一致性和標準化。
- 確保所有文件遵循一致的風格和術語標準。
- 制定詳細的風格指南和術語表，並對文件編寫者進行培訓，確保他們能夠正確應用這些規則。
覆蓋全面：確保文件的完整性、及時性、準確性。
- 確保知識庫覆蓋問答所需的高頻知識。針對需要高精確度回答的問題，知識無遺漏，如對於某個API的諮詢，需確保包含了所有相關的介面、引數。
- 定期對知識庫進行稽核和更新，補充缺失的知識點，淘汰過時的內容。
遵循上述原則，不僅能幫助企業知識庫管理員建立高質量的產品文件，還能提升使用者的滿意度和體驗。透過系統化的方法來組織和維護文件，確保了資訊的準確性、易用性和完整性，為使用者提供了一個更加可靠的知識資源庫。
知識庫許可權管理
知識庫的劃分，通常是根據內容主題和可見成員物件來確定。
一方面，可以建立企業內所有已授權開發者可見的通用型知識庫，用於共享企業內的規範性文件和指南，如企業程式碼規範、安全標準等；另一方面，也可以為特定團隊或部門建立垂直型知識庫，如具體業務的開發文件、培訓材料和運維指南，或面向企業新人的技術指南等。
新建知識庫
在通義靈碼的企業管理臺，選擇知識管理模組，單擊新建知識庫，選擇智慧問答場景，可見範圍選擇私有-僅知識庫成員。
說明：可見範圍選擇公開則企業內所有已授權使用通義靈碼的開發者均對知識庫可見，選擇私有則可以自定義可見成員的範圍，推薦選擇私有。
管理知識庫可見成員
在通義靈碼的企業管理臺，選擇知識管理模組，選擇需要操作的知識庫，在知識庫的可見成員管理列表中選擇新增開發者或移除。如需瞭解知識庫更多操作請參見。
說明：在管理知識庫的可見成員時，需確保每位成員僅訪問與其職責和工作相關的知識內容。這不僅保護了資料隔離和隱私安全，還減少了不必要的資訊干擾，提升了使用者的專注度和知識檢索的效率。
