# GitHub Copilot CLI에 LLM 모델 추가하기
Copilot CLI에서 원하는 원격 또는 로컬 모델을 사용합니다.
Copilot CLI에 모델을 추가할 수 있는 다양한 방법이 있습니다.
* **Ollama**: Copilot CLI 컴퓨터에서 실행되는 Ollama에서 제공하는 모델을 자동으로 감지하고 모델 선택기에서 이러한 모델을 추가할 수 있습니다.
* **수동으로 구성된 모델 공급자**: 구성 파일에서 사용자 고유의 자격 증명을 지정하여 외부 모델 공급자를 추가합니다. 이 메서드는 BYOK(Bring Your Own Key)라고도 합니다.
* **로컬 설치MAI Code 1.1 Flash**: 필요한 시스템 사양을 가진 Windows 사용자는 모델 선택기에서 직접 이 모델을 설치하고 로컬 컴퓨터에서 실행할 수 있습니다.
> [!NOTE]
> 이 문서에서는 사용자 지정 모델을 사용자 고유의 용도로 구성하는 방법을 설명합니다. 조직 또는 엔터프라이즈의 사용자에 대한 사용자 지정 모델을 설정하려면 [AUTOTITLE 및 AUTOTITLE](/ko/copilot/how-tos/administer-copilot/manage-for-organization/enable-custom-models) 을 참조 [하세요](/ko/copilot/how-tos/administer-copilot/manage-for-enterprise/enable-custom-models).
## 모델 요구 사항
**도구 호출**(함수 호출이라고도 함) 및 **스트리밍을** 지원하는 모델 및 엔드포인트를 선택합니다. 이러한 기능을 사용하면 Copilot CLI가 도구를 사용하고 응답이 도착하는 대로 표시할 수 있습니다.
특히 더 작은 로컬 모델의 경우 모델과 일치하도록 토큰 제한을 구성합니다. 알 수 없는 모델의 경우 Copilot CLI 기본 제한이 128,000개의 프롬프트 토큰으로 설정될 수 있으며, 이는 모델의 실제 용량을 초과할 수 있습니다. 더 높은 제한을 설정해도 모델의 컨텍스트 창이 증가하지는 않습니다.
## Ollama에서 모델 추가
Ollama가 로컬 컴퓨터에서 실행 중이고 모델을 이미 다운로드한 경우 Copilot CLI가 해당 모델을 감지하고 모델 선택기에서 추가할 수 있도록 합니다.
### 전제 조건
로컬 컴퓨터에 Ollama를 이미 설치했고 하나 이상의 모델을 다운로드해 두어야 합니다. 자세한 내용은 [Ollama 웹 사이트에서 Ollama 다운로드](https://ollama.com/download) 를 참조하세요.
### 모델 추가
1. 대화형 세션에서 `/model`를 입력합니다.
2. "로컬 및 자체 호스팅"에서 Ollama 제공 모델을 찾으세요.
Ollama에서 다운로드했지만 아직 추가되지 않은 모든 모델은 "Discovered" 상태로 표시됩니다.
3. 검색된 모델을 선택하고 Enter 키를 누릅니다.
4. **이 세션에서 추가 후 사용**을 선택하여 모델로 전환하거나 **전환하지 않고 추가**를 선택하여 현재 모델을 계속 사용하세요.
5. Esc 키를 눌러 선택기를 종료합니다.
CLI는 이후 세션에서 사용할 수 있도록 모델 세부 정보를 `providers.json` 파일에 저장합니다.
> [!NOTE]
> Copilot는 기본적으로 `http://127.0.0.1:11434`에서 Ollama를 확인합니다. Ollama가 다른 로컬 주소 또는 포트를 사용하는 경우 CLI를 시작하기 전에 `OLLAMA_HOST`를 설정합니다. 자동 검색은 현재 사용 중인 컴퓨터의 주소만 확인합니다. 다른 컴퓨터의 Ollama 서버의 경우 공급자 구성 파일을 대신 사용합니다.
## 모델 공급자 구성 수동 추가
Ollama 이외의 모델 공급자를 사용하려면 공급자 세부 정보를 `providers.json` 파일에 수동으로 추가해야 합니다.
### 전제 조건
인증이 필요한 모델 공급자를 추가하려면 API 키가 있어야 합니다.
### 지원되는 공급자
모델 공급자의 API에 대한 연결의 경우 다음 공급자 유형을 사용할 수 있습니다.
| 공급자 유형 | 호환되는 서비스 |
| ----------- | ---------------------------------------------------------------------------------- |
| `openai` | OpenAI 및 Ollama, vLLM, Foundry Local과 같은 OpenAI 호환 API를 사용하는 서비스입니다. 기본 공급자 유형입니다. |
| `azure` | Azure OpenAI Service. |
| `anthropic` | Anthropic (클로드 모델) |
### 공급자 및 모델 추가
`providers.json` 파일은 구성된 공급자 및 모델의 세부 정보를 저장합니다. 일반적으로 사용자의 CLI 구성 디렉터리(`~/.copilot`)에 있습니다. CLI를 시작하기 전에 `COPILOT_PROVIDERS_CONFIG`를 해당 파일의 경로로 설정하여 다른 파일을 사용할 수 있습니다.
`providers.json` 파일에서 구성한 모델은 계정에서 사용할 수 있는 GitHub에서 제공하는 모델과 함께 CLI의 모델 선택기에서 사용할 수 있습니다.
> [!IMPORTANT]
> 이 파일에 입력된 자격 증명은 일반 텍스트로 저장됩니다. 파일을 비공개로 유지하고 리포지토리에 커밋하거나 공유하지 마세요. JSON에서 `$MY_API_KEY`와 같은 값은 사용자 환경에서 읽지 않고 리터럴 텍스트로 처리됩니다.
1. `providers.json`을(를) 열거나, 없으면 만듭니다. 공급자 및 모델을 추가합니다. 예를 들어 이 구성은 OpenAI 모델 공급자와 하나의 모델을 추가합니다.
```json
{
"providers": [
{
"name": "my-provider",
"type": "openai",
"baseUrl": "https://api.openai.com/v1",
"apiKey": "YOUR-API-KEY"
}
],
"models": [
{
"id": "YOUR-MODEL-NAME",
"provider": "my-provider"
}
]
}
```
`YOUR-MODEL-NAME`를 공급자의 API 키로, `YOUR-API-KEY`를 계정에서 사용할 수 있는 모델 이름으로 바꾸세요. 다른 OpenAI 호환 공급자의 경우 `baseUrl`를 해당 API URL로 변경합니다. 공급자가 인증을 요구하지 않으면 `apiKey`을 생략합니다.
파일에 공급자 및 모델이 이미 포함되어 있는 경우 기존 데이터를 바꾸는 대신 기존 데이터에 추가합니다.
추가 설정이 필요한 공급자 또는 모델의 경우:
* 공급자의 `type`를 Azure OpenAI의 경우 `azure`, Anthropic의 경우 `anthropic`로 설정하고 해당 공급자의 API URL 및 자격 증명을 사용합니다.
* 응답 API를 사용하는 OpenAI 또는 Azure 모델의 경우 공급자에 `"wireApi": "responses"`를 추가합니다. 기본값은 `completions`입니다.
* Azure 배포의 경우 모델의 `wireModel`을(를) 배포 이름으로, `modelId`을(를) 배포한 모델의 이름으로 설정합니다. 특정 API 버전이 필요한 경우 프로바이더에 `"azure": { "apiVersion": "YOUR-API-VERSION" }`를 추가합니다.
`YOUR-API-VERSION`를 엔드포인트에 필요한 버전으로 바꿉니다.
* 모델의 `id`가 공급자가 허용한 이름이 아니라 사용자가 선택한 이름인 경우, `wireModel`을 공급자의 모델 이름으로 설정합니다.
`modelId`를 CLI에서 인식하는 모델 이름으로 설정하여 해당 모델의 기능과 제한을 사용할 수 있도록 하세요.
* 지원되는 제한에 맞게 모델에서 `maxOutputTokens` 및 `maxPromptTokens`을 설정합니다. 0보다 큰 정수를 사용합니다.
* API 키 대신 베어러 토큰으로 인증하려면 `bearerToken`를 공급자에 설정합니다.
이 파일에서 다른 많은 매개 변수를 구성할 수 있습니다. 자세한 내용은 [GITHUB COPILOT CLI 구성 디렉터리](/ko/copilot/reference/copilot-cli-reference/cli-config-dir-reference#providersjson)을(를) 참조하세요.
1. 동일한 공급자의 다른 모델을 추가하려면 `id`에 다른 `provider` 및 동일한 `models`를 사용하여 항목을 하나 더 추가합니다.
> [!NOTE]
> 각 모델의 `provider` 값은 공급자의 `name`와 일치해야 합니다.
2. 다른 공급자를 추가하려면 `name`에 고유한 `providers`로 항목을 추가한 다음 해당 모델을 추가합니다.
3. 파일을 저장하고 CLI를 다시 시작합니다.
4. 세션을 시작할 때 예제 모델을 선택하려면 다음을 실행합니다.
```shell
copilot --model PROVIDER-NAME/MODEL-NAME
```
5. 세션 중에 모델을 전환하려면 슬래시 명령을 사용합니다 `/model` . 자세한 내용은 [GitHub Copilot CLI에서 모델 선택](/ko/copilot/how-tos/copilot-cli/use-copilot-cli/choose-a-model)을(를) 참조하세요.
6. 저장된 구성에서 공급자 로드를 중지하려면 `providers`에서 해당 공급자 항목을 제거하고 `models`에서 해당 모델 항목을 제거한 다음 CLI를 다시 시작합니다. 현재 기본 모델을 제거하기 전에 `/model --global` 다른 기본값을 선택하세요.
## 모델 선택기에서 로컬 모델 설치
> [!NOTE]
> 이 기능은 공개 미리 보기에 있으며 변경될 수 있습니다. 이 기능을 사용하려면 CLI를 `--experimental` 옵션으로 시작하거나 대화형 세션에서 `/experimental on`를 사용하여 현재 및 이후 세션에 대해 이 기능 및 기타 실험적 기능을 사용하도록 설정할 수 있습니다.
Windows를 사용하고 컴퓨터가 다음 필수 조건을 충족하는 경우 CLI의 모델 선택기를 사용하여 디바이스에서 다음 모델을 로컬로 설치하고 실행할 수 있습니다.
* MAI Code 1.1 Flash
* Flint NVFP4
### Prerequisites
필요한 것은 다음과 같습니다.
* Windows PC 한 대
* NVIDIA GPU(AMD는 지원되지 않음)
* 모델당 사용 가능한 최소 결합 RAM:
* **MAI Code 1.1 Flash:** 96GB
* **Flint NVFP4:** 48GB
* 모델당 사용 가능한 최소 스토리지:
* **MAI Code 1.1 Flash:** 60GB
* **Flint NVFP4:** 23GB
* llama.cpp v0.7.0 이상이 설치되어 있고 `LLAMACPP_SERVER_PATH`가 해당 경로로 설정되어 있어야 합니다. 필수 빌드 버전:
* **MAI Code 1.1 Flash:** [b11669](https://github.com/ggml-org/llama.cpp/releases/tag/b11669?utm_source=local-model-prereq-mai-code\&utm_medium=docs\&utm_campaign=universe-2026) 이상
* **Flint NVFP4:** [b11803](https://github.com/ggml-org/llama.cpp/releases?q=flint\&expanded=true\&utm_source=local-model-prerequisite-flint\&utm_medium=docs\&utm_campaign=universe-2026#release-b11803) 이상
[Windows llama.cpp 설치를](#installing-llamacpp-for-windows) 참조하세요.
### 로컬 사용 MAI Code 1.1 Flash 의 이점
MAI Code 1.1 Flash는 Windows PC에서 로컬로 실행할 수 있는 코딩 최적화 모델입니다. 로컬로 실행되는 모델을 사용하면 Copilot를 오프라인으로 사용할 수 있고 GitHub AI Credits를 소비하지 않을 수 있습니다.
MAI Code 1.1 Flash를 설치한 후 다른 모델과 마찬가지로 모델 선택기에서 선택할 수 있습니다. 모델도 Fusion Standard의 Copilot Fusion 노력 수준에서 사용할 수 있게 됩니다. 모델 선택을 Fusion Standard와 함께 **Copilot Fusion**(으)로 설정하면, 적절한 작업을 처리하도록 MAI Code 1.1 Flash가 자동으로 선택되며, 더 많은 리소스 또는 더 높은 성능이 필요한 작업은 클라우드 기반 모델에 맡기게 됩니다.
### Windows llama.cpp 설치
CUDA 빌드를 사용하여 Windows llama.cpp 설치하려면 다음을 수행합니다.
1. 브라우저에서 llama.cpp 리포지토리의 릴리스 페이지로 이동하세요: [https://github.com/ggml-org/llama.cpp/releases](https://github.com/ggml-org/llama.cpp/releases?utm_source=llama-windows-install-cta\&utm_medium=docs\&utm_campaign=universe-2026).
2. 설치하려는 릴리스(예: [b11803](https://github.com/ggml-org/llama.cpp/releases?q=flint\&expanded=true\&utm_source=local-model-prerequisite-flint\&utm_medium=docs\&utm_campaign=universe-2026#release-b11803))를 선택합니다.
3. 링크를 클릭하여 Windows CUDA 13.4 ARM64 빌드에 대한 두 파일을 모두 다운로드합니다.
* Windows arm64(CUDA 13)
* CUDA 13.4 DLL들
4. 명령 프롬프트를 열고 설치 폴더를 만듭니다.
```shell copy
mkdir "%LOCALAPPDATA%\Programs\llama.cpp\BUILD-cuda-13.4-arm64"
```
빌드 번호를를 교체하는 것 `BUILD`—예를 들어, `b11803`.
5. 두 ZIP 파일의 모든 파일을 이 폴더로 직접 추출하십시오. 파일 탐색기에서 **모두 추출**을 사용하는 경우 기본적으로 파일 탐색기에서 각 ZIP 파일에 대해 별도의 하위 폴더를 만들기 때문에 대상을 이 폴더로 변경하세요. 완료되면 폴더에는 하위 폴더 없이 `cudart64_13.dll`, `cublas64_13.dll`, `cublasLt64_13.dll` 및 `llama-server.exe`를 포함한 많은 수의 파일이 들어 있어야 합니다.
6. 환경 변수를 `LLAMACPP_SERVER_PATH` 설정합니다.
```shell copy
setx LLAMACPP_SERVER_PATH "%LOCALAPPDATA%\Programs\llama.cpp\BUILD-cuda-13.4-arm64\llama-server.exe"
```
`BUILD` 그 그 빌드 번호를 바꾸기.
1. 명령 프롬프트를 닫고 새 명령 프롬프트 창을 엽니다.
Copilot app 또는 VS Code이 이미 열려 있으면 다시 시작합니다.
Copilot CLI가 실행 중이면 종료하고 새 터미널 창에서 다시 시작합니다.
2. 설치 상태를 확인하려면 다음을 실행하세요:
```shell copy
"%LLAMACPP_SERVER_PATH%" --list-devices
```
### 모델 선택기를 사용하여 로컬 모델을 설치하기
1. 로컬 대화형 세션에서 `/model`를 입력합니다.
2. "로컬 및 자체 호스팅"에서 지원되는 로컬 모델을 찾아보세요.
상태는 "다운로드 필요"로 표시됩니다.
> [!NOTE]
> 로컬 모델은 로컬 컴퓨터가 GPU 및 메모리 요구 사항을 충족하는 Windows PC인 경우에만 다운로드할 수 있습니다.
3. 아래쪽 화살표 키를 사용하여 로컬 모델을 선택한 다음 Enter 키를 누릅니다.
CLI는 컴퓨터가 설치 요구 사항을 충족하는지 확인합니다. 이 문서의 앞부분에 나열된 [필수 구성 요소를](#prerequisites) 참조하세요.
4. **다운로드 및 설정**을 선택하여 모델 다운로드를 시작합니다.
다운로드가 진행되는 동안 다른 모델을 계속 사용할 수 있습니다. CLI는 다운로드가 완료되면 대화 출력에서 알려줍니다.
### 로컬 모델 사용
다운로드가 완료되면 로컬 모델을 세션에서 사용할 수 있습니다.
다음을 할 수 있습니다:
* 모델 선택기에서 선택한 다음, **이 모델 선택**을 선택합니다.
[GitHub Copilot CLI에서 모델 선택](/ko/copilot/how-tos/copilot-cli/use-copilot-cli/choose-a-model#choosing-a-model)을(를) 참조하세요.
* \*\*MAI Code 1.1 Flash only:\*\***Copilot Fusion** 을/를 선택한 다음 모델 선택기에서 **Fusion Standard** 을/를 선택하면, Copilot에서 적절한 경우 로컬 모델을 자동으로 사용합니다.
* 집중 작업용 custom agent에 할당합니다. 그런 다음, 기본 세션은 클라우드의 다른 모델에 유지한 채 작업의 일부에 해당 사용자 지정 에이전트를 사용하라고 Copilot에 지시할 수 있습니다.
[사용자 지정 에이전트 만들기 및 사용 GitHub Copilot CLI](/ko/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli#delegating-focused-tasks-to-a-specific-model)을(를) 참조하세요.
> [!IMPORTANT]
> 모델 선택기에서 로컬 모델을 다운로드한 후에는 직접 선택하거나 Copilot Fusion를 통해 서로 다른 Copilot 환경, 즉 (Copilot CLI, VS Code, Copilot app)의 세션에서 동시에 사용하지 마세요. 각 표면은 모델의 자체 인스턴스를 메모리에 로드하므로 로컬 컴퓨터의 RAM이 부족해질 수 있습니다.
## 오프라인 모드에서 실행
예를 들어 원격 분석 데이터를 보내기 위해 GitHub이 Copilot CLI의 서버에 연결하지 못하도록 하려면 CLI를 시작하기 전에 `true` 환경 변수를 `COPILOT_OFFLINE`로 설정하세요. 전체 네트워크 격리의 경우 모델 공급자도 로컬이거나 동일한 격리된 환경 내에 있어야 합니다.
[GitHub Copilot CLI를 인증하기](/ko/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli#offline-mode)을(를) 참조하세요.
## Troubleshooting
* **Ollama 모델이 없습니다.** Ollama가 실행 중이고 모델이 다운로드되었는지 확인합니다.
을 열고 +`/model`을 눌러 다시 검사합니다. 다른 컴퓨터에 있는 서버의 경우 `/v1`를 포함한 OpenAI 호환 API URL을 수동으로 구성합니다.
* **저장된 모델이 누락되었습니다:** 해당 `provider`이 공급자의 `name`와 일치하는지 확인한 다음 CLI를 다시 시작합니다. 검색된 모델을 추가했을 때 저장 경고가 표시된 경우 경고의 안내를 따라 파일 또는 해당 권한을 수정합니다.
* **환경 설정은 영향을 주지 않습니다:**`COPILOT_PROVIDERS_CONFIG`, 또는 `providers.json`로 선택한 파일에 공급자 또는 모델이 이미 포함되어 있는지 확인합니다. 해당 파일이 우선합니다.
* **요청이 실패합니다.** API URL, 자격 증명, 모델 이름 및 API 선택을 확인합니다. Azure OpenAI의 경우 배포 이름을 확인합니다. 요청 크기에 대한 오류의 경우 모델에 맞는 토큰 제한을 설정합니다.