> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Proveedores personalizados

> Explica cómo configurar proveedores BYOK como APIs compatibles con OpenAI, Ollama o Azure OpenAI en Laravel Copilot SDK.

## 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**.

```php theme={null}
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.

```php theme={null}
$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.

```php theme={null}
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)

```php theme={null}
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

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

* 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()`.

```php theme={null}
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).

```php theme={null}
// 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é.

<Info>
  Consulta la información más reciente en el [repositorio de GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Crear un proveedor personalizado del AI SDK](/es/advanced/ai-sdk-custom-provider.md)
- [Socialite for Discord](/es/packages/socialite-discord.md)
- [Primeros pasos - GitHub Copilot SDK for Laravel](/es/packages/laravel-copilot-sdk/getting-started.md)
- [Agentes personalizados](/es/packages/laravel-copilot-sdk/custom-agents.md)
- [Casts personalizados de Eloquent](/es/advanced/eloquent-casts.md)