Benutzerdefinierte Provider

Mit benutzerdefinierten Providern (BYOK – Bring Your Own Key) können Sie mit eigenen API-Schlüsseln OpenAI-kompatible API-Endpunkte anbinden. Lokale Provider wie Ollama werden ebenfalls unterstützt.

ProviderConfig

Die Klasse ProviderConfig hat folgende Eigenschaften.

Eigenschaft	Typ	Beschreibung
`baseUrl`	`string`	Erforderlich. URL des API-Endpunkts
`type`	`string\|null`	Provider-Typ. `openai` (Standard), `azure`, `anthropic`
`wireApi`	`string\|null`	API-Format (nur openai/azure). `completions` (Standard) oder `responses`
`apiKey`	`string\|null`	API-Schlüssel. Für lokale Provider wie Ollama nicht erforderlich
`apiKeyCommand`	`string\|null`	Befehl, den die Copilot-Runtime vor jeder Provider-Anfrage ausführt, um einen aktuellen API-Schlüssel abzurufen. Schlägt der Befehl fehl, schlägt der Turn vor der Modellanfrage fehl. Wird nicht ausgeführt, wenn `bearerTokenProvider` angegeben ist
`bearerToken`	`string\|null`	Für Bearer-Token-Authentifizierung. Hat Vorrang vor `apiKey`
`bearerTokenProvider`	`callable\|null`	Callback, der für jede Provider-Anfrage ein Bearer-Token zurückgibt. Wird nicht serialisiert
`azure`	`array\|null`	Azure-spezifische Optionen, z. B. `['apiVersion' => '2024-10-21']`

Grundlegende Verwendung

Wenn Sie einen benutzerdefinierten Provider verwenden, ist der Parameter model erforderlich.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4', // Bei benutzerdefinierten Providern erforderlich
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

Die Angabe im Array-Format ist ebenfalls möglich.

$response = Copilot::run(
    prompt: 'Hello!',
    config: [
        'model' => 'gpt-4',
        'provider' => [
            'baseUrl' => 'https://my-api.example.com/v1',
            'apiKey' => config('services.openai.key'),
        ],
    ],
);

Ollama (lokaler Provider)

Für lokale Provider wie Ollama ist apiKey nicht erforderlich.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'deepseek-coder-v2:16b',
        provider: new ProviderConfig(
            type: 'openai',
            baseUrl: 'http://localhost:11434/v1',
        ),
    ),
);

Azure OpenAI

Beachten Sie bei der Verwendung von Azure OpenAI Folgendes.

Für type muss zwingend azure angegeben werden (nicht openai)
In baseUrl nur den Host angeben (keine Pfade wie /openai/v1 mitgeben)

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure', // Bei Azure-Endpunkten immer 'azure' angeben
            baseUrl: 'https://my-resource.openai.azure.com', // Nur der Host
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Azure Managed Identity

Verwenden Sie bearerTokenProvider, wenn Ihr Provider kurzlebige Tokens verwendet, etwa bei Azure Managed Identity. Die Runtime ruft den Callback bei jeder Provider-Anfrage auf. Der Callback erhält ein Array mit providerName und sessionId und muss das Bearer-Token als String zurückgeben. Das folgende Beispiel ruft einen Token-Service Ihrer Anwendung auf.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure',
            baseUrl: 'https://my-resource.openai.azure.com',
            azure: ['apiVersion' => '2024-10-21'],
            bearerTokenProvider: fn (array $args): string => app(AzureManagedIdentityTokenProvider::class)->getToken(),
        ),
    ),
);

Abruf, Caching und Aktualisierung des Tokens erledigen Sie innerhalb Ihres Callbacks.

API-Schlüssel-Befehl

Wenn Sie rotierende API-Schlüssel verwenden, können Sie mit apiKeyCommand vor jeder Provider-Anfrage einen Befehl ausführen, der den aktuellen Schlüssel abruft. Der Befehl wird von der Copilot-Runtime ausgeführt, nicht von diesem Paket.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKeyCommand: config('services.my_api.key_command'),
        ),
    ),
);

apiKeyCommand muss null oder ein nicht leerer String sein. Bei einem leeren String oder einem String nur aus Leerzeichen wird vor dem Senden der Anfrage eine InvalidArgumentException ausgelöst. Auch wenn Sie im Array-Format einen Nicht-String angeben, wird eine InvalidArgumentException ausgelöst. Übergeben Sie dem ProviderConfig-Konstruktor einen Nicht-String, löst die PHP-Typprüfung einen TypeError aus. Die Ausnahmemeldung enthält den Befehl nicht.
Ein Fehlschlagen des Befehls wird von der Runtime als fehlgeschlagener Turn behandelt, und es wird keine Anfrage an das Modell gesendet.
Wenn bearerTokenProvider angegeben ist, hat dieser Vorrang, und apiKeyCommand wird nicht ausgeführt.
Behandeln Sie den Befehls-String wie Zugangsdaten als vertraulich und geben Sie ihn nicht in Logs oder Ausnahmemeldungen aus. Auch dieses Paket protokolliert weder den Befehl noch dessen Ausgabe.
apiKeyCommand ist nur in ProviderConfig verfügbar (in NamedProviderConfig nicht unterstützt).

Wichtige Hinweise

Bei Verwendung eines benutzerdefinierten Providers ist der Parameter model erforderlich. Ohne Angabe kommt es zu einem Fehler.

Verwenden Sie bei Azure-Endpunkten (*.openai.azure.com) unbedingt type: 'azure'
Geben Sie in baseUrl nur den Host an; die Pfadbildung übernimmt das SDK automatisch

onListModels-Handler

Wenn Sie im BYOK-Modus einen benutzerdefinierten Provider einsetzen, können Sie client->listModels() so konfigurieren, dass statt des CLI-Servers ein benutzerdefinierter Handler aufgerufen wird. Konfigurieren Sie ihn mit der Methode listModelsUsing(). Da der Client leicht initialisiert wird, setzen Sie listModelsUsing() stets vor listModels().

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ModelInfo;

$models = Copilot::client()->listModelsUsing(function (): array {
    // Die im benutzerdefinierten Provider verfügbaren Modelle zurückgeben
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Bei Übergabe von null wird der Handler aufgehoben, und das Standardverhalten des CLI-Servers wird wiederhergestellt.

// Handler aufheben und zum Standardverhalten (Abfrage am CLI-Server) zurückkehren
$models = Copilot::client()->listModelsUsing(null)->listModels();

Wenn listModelsUsing() konfiguriert ist, benötigt listModels() keine Verbindung zum CLI-Server und verwendet auch keinen Cache.

Aktuelle Informationen finden Sie im GitHub-Repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds und RSS

Middleware

Benutzerdefinierte Provider