Thanks to visit codestin.com
Credit goes to docs.github.com

Skip to main content

BYOK (traiga su propia clave)

BYOK permite usar el SDK de Copilot con sus propias claves de API de proveedores de modelos, pasando GitHub Copilot autenticación. 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/Fundición de IA de Azure"azure"modelos hospedados Azure
Anthropic"anthropic"Modelos de Claude
Ollama"openai"Modelos locales a través de la API compatible con OpenAI
local de Microsoft Foundry"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, etc.

Inicio rápido: Fundición de IA de Azure

Fundición de IA de Azure (anteriormente Azure OpenAI) es un destino de implementación BYOK común para empresas. Este es un ejemplo completo:

Python
import asyncio
import os
from copilot import CopilotClient
from copilot.session import PermissionHandler

FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/"
# Set FOUNDRY_API_KEY environment variable

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", provider={
        "type": "openai",
        "base_url": FOUNDRY_MODEL_URL,
        "wire_api": "responses",  # Use "completions" for older models
        "api_key": os.environ["FOUNDRY_API_KEY"],
    })

    done = asyncio.Event()

    def on_event(event):
        if event.type.value == "assistant.message":
            print(event.data.content)
        elif event.type.value == "session.idle":
            done.set()

    session.on(on_event)
    await session.send("What is 2+2?")
    await done.wait()

    await session.disconnect()
    await client.stop()

asyncio.run(main())
TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5.2-codex",  // Your deployment name
    provider: {
        type: "openai",
        baseUrl: FOUNDRY_MODEL_URL,
        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();
Go
package main

import (
    "context"
    "fmt"
    "os"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        panic(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-5.2-codex",  // Your deployment name
        Provider: &copilot.ProviderConfig{
            Type:    "openai",
            BaseURL: "https://your-resource.openai.azure.com/openai/v1/",
            WireAPI: "responses",  // Use "completions" for older models
            APIKey:  os.Getenv("FOUNDRY_API_KEY"),
        },
    })
    if err != nil {
        panic(err)
    }

    response, err := session.SendAndWait(ctx, copilot.MessageOptions{
        Prompt: "What is 2+2?",
    })
    if err != nil {
        panic(err)
    }

    if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
        fmt.Println(d.Content)
    }
}
.NET
using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5.2-codex",  // Your deployment name
    Provider = new ProviderConfig
    {
        Type = "openai",
        BaseUrl = "https://your-resource.openai.azure.com/openai/v1/",
        WireApi = "responses",  // Use "completions" for older models
        ApiKey = Environment.GetEnvironmentVariable("FOUNDRY_API_KEY"),
    },
});

var response = await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "What is 2+2?",
});
Console.WriteLine(response?.Data.Content);
Java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient();
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-5.2-codex")  // Your deployment name
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setProvider(new ProviderConfig()
        .setType("openai")
        .setBaseUrl("https://your-resource.openai.azure.com/openai/v1/")
        .setWireApi("responses")  // Use "completions" for older models
        .setApiKey(System.getenv("FOUNDRY_API_KEY")))
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("What is 2+2?")).get();
System.out.println(response.getData().content());

client.stop().get();

Referencia de configuración del proveedor

Campos ProviderConfig

CampoTipoDescription
type
"openai"
|
"azure"
|
"anthropic"
Tipo de proveedor (valor predeterminado: "openai")
baseUrl / base_urlstring
Obligatorio. Dirección URL del punto de conexión de API
apiKey / api_keystringClave de API (opcional para proveedores locales como Ollama)
bearerToken / bearer_tokenstringAutenticación de token de portador (tiene prioridad sobre apiKey)
wireApi / wire_api
"completions"
|
"responses"
Seleccione "completions" para una amplia compatibilidad de modelos (la API de finalizaciones de chat); seleccione "responses" para la administración de estados multiturno, el espacio de nombres de las herramientas y la compatibilidad con el razonamiento (api de respuestas). Anthropic modelos siempre usan la API Messages independientemente de esta configuración.
azure.apiVersion / azure.api_versionstringversión de api de Azure (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) para una amplia compatibilidad del modelo.
  • "responses" - Api de respuestas para la administración de estados multiturno, el espacio de nombres de las herramientas y la compatibilidad con el razonamiento.

Anthropic modelos usan siempre la API de mensajes de Anthropic independientemente de esta configuración.

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")

  • Uso para puntos de conexión de OpenAI de Azure nativos
  • baseUrl debe ser solo el host (por ejemplo, https://my-resource.openai.azure.com)
  • No incluir /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

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:

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

Fundición de IA de Azure (punto de conexión compatible con OpenAI)

Para las implementaciones de Fundición de IA de Azure con /openai/v1/ puntos de conexión, use type: "openai":

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)

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

local de Microsoft Foundry

Microsoft Foundry Local permite ejecutar modelos de INTELIGENCIA ARTIFICIAL localmente en su propio dispositivo 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:

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

Nota:

Foundry Local se inicia en un puerto dinámico; el puerto no es fijo. Use 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:

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

# macOS / Linux: see https://foundrylocal.ai for installation instructions
# 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

Anthropic

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:

provider: {
    type: "openai",
    baseUrl: "https://my-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 . Esto permite a los consumidores de nivel inferior detectar modelos disponibles sin consultar la CLI.

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 },
            },
        },
    ],
});
Python
from copilot import CopilotClient
from copilot.client import ModelInfo, ModelCapabilities, ModelSupports, ModelLimits

client = CopilotClient(
    on_list_models=lambda: [
        ModelInfo(
            id="my-custom-model",
            name="My Custom Model",
            capabilities=ModelCapabilities(
                supports=ModelSupports(vision=False, reasoning_effort=False),
                limits=ModelLimits(max_context_window_tokens=128000),
            ),
        )
    ],
)
Go
package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        OnListModels: func(ctx context.Context) ([]copilot.ModelInfo, error) {
            return []copilot.ModelInfo{
                {
                    ID:   "my-custom-model",
                    Name: "My Custom Model",
                    Capabilities: copilot.ModelCapabilities{
                        Supports: copilot.ModelSupports{Vision: false, ReasoningEffort: false},
                        Limits:   copilot.ModelLimits{MaxContextWindowTokens: 128000},
                    },
                },
            }, nil
        },
    })
    _ = client
}
.NET
using GitHub.Copilot;

var client = new CopilotClient(new CopilotClientOptions
{
    OnListModels = (ct) => Task.FromResult<IList<ModelInfo>>(new List<ModelInfo>
    {
        new()
        {
            Id = "my-custom-model",
            Name = "My Custom Model",
            Capabilities = new ModelCapabilities
            {
                Supports = new ModelSupports { Vision = false, ReasoningEffort = false },
                Limits = new ModelLimits { MaxContextWindowTokens = 128000 }
            }
        }
    })
});
Java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;
import java.util.List;
import java.util.concurrent.CompletableFuture;

var client = new CopilotClient(new CopilotClientOptions()
    .setOnListModels(() -> CompletableFuture.completedFuture(List.of(
        new ModelInfo()
            .setId("my-custom-model")
            .setName("My Custom Model")
            .setCapabilities(new ModelCapabilities()
                .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false))
                .setLimits(new ModelLimits().setMaxContextWindowTokens(128000)))
    )))
);

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

Limitaciones

Al usar BYOK, tenga en cuenta estas limitaciones:

Limitaciones de identidad

La autenticación BYOK solo usa credenciales estáticas.

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

Limitaciones de características

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

  • Disponibilidad del modelo : solo están disponibles los modelos admitidos por el proveedor.
  • Rate limite : sujeto a los límites de velocidad del proveedor, no a los Copilot
  • Usage tracking: el proveedor realiza un seguimiento del uso, no GitHub Copilot
  • solicitudes Premium: no contar con las cuotas de solicitud premium de Copilot

Limitaciones específicas del proveedor

ProviderLimitaciones
Azure AI FoundryNo Entra ID autenticación; debe usar claves de API
OllamaSin clave de API; solo local; La compatibilidad del modelo varía
Microsoft 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",  // Required!
    provider: { type: "openai", baseUrl: "..." },
});

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

Para Azure puntos de conexión de OpenAI (*.openai.azure.com), use el tipo correcto:

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

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "azure",
        baseUrl: "https://my-resource.openai.azure.com",
    },
});
// ❌ Wrong: Using "openai" type with native Azure endpoint
provider: {
    type: "openai",  // This won't work correctly
    baseUrl: "https://my-resource.openai.azure.com",
}

// ✅ Correct: Using "azure" type
provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",
}

Sin embargo, si la implementación de Fundición de IA de Azure proporciona una ruta de acceso de punto de conexión compatible con OpenAI (por ejemplo, /openai/v1/), use type: "openai":

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

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    },
});
// ✅ 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:

# 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:

# Check the service status and port
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:

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).

Pasos siguientes