自定义提供商

使用自定义提供商（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 参数是 必需的。

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'),
        ),
    ),
);

也可以用数组形式指定。

$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。

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 等路径）

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',
            ],
        ),
    ),
);

重要注意事项

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

在 Azure 端点（*.openai.azure.com）上，请务必使用 type: 'azure'
baseUrl 只指定 host，路径的构建由 SDK 自动完成

onListModels 处理器

在 BYOK 模式下使用自定义提供商时，可以配置让 client->listModels() 调用自定义处理器而不是 CLI 服务器。使用 listModelsUsing() 方法进行配置。由于 client 容易被初始化，因此请始终在 listModels() 之前设置 listModelsUsing()。

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 服务器行为。

// 解除处理器，回到默认行为（询问 CLI 服务器）
$models = Copilot::client()->listModelsUsing(null)->listModels();

设置了 listModelsUsing() 时，listModels() 不需要连接 CLI 服务器，也不使用缓存。

最新信息请参考 GitHub 仓库。