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
`bearerToken`	`string\|null`	Para autenticación con Bearer Token. Tiene prioridad sobre `apiKey`
`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',
            ],
        ),
    ),
);

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.