Bring Your Own Key (BYOK)

Utilice SDK de Copilot con sus propias claves de API de proveedores de modelos diferentes, eludiendo la autenticación GitHub Copilot.

¿Quién puede utilizar esta característica?

SDK de GitHub Copilot está disponible con todos los Copilot planes.

En este artículo

Nota:

          SDK de Copilot actualmente está en versión preliminar pública. La funcionalidad y la disponibilidad están sujetas a cambios.

Traiga su propia clave (BYOK) le permite usar SDK de Copilot con sus propias claves de API de proveedores de modelos, evitando la autenticación de GitHub Copilot. Esto es útil para las implementaciones empresariales, el hospedaje de modelos personalizados o cuando quiera facturar directamente con el proveedor de modelos.

Proveedores compatibles

ProviderValor de tipoNotas
OpenAI"openai"Api de OpenAI y puntos de conexión compatibles con OpenAI
Azure OpenAI/Azure AI Foundry
          `"azure"` o `"openai"` | Modelos hospedados en Azure (consulte [Tipos de punto de conexión de Azure](#azure-endpoint-type-confusion)) |

| Anthropic | "anthropic" | Modelos de Claude | | Ollama | "openai" | Modelos locales a través de la API compatible con OpenAI | | Microsoft Foundry Local | "openai" | Ejecución de modelos de IA localmente en el dispositivo a través de la API compatible con OpenAI | | Otros compatibles con OpenAI | "openai" | vLLM, LiteLLM y similar |

Inicio rápido: Azure AI Foundry

Azure AI Foundry (anteriormente Azure OpenAI) es un destino de implementación BYOK común para empresas. En el ejemplo siguiente se muestra una configuración completa de Node.js/TypeScript:

  1. Cree una sesión con el punto de conexión y la clave de API de Azure AI Foundry:

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

Reemplace por YOUR-RESOURCE el nombre del recurso de Azure y YOUR-DEPLOYMENT-NAME por el nombre de implementación del modelo. Establezca la variable de entorno en la FOUNDRY_API_KEY clave de API de Azure.

Para obtener ejemplos en Python, Go y .NET, consulte BYOK en el github/copilot-sdk repositorio. Para Java, consulte el github/copilot-sdk-java repositorio.

Referencia de configuración del proveedor

Campos ProviderConfig

CampoTipoDescripción
type
          `"openai"`
          \|
          `"azure"`
          \|
          `"anthropic"`
         | Tipo de proveedor. Tiene como valor predeterminado `"openai"`. |

| baseUrl | cuerda / cadena | Obligatorio. Dirección URL del punto de conexión de API. | | apiKey | cuerda / cadena | Clave de API. Opcional para proveedores locales como Ollama. | | bearerToken | cuerda / cadena | Autenticación por token de portador. Tiene prioridad sobre apiKey. | | wireApi | "completions" | "responses" | Formato de API. Tiene como valor predeterminado "completions". | | azure.apiVersion | cuerda / cadena | Versión de la API de Azure. Tiene como valor predeterminado "2024-10-21". |

Formato de WIRE API

La wireApi configuración determina qué formato de API de OpenAI se va a usar:

          `"completions"`
          ** (valor predeterminado): API de finalizaciones de chat (`/chat/completions`). Se usa para la mayoría de los modelos.

          `"responses"`
          **: API de respuestas. Se usa para los modelos de la serie GPT-5 que admiten el formato de respuestas más reciente.

Notas específicas del tipo

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

  • Funciona con la API de OpenAI y cualquier punto de conexión compatible con OpenAI.

  • baseUrl debe incluir la ruta de acceso completa, por ejemplo, https://api.openai.com/v1.

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

  • Use para puntos de conexión nativos de Azure OpenAI.

  • baseUrl debe ser solo el host, por ejemplo, https://YOUR-RESOURCE.openai.azure.com.

  • No incluya /openai/v1 en la dirección URL: el SDK controla la construcción de la ruta de acceso.

            **Antrópica (`type: "anthropic"`)**

  • Para el acceso directo a la API de Anthropic.

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

Configuraciones de ejemplo

OpenAI canal directo

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

Azure OpenAI (punto de conexión nativo de Azure)

Use type: "azure" para puntos de conexión en *.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",
    },
}

Reemplace por YOUR-RESOURCE el nombre del recurso de Azure.

Azure AI Foundry (punto de conexión compatible con OpenAI)

Para las implementaciones de Azure AI Foundry con /openai/v1/ puntos de conexión, 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

          [Microsoft Foundry Local](https://foundrylocal.ai) le permite ejecutar modelos de INTELIGENCIA ARTIFICIAL localmente con una API compatible con OpenAI. Instálelo a través de la CLI local de Foundry y, a continuación, apunte el SDK en el punto de conexión local:
TypeScript
provider: {
    type: "openai",
    baseUrl: "http://localhost:YOUR-PORT/v1",
    // No apiKey needed for local Foundry Local
}

Nota:

Foundry Local se inicia en un puerto dinámico que no es fijo. Ejecute foundry service status para confirmar el puerto en el que el servicio está escuchando actualmente y, a continuación, use ese puerto en baseUrl.

Para empezar a trabajar con 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 la instalación de macOS/Linux, consulte foundrylocal.ai.

Anthropic

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

Autenticación por token de portador

Algunos proveedores requieren autenticación de token de portador en lugar de claves de API:

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

Nota:

La bearerToken opción solo acepta una cadena de token estática. El SDK no actualiza este token automáticamente. Si el token expira, se producirá un error en las solicitudes y deberá crear una nueva sesión con un token nuevo.

Lista de modelos personalizados

Al usar BYOK, es posible que el servidor de la CLI no sepa qué modelos admite el proveedor. Puede proporcionar un controlador personalizado onListModels en el nivel de cliente para que client.listModels() devuelva los modelos del proveedor en el formato estándar 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 },
            },
        },
    ],
});

Los resultados se almacenan en caché después de la primera llamada. El controlador reemplaza completamente la RPC de models.list la CLI; no ocurre ningún mecanismo de respaldo al servidor.

Para obtener ejemplos en Python, Go y .NET, consulte BYOK en el github/copilot-sdk repositorio. Para Java, consulte el github/copilot-sdk-java repositorio.

Limitaciones

Limitaciones de identidad

La autenticación BYOK solo usa credenciales estáticas. No se admiten los siguientes proveedores de identidades:

  • Microsoft Entra ID (Azure AD): no se admiten identidades administradas o entidades de servicio de Entra.
  • Proveedores de identidades de terceros: sin OIDC, SAML u otra identidad federada.
  • Identidades administradas: no se admite La identidad administrada de Azure.

Debe usar una clave de API o un token de portador estático que administre usted mismo.

Nota:

Aunque Entra ID emite tokens de portador, estos tokens son de corta duración (normalmente una hora) y requieren actualización automática a través del SDK de identidad de Azure. La bearerToken opción solo acepta una cadena estática: no hay ningún mecanismo de devolución de llamada para que el SDK solicite tokens nuevos. En el caso de trabajos de larga duración que requieren autenticación Entra, necesitaría implementar una lógica propia para la actualización de tokens e iniciar nuevas sesiones con los tokens actualizados.

Limitaciones de características

Algunas Copilot características pueden comportarse de forma diferente con BYOK:

  • Disponibilidad del modelo: solo están disponibles los modelos admitidos por el proveedor.
  • Limitación de velocidad: sujeto a los límites de su proveedor, no a los de Copilot.
  • Seguimiento de uso: el proveedor realiza un seguimiento del uso, no GitHub.
  •           **Solicitudes Premium**: no cuentan para Copilot las cuotas de solicitudes premium.

Limitaciones específicas del proveedor

ProviderLimitaciones
Azure AI FoundryNo se utiliza autenticación de Entra ID; se deben usar claves de API.
OllamaSin clave de API; solo local; La compatibilidad del modelo varía.
Microsoft Foundry LocalSolo local; la disponibilidad del modelo depende del hardware del dispositivo; no se requiere ninguna clave de API.
OpenAISujeto a límites y cuotas de tasa de OpenAI.

Solución de problemas

Error "No se ha especificado el modelo"

Cuando se usa BYOK, se requiere el model parámetro :

// 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: "..." },
});

Confusión del tipo de punto de conexión de Azure

Para los puntos de conexión de Azure OpenAI (*.openai.azure.com), asegúrese de usar el tipo de proveedor correcto:

// 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",
}

Si la implementación de Azure AI Foundry proporciona una ruta de acceso de punto de conexión compatible con OpenAI (por ejemplo, /openai/v1/), use type: "openai" en su lugar:

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

Conexión rechazada (Ollama)

Asegúrese de que Ollama está en ejecución y accesible:

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

# Start Ollama if not running
ollama serve

Conexión rechazada (Fundición Local)

Foundry Local usa un puerto dinámico que puede cambiar entre reinicios. Confirme el puerto activo:

Bash
foundry service status

Actualiza tu baseUrl para que coincida con el puerto que se muestra en la salida. Si el servicio no se está ejecutando, inicie un modelo para iniciarlo:

Bash
foundry model run phi-4-mini

Error de autenticación

  1. Compruebe que la clave de API es correcta y no ha expirado.
  2. Compruebe que coincide con el baseUrl formato esperado del proveedor.
  3. Para los tokens de portador, asegúrese de que se proporciona el token completo, no solo un prefijo.