커스텀 프로바이더

커스텀 프로바이더(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 매개변수가 필수입니다.

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에는 호스트만 지정합니다(/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', // 호스트만
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

중요한 주의점

커스텀 프로바이더 사용 시 model 매개변수는 필수입니다. 지정하지 않으면 에러가 발생합니다.

Azure 엔드포인트(*.openai.azure.com)에서는 반드시 type: 'azure'를 사용하세요
baseUrl은 호스트만 지정하고, 경로 구성은 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 저장소를 참고하세요.