自定义提供商

使用自定义提供商（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 等本地提供商不需要
`apiKeyCommand`	`string\|null`	在每次提供商请求前由 Copilot 运行时执行、用于获取最新 API key 的命令。命令失败时，该轮次会在发送模型请求前失败。指定了 `bearerTokenProvider` 时不会执行
`bearerToken`	`string\|null`	Bearer Token 认证用。优先级高于 `apiKey`
`bearerTokenProvider`	`callable\|null`	为每次提供商请求返回 Bearer Token 的回调。不会被序列化
`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',
            ],
        ),
    ),
);

Azure Managed Identity

当提供商使用 Azure Managed Identity 等短期有效的令牌时，请使用 bearerTokenProvider。运行时会在每次提供商请求时调用该回调。回调会接收一个包含 providerName 和 sessionId 的数组，并且必须以字符串形式返回 Bearer Token。以下示例调用了应用中的令牌服务。

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',
            baseUrl: 'https://my-resource.openai.azure.com',
            azure: ['apiVersion' => '2024-10-21'],
            bearerTokenProvider: fn (array $args): string => app(AzureManagedIdentityTokenProvider::class)->getToken(),
        ),
    ),
);

请在回调内部处理令牌的获取、缓存和刷新。

API key 命令

使用会轮换的 API key 时，可以通过 apiKeyCommand 在每次提供商请求前执行命令以获取最新的 key。该命令由 Copilot 运行时执行，而不是由本包执行。

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',
            apiKeyCommand: config('services.my_api.key_command'),
        ),
    ),
);

apiKeyCommand 必须是 null 或非空白字符串。如果是空字符串或仅包含空白，会在发送请求前抛出 InvalidArgumentException。在数组形式中指定非字符串值时也会抛出 InvalidArgumentException。向 ProviderConfig 构造函数传入非字符串值时，PHP 的类型检查会抛出 TypeError。异常消息中不会包含命令内容。
命令失败会在运行时侧被视为该轮次失败，不会向模型发送请求。
指定 bearerTokenProvider 时以其为优先，apiKeyCommand 不会被执行。
请像对待凭据一样将命令字符串视为敏感信息，不要将其输出到日志或异常消息中。本包也不会在日志中记录命令或其输出。
apiKeyCommand 仅可在 ProviderConfig 中使用（NamedProviderConfig 不支持）。

重要注意事项

使用自定义提供商时，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 仓库。

GitHub Copilot

SDK

AI SDK

VOICEVOX

启动套件

Feed 与 RSS

中间件

自定义提供商