Provider personalizzati

Utilizzando un provider personalizzato (BYOK - Bring Your Own Key), puoi collegarti a endpoint API compatibili con OpenAI usando la tua chiave. Sono supportati anche provider locali come Ollama.

ProviderConfig

La classe ProviderConfig ha le seguenti proprietà.

Proprietà	Tipo	Descrizione
`baseUrl`	`string`	Obbligatorio. URL dell’endpoint API
`type`	`string\|null`	Tipo di provider. `openai` (default), `azure`, `anthropic`
`wireApi`	`string\|null`	Formato API (solo openai/azure). `completions` (default) o `responses`
`apiKey`	`string\|null`	API key. Non necessaria per provider locali come Ollama
`apiKeyCommand`	`string\|null`	Comando eseguito dal runtime Copilot prima di ogni richiesta al provider per ottenere l’API key più recente. Se il comando fallisce, il turno fallisce prima della richiesta al modello. Non viene eseguito se è specificato `bearerTokenProvider`
`bearerToken`	`string\|null`	Per autenticazione Bearer Token. Ha priorità su `apiKey`
`bearerTokenProvider`	`callable\|null`	Callback che restituisce un bearer token per ogni richiesta al provider. Non viene serializzato
`azure`	`array\|null`	Opzioni specifiche per Azure. Ad esempio `['apiVersion' => '2024-10-21']`

Uso di base

Quando usi un provider personalizzato, il parametro model è obbligatorio.

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', // obbligatorio con provider personalizzato
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

Puoi specificarlo anche come array.

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

Ollama (provider locale)

Per provider locali come Ollama, apiKey non è necessaria.

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

Quando usi Azure OpenAI, tieni presente quanto segue.

Specifica sempre type come azure (non openai)
Indica in baseUrl solo l’host (non includere path come /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', // con endpoint Azure specifica sempre 'azure'
            baseUrl: 'https://my-resource.openai.azure.com', // solo host
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Azure Managed Identity

Usa bearerTokenProvider quando il provider utilizza token di breve durata, come Azure Managed Identity. Il runtime chiama il callback a ogni richiesta al provider. Il callback riceve un array contenente providerName e sessionId e deve restituire il bearer token come stringa. L’esempio seguente chiama un servizio di token della tua applicazione.

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

Gestisci l’ottenimento, la memorizzazione nella cache e il rinnovo del token all’interno del callback.

Comando per l’API key

Se usi API key soggette a rotazione, con apiKeyCommand puoi eseguire un comando prima di ogni richiesta al provider per ottenere la chiave più recente. Il comando viene eseguito dal runtime Copilot, non da questo pacchetto.

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 deve essere null oppure una stringa non vuota. Una stringa vuota o composta solo da spazi solleva InvalidArgumentException prima dell’invio della richiesta. Anche un valore non stringa nel formato array solleva InvalidArgumentException. Passando un valore non stringa al costruttore di ProviderConfig, il controllo dei tipi di PHP solleva un TypeError. Il messaggio dell’eccezione non include il comando.
Il fallimento del comando viene trattato dal runtime come fallimento del turno e nessuna richiesta viene inviata al modello.
Se specifichi bearerTokenProvider, questo ha la priorità e apiKeyCommand non viene eseguito.
Tratta la stringa del comando come riservata, al pari delle credenziali, e non riportarla nei log o nei messaggi di eccezione. Anche questo pacchetto non registra nei log il comando né il suo output.
apiKeyCommand è disponibile solo in ProviderConfig (non supportato in NamedProviderConfig).

Considerazioni importanti

Quando usi un provider personalizzato, il parametro model è obbligatorio. Se non lo specifichi, otterrai un errore.

Per gli endpoint Azure (*.openai.azure.com) usa sempre type: 'azure'
Specifica in baseUrl solo l’host; la costruzione del path è gestita automaticamente dall’SDK

Handler onListModels

Se usi un provider personalizzato in modalità BYOK, puoi configurare client->listModels() in modo che invochi un handler personalizzato invece del server CLI. Configuralo con il metodo listModelsUsing(). Poiché il client tende a essere già inizializzato, imposta sempre listModelsUsing() prima di listModels().

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

$models = Copilot::client()->listModelsUsing(function (): array {
    // Restituisce i modelli disponibili dal provider personalizzato
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Passando null rimuovi l’handler e torni al comportamento predefinito del server CLI.

// Rimuove l'handler e torna al comportamento predefinito (query al server CLI)
$models = Copilot::client()->listModelsUsing(null)->listModels();

Se listModelsUsing() è impostato, listModels() non richiede una connessione al server CLI e non usa la cache.

Per le informazioni più recenti fai riferimento al repository GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

Provider personalizzati