Proveedores personalizados

Los proveedores personalizados (BYOK - Bring Your Own Key) permiten conectarse a endpoints de API compatibles con OpenAI usando tu propia API key. También admite proveedores locales como Ollama.

ProviderConfig

La clase ProviderConfig tiene las siguientes propiedades:

Propiedad	Tipo	Descripción
`baseUrl`	`string`	Obligatoria. URL del endpoint de la API
`type`	`string\|null`	Tipo de proveedor. `openai` (por defecto), `azure` o `anthropic`
`wireApi`	`string\|null`	Formato de API (solo openai/azure). `completions` (por defecto) o `responses`
`apiKey`	`string\|null`	API key. No es necesaria para proveedores locales como Ollama
`apiKeyCommand`	`string\|null`	Comando que el runtime de Copilot ejecuta antes de cada solicitud al proveedor para obtener la API key más reciente. Si el comando falla, el turno falla antes de la solicitud al modelo. No se ejecuta si indicas `bearerTokenProvider`
`bearerToken`	`string\|null`	Para autenticación con Bearer Token. Tiene prioridad sobre `apiKey`
`bearerTokenProvider`	`callable\|null`	Callback que devuelve un bearer token para cada solicitud al proveedor. No se serializa
`azure`	`array\|null`	Opciones específicas de Azure. Por ejemplo `['apiVersion' => '2024-10-21']`

Uso básico

Cuando usas un proveedor personalizado, el parámetro model es obligatorio.

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', // obligatorio al usar un proveedor personalizado
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

También puedes indicarlo como array.

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

Ollama (proveedor local)

Para proveedores locales como Ollama, apiKey no es necesaria.

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

Para usar Azure OpenAI, ten en cuenta lo siguiente:

Indica siempre type como azure (no openai)
En baseUrl indica solo el host (no incluyas la ruta /openai/v1 u otras)

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', // para endpoints Azure, indica siempre 'azure'
            baseUrl: 'https://my-resource.openai.azure.com', // solo el host
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Azure Managed Identity

Usa bearerTokenProvider cuando tu proveedor utilice tokens de corta duración, como Azure Managed Identity. El runtime llama al callback en cada solicitud al proveedor. El callback recibe un array que contiene providerName y sessionId, y debe devolver el bearer token como string. El siguiente ejemplo llama a un servicio de tokens de tu aplicación.

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

Gestiona la obtención, el almacenamiento en caché y la renovación del token dentro del callback.

Comando de API key

Si usas API keys que rotan, con apiKeyCommand puedes ejecutar un comando antes de cada solicitud al proveedor para obtener la key más reciente. El comando lo ejecuta el runtime de Copilot, no este paquete.

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 debe ser null o una cadena que no esté en blanco. Si es una cadena vacía o solo contiene espacios, se lanza InvalidArgumentException antes de enviar la solicitud. También se lanza InvalidArgumentException si en el formato de array indicas un valor que no es una cadena. Si pasas un valor que no es una cadena al constructor de ProviderConfig, la comprobación de tipos de PHP lanza un TypeError. Los mensajes de excepción no incluyen el comando.
El runtime trata un fallo del comando como un fallo del turno, y no se envía ninguna solicitud al modelo.
Si indicas bearerTokenProvider, este tiene prioridad y apiKeyCommand no se ejecuta.
Trata la cadena del comando como información sensible, igual que las credenciales, y no la escribas en logs ni en mensajes de excepción. Este paquete tampoco registra el comando ni su salida.
apiKeyCommand solo está disponible en ProviderConfig (no es compatible con NamedProviderConfig).

Consideraciones importantes

Al usar un proveedor personalizado, el parámetro model es obligatorio. Si no lo indicas, se produce un error.

En endpoints de Azure (*.openai.azure.com), usa siempre type: 'azure'
Indica en baseUrl solo el host; el SDK construye la ruta automáticamente

Handler `onListModels`

Cuando usas un proveedor personalizado en modo BYOK, puedes hacer que client->listModels() invoque un handler personalizado en lugar del servidor CLI. Se configura con el método listModelsUsing(). Como el client es fácil de inicializar, define siempre listModelsUsing() antes de listModels().

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

$models = Copilot::client()->listModelsUsing(function (): array {
    // Devuelve los modelos disponibles en el proveedor personalizado
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Pasando null se elimina el handler y se vuelve al comportamiento por defecto (consultar al servidor CLI).

// Elimina el handler y vuelve al comportamiento por defecto (consulta al servidor CLI)
$models = Copilot::client()->listModelsUsing(null)->listModels();

Si tienes definido listModelsUsing(), listModels() no necesita conexión con el servidor CLI ni usa la caché.

Consulta la información más reciente en el repositorio de GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds y RSS

Middleware

Proveedores personalizados