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

# カスタムプロバイダー

> Laravel Copilot SDK で OpenAI互換 API、Ollama、Azure OpenAI などの BYOK プロバイダーを設定する方法を説明します。

## カスタムプロバイダー

カスタムプロバイダー（BYOK - Bring Your Own Key）を使用すると、独自の API キーで OpenAI 互換の API エンドポイントに接続できます。Ollama などのローカルプロバイダーもサポートしています。

## ProviderConfig

`ProviderConfig` クラスは以下のプロパティを持ちます。

| プロパティ         | 型              | 説明                                                           |
| ------------- | -------------- | ------------------------------------------------------------ |
| `baseUrl`     | `string`       | **必須**。APIエンドポイントのURL                                        |
| `type`        | `string\|null` | プロバイダータイプ。`openai`（デフォルト）、`azure`、`anthropic`                |
| `wireApi`     | `string\|null` | APIフォーマット（openai/azureのみ）。`completions`（デフォルト）または`responses` |
| `apiKey`      | `string\|null` | APIキー。Ollamaなどのローカルプロバイダーでは不要                                |
| `bearerToken` | `string\|null` | Bearer Token認証用。`apiKey`より優先される                              |
| `azure`       | `array\|null`  | Azure固有のオプション。`['apiVersion' => '2024-10-21']`など             |

## 基本的な使い方

カスタムプロバイダーを使用する場合、`model` パラメータは**必須**です。

```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(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);
```

配列形式でも指定可能です。

```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（ローカルプロバイダー）

Ollama などのローカルプロバイダーでは `apiKey` は不要です。

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

Azure OpenAI を使用する場合、以下の点に注意してください。

* `type` は必ず `azure` を指定（`openai` ではなく）
* `baseUrl` にはホストのみを指定（`/openai/v1` などのパスは含めない）

```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', // Azureエンドポイントでは必ず'azure'を指定
            baseUrl: 'https://my-resource.openai.azure.com', // ホストのみ
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);
```

## 重要な注意点

<Warning>
  カスタムプロバイダー使用時は `model` パラメータが必須です。指定しないとエラーになります。
</Warning>

* Azureエンドポイント（`*.openai.azure.com`）では、必ず `type: 'azure'` を使用してください
* `baseUrl` はホストのみを指定し、パスの構築は SDK が自動的に行います

## onListModels ハンドラー

BYOK モードでカスタムプロバイダーを使用している場合、`client->listModels()` が CLI サーバーではなくカスタムハンドラーを呼び出すように設定できます。

`listModelsUsing()` メソッドを使って設定します。client は初期化されやすいため、`listModels()` の前に常に `listModelsUsing()` を設定してください。

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ModelInfo;

$models = Copilot::client()->listModelsUsing(function (): array {
    // カスタムプロバイダーで利用可能なモデルを返す
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();
```

`null` を渡すとハンドラーを解除してデフォルトの CLI サーバー動作に戻ります。

```php theme={null}
// ハンドラーを解除してデフォルト動作（CLIサーバーに問い合わせ）に戻す
$models = Copilot::client()->listModelsUsing(null)->listModels();
```

`listModelsUsing()` が設定されている場合、`listModels()` は CLI サーバーへの接続を必要とせず、キャッシュも使用しません。

<Info>
  最新情報は [GitHub リポジトリ](https://github.com/invokable/laravel-copilot-sdk) を参照してください。
</Info>