Connect GitHub Copilot CLI 到 Windows Server 推論端點

GitHub Copilot CLI 是一款 AI 編碼代理程式，能將支援的 Windows 用戶端的模型請求傳送到託管於 Windows Server 上的 OpenAI 相容推論端點。 此配置允許您從終端機使用組織託管模型，而 Windows Server 則集中管理模型主機與運算。

本文將教你如何配置客戶端連線，並驗證已設定的模型是否有回應。 它不會部署或保護推理服務。

Prerequisites

  • 一台執行 GitHub Copilot CLI 支援的 Windows 版本的用戶端電腦，具備以下功能：
  • 有效的 GitHub Copilot 訂閱。 若組織或企業提供您的訂閱，其管理員必須允許 GitHub Copilot CLI。
  • 一個可信的工作目錄，用來啟動 GitHub Copilot CLI。
  • Windows Server 上既有的、與 OpenAI 相容的端點，具備：
    • 可從用戶端電腦存取。
    • 需要驗證。 此程序適用於遠端 Windows Server 連線。 在非此程序的迴圈情境下，將未驗證的端點保留。
    • 它只監聽預期伺服器網路介面，只允許來自授權客戶端電腦或子網的入站連線，且不接受來自公共網際網路的直接連線。
    • 支援串流以及工具呼叫或函數呼叫功能。 僅有 OpenAI 相容性並不保證支援所有 GitHub Copilot CLI 功能。 用端點操作員驗證端點及所選模型能力。
  • Windows 用戶端與 Windows Server 之間的網路連線，具備：
    • 可從用戶端電腦解析的 Windows Server 推論端點 DNS 名稱。
    • 網路路由與防火牆規則，允許只有授權的用戶端或子網連接端點埠。
    • 客戶端信任且主體名稱或主體替代名稱與端點 DNS 名稱相符的 HTTPS 憑證。
  • 端點基底 URL，例如 https://inference.contoso.com/v1。
  • 端點操作員指定的端點憑證與認證類型。

安裝 GitHub Copilot CLI

  1. 開啟 PowerShell。

  2. 安裝穩定的 GitHub Copilot CLI 套件：

    winget install GitHub.Copilot

  3. 確認安裝成功：

    copilot --version

    該指令會回傳已安裝的 GitHub Copilot CLI 版本。

從 Windows Server 推論端點取得模型 ID

  1. 設定端點操作員提供的基礎網址：

    $BaseUrl = 'https://inference.contoso.com/v1'

  2. 輸入端點操作員指定的 API 金鑰或承載令牌。 使用短暫且權限最低的憑證。 當您的組織提供核准的秘密儲存指令時，請用它來取得該憑證，而非直接輸入。 以下指令將該 SecureString 值轉換為明文 $endpointCredential 值，該值會保留在本 PowerShell 會話中儲存在記憶體中。

    $secureEndpointCredential = Read-Host 'Enter the endpoint credential' -AsSecureString
$endpointCredential = [System.Net.NetworkCredential]::new('', $secureEndpointCredential).Password

  3. 將GET請求傳送至$BaseUrl/models。 在 Authorization: Bearer 標頭中包含 $endpointCredential，並從回應的 data 陣列中讀取各個模型 ID：

    $requestParameters = @{
   Uri = "$BaseUrl/models"
   Method = 'Get'
}

try {
   $requestParameters.Headers = @{ Authorization = "Bearer $endpointCredential" }
   $models = Invoke-RestMethod @requestParameters
   $models.data | Select-Object -ExpandProperty id
}
finally {
   $requestParameters.Headers = $null
}

    指令會回傳一個或多個型號 ID。 複製支援串流及工具或函式呼叫的模型的精確 ID。

配置 GitHub Copilot CLI 提供者與模型

  1. 設定$BaseUrl為 Windows Server 端點的基底 URL，並$endpointCredential設定為其 API 金鑰或承載標記。 在同一個 PowerShell 工作階段中，設定提供者類型、端點基址 URL 和精確的模型 ID。 用 Windows Server 端點回傳的 ID 來取代<MODEL_ID>。

    $env:COPILOT_PROVIDER_TYPE = 'openai'
$env:COPILOT_PROVIDER_BASE_URL = $BaseUrl
$env:COPILOT_MODEL = '<MODEL_ID>'

    提供者 openai 類型支援與 OpenAI 相容的端點，包括 vLLM。

  2. 清除目前 PowerShell 會話繼承的任何提供者認證變數：

    Remove-Item Env:COPILOT_PROVIDER_API_KEY, Env:COPILOT_PROVIDER_BEARER_TOKEN, Env:COPILOT_PROVIDER_API_KEY_COMMAND -ErrorAction SilentlyContinue

  3. 設定端點操作員指定的認證方法：

    • 對於標準的 OpenAI API 金鑰驗證，只要有可用的組織核准秘密儲存區指令，請使用：

      $env:COPILOT_PROVIDER_API_KEY_COMMAND = '<APPROVED_SECRET_STORE_COMMAND>'

      指令必須從核准的秘密儲存庫取得憑證，僅輸出憑證，且不得記錄或持久化。 COPILOT_PROVIDER_API_KEY_COMMAND 優先於 COPILOT_PROVIDER_API_KEY。

    • 若無核准的秘密儲存指令可用，請直接將 API 金鑰設為當前 PowerShell 會話的短暫備用：

      $env:COPILOT_PROVIDER_API_KEY = $endpointCredential

    • 對於持有人-令牌認證，請設定持有人令牌：

      $env:COPILOT_PROVIDER_BEARER_TOKEN = $endpointCredential

    Important

    不要在腳本、原始碼控制或指令範例中放入 API 金鑰。 copilot 而它啟動的任何程序都會繼承提供者認證環境的變數。 使用短效、最低權限的憑證，並在退出 GitHub Copilot CLI 後移除變數。

  4. 檢視你已安裝版本中支援的提供者變數：

    copilot help providers

啟動並驗證 GitHub Copilot CLI

  1. 切換到你信任的檔案目錄：

    Set-Location 'C:\path\to\trusted-project'

Important

如果你在開始 copilot前停止，或先前的指令失敗，請移除提供者認證變數、清除請求標頭，並在關閉 PowerShell 前處理安全憑證：

if ($requestParameters) {
   $requestParameters.Headers = $null
}

Remove-Item Env:COPILOT_PROVIDER_API_KEY, Env:COPILOT_PROVIDER_BEARER_TOKEN, Env:COPILOT_PROVIDER_API_KEY_COMMAND -ErrorAction SilentlyContinue

if ($secureEndpointCredential) {
   $secureEndpointCredential.Dispose()
}

清理完成後關閉 PowerShell 會話。 不可變的明文字 $endpointCredential 串會一直留在記憶體中，直到程序退出。

  1. 啟動 GitHub Copilot CLI，並在 try 區塊中執行驗證步驟，讓 PowerShell 在您結束時或命令失敗時移除提供者驗證環境變數，並釋放 SecureString 值：

    try {
   copilot
}
finally {
   if ($requestParameters) {
      $requestParameters.Headers = $null
   }

   Remove-Item Env:COPILOT_PROVIDER_API_KEY, Env:COPILOT_PROVIDER_BEARER_TOKEN, Env:COPILOT_PROVIDER_API_KEY_COMMAND -ErrorAction SilentlyContinue

   if ($secureEndpointCredential) {
      $secureEndpointCredential.Dispose()
   }
}

  2. 確認「受信任目錄」提示訊息。 只有在你能控制該目錄的內容，且預期它會持續維持為可信任時，才在未來的工作階段中信任該目錄。

  3. 如果 GitHub Copilot CLI 提示你，輸入/login並依照指示驗證 GitHub。 GitHub 認證與驗證推論端點的 API 金鑰是分開的。

  4. 請輸入這個測試提示：

    Reply with exactly: Local inference test succeeded

    Windows Server端點上的配置模型會回傳Local inference test succeeded，且不會有提供者、認證或模型相容性錯誤。 當你退出 GitHub Copilot CLI 後，PowerShell 會執行該finally區塊。 PowerShell 無法可靠地從記憶體中抹除不可變的明文 $endpointCredential 字串，因此指令完成後關閉 PowerShell 會話以釋放程序記憶體。

故障排除 GitHub Copilot CLI 與 Windows Server 推論端點的連線

問題 要檢查的事項
模型請求無法抵達端點 驗證端點基礎 URL、DNS 解析、埠口、網路路由、服務狀態及 TLS 憑證信任度。 基礎 URL 應包含端點運算元提供的 API 前綴，例如 /v1。
模型要求會返回 401 或 403 確認憑證的有效性。 對於 API 金鑰認證，建議 COPILOT_PROVIDER_API_KEY_COMMAND 使用核准的秘密儲存指令。 COPILOT_PROVIDER_API_KEY只當作短暫的備用方案使用。 對於 Bearer Token 驗證，請依照端點操作人員的指定設定 COPILOT_PROVIDER_BEARER_TOKEN。
GitHub Copilot CLI 使用不同的提供者或模型 在同一個啟動 copilot的 PowerShell 會話中設定提供者類型、基本網址、模型，並選擇了認證變數。 使用端點回傳的精確模型 ID。 另請檢查 $HOME\.copilot\providers.json；該檔案中的提供者或模型宣告優先於 COPILOT_PROVIDER_* 變數。
GitHub Copilot CLI 找不到該模型 再次查詢 $BaseUrl/models ，並將該 COPILOT_MODEL 值與 id 端點回傳的數值（包括大小寫與標點符號）進行比較。
當端點接受請求後，提示符會失敗 確認模型和端點同時支援串流以及工具或函式呼叫。 檢查端點日誌中是否有不支援的請求欄位、工具架構、上下文限制或回應格式。

相關內容

  • Last updated on