Bring Your Own Key (BYOK)

Hinweis

          Copilot SDK ist zurzeit in öffentliche Vorschau. Funktionalität und Verfügbarkeit können geändert werden.

Mit Bring Your Own Key (BYOK) können Sie Copilot SDK mit Ihren eigenen API-Schlüsseln von Modellanbietern verwenden und die Authentifizierung von GitHub Copilot umgehen. Dies ist nützlich für Unternehmensbereitstellungen, benutzerdefiniertes Modellhosting oder wenn Sie eine direkte Abrechnung mit Ihrem Modellanbieter wünschen.

Unterstützte Anbieter

Provider	Typwert	Hinweise
OpenAI	`"openai"`	OpenAI-API und openAI-kompatible Endpunkte
Azure OpenAI / Azure AI Foundry

          `"azure"` oder `"openai"` | In Azure gehostete Modelle (siehe [Azure-Endpunkttypen](#azure-endpoint-type-confusion)) |

Schnellstart: Azure AI Foundry

Azure AI Foundry (früher Azure OpenAI) ist ein gängiges BYOK-Bereitstellungsziel für Unternehmen. Das folgende Beispiel zeigt ein vollständiges Node.js/TypeScript-Setup:

Erstellen Sie eine Sitzung mit Ihrem Azure AI Foundry-Endpunkt und API-Schlüssel:

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

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

Ersetzen Sie YOUR-RESOURCE mit dem Namen Ihrer Azure-Ressource und YOUR-DEPLOYMENT-NAME mit Ihrem Modellbereitstellungsnamen. Legen Sie die Umgebungsvariable FOUNDRY_API_KEY auf Ihren Azure-API-Schlüssel fest.

Beispiele in Python, Go und .NET finden Sie unter BYOK im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

Anbieterkonfigurationsreferenz

ProviderConfig-Felder

Feld	Typ	Beschreibung
`type`

          `"openai"`
          \|
          `"azure"`
          \|
          `"anthropic"`
         | Anbietertyp. Wird standardmäßig auf `"openai"` festgelegt. |

Draht-API-Format

Die wireApi Einstellung bestimmt, welches OpenAI-API-Format verwendet werden soll:

        **
        `"completions"`
        ** (Standard): Api für Chatabschlusse (`/chat/completions`). Wird für die meisten Modelle verwendet.

        **
        `"responses"`
        **: Antwort-API. Wird für GPT-5-Serienmodelle verwendet, die das neuere Antwortformat unterstützen.

Typspezifische Notizen

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

Funktioniert mit der OpenAI-API und jedem openAI-kompatiblen Endpunkt.

        `baseUrl` sollte den vollständigen Pfad enthalten, z. B. `https://api.openai.com/v1`.

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

Wird für systemeigene Azure OpenAI-Endpunkte verwendet.

        `baseUrl` sollte nur der Host sein, z. B. `https://YOUR-RESOURCE.openai.azure.com`.

Fügen Sie /openai/v1 nicht in die URL ein – das SDK behandelt die Pfaderstellung.
```
        **Anthropic (`type: "anthropic"`)**
```
Für direkten Anthropic API-Zugriff.
Verwendet claudespezifisches API-Format.

Beispielkonfigurationen

OpenAI direct

TypeScript

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

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

Azure OpenAI (nativer Azure-Endpunkt)

Verwenden Sie type: "azure" für Endpunkte bei *.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",
    },
}

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

Ersetzen Sie YOUR-RESOURCE durch den Namen Ihrer Azure-Ressource.

Azure AI Foundry (OpenAI-kompatibler Endpunkt)

Für Azure AI Foundry-Bereitstellungen mit /openai/v1/ Endpunkten, verwenden Sie 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
}

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

TypeScript

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

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

Microsoft Entwicklungszentrum Local

          [Mit Microsoft Foundry Local](https://foundrylocal.ai) können Sie KI-Modelle lokal mit einer openAI-kompatiblen API ausführen. Installieren Sie es über das Foundry Local CLI und richten Sie das SDK dann auf Ihren lokalen Endpunkt aus.

TypeScript

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

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

Hinweis

Foundry Local startet auf einem dynamischen Port, der nicht behoben ist. Führen Sie foundry service status aus, um zu bestätigen, auf welchem Port der Dienst aktuell lauscht, und verwenden Sie diesen Port in Ihrem baseUrl.

Erste Schritte mit 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

# 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

Informationen zur MacOS/Linux-Installation finden Sie unter foundrylocal.ai.

Anthropisch

TypeScript

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

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

Bearertokenauthentifizierung

Einige Anbieter erfordern die Bearertokenauthentifizierung anstelle von API-Schlüsseln:

TypeScript

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

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

Hinweis

Die bearerToken Option akzeptiert nur eine statische Tokenzeichenfolge. Das SDK aktualisiert dieses Token nicht automatisch. Wenn Ihr Token abläuft, schlagen Anforderungen fehl, und Sie müssen eine neue Sitzung mit einem neuen Token erstellen.

Auflistung benutzerdefinierter Modelle

Bei Verwendung von BYOK weiß der CLI-Server möglicherweise nicht, welche Modelle Ihr Anbieter unterstützt. Sie können einen benutzerdefinierten onListModels Handler auf Clientebene bereitstellen, sodass die client.listModels() Modelle Ihres Anbieters im Standardformat ModelInfo zurückgegeben werden:

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 },
            },
        },
    ],
});

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 },
            },
        },
    ],
});

Die Ergebnisse werden nach dem ersten Aufruf zwischengespeichert. Der Handler ersetzt das RPC der CLI models.list vollständig – es erfolgt kein Fallback auf den Server.

Beispiele in Python, Go und .NET finden Sie unter BYOK im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

Einschränkungen

Identitätseinschränkungen

BYOK-Authentifizierung verwendet nur statische Anmeldeinformationen. Die folgenden Identitätsanbieter werden nicht unterstützt:

Microsoft Entra ID (Azure AD) – keine Unterstützung für verwaltete Entra-Identitäten oder Dienstprinzipale.
Drittanbieter-Identitätsanbieter – keine OIDC-, SAML- oder andere föderierte Identität.
Verwaltete Identitäten – Azure Managed Identity wird nicht unterstützt.

Sie müssen einen API-Schlüssel oder statisches Bearertoken verwenden, das Sie selbst verwalten.

Hinweis

Während entra ID Bearertoken ausstellen kann, sind diese Token kurzlebig (in der Regel eine Stunde) und erfordern eine automatische Aktualisierung über das Azure Identity SDK. Die bearerToken Option akzeptiert nur eine statische Zeichenfolge – es gibt keinen Rückrufmechanismus für das SDK, um frische Token anzufordern. Für lang andauernde Workloads, die eine Entra-Authentifizierung erfordern, müssen Sie Ihre eigene Logik zur Token-Aktualisierung implementieren und neue Sitzungen mit aktualisierten Tokens erstellen.

Featurebeschränkungen

Einige Copilot Features verhalten sich möglicherweise anders mit BYOK:

        **Modellverfügbarkeit**: Es sind nur Modelle verfügbar, die von Ihrem Anbieter unterstützt werden.

        **Rate Limiting**: Abhängig von den Zugriffsbeschränkungen Ihres Providers, nicht von Copilot.

        **Nutzungsnachverfolgung**: Die Nutzung wird von Ihrem Anbieter nachverfolgt, nicht GitHub.

        **Premiumanforderungen**: Werden nicht auf das Copilot Premiumanforderungskontingent angerechnet.

Anbieterspezifische Einschränkungen

Provider	Einschränkungen
Azure AI Foundry	Keine Entra-ID-Authentifizierung; müssen API-Schlüssel verwenden.
Ollama	Kein API-Schlüssel; nur lokal; Die Modellunterstützung variiert.
Microsoft Entwicklungszentrum Local	Nur lokal; Die Modellverfügbarkeit hängt von der Gerätehardware ab; kein API-Schlüssel erforderlich.
OpenAI	Vorbehaltlich der OpenAI-Zinslimits und -quoten.

Problembehandlung

Fehler "Modell nicht angegeben"

Bei Verwendung von BYOK ist der model Parameter erforderlich:

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

Verwirrung beim Azure-Endpunkttyp

Stellen Sie für Azure OpenAI-Endpunkte (*.openai.azure.com) sicher, dass Sie den richtigen Anbietertyp verwenden:

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

Wenn Ihre Azure AI Foundry-Bereitstellung einen OpenAI-kompatiblen Endpunktpfad (z. B. /openai/v1/) bereitstellt, verwenden Sie stattdessen type: "openai".

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

Verbindung verweigert (Ollama)

Stellen Sie sicher, dass Ollama ausgeführt wird und barrierefrei ist:

Bash

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

# Start Ollama if not running
ollama serve

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

# Start Ollama if not running
ollama serve

Verbindung verweigert (Foundry Local)

Foundry Local verwendet einen dynamischen Port, der sich zwischen Neustarts ändern kann. Bestätigen Sie den aktiven Port:

Bash

foundry service status

foundry service status

Aktualisieren Sie Ihr baseUrl, damit es mit dem in der Ausgabe angezeigten Port übereinstimmt. Wenn der Dienst nicht ausgeführt wird, starten Sie ein Modell, um es zu starten:

Bash

foundry model run phi-4-mini

foundry model run phi-4-mini

Fehler bei der Authentifizierung.

Überprüfen Sie, ob Der API-Schlüssel korrekt und nicht abgelaufen ist.
Überprüfen Sie, ob das baseUrl erwartete Format Ihres Anbieters entspricht.
Stellen Sie bei Bearertoken sicher, dass das vollständige Token bereitgestellt wird, nicht nur ein Präfix.

Wer kann dieses Feature verwenden?

In diesem Artikel

Unterstützte Anbieter

Schnellstart: Azure AI Foundry

Anbieterkonfigurationsreferenz

ProviderConfig-Felder

Draht-API-Format

Typspezifische Notizen

Beispielkonfigurationen

OpenAI direct

Azure OpenAI (nativer Azure-Endpunkt)

Azure AI Foundry (OpenAI-kompatibler Endpunkt)

Ollama (lokal)

Microsoft Entwicklungszentrum Local

Anthropisch

Bearertokenauthentifizierung

Auflistung benutzerdefinierter Modelle

Einschränkungen

Identitätseinschränkungen

Featurebeschränkungen

Anbieterspezifische Einschränkungen

Problembehandlung

Fehler "Modell nicht angegeben"

Verwirrung beim Azure-Endpunkttyp

Verbindung verweigert (Ollama)

Verbindung verweigert (Foundry Local)

Fehler bei der Authentifizierung.