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

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