> ## 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 key 连接到 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 key。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` 只指定 host（不包含 `/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', // 仅 host
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);
```

## 重要注意事项

<Warning>
  使用自定义提供商时，`model` 参数是必需的。不指定会报错。
</Warning>

* 在 Azure 端点（`*.openai.azure.com`）上，请务必使用 `type: 'azure'`
* `baseUrl` 只指定 host，路径的构建由 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>


## Related topics

- [Laravel Socialite（社交登录）](/zh/socialite.md)
- [Telemetry](/zh/packages/laravel-copilot-sdk/telemetry.md)
- [服务提供者](/zh/service-providers.md)
- [快速开始 - GitHub Copilot SDK for Laravel](/zh/packages/laravel-copilot-sdk/getting-started.md)
- [认证 - GitHub Copilot SDK for Laravel](/zh/packages/laravel-copilot-sdk/auth.md)