traga sua própria chave (BYOK)

Use SDK do Copilot com suas próprias chaves de API de diferentes provedores de modelo, ignorando a GitHub Copilot autenticação.

Quem pode usar esse recurso?

SDK do GitHub Copilot está disponível com todos os Copilot planos.

Neste artigo

Observação

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Traga sua própria chave (BYOK) permite que você use SDK do Copilot com suas próprias chaves de API de provedores de modelo, ignorando GitHub Copilot a autenticação. Isso é útil para implantações empresariais, hospedagem de modelo personalizado ou quando você deseja cobrança direta com seu provedor de modelo.

Provedores com suporte

FornecedorTipo de valorObservações
OpenAI"openai"API OpenAI e endpoints compatíveis com OpenAI
Azure OpenAI /Azure AI Foundry
          `"azure"` ou `"openai"` | Modelos hospedados no Azure (consulte [os tipos de ponto de extremidade do Azure](#azure-endpoint-type-confusion)) |

| Anthropic | "anthropic" | Modelos de Claude | | Ollama | "openai" | Modelos locais por meio da API compatível com OpenAI | | Microsoft Foundry Local | "openai" | Executar modelos de IA localmente em seu dispositivo por meio da API compatível com OpenAI | | Outros compatíveis com OpenAI | "openai" | vLLM, LiteLLM e similares |

Início rápido: Azure AI Foundry

O Azure AI Foundry (antigo Azure OpenAI) é um destino de implantação BYOK comum para empresas. O exemplo a seguir mostra uma configuração completa Node.js/TypeScript:

  1. Crie uma sessão com o endpoint do Azure AI Foundry e a chave de API.

    TypeScript
    import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "YOUR-DEPLOYMENT-NAME",
    provider: {
        type: "openai",
        baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
        wireApi: "responses",  // Use "completions" for older models
        apiKey: process.env.FOUNDRY_API_KEY,
    },
});

session.on("assistant.message", (event) => {
    console.log(event.data.content);
});

await session.sendAndWait({ prompt: "What is 2+2?" });
await client.stop();

Substitua YOUR-RESOURCE pelo nome do recurso do Azure e YOUR-DEPLOYMENT-NAME pelo nome da implantação do modelo. Defina a variável de FOUNDRY_API_KEY ambiente para sua chave de API do Azure.

Para obter exemplos em Python, Go e .NET, consulte BYOK no github/copilot-sdk repositório.

Referência de configuração do provedor

Campos ProviderConfig

CampoTipoDescrição
type
          `"openai"`
          \|
          `"azure"`
          \|
          `"anthropic"`
         | Tipo de provedor. Usa `"openai"` como padrão. |

| baseUrl | cadeia | Obrigatório. URL do ponto de extremidade da API. | | apiKey | cadeia | Chave de API. Opcional para provedores locais como o Ollama. | | bearerToken | cadeia | Autenticação com token de portador. Tem precedência sobre apiKey. | | wireApi | "completions" | "responses" | Formato de API. Usa "completions" como padrão. | | azure.apiVersion | cadeia | Versão da API do Azure. Usa "2024-10-21" como padrão. |

Formato da API do Wire

A wireApi configuração determina qual formato de API OpenAI usar:

  •         **
        `"completions"`
        ** (padrão): API de Conclusões de Chat (`/chat/completions`). Utilize para a maioria dos modelos.

  •         **
        `"responses"`
        **: API de respostas. Use para modelos da linha GPT-5 que suportam o formato mais recente de respostas.

Notas específicas do tipo

          **OpenAI (`type: "openai"`)**

  • Funciona com a API OpenAI e qualquer endpoint compatível com a OpenAI.

  •         `baseUrl` deve incluir o caminho completo, por exemplo, `https://api.openai.com/v1`.

        **Azure (`type: "azure"`)**

  • Para uso com endpoints nativos do Azure OpenAI.

  •         `baseUrl` deve ser apenas o host, por exemplo, `https://YOUR-RESOURCE.openai.azure.com`.

  • Não inclua /openai/v1 na URL – o SDK manipula a construção do caminho.

            **Anthropic (`type: "anthropic"`)**

  • Para acesso direto à API Anthropic.

  • Usa o formato de API específico de Claude.

Configurações de exemplo

OpenAI direto

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY,
}

Azure OpenAI (ponto de extremidade nativo do Azure)

Utilize type: "azure" para os endpoints em *.openai.azure.com:

TypeScript
provider: {
    type: "azure",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",  // Just the host
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: {
        apiVersion: "2024-10-21",
    },
}

Substitua YOUR-RESOURCE pelo nome do recurso do Azure.

Azure AI Foundry (endpoint compatível com OpenAI)

Para implantações do Azure AI Foundry com /openai/v1/ endpoints, use type: "openai":

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // For GPT-5 series models
}

Ollama (local)

TypeScript
provider: {
    type: "openai",
    baseUrl: "http://localhost:11434/v1",
    // No apiKey needed for local Ollama
}

Microsoft Foundry Local

O Microsoft Foundry Local permite executar modelos de IA localmente com uma API compatível com OpenAI. Instale através do Foundry Local CLI e direcione o SDK para o endpoint local.

TypeScript
provider: {
    type: "openai",
    baseUrl: "http://localhost:YOUR-PORT/v1",
    // No apiKey needed for local Foundry Local
}

Observação

O Foundry Local inicia em uma porta dinâmica que não é corrigida. Execute foundry service status para confirmar a porta em que o serviço está escutando no momento e use essa porta em sua baseUrl.

Para começar a usar o Foundry Local:

Bash
# Windows: Install Foundry Local CLI (requires winget)
winget install Microsoft.FoundryLocal

# List available models
foundry model list

# Run a model (starts the local server automatically)
foundry model run phi-4-mini

# Check the port the service is running on
foundry service status

Para a instalação do macOS/Linux, consulte foundrylocal.ai.

Anthropic

TypeScript
provider: {
    type: "anthropic",
    baseUrl: "https://api.anthropic.com",
    apiKey: process.env.ANTHROPIC_API_KEY,
}

Autenticação com Bearer Token

Alguns provedores exigem autenticação de token de portador em vez de chaves de API:

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://YOUR-CUSTOM-ENDPOINT.example.com/v1",
    bearerToken: process.env.MY_BEARER_TOKEN,  // Sets Authorization header
}

Observação

A bearerToken opção aceita apenas uma cadeia de caracteres de token estático. O SDK não atualiza esse token automaticamente. Se o token expirar, as solicitações falharão e você precisará criar uma nova sessão com um novo token.

Listagem de modelo personalizado

Ao usar BYOK, o servidor da CLI pode não saber quais modelos seu provedor dá suporte. Você pode fornecer um manipulador personalizado onListModels no nível do cliente para que client.listModels() retorne os modelos do provedor no formato padrão ModelInfo :

TypeScript
import { CopilotClient } from "@github/copilot-sdk";
import type { ModelInfo } from "@github/copilot-sdk";

const client = new CopilotClient({
    onListModels: () => [
        {
            id: "my-custom-model",
            name: "My Custom Model",
            capabilities: {
                supports: { vision: false, reasoningEffort: false },
                limits: { max_context_window_tokens: 128000 },
            },
        },
    ],
});

Os resultados são armazenados em cache após a primeira chamada. O manipulador substitui completamente o RPC da models.list CLI— não ocorre nenhum fallback para o servidor.

Para obter exemplos em Python, Go e .NET, consulte BYOK no github/copilot-sdk repositório.

Limitações

Limitações de identidade

A autenticação BYOK usa apenas credenciais estáticas. Não há suporte para os seguintes provedores de identidade:

  • Microsoft Entra ID (Azure AD)— sem suporte para identidades gerenciadas do Entra ou entidades de serviço.
  • Provedores de identidade de terceiros — sem OIDC, SAML ou outra identidade federada.
  • Identidades gerenciadas — a Identidade Gerenciada do Azure não tem suporte.

Você deve usar uma chave de API ou um token de portador estático que você mesmo gerencie.

Observação

Embora a ID do Entra emita tokens de portador, esses tokens são de curta duração (normalmente uma hora) e exigem atualização automática por meio do SDK de Identidade do Azure. A bearerToken opção aceita apenas uma cadeia de caracteres estática— não há mecanismo de retorno de chamada para o SDK solicitar tokens novos. Para cargas de trabalho de longa execução que exigem a autenticação do Entra, você precisaria implementar sua própria lógica de atualização de token e criar novas sessões com tokens atualizados.

Limitações de funcionalidades

Alguns Copilot recursos podem se comportar de forma diferente com BYOK:

  •         **Disponibilidade do modelo**: somente os modelos compatíveis com seu provedor estão disponíveis.

  •         **Limitação de taxa**: sujeito aos limites de taxa do seu provedor, não o da Copilot.

  •         **Acompanhamento de uso**: o uso é acompanhado pelo seu provedor, não GitHub.

  •         **Solicitações Premium**: não contam nas Copilot cotas de solicitação premium.

Limitações específicas do provedor

FornecedorLimitações
Fábrica de IA do AzureA autenticação de ID do Entra não é permitida; deve-se usar chaves de API.
OllamaNenhuma chave de API; somente local; O suporte ao modelo varia.
Microsoft Foundry LocalSomente local; A disponibilidade do modelo depende do hardware do dispositivo; nenhuma chave de API necessária.
OpenAISujeito a limites de taxa e cotas do OpenAI.

Solução de problemas

Erro "Modelo não especificado"

Ao usar BYOK, o model parâmetro é necessário:

// Error: model required with custom provider
const session = await client.createSession({
    provider: { type: "openai", baseUrl: "..." },
});

// Correct: model specified
const session = await client.createSession({
    model: "gpt-4",
    provider: { type: "openai", baseUrl: "..." },
});

Confusão quanto ao tipo de ponto de extremidade no Azure

Para pontos de extremidade do Azure OpenAI (*.openai.azure.com), certifique-se de usar o tipo de provedor correto:

// Wrong: using "openai" type with native Azure endpoint
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",
}

// Correct: using "azure" type
provider: {
    type: "azure",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",
}

Se a implantação do Azure AI Foundry fornecer um caminho de ponto de extremidade compatível com OpenAI (por exemplo, /openai/v1/), use type: "openai" em vez disso:

// Correct: OpenAI-compatible Azure AI Foundry endpoint
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
}

Conexão recusada (Ollama)

Verifique se o Ollama está em execução e acessível:

Bash
# Check Ollama is running
curl http://localhost:11434/v1/models

# Start Ollama if not running
ollama serve

Conexão recusada (Foundry Local)

O Foundry Local usa uma porta dinâmica que pode mudar entre reinicializações. Confirme a porta ativa:

Bash
foundry service status

Atualize-o baseUrl para corresponder à porta mostrada na saída. Se o serviço não estiver em execução, inicie um modelo para iniciá-lo:

Bash
foundry model run phi-4-mini

Falha na autenticação

  1. Verifique se a chave de API está correta e não expirou.
  2. Verifique se o formato do baseUrl corresponde ao esperado pelo seu provedor.
  3. Para tokens de portador, verifique se o token completo é fornecido, não apenas um prefixo.