建立應用程式現代化評估

Migration Center 應用程式翻新評估 (codmod) 是一項 AI 輔助工具，可自動評估應用程式翻新作業。本頁面概述安裝、使用 codmod 工具及排解相關問題的步驟。

關於應用程式翻新評估

一般現代化評估程序需要幾週時間，且需要大量專業知識。codmod 工具會自動執行這項程序，大幅縮短所需時間至幾小時。

這項工具旨在提供實證資訊，說明目前應用程式的架構、功能，以及可能減緩雲端轉換速度的潛在阻礙。

這項工具適用於下列角色：

  • IT 架構師
  • 決策者
  • 應用程式擁有者

codmod 工具旨在加快應用程式轉換速度，清楚呈現所需變更，以及將應用程式轉換為 Google Cloud的好處。codmod 是可攜式 CLI 工具，使用 Gemini 分析原始碼，並根據 Google Cloud 最佳做法提供建議。

事前準備

codmod 工具需要下列先決條件：

  • Linux 或 Windows (10 以上版本) 工作站。
  • 可存取已啟用 Vertex AI API 的 Google Cloud 專案。
  • 在工作站安裝 gcloud CLI。詳情請參閱「安裝 gcloud CLI」。

定價

使用 Gemini 評估程式碼的費用主要取決於程式碼集的大小，並以權杖為單位計算。下表列出根據程式碼行數和所選模型預估的費用：

程式碼集 程式碼行數 (LOC) 預估費用
adaptive 2.5-flash 2.5-pro 3.5-flash 3.8-flash (預設)
Spring Petclinic ~6,500 $20 美元 $3 美元 $20 美元 $3 美元 $9 美元
James 專案 ~1,000,000 $40 美元 $30 美元 $200 $200 $200
Elasticsearch ~5,000,000 $200 $200 $900 $500 美元 $500 美元

這些值可能高估了，因為未考量下列因素可能節省的費用：

  • 短查詢的價格較低。
  • 隱含快取價格調降。
  • 承諾使用折扣 (CUD)。

這些參數的成本預計只占總成本的一小部分，尤其是大型程式碼集。詳情請參閱「Gemini API 定價」。

其他資訊

這項工具運用 Vertex AI API 的進階程式碼理解和分析功能，如要進一步瞭解可用的模型及其功能，請參閱 Vertex AI API 說明文件中的 Google 模型。

為維持最佳效能和成本效益，codmod 的程式碼集大小限制約為 600 萬行程式碼。如果程式碼集超過這項限制，建議您將其分成較小、易於管理的部分，再進行分析。分析較小的部分也有助於進行更集中的評估，並可能縮短整體處理時間。

設定 codmod

本節提供 codmod 工具的安裝和驗證操作說明。

安裝「codmod」

Windows

在 Windows PowerShell 中執行下列指令，下載最新版本的 codmod：

$version=curl.exe -s https://codmod-release.storage.googleapis.com/latest
curl.exe -O "https://codmod-release.storage.googleapis.com/${version}/windows/amd64/codmod.exe"

Linux

執行下列指令，下載最新版本的 codmod：

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/linux/amd64/codmod"
chmod +x codmod

如要使用 codmod 指令，請將可執行檔新增至路徑，或建立別名。

驗證 Google Cloud

如要使用 codmod 工具，您需要 Google Cloud 專案。

  1. 請在控制台中，或使用 CLI 確認專案已啟用 Vertex AI API：

    gcloud services enable aiplatform.googleapis.com --project <project-id>

  2. 確認您具備專案的 roles/aiplatform.user 角色或類似角色。

  3. 執行下列指令進行驗證：

    gcloud auth application-default login

或者，您也可以使用服務帳戶，並設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數。詳情請參閱「應用程式預設憑證的運作方式」。

管理 codmod 設定

以下各節說明如何使用 codmod config 指令設定 codmod。

列出所有設定

如要查看所有目前的設定屬性及其值，請執行下列指令：

codmod config list

設定旗標的預設值

如要設定屬性的預設值，請使用 set 指令。例如，如要設定預設專案 ID，請執行：

codmod config set project "PROJECT_ID"

將 PROJECT_ID 替換為 Google Cloud 專案 ID。

如要設定預設區域，請執行下列指令：

codmod config set region "REGION"

將 REGION 替換為 Google Cloud 區域。請參閱可用區域清單。如果不確定要使用哪個區域，請使用 us-central1。

取得特定值

如要查看單一屬性的值，請使用 get 指令。舉例來說，如要取得設定的專案 ID，請執行下列指令：

codmod config get project

取消設定預設值

如要移除設定的預設值，並還原為工具的原始預設設定，請使用 unset 指令。例如，如要移除預設專案 ID，請執行下列指令：

codmod config unset project

建立codmod評估報表

以下各節說明如何建立預設評估，以及如何根據需求自訂評估。

建立預設報表

如要建立評估報表，請使用下列旗標執行 codmod 工具：

codmod create -c "CODEBASE" -o "OUTPUT"

更改下列內容：

  • CODEBASE：指定包含要分析的原始碼的目錄，可以指定多次。
  • OUTPUT：指定產生的報表儲存路徑。報告格式為 HTML。

您可以使用 -p "PROJECT_ID" 和 -r "REGION" 旗標，分別覆寫預設專案和區域。

您也可以指定下列選用旗標：

  • --modelset [2.5-flash|2.5-pro|3.5-flash|3.8-flash|adaptive]：指定要使用的 Gemini 模型。預設值為 3.8-flash。與2.5-pro相比，Adaptive 模式可大幅降低成本，但報表品質可能較低。
  • --format <html|markdown|odt|json>：生成報表使用的格式。預設為 HTML。
  • --allow-large-codebase：根據預設，如果程式碼集超過 100 萬行，codmod 會先要求確認再分析，避免產生高昂費用。這個選項可做為非互動式確認。您也可以執行 codmod config set allow_large_codebase true，預設啟用這項功能。
  • --improve-fidelity：設定後，codmod 會依序產生區段，而非平行產生。這可提升最終報表不同部分的一致性，但需要較長的執行時間。
  • --force-include <strings>、--force-exclude <strings>：codmod 預設會掃描常見的副檔名，包括 Java、.NET 和 Python。使用這些旗標可納入或排除副檔名。引數必須是採用 RE2 語法的規則運算式。
  • --experiments：指定 --experiments=enable_pdf,enable_images，支援 codmod 中的 PDF 和圖片。
  • --context <string>：您想提供的任何其他專案相關背景資訊。生成報表時，這項工具會將這項背景資訊納入考量。
  • --context-file <path>：與 --context 相同，但情境資訊是由指定檔案提供。
  • --supporting-documents <path>：指定程式碼集相關支援文件的目錄。您可以使用 --context 或 --context-file 旗標提供的內容，參照這個目錄中的檔案，以便納入分析。支援的格式包括文字、PDF 和圖片 (PNG、JPG、JPEG)。

建立完整報告

如需完整分析，請使用 create full 指令建立報表：

codmod create full -c "~/mycodebase/" -o "report.html"

建立著重於資料層的報表

如果需要更深入地關注資料層，可以建立一份著重於這個領域的報表：

codmod create data-layer -c "CODEBASE" -o "OUTPUT"

建立特定轉型意圖的報表

如要將報表著重於特定翻新意圖，可以使用下列其中一種支援的意圖：

  • Microsoft 工作負載轉換 (MICROSOFT_MODERNIZATION)：適用於在 Microsoft OS 上執行的應用程式，評估重點在於轉換作業，將以 .NET 為基礎的架構現代化，以便使用最新版本，並減少對 Microsoft 授權的依賴。
  • 雲端對雲端工作負載轉換 (CLOUD_TO_CLOUD)：適用於在其他超大規模基礎架構上執行的應用程式。評估作業會著重於轉換應用程式的建議變更，例如將其他雲端供應商服務對應至Google Cloud 服務。
  • 舊版 Java 轉換 (JAVA_LEGACY_TO_MODERN)：適用於執行 Java 8 或類似版本的應用程式，評估作業會著重於找出升級依附元件，以及程式碼中受變更影響的部分，以便升級至 Java 21 (目前的 LTS)。
  • 舊版 Java WILDFLY 轉換 (WILDFLY_LEGACY_TO_MODERN)：適用於在 WildFly 應用程式伺服器 (最新版本之前) 上執行的 Java EE/Jakarta EE 程式碼集。評估作業會著重於找出升級依附元件，以及程式碼中受 WildFly 應用程式伺服器版本升級影響的部分，包括因應 API 差異和相容性而需進行的變更。
  • 將 C/C++ 應用程式遷移至 Arm 架構 (ARM_MIGRATION)：搭配 C/C++ 應用程式使用，評估是否準備就緒，以及從 x86 架構遷移至 Arm 架構 (例如 Google Cloud Axion C4A VM) 所需的工作。評估重點在於找出潛在的程式碼可攜性問題、架構專屬依附元件、建構系統修改，以及從Google Cloud 或其他 CSP (例如 AWS 的 Graviton 執行個體) 成功轉換至 Arm 所需的測試考量。

如要建立意圖導向報表，請使用 --intent 旗標：

codmod create -c "CODEBASE" -o "OUTPUT" --intent "INTENT"

建立包含其他區段的報表

這項工具支援納入預設不包含的其他區段，以降低成本。支援下列區段：

  • files：專案資料夾的結構化階層檢視畫面，以及各資料夾內容的說明，協助您瞭解專案檔案。
  • classes：程式碼類別目錄，其中包含各類別的資訊，以及與其他類別的依附關係。支援的語言為 Java 和 C#。

如要建立其他區段，請使用 --optional-sections 旗標：

codmod create -c "CODEBASE" -o "OUTPUT" --optional-sections "SECTIONS"

將 SECTIONS 替換為以半形逗號分隔的值清單。

建立自訂報表

如要探索特定自訂主題，可以使用下列指令，根據提供的內容建立自訂報表：

codmod create custom -c "CODEBASE" -o "OUTPUT" --context "CONTEXT"

根據預設，系統會使用 LLM 擴充提供的背景資訊並加以調整，確保生成連貫的章節。如要停用這項行為，請指定 --improve-context=false。

其他旗標：

  • --from-template <path>：指定範本檔案，以文字或 PDF 檔案格式定義文件結構。codmod 會偵測結構，並要求核准，才能繼續產生報表。
  • --skip-template-approval：使用 --from-template 旗標時，略過核准要求。

修改現有報表

您可以在報表中建立新區段，或根據特定區段修改現有區段。舉例來說，您可能想著重於系統架構的特定層面，或特定類型的安全漏洞。

修改報表的指令需要下列旗標：

  • --context 和 --context-file 擇一：指定修改要求。
  • --from-report：指定現有報表檔案的路徑。
  • --from-section：要用來做為新章節基礎的章節名稱 (例如「Overview」或「Architecture」)。

如要顯示特定報表中所有可用的區段，請執行下列指令：

codmod list-sections --from-report "REPORT"

修改報表部分

執行下列指令，修改現有區段：

codmod revise section -c "CODEBASE" --from-report "REPORT" \
  -o "REVISED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"

建立新的報表區段

使用下列指令建立新區段：

codmod create section -c "CODEBASE" --from-report "REPORT" \
  -o "REGENERATED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"
  • create section 指令中的 from-section 旗標為選用。
  • 根據預設，系統會使用 LLM 擴充提供的背景資訊，並加以調整，確保生成連貫的章節。如要停用這項行為，請指定 --improve-context=false。

注意事項：

  • create section 和 revise section 僅支援 html 報表格式。
  • create section、revise section、list-sections 預期 --from-report 旗標會指向 HTML 格式的報表。

估算評估費用

codmod 工具可讓您計算建立報表的大致費用，協助您瞭解使用這項工具的成本。如要查看費用預估，請執行下列指令：

codmod create --estimate-cost -c "CODEBASE"

create section 和 create custom 指令不支援費用估算功能。

設定詳細程度

codmod 詳細程度是使用 --verbosity LEVEL 旗標設定。記錄的詳細程度為下列其中一項：debug、info、warn、error 或 none。預設值為 warn。

檢查並更新 codmod CLI 版本

codmod CLI 可自動檢查是否有新版本。

自動檢查

CLI 每 24 小時會輪詢 Cloud Storage bucket，確認是否有新版 codmod 發布。如果找到較新版本，終端機就會顯示通知訊息。訊息中會包含新版本號碼和下載更新的連結。 這項程序可確保您能及時取得最新功能、改善項目和錯誤修正。

停用版本檢查

如要停用自動版本檢查，請使用 config set 指令：

codmod config set disable_version_check true

如要重新啟用版本檢查，請將值改回 false：

codmod config set disable_version_check false

如要查看這項設定和其他設定的目前狀態，請執行下列指令：

codmod config list

指令列自動完成

codmod CLI 工具支援 Bash、Zsh、Fish 和 PowerShell 的殼層指令列自動完成功能。這項功能可讓您快速輸入指令、旗標和引數，只要按下 Tab 鍵，即可查看及選取可用選項。

自動完成功能有以下優點：

  • 自動完成指令和旗標：開始輸入 codmod 指令或旗標，然後按下 Tab 鍵，即可查看可能的自動完成選項。
  • 探索選項：查看特定旗標的有效值。例如：
    • codmod create --modelset [TAB] 會建議可用的模型組合 (例如 2.0-flash、2.5-pro)。
    • codmod create --format [TAB] 會建議輸出格式 (例如 html、json、markdown)。
    • codmod create --intent [TAB] 會建議預先定義的意圖。
  • 情境感知建議：根據指令提供補全建議。例如：
    • codmod config set [TAB] 會建議您可以設定的可用配置鍵。
    • codmod config get [TAB] 會建議您可以取得的可用設定鍵。
    • 只有在旗標或引數預期檔案或目錄路徑時，才會提供檔案路徑自動完成功能 (例如 --codebase、--output-path)。其他旗標 (例如 --project) 不再建議檔案名稱。

啟用殼層完成功能

啟用殼層自動完成功能之前，請先將可執行檔新增至路徑，或建立別名，確認 codmod 指令可正常運作。

如要載入殼層的自動完成功能，請執行適當的指令。操作說明會因殼層而異。使用 help 指令取得特定操作說明：

# For Bash
codmod completion bash --help

# For Zsh
codmod completion zsh --help

# For Fish
codmod completion fish --help

# For PowerShell
codmod completion powershell --help

舉例來說，如要在 Linux 上載入 Bash 自動完成功能，可以在 ~/.bashrc 中加入以下內容：

source <(codmod completion bash)

請務必重新啟動殼層或設定檔來源 (例如 source ~/.bashrc)，變更才會生效。

疑難排解

  • 權限遭拒：如果遇到「權限遭拒」錯誤，請務必執行 chmod +x codmod 指令，將執行權限授予 codmod 二進位檔。
  • CLI 似乎停止運作：分析可能需要很長時間，但您通常可以在 CLI 的進度列中查看進度。如果 15 分鐘後進度列仍停留在 0%，請確認相關模型的配額是否充足。根據預設，codmod 會使用 gemini-3.8-flash 模型。不過，由於不同的模型集會針對不同用途使用不同的模型，因此這項設定可能會有所變動。

  • 回報錯誤：如果發生需要調查的錯誤，請收集偵錯資訊，協助我們的開發團隊。記錄檔提供疑難排解的重要詳細資料。執行下列指令收集記錄，然後將產生的封存檔壓縮並傳送給 codmod-feedback-external@google.com 團隊。

    codmod collect-logs -o "codmod_logs.zip"

開放原始碼授權

如要下載最新版本 codmod 依附元件的開放原始碼聲明，請執行下列指令：

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/THIRD_PARTY_NOTICES.txt"

取得支援及提供意見

為提升這項產品的品質，我們會收集偽匿名使用資料。我們會依據《Google Cloud 隱私權聲明》處理這類資料。您隨時可以執行下列指令來變更偏好設定：

codmod config set disable_usage_reporting true

您可以透過下列方式取得支援及提供意見：

  • 如需 codmod 支援，請按一下產生的 HTML 報表中的「Support」(支援) 按鈕，或傳送電子郵件至 codmod-feedback-external@google.com。
  • 如要提供 codmod 的意見回饋，請按一下產生的 HTML 報表中的「Feedback」(意見回饋) 按鈕。