Conecte a CLI do GitHub Copilot a um endpoint de inferência do Windows Server

O GitHub Copilot CLI é um agente de codificação de IA que pode enviar requisições de modelo de um cliente Windows suportado para um endpoint de inferência compatível com OpenAI hospedado no Windows Server. Essa configuração permite que você use um modelo hospedado pela organização a partir do seu terminal, enquanto o Windows Server centraliza a hospedagem e o processamento do modelo.

Este artigo mostra como configurar a conexão do cliente e verificar se o modelo configurado responde. Ele não implanta nem protege o serviço de inferência.

Prerequisites

Um computador cliente que roda uma versão para Windows que o GitHub Copilot CLI suporta, com:
- PowerShell 6 ou posterior.
- Windows Gerenciador de Pacotes (WinGet).
Uma assinatura GitHub Copilot ativa. Se uma organização ou empresa fornecer sua assinatura, seu administrador deve permitir a CLI do GitHub Copilot.
Um diretório funcional confiável a partir do qual iniciar a CLI do GitHub Copilot.
Um endpoint compatível com OpenAI existente no Windows Server que:
- É acessível a partir do computador cliente.
- Requer autenticação. Esse procedimento se aplica a conexões remotas do Windows Server. Reserve os endpoints sem autenticação somente para cenários de loopback fora deste procedimento.
- Escuta apenas na interface de rede do servidor pretendida, permite conexões de entrada apenas de computadores ou sub-redes clientes autorizadas, e não aceita conexões diretas da internet pública.
- Suporta streaming e chamada de ferramentas ou funções. A compatibilidade com OpenAI sozinha não garante suporte para todas as capacidades de CLI do GitHub Copilot. Verifique, junto ao operador do endpoint, as capacidades do endpoint e do modelo selecionado.
Uma conexão de rede Windows-cliente-para-Windows-Server que possui:
- Um nome DNS para o endpoint de inferência do Windows Server que possa ser resolvido no computador cliente.
- Regras de roteamento de rede e de firewall que permitem que apenas clientes ou sub-redes autorizados se conectem à porta do endpoint.
- Um certificado HTTPS no qual o cliente confia e cujo nome de assunto ou nome alternativo corresponde ao nome DNS do endpoint.
A URL de base do endpoint, como https://inference.contoso.com/v1.
A credencial do endpoint e o tipo de autenticação especificados pelo operador do endpoint.

Instale a CLI do GitHub Copilot

Abra o PowerShell.
Instale o pacote estável de CLI GitHub Copilot:
```
winget install GitHub.Copilot
```
Confirme que a instalação foi bem-sucedida:
```
copilot --version
```
O comando retorna a versão instalada do GitHub Copilot CLI.

Obtenha um ID de modelo do endpoint de inferência do Windows Server

Defina a URL base que o operador do endpoint forneceu:
```
$BaseUrl = 'https://inference.contoso.com/v1'
```
Insira a chave de API ou o token Bearer especificado pelo operador do endpoint. Use uma credencial de curta duração, com menor privilégio. Quando sua organização fornecer um comando de armazenamento secreto aprovado, use-o para recuperar a credencial em vez de digitá-la diretamente. O comando seguinte converte o SecureString valor para o valor do texto $endpointCredential simples, que permanece na memória para esta sessão do PowerShell.
```
$secureEndpointCredential = Read-Host 'Enter the endpoint credential' -AsSecureString
$endpointCredential = [System.Net.NetworkCredential]::new('', $secureEndpointCredential).Password
```

Envie um GET pedido para $BaseUrl/models. Inclua $endpointCredential em um cabeçalho Authorization: Bearer, e leia cada ID de modelo do array data da resposta:

$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
}

O comando retorna um ou mais IDs de modelo. Copie o ID exato de um modelo que suporta streaming e chamada de ferramentas ou funções.

Configure o provedor e modelo da CLI do GitHub Copilot

Defina $BaseUrl para a URL base do endpoint do Windows Server e $endpointCredential para sua chave API ou token portador. Na mesma sessão PowerShell, defina o tipo de provedor, a URL base do endpoint e o ID exato do modelo. Substitua <MODEL_ID> por um ID que o endpoint do Windows Server retorna.
```
$env:COPILOT_PROVIDER_TYPE = 'openai'
$env:COPILOT_PROVIDER_BASE_URL = $BaseUrl
$env:COPILOT_MODEL = '<MODEL_ID>'
```
O openai tipo de provedor suporta endpoints compatíveis com OpenAI, incluindo vLLM.

Elimine quaisquer variáveis de autenticação do provedor que a sessão atual do PowerShell tenha herdado:

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

Configure o método de autenticação que o operador do endpoint especificou:
- Para autenticação padrão com chave de API do OpenAI, use um comando secret-store aprovado pela organização sempre que um estiver disponível:
```
$env:COPILOT_PROVIDER_API_KEY_COMMAND = '<APPROVED_SECRET_STORE_COMMAND>'
```
  O comando deve recuperar a credencial de um cofre de segredos aprovado, retornar apenas a credencial e não registrá-la em log nem persisti-la. COPILOT_PROVIDER_API_KEY_COMMAND tem precedência sobre COPILOT_PROVIDER_API_KEY.
- Se não houver um comando de secret-store aprovado disponível, defina diretamente a chave de API como uma alternativa temporária de curta duração para a sessão atual do PowerShell:
```
$env:COPILOT_PROVIDER_API_KEY = $endpointCredential
```
- Para autenticação por token de portador, defina o token de portador:
```
$env:COPILOT_PROVIDER_BEARER_TOKEN = $endpointCredential
```
Importante

Não coloque chaves de API em scripts, controle de versão ou exemplos de comandos. copilot e quaisquer processos que ele inicie herdam variáveis do ambiente de autenticação do provedor. Use credenciais de curta duração, com privilégio mínimo, e remova as variáveis depois de sair da CLI do GitHub Copilot.
Revise as variáveis do provedor suportadas na sua versão instalada:
```
copilot help providers
```

Inicie e verifique a CLI do GitHub Copilot

Mude para um diretório cujos arquivos você confia:
```
Set-Location 'C:\path\to\trusted-project'
```

Importante

Se você parar antes de começar copilot, ou se um comando anterior falhar, remova as variáveis de autenticação do provedor, limpe os cabeçalhos das requisições e elimine a credencial segura antes de fechar o 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()
}

Feche a sessão do PowerShell após a limpeza ser executada. A cadeia de texto $endpointCredential simples imutável permanece na memória até o fim do processo.

Inicie a CLI do GitHub Copilot e execute as etapas de verificação em um bloco try para que o PowerShell remova as variáveis de ambiente de autenticação do provedor e descarte o valor SecureString quando você sair ou o comando falhar:

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()
   }
}

Confirme o prompt de diretório confiável. Confie no diretório para sessões futuras somente se você controlar seu respectivo conteúdo e esperar que este continue sendo confiável.
Se a CLI do GitHub Copilot te solicitar, insira /login e siga as instruções para autenticar no GitHub. A autenticação no GitHub é separada da chave API que autentica o endpoint de inferência.
Digite este prompt de teste:
```
Reply with exactly: Local inference test succeeded
```
O modelo configurado no endpoint do Windows Server retorna Local inference test succeeded sem erro de provedor, autenticação ou compatibilidade de modelo. Depois que você sai da CLI do GitHub Copilot, o PowerShell roda o finally bloco. O PowerShell não consegue apagar de forma confiável a string de texto $endpointCredential simples imutável da memória, então feche a sessão do PowerShell após o comando terminar para liberar a memória do processo.

Solucionar problemas de conexão do GitHub Copilot CLI com um endpoint de inferência no Windows Server

Questão	O que verificar
A solicitação de modelos não consegue alcançar o endpoint	Verifique a URL base do endpoint, resolução DNS, porta, rota de rede, status do serviço e confiança do certificado TLS. A URL base deve incluir o prefixo da API que o operador do endpoint fornece, como `/v1`.
Os modelos solicitam retornos `401` ou `403`	Verifique se a credencial é válida. Para autenticação com chave de API, prefira `COPILOT_PROVIDER_API_KEY_COMMAND` com um comando secret-store aprovado. Use `COPILOT_PROVIDER_API_KEY` apenas como um plano B de curta duração. Para autenticação por token de portador, defina `COPILOT_PROVIDER_BEARER_TOKEN`, conforme especificado pelo operador endpoint.
A CLI do GitHub Copilot usa um provedor ou modelo diferente	Defina o tipo de provedor, URL base, modelo e variável de autenticação selecionada na mesma sessão PowerShell que inicia `copilot`. Use o ID exato do modelo que o endpoint retorna. Também verifique `$HOME\.copilot\providers.json`; as declarações do provedor ou modelo daquele arquivo têm precedência sobre as `COPILOT_PROVIDER_*` variáveis.
A CLI do GitHub Copilot não consegue encontrar o modelo	Consulte `$BaseUrl/models` novamente e compare o valor de `COPILOT_MODEL` com o valor de `id` retornado pelo endpoint, incluindo capitalização e pontuação.
O prompt falha depois que o endpoint aceita a solicitação	Confirme se o modelo e o endpoint suportam tanto streaming quanto chamada de ferramentas ou funções. Verifique os logs do endpoint em busca de um campo da solicitação, esquema de ferramenta, limite de contexto ou formato de resposta não suportado.

Comentários

Esta página foi útil?

Last updated on 2026-09-28