Foundry 로컬 명령줄 인터페이스(CLI) 참조

Important

  • Foundry 로컬 CLI는 미리 보기로 제공됩니다. 공개 미리 보기 릴리스는 활성 배포 중인 기능에 대한 초기 access 제공합니다.
  • GA(일반 공급) 전에는 기능, 방식 및 프로세스가 변경되거나 기능이 제한될 수 있습니다.

이 문서에서는 Foundry CLI(로컬 명령줄 인터페이스)에 대한 포괄적인 참조를 제공합니다. CLI는 모델을 관리하고, 로컬 서버를 제어하고, 로컬 캐시를 유지 관리하는 데 도움이 되도록 명령을 논리적 범주로 구성합니다.

사전 요구 사항

  • Foundry Local을 설치합니다.
  • CLI를 foundry 사용할 수 있는 로컬 터미널입니다.
  • 최초 다운로드(실행 제공자 및 모델)를 위해 인터넷 연결이 있는지 확인하십시오.
  • Azure RBAC: 해당 없음(로컬로 실행).
  • Windows Intel NPU가 있는 경우 최적의 NPU 가속을 위해 인텔 NPU 드라이버 설치합니다.

Foundry 로컬 설치

운영 체제에 대한 패키지 관리자를 사용하여 Foundry Local을 설치합니다.

  • Windows: 터미널을 열고 다음을 실행합니다.
    winget install Microsoft.FoundryLocal
  • macOS: 터미널을 열고 다음을 실행합니다. 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    또는 foundry 샘플 GitHub 리포지토리에서 설치 관리자를 다운로드합니다.

설치를 확인합니다.

foundry --version

소프트웨어를 설치할 수 있는 관리자 권한이 있는지 확인합니다.

Tip

설치 후 서비스 연결 오류가 표시되면(예: Request to local service failed) 을 실행합니다 foundry server restart.

빠른 확인

다음 명령을 실행하여 CLI가 설치되고 서비스에 연결할 수 있는지 확인합니다.

  1. CLI 도움말 표시:

     foundry --help

    이 명령은 사용량 정보와 사용 가능한 명령 그룹 목록을 출력합니다.

    참조: 개요

  2. 서버 상태를 확인합니다.

foundry 서버 상태 '''

이 명령은 Foundry 로컬 디먼이 실행 중인지 여부를 출력하고 로컬 엔드포인트를 포함합니다.

참조: 서버 명령

개요

기본 제공 도움말을 사용하여 명령 및 옵션을 탐색합니다.

CLI는 명령을 다음 그룹으로 구성합니다.

  • 모델: model, cache
  • Run: run, chat, completetranscribe
  • 서버: server
  • 설치:config
  • 도움말: statusreport

다음 표에서는 최상위 명령을 요약합니다.

Command 설명
foundry model 로컬 모델을 검색, 검사, 다운로드, 로드 및 언로드합니다.
foundry chat <model> 대화형 로컬 채팅 세션을 시작합니다.
foundry complete <model> <prompt> 하나의 상태 비주성 텍스트 완성을 생성합니다.
foundry run <model> 채팅 또는 전사에 대한 자동 라우팅을 사용하여 모델을 실행합니다.
foundry server 로컬 Foundry 디먼을 시작, 중지, 다시 시작, 검사 및 문제 해결합니다.
foundry cache 다운로드한 모델 캐시 항목을 검사하고 관리합니다.
foundry config 영구 Foundry CLI 설정을 보고 편집합니다.
foundry status 시스템, 서비스, 모델 및 연결 진단을 표시합니다.
foundry report 진단과 함께 미리 채워진 GitHub 문제를 엽니다.
foundry transcribe 대화형 로컬 음성 전사 세션을 시작하거나 파일을 전사합니다.

모델 명령

다음 표에는 모델 관리 및 실행과 관련된 명령이 요약되어 있습니다.

메모

인수를 model별칭 또는 모델 ID로 지정할 수 있습니다. 별칭 사용:

  • 사용 가능한 하드웨어에 가장 적합한 모델을 자동으로 선택합니다. 예를 들어 Nvidia GPU를 사용할 수 있는 경우 Foundry Local은 최상의 GPU 모델을 선택합니다. 지원되는 NPU를 사용할 수 있는 경우 Foundry Local은 NPU 모델을 선택합니다.
  • 모델 ID를 기억할 필요 없이 더 짧은 이름을 사용할 수 있습니다.

특정 모델을 실행하려면 모델 ID를 사용합니다. 예를 들어 사용 가능한 하드웨어와 상관없이 qwen2.5-0.5b를 CPU에서 실행하려면 다음을 사용하십시오: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Command 설명
foundry model --help 사용 가능한 모든 모델 관련 명령과 사용량을 표시합니다.
foundry model run <model> 지정된 모델을 실행하고, 캐시되지 않은 경우 다운로드하고, 상호 작용을 시작합니다.
foundry model list 로컬에서 사용할 수 있는 모든 모델을 나열합니다. 처음 실행 시 하드웨어에 대한 실행 공급자(EP)를 다운로드합니다.
foundry model list --filter <key>=<value> 지정된 조건(디바이스, 작업, 별칭, 공급자)으로 필터링된 모델을 나열합니다.
foundry model info <model> 특정 모델에 대한 자세한 정보를 표시합니다.
foundry model info <model> --license 특정 모델에 대한 라이선스 정보를 표시합니다.
foundry model download <model> 모델을 실행하지 않고 로컬 캐시에 다운로드합니다.
foundry model load <model> 모델을 서비스에 로드합니다.
foundry model unload <model> 서비스에서 모델을 언로드합니다.

모델 목록 순서 지정

별칭에 대해 여러 모델 ID 변형을 사용할 수 있는 경우 모델 목록에 우선 순위가 지정된 모델이 표시됩니다. 목록의 첫 번째 모델은 모델을 지정하는 경우 실행되는 모델 alias입니다.

모델 목록 필터링

이 명령은 옵션을 foundry model list 사용하여 모델 필터링을 지원합니다 --filter . 키-값 쌍을 사용하여 단일 특성에 따라 모델을 필터링할 수 있습니다.

foundry model list --filter <key>=<value>

이 명령은 필터 키 및 값과 일치하는 모델을 출력합니다.

참조: 모델 목록 필터링

메모

설치 후 처음으로 실행 foundry model list 하면 Foundry Local은 컴퓨터의 하드웨어 구성에 대한 관련 실행 공급자(EP)를 자동으로 다운로드합니다. 모델 목록이 나타나기 전에 다운로드 완료를 나타내는 진행률 표시줄이 표시됩니다.

지원되는 필터 키:

디바이스 - 하드웨어 디바이스 유형

실행 중인 하드웨어 디바이스를 기준으로 모델을 필터링합니다.

가능한 값:

  • CPU - 중앙 처리 단위 모델
  • GPU - 그래픽 처리 단위 모델
  • NPU - 신경망 처리 단위 모델

공급자 - 실행 공급자

실행 공급자 또는 런타임별로 모델을 필터링합니다.

가능한 값:

  • CPUExecutionProvider - CPU 기반 실행
  • CUDAExecutionProvider - NVIDIA CUDA GPU 실행
  • WebGpuExecutionProvider - WebGPU 실행
  • QNNExecutionProvider - Qualcomm 신경망 실행(NPU)
  • OpenVINOExecutionProvider - Intel OpenVINO 실행
  • NvTensorRTRTXExecutionProvider - NVIDIA TensorRT 실행
  • VitisAIExecutionProvider - AMD Vitis AI 실행

작업 - 모델 작업 유형

모델을 의도한 사용 사례 또는 작업으로 필터링합니다.

공통 값:

  • chat-completion: 대화형 AI 모델
  • text-generation: 텍스트 생성 모델

별칭 - 모델 별칭

별칭 식별자를 사용하여 모델을 필터링합니다. * 접미사를 사용한 와일드카드 일치를 지원합니다.

샘플 값:

  • phi4-cpu
  • qwen2.5-coder-0.5b-instruct-generic-cpu
  • deepseek-r1-distill-qwen-1.5b-generic-cpu
  • phi-4-mini-instruct-generic-cpu

특수 필터 기능

부정 지원: 일치하는 모델을 제외할 값을 접두사로 ! 지정합니다.

foundry model list --filter device=!GPU

이 명령은 결과에서 GPU 모델을 제외합니다.

참조: 특수 필터 기능

와일드카드 일치(별칭만 해당): 별칭으로 필터링할 때 접두사를 일치하도록 추가 * 합니다.

foundry model list --filter alias=qwen*

이 명령은 별칭이 .로 qwen시작하는 모델을 반환합니다.

참조: 특수 필터 기능

예제

foundry model list --filter device=GPU
foundry model list --filter task=chat-completion
foundry model list --filter provider=CUDAExecutionProvider

이러한 예제에서는 디바이스, 작업 및 실행 공급자별로 모델 목록을 필터링합니다.

참조: 모델 목록 필터링

메모

  • 모든 비교는 대/소문자를 구분하지 않습니다.
  • 명령당 하나의 필터만 사용할 수 있습니다.
  • 인식할 수 없는 필터 키로 인해 오류가 발생합니다.

대화형으로 모델 실행

모델을 실행하고 터미널에서 직접 상호 작용합니다.

foundry model run qwen2.5-0.5b

Foundry Local은 처음 실행 시 모델을 다운로드한 다음 대화형 세션을 시작합니다. 응답을 받을 프롬프트를 입력합니다.

Why is the sky blue?

Foundry 로컬 실행 명령의 출력 스크린샷

Tip

카탈로그의 모든 모델 별칭으로 바꿉 qwen2.5-0.5b 니다. 실행 foundry model list 하여 사용 가능한 모델을 봅니다. Foundry Local은 하드웨어와 가장 일치하는 변형(예: NVIDIA GPU용 CUDA 변형 또는 Qualcomm NPU용 NPU 변형)을 다운로드합니다.

서버 명령

다음 표에는 Foundry 로컬 서비스 관리 및 실행과 관련된 명령이 요약되어 있습니다.

Command 설명
foundry server --help 사용 가능한 모든 서버 관련 명령과 사용량을 표시합니다.
foundry server start Foundry 로컬 디먼 및 OpenAI 호환 로컬 서비스를 시작합니다.
foundry server start --port <port> 지정된 TCP 포트에서 로컬 서비스를 시작합니다. OS 할당 포트에 사용합니다 0 .
foundry server start --idle-timeout <minutes> 지정된 비활성 시간(분) 후에 디먼을 중지합니다. 디먼을 계속 실행하는 데 사용합니다 0 .
foundry server stop Foundry 로컬 디먼을 중지합니다.
foundry server restart Foundry 로컬 디먼 및 로컬 서비스를 다시 시작합니다.
foundry server restart --port <port> --idle-timeout 0 지정된 TCP 포트에서 로컬 서비스를 다시 시작하고 디먼을 계속 실행합니다.
foundry server status 디먼 상태, 로컬 서비스 URL, 프로세스 ID, 가동 시간 및 로그 위치를 표시합니다.
foundry server logs Foundry 로컬 디먼 및 SDK 로그를 표시합니다.

고정 포트 로컬 서버

고정 포트에서 로컬 서비스를 시작하고 디먼을 계속 실행하려면 다음을 --idle-timeout 0사용합니다--port.

foundry server start --port 39839 --idle-timeout 0

디먼이 이미 실행 중이고 새 포트를 적용해야 하는 경우 동일한 옵션을 사용하여 다시 시작합니다.

foundry server restart --port 39839 --idle-timeout 0

로컬 엔드포인트 URL을 확인하려면 다음을 실행합니다.

foundry server status

캐시 명령

다음 표에는 모델이 저장되는 로컬 캐시를 관리하기 위한 명령이 요약되어 있습니다.

Command 설명
foundry cache --help 사용 가능한 모든 캐시 관련 명령 및 해당 사용량을 표시합니다.
foundry cache location 현재 캐시 디렉터리를 표시합니다.
foundry cache list 로컬 캐시에 저장된 모든 모델을 나열합니다.
foundry cache cd <path> 캐시 디렉터리를 지정된 경로로 변경합니다.
foundry cache remove <model> 로컬 캐시에서 모델을 제거합니다.

실행 공급자

실행 공급자는 디바이스에서 가능한 한 효율적으로 모델을 실행하는 하드웨어별 가속 라이브러리입니다.

기본 제공 실행 공급자

Foundry Local에는 CPU 실행 공급자, WebGPU 실행 공급자 및 CUDA 실행 공급자가 포함됩니다.

CPU 실행 공급자는 Microsoft MLAS(선형 대수 서브루틴) 를 사용하여 CPU에서 실행하며 Foundry Local의 CPU 대체입니다.

WebGPU 실행 공급자는 GPU의 가속을 위해 웹 기반 API의 네이티브 구현인 Dawn를 사용하며 Foundry Local의 GPU 대체입니다.

CUDA 실행 공급자는 NVIDIA GPU에서 가속을 위해 NVIDIA CUDA를 사용합니다. 최소 권장 드라이버 버전 32.0.15.5585 및 CUDA 버전 12.5를 사용하는 NVIDIA GeForce RTX 30 시리즈 이상이 필요합니다. NVIDIA 소프트웨어 개발 키트에 대한 사용권 계약(EULA)의 사용 조건의 적용을 받습니다.

플러그 인 실행 공급자

다음 표에 나열된 실행 공급자는 디바이스 및 드라이버 호환성에 따라 Windows 동적 다운로드 및 등록에 사용할 수 있습니다. 지정된 사용 조건의 적용을 받습니다.

Foundry Local은 처음 실행 시 이러한 실행 공급자를 자동으로 다운로드합니다. 플러그 인 실행 공급자는 새 버전을 사용할 수 있을 때 자동으로 업데이트됩니다.

이름(공급업체) 요구 사항 사용 조건
NvTensorRTRTXExecutionProvider (엔비디아) 최소 권장 드라이버 버전 32.0.15.5585 및 CUDA 버전 12.5를 사용하는 NVIDIA GeForce RTX 30XX 이상 버전 NVIDIA 소프트웨어 개발 키트에 대한 사용권 계약 - EULA
OpenVINOExecutionProvider (인텔) CPU: 최소 권장 드라이버 32.0.100.9565를 사용하는 Intel TigerLake(11세대) 이상 버전
GPU: 최소 권장 드라이버 32.0.101.1029를 사용하는 Intel AlderLake(12세대) 이상 버전
NPU: 최소 권장 드라이버 32.0.100.4239를 사용하는 Intel ArrowLake(15세대) 이상 버전		 Intel OBL 배포 상용 사용권 계약 v2025.02.12
QNNExecutionProvider (퀄컴) Snapdragon(R) X Elite - X1Exxxxx - 최소 드라이버 버전 30.0.140.0 이상 버전의 Qualcomm(R) Hexagon(TM) NPU
Snapdragon(R) X Plus - X1Pxxxxx - 최소 드라이버 버전 30.0.140.0 이상 버전의 Qualcomm(R) Hexagon(TM) NPU		 QNN 라이선스를 보려면 Qualcomm® 신경망 처리 SDK를 다운로드하고 ZIP을 추출한 다음 LICENSE.pdf 파일을 엽니다.
VitisAIExecutionProvider (AMD) 최소 요구 사항: Adrenalin Edition 25.6.3과 NPU 드라이버 32.00.0203.280
Max: NPU 드라이버 32.00.0203.297이 포함된 Adrenalin Edition 25.9.1		 추가 라이선스가 필요하지 않습니다.

로컬 서버에서 Open WebUI 사용

디바이스에서 완전히 실행되는 브라우저 기반 채팅 인터페이스를 위해 Open WebUI 를 Foundry Local에 연결합니다.

  1. 모델을 시작하고 터미널을 열어 둡니다.

    foundry model run qwen2.5-0.5b

  2. 로컬 엔드포인트 URL을 가져옵니다.

foundry 서버 상태


Copy the endpoint URL. Foundry Local assigns a dynamic port each time the service starts.

1. Install and launch [Open WebUI](https://github.com/open-webui/open-webui), then open `http://localhost:8080` in your browser.

1. Connect Open WebUI to Foundry Local:

1. Go to **Settings** > **Admin Settings** > **Connections** and enable **Direct Connections**.
1. Go to **Settings** > **Connections** > **Manage Direct Connections** and select **+**.
1. Set **URL** to `http://localhost:PORT/v1` (replace `PORT` with the port from step 2) and **Auth** to **None**.
1. Select **Save**.

1. Select a model from the dropdown and start chatting.

> [!TIP]
> If no models appear, run `foundry model run <model>` in a terminal and reload Open WebUI. If the connection fails, confirm the port with `foundry server status`.

## Upgrade Foundry Local

Run the command for your operating system to upgrade Foundry Local.

- **Windows**:
```bash
winget upgrade --id Microsoft.FoundryLocal
  • macOS: 
    brew upgrade foundrylocal

Foundry 로컬 제거

운영 체제에 대한 명령을 실행하여 Foundry Local을 제거합니다.

  • Windows: 
    winget uninstall Microsoft.FoundryLocal
  • macOS: 
    brew rm foundrylocal
brew untap microsoft/foundrylocal
brew cleanup --scrub

Troubleshooting

서비스 연결 문제

다음과 같은 foundry model list명령을 실행할 때 이 오류가 표시되는 경우:

Exception: Request to local service failed.
Uri: http://127.0.0.1:0/foundry/list

The requested address is not valid in its context. (127.0.0.1:0)

Please check service status with 'foundry server status'.

서비스를 다시 시작합니다.

foundry server restart

이 명령은 포트 바인딩 문제로 인해 서버가 실행되지만 액세스할 수 없는 경우를 해결합니다.

자세한 문제 해결 지침은 모범 사례 및 문제 해결을 참조하세요.

  • Last updated on