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

# 自訂 Provider

> 說明如何在 Laravel Copilot SDK 中設定 OpenAI 相容 API、Ollama、Azure OpenAI 等 BYOK provider。

## 自訂 Provider

使用自訂 provider（BYOK - Bring Your Own Key）可以用自己的 API 金鑰連接至 OpenAI 相容的 API 端點。Ollama 等本機 provider 也支援。

## ProviderConfig

`ProviderConfig` 類別具有下列屬性。

| 屬性            | 型別             | 說明                                                      |
| ------------- | -------------- | ------------------------------------------------------- |
| `baseUrl`     | `string`       | **必填**。API 端點的 URL                                      |
| `type`        | `string\|null` | Provider 類型。`openai`（預設）、`azure`、`anthropic`            |
| `wireApi`     | `string\|null` | API 格式（僅適用 openai/azure）。`completions`（預設）或 `responses` |
| `apiKey`      | `string\|null` | API 金鑰。Ollama 等本機 provider 不需要                          |
| `bearerToken` | `string\|null` | 用於 Bearer Token 認證。優先於 `apiKey`                         |
| `azure`       | `array\|null`  | Azure 專屬選項。如 `['apiVersion' => '2024-10-21']`           |

## 基本用法

使用自訂 provider 時，`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 時必填
        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（本機 provider）

在 Ollama 等本機 provider 上，不需要 `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>
  使用自訂 provider 時 `model` 參數為必填。未指定會造成錯誤。
</Warning>

* 使用 Azure 端點（`*.openai.azure.com`）時，務必使用 `type: 'azure'`
* `baseUrl` 只需指定主機，路徑會由 SDK 自動組合

## onListModels handler

在 BYOK 模式下使用自訂 provider 時，可設定 `client->listModels()` 改為呼叫自訂 handler，而非 CLI 伺服器。

透過 `listModelsUsing()` 方法進行設定。因 client 常會被初始化，請務必在呼叫 `listModels()` 前設定 `listModelsUsing()`。

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

$models = Copilot::client()->listModelsUsing(function (): array {
    // 回傳自訂 provider 可用的模型
    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` 會解除 handler，恢復為 CLI 伺服器的預設行為。

```php theme={null}
// 解除 handler，恢復預設行為（查詢 CLI 伺服器）
$models = Copilot::client()->listModelsUsing(null)->listModels();
```

若設定了 `listModelsUsing()`，`listModels()` 就不需連接 CLI 伺服器，也不會使用快取。

<Info>
  最新資訊請參考 [GitHub 儲存庫](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [Telemetry](/zh-TW/packages/laravel-copilot-sdk/telemetry.md)
- [自訂驗證 Guard 的實作](/zh-TW/advanced/custom-auth-guard.md)
- [進階主題](/zh-TW/advanced/index.md)
- [Laravel AI Agent 支援 MCP 伺服器](/zh-TW/blog/ai-sdk-mcp-client.md)
- [Laravel Socialite（社群認證）](/zh-TW/socialite.md)