> ## 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 키로 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` 매개변수가 **필수**입니다.

```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`에는 호스트만 지정합니다(`/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>
  커스텀 프로바이더 사용 시 `model` 매개변수는 필수입니다. 지정하지 않으면 에러가 발생합니다.
</Warning>

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

- [Telemetry](/ko/packages/laravel-copilot-sdk/telemetry.md)
- [AI SDK의 커스텀 프로바이더 만들기](/ko/advanced/ai-sdk-custom-provider.md)
- [서비스 프로바이더](/ko/service-providers.md)
- [GeneratorCommand — 커스텀 make: 명령어 구현](/ko/advanced/generator-command.md)
- [Laravel Socialite (소셜 인증)](/ko/socialite.md)