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

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