Custom providers

Met custom providers (BYOK - Bring Your Own Key) kun je met je eigen API-sleutel verbinding maken met OpenAI-compatibele API-endpoints. Lokale providers zoals Ollama worden ook ondersteund.

ProviderConfig

De klasse ProviderConfig heeft de volgende properties.

Property	Type	Beschrijving
`baseUrl`	`string`	Verplicht. De URL van het API-endpoint
`type`	`string\|null`	Providertype. `openai` (standaard), `azure`, `anthropic`
`wireApi`	`string\|null`	API-formaat (alleen openai/azure). `completions` (standaard) of `responses`
`apiKey`	`string\|null`	API-sleutel. Niet nodig voor lokale providers zoals Ollama
`apiKeyCommand`	`string\|null`	Commando dat de Copilot-runtime vóór elke providerrequest uitvoert om een actuele API-sleutel op te halen. Als het commando mislukt, mislukt de beurt vóór de modelrequest. Wordt niet uitgevoerd als `bearerTokenProvider` is opgegeven
`bearerToken`	`string\|null`	Voor Bearer Token-authenticatie. Heeft voorrang op `apiKey`
`bearerTokenProvider`	`callable\|null`	Callback die voor elke providerrequest een bearer token retourneert. Wordt niet geserialiseerd
`azure`	`array\|null`	Azure-specifieke opties, zoals `['apiVersion' => '2024-10-21']`

Basisgebruik

Wanneer je een custom provider gebruikt, is de parameter model verplicht.

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', // Verplicht bij gebruik van een custom provider
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

Je kunt dit ook als array opgeven.

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

Ollama (lokale provider)

Voor lokale providers zoals Ollama is geen apiKey nodig.

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

Let bij het gebruik van Azure OpenAI op de volgende punten.

Geef voor type altijd azure op (niet openai)
Geef in baseUrl alleen de host op (geen paden zoals /openai/v1)

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', // Geef voor Azure-endpoints altijd 'azure' op
            baseUrl: 'https://my-resource.openai.azure.com', // Alleen de host
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Azure Managed Identity

Gebruik bearerTokenProvider als je provider kortlevende tokens gebruikt, zoals bij Azure Managed Identity. De runtime roept de callback aan bij elke providerrequest. De callback ontvangt een array met providerName en sessionId, en moet de bearer token als string retourneren. Het volgende voorbeeld roept een tokenservice in je applicatie aan.

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

Regel het ophalen, cachen en vernieuwen van tokens binnen je callback.

API-sleutelcommando

Gebruik je API-sleutels die worden geroteerd, dan kun je met apiKeyCommand vóór elke providerrequest een commando laten uitvoeren dat de actuele sleutel ophaalt. Het commando wordt uitgevoerd door de Copilot-runtime, niet door dit package.

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 moet null zijn of een string die niet leeg is. Bij een lege string of een string met alleen witruimte wordt er een InvalidArgumentException gegooid voordat de request wordt verstuurd. Ook een niet-string-waarde in de array-vorm leidt tot een InvalidArgumentException. Geef je een niet-string-waarde door aan de ProviderConfig-constructor, dan levert de typecontrole van PHP een TypeError op. De exceptionmelding bevat het commando niet.
Als het commando mislukt, behandelt de runtime dit als een mislukte beurt en wordt er geen request naar het model verstuurd.
Als bearerTokenProvider is opgegeven, heeft die voorrang en wordt apiKeyCommand niet uitgevoerd.
Behandel de commandostring net zo vertrouwelijk als inloggegevens en schrijf hem niet naar logs of exceptionmeldingen. Ook dit package logt het commando en de uitvoer ervan niet.
apiKeyCommand is alleen beschikbaar in ProviderConfig (niet ondersteund in NamedProviderConfig).

Belangrijke aandachtspunten

Bij gebruik van een custom provider is de parameter model verplicht. Zonder deze parameter krijg je een foutmelding.

Gebruik voor Azure-endpoints (*.openai.azure.com) altijd type: 'azure'
Geef in baseUrl alleen de host op; de SDK bouwt het pad automatisch op

onListModels-handler

Als je een custom provider in BYOK-modus gebruikt, kun je instellen dat client->listModels() een custom handler aanroept in plaats van de CLI-server. Dit configureer je met de methode listModelsUsing(). Omdat de client makkelijk al geïnitialiseerd raakt, moet je listModelsUsing() altijd vóór listModels() instellen.

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

$models = Copilot::client()->listModelsUsing(function (): array {
    // Retourneer de modellen die beschikbaar zijn bij de custom provider
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Geef null door om de handler te verwijderen en terug te keren naar het standaardgedrag van de CLI-server.

// Verwijder de handler en keer terug naar het standaardgedrag (opvragen bij de CLI-server)
$models = Copilot::client()->listModelsUsing(null)->listModels();

Wanneer listModelsUsing() is ingesteld, heeft listModels() geen verbinding met de CLI-server nodig en wordt er ook geen cache gebruikt.

Raadpleeg de GitHub-repository voor de meest actuele informatie.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

Custom providers