将 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 名称。
    • 网络路由和防火墙规则，允许只有授权的客户端或子网连接到终端端口。
    • 客户端信任的HTTPS证书，其主体名或主体替代名与端点DNS名称相匹配。
  • 端点基础 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. 设置端点操作员提供的基础URL：

    $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 令牌身份验证，请按照端点运营方的指定设置 COPILOT_PROVIDER_BEARER_TOKEN。
GitHub Copilot CLI 使用不同的提供者或模型 在启动 copilot 的同一个 PowerShell 会话中，设置提供程序类型、基础 URL、模型和所选身份验证变量。 使用端点返回的准确型号ID。 还要检查 $HOME\.copilot\providers.json;该文件的提供者或模型声明优先 COPILOT_PROVIDER_* 于变量。
GitHub Copilot CLI 找不到该模型 再次查询 $BaseUrl/models ，并将该 COPILOT_MODEL 值与 id 端点返回的值（包括大小写和标点）进行比较。
提示在端点接受请求后失败 确认模型和端点同时支持流式输出以及工具或函数调用。 检查终端日志中是否有不支持的请求字段、工具模式、上下文限制或响应格式。

相关内容

  • Last updated on