為 Modernize CLI 設定自帶模型或金鑰(BYOM/BYOK)

自帶模型(BYOM)和自帶金鑰(BYOK),讓你設定 Modernize CLI 使用客戶提供的模型,而非 GitHub 主機的模型。 當提供者需要時,你提供模型提供者、端點、模型識別碼,以及 API 金鑰。

當您的組織需要經過自訂訓練的模型,或需要透過其控制的基礎設施路由模型請求時,請使用 BYOM/BYOK。 你要負責你所設定的模型供應商的安全與合規狀態。

Warning

在 BYOM/BYOK 模式下,你的程式碼和上下文會被傳送到已設定的提供者端點。 確認該提供者符合貴組織的安全、合規及資料駐留要求。

Prerequisites

了解組態

請設定以下環境變數以啟用 BYOM/BYOK:

Variable Required Description
COPILOT_OFFLINE Yes 啟用 BYOM/BYOK 模式。 設定為 true 或 1。 此設定繞過 GitHub 認證與 GitHub 模型發現。
COPILOT_PROVIDER_BASE_URL Yes 指定模型提供者的基礎網址。
COPILOT_MODEL Yes 指定提供者接收的模型識別碼。
COPILOT_PROVIDER_API_KEY No 指定提供者 API 金鑰。 如果供應商不要求驗證,就省略它。
COPILOT_PROVIDER_TYPE No 指定 openai、 azure、 或 anthropic。 預設值為 openai。
COPILOT_PROVIDER_WIRE_API No 指定 completions 或 responses 為 OpenAI 相容的提供者。 預設值為 completions。

Important

COPILOT_OFFLINE繞過 GitHub 認證與 GitHub 模型探索。 它不是防火牆,也不保證網路隔離。 Modernize CLI 仍可連接您的模型提供者,以及其現代化工作流程所需的其他服務。

配置模型提供者

在執行 Modernize CLI 的終端機會話中設定變數。

$env:COPILOT_OFFLINE = "true"
$env:COPILOT_PROVIDER_TYPE = "<openai|azure|anthropic>"
$env:COPILOT_PROVIDER_BASE_URL = "<provider-base-url>"
$env:COPILOT_MODEL = "<model-name>"
$env:COPILOT_PROVIDER_API_KEY = "<provider-api-key>"

如果服務提供者不要求認證,請省略 COPILOT_PROVIDER_API_KEY。

使用與 OpenAI 相容的供應商

對於 OpenAI 相容的提供者,請設 COPILOT_PROVIDER_TYPE 為 openai。 當提供者要求時,請在基礎網址中包含 API 版本路徑。

$env:COPILOT_OFFLINE = "true"
$env:COPILOT_PROVIDER_TYPE = "openai"
$env:COPILOT_PROVIDER_BASE_URL = "https://<provider-host>/v1"
$env:COPILOT_MODEL = "<model-name>"
$env:COPILOT_PROVIDER_API_KEY = "<provider-api-key>"

使用原生的 Azure OpenAI 端點

對於 Azure 部署,設定COPILOT_PROVIDER_TYPE為 azure。 使用部署名稱作為模型值。

$env:COPILOT_OFFLINE = "true"
$env:COPILOT_PROVIDER_TYPE = "azure"
$env:COPILOT_PROVIDER_BASE_URL = "https://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>"
$env:COPILOT_MODEL = "<deployment-name>"
$env:COPILOT_PROVIDER_API_KEY = "<azure-openai-api-key>"

使用 Microsoft Foundry

對於 Microsoft Foundry OpenAI 相容端點,設定COPILOT_PROVIDER_TYPE為openai並使用/openai/v1/基本網址。 設定 COPILOT_PROVIDER_WIRE_API 為部署模型支援的 API。 使用 responses 來將需要回應 API 的工具呼叫工作流程和模型現代化。 對於僅支援聊天完成 API 的部署,請使用 completions。

$env:COPILOT_OFFLINE = "true"
$env:COPILOT_PROVIDER_TYPE = "openai"
$env:COPILOT_PROVIDER_BASE_URL = "https://<resource-name>.openai.azure.com/openai/v1/"
$env:COPILOT_PROVIDER_WIRE_API = "responses"
$env:COPILOT_MODEL = "<deployment-name>"
$env:COPILOT_PROVIDER_API_KEY = "<foundry-api-key>"

欲了解更多選擇 wire API 的資訊,請參閱 BYOK(自帶金鑰)。

使用 Anthropic

對於 Anthropic,設定COPILOT_PROVIDER_TYPE為 anthropic。

$env:COPILOT_OFFLINE = "true"
$env:COPILOT_PROVIDER_TYPE = "anthropic"
$env:COPILOT_PROVIDER_BASE_URL = "https://api.anthropic.com"
$env:COPILOT_MODEL = "<model-name>"
$env:COPILOT_PROVIDER_API_KEY = "<anthropic-api-key>"

驗證設定

列出 Modernize CLI 可辨識的模型:

modernize help models

在 BYOM/BYOK 模式下,指令會列出一個模型。 型號名稱和 ID 應該是相符 COPILOT_MODEL的。 此結果確認 CLI 已識別設定,但不會向提供者發送請求。

為了驗證提供者是否回應,請執行現代化作業:

modernize plan create "Create a modernization plan for this application" --source .

指令使用透過 BYOM/BYOK 環境變數選擇的模型。 若要覆寫此指令的模型,請使用選項 --model 。 欲了解更多資訊,請參閱 了解模型選擇優先順序。

若操作成功完成,已設定的提供者即可完成請求。

了解模型選擇優先順序

啟用 COPILOT_OFFLINE時,Modernize CLI 會依照以下順序選擇模型:

  1. --model 指令選項。
  2. COPILOT_MODEL 環境變數。

MODERNIZE_MODEL環境變數和持久模型設定在離線模式下不會覆寫COPILOT_MODEL。

Note

--model 這個選項會在離線模式下覆寫 COPILOT_MODEL。 指定的型號識別碼仍會傳送給已設定的自訂提供者。 該指令只有在該提供者接受模型識別碼時才會成功。

回到 GitHub Copilot 模型頁面

移除 BYOM/BYOK 環境變數,然後重新列出可用模型。

Remove-Item Env:COPILOT_OFFLINE,
    Env:COPILOT_PROVIDER_TYPE,
    Env:COPILOT_PROVIDER_BASE_URL,
    Env:COPILOT_PROVIDER_WIRE_API,
    Env:COPILOT_PROVIDER_API_KEY,
    Env:COPILOT_MODEL,
    Env:MODERNIZE_MODEL -ErrorAction SilentlyContinue

modernize help models

指令現在會列出可用的 GitHub Copilot 模型,而非單一客戶配置的模型。 此結果證實 Modernize CLI 已回歸 GitHub 認證與模型探索。

Warning

當你回到 GitHub 託管的模型時,你的程式碼和上下文會被傳送到 GitHub 服務。

網路受限環境中的限制

BYOM/BYOK 移除了 Modernize CLI 對 GitHub 認證與模型發現的依賴,但其他網路依賴仍然存在:

  • 配置好的模型提供者必須可連線。
  • AppCAT 和所需的 .NET SDK 必須先安裝,才能執行評估。 否則,CLI 會嘗試下載它們。
  • CVE 評估會查詢 GitHub Advisory API。 如果無法存取 API,CVE 結果就是空白。
  • 成本估算會查詢 Azure 零售價格 API。
  • 遠端 Git 儲存庫必須可存取,除非原始碼在本地可用。
  • GitHub API 與雲端代理操作都需要 GitHub 認證。 當 BYOM/BYOK 模式繞過該認證時,委派到雲端的操作無法運作。

不支援完整的網路隔離、管理身份或無鑰匙認證,以及多個供應商的命名設定檔。

故障排除 BYOM/BYOK

OfflineModeMissingConfig

同時設定 COPILOT_PROVIDER_BASE_URL 和 COPILOT_MODEL。 你可以針對個別指令傳遞 --model,但必須有 COPILOT_MODEL,modernize help models 才能列出自訂模型。

僅顯示一個模型

BYOM/BYOK 模式支援一個模型。 CLI 從 COPILOT_MODEL建立該條目。 移除 BYOM/BYOK 環境變數,才能回到 GitHub 模型探索。

提供者認證失敗

確認 COPILOT_PROVIDER_API_KEY 有效且能存取已設定的模型。 如果提供者不需要認證,就移除變數。

GitHub API 或雲端代理操作失敗

BYOM/BYOK 模式會繞過 GitHub 認證。 在執行需要 GitHub API 或雲端代理的操作前,先移除 BYOM/BYOK 環境變數。