Molayo

© 2026 Molayo

Zenn헤드라인2026. 05. 27. 10:51

Foundry Local 심층 분석: in-process Core API, OpenAI 호환성, WinML 통합을 통해 살펴보는 Windows

요약

Microsoft의 Foundry Local은 로컬 LLM을 OpenAI 호환 API로 구동할 수 있는 새로운 런타임입니다. CLI 서비스 형태와 앱 내부에 직접 로드되는 SDK 형태를 모두 지원하며, Windows ML과의 통합을 통해 독자적인 실행 환경을 제공합니다.

핵심 포인트

  • OpenAI 호환 API를 지원하는 로컬 LLM 런타임
  • CLI 서비스 방식과 In-process SDK 방식의 이중 구조
  • Windows ML을 통한 효율적인 Execution Provider 관리
  • Ollama와 차별화된 추상화 계층 및 아키텍처

이 기사에 대하여

Microsoft의 Foundry Local은 로컬 LLM을 OpenAI 호환 API로 구동할 수 있는 새로운 런타임(Runtime)입니다. winget install Microsoft.FoundryLocal

한 줄로 설치하고, foundry model run phi-4-mini 명령으로 간편하게 채팅할 수 있어 "Ollama의 Microsoft 버전"으로 소개되기도 합니다.

하지만 내부를 조금 들여다보면, Ollama와는 추상화 계층(Abstraction Layer)이 상당히 다른 별개의 소프트웨어라는 것을 알 수 있습니다. Foundry Local은 CLI 이면에 상주하는 서비스이기도 하며, SDK로서 앱 내부에 in-process로 로드되는 네이티브 라이브러리이기도 합니다. Windows에서는 더욱이 Windows ML이 EP(Execution Provider) 플러그인의 취득 및 등록을 대신 처리해주고 있어, "ONNX Runtime을 직접 호출하는 것"이나 "llama.cpp 계열의 단순한 래퍼(Wrapper)"와도 다른 독자적인 위치를 차지하고 있습니다.

이 기사는 Foundry Local 단독을 심층 분석합니다. CLI와 SDK의 이면 구성, 모델 alias와 variant, WinML과의 역할 분담, BYOM(Bring Your Own Model) 절차, Ollama / LM Studio와의 위치 관계, 제약 사항까지, 공식 Docs를 1차 정보로 하여 정리합니다.

대상 독자는 Windows 상에서 OSS(Open Source Software) LLM/SLM을 로컬 실행하고자 하는 .NET / Python / Node / Rust 개발자, 혹은 Ollama / LM Studio를 사용해 오면서 Foundry Local의 위치를 정리하고 싶은 분들입니다. ONNX / ONNX Runtime / Execution Provider 용어는 전제 조건으로 하지만, 필요한 부분에서는 다시 언급하겠습니다.

0. 전제: 연재 측에서 다룬 지도를 3줄로 요약

연재 제1회(Windows 로컬 AI 기술 지도)에서는 Windows 로컬 AI의 "4가지 입구"를 제시했습니다.

Windows AI APIs: Microsoft가 제공하는 기성 AI 기능(Phi Silica 등). Copilot+ PC 필수 -
Foundry Local: 기성 OSS LLM / 음성 모델을 OpenAI 호환 API로. 임의의 Windows 하드웨어 -
Windows ML: 자체 ONNX 모델을 공유 ORT + 자동 EP 배포로 -
ORT 직접 사용: EP와 배포를 모두 직접 관리

본 기사는 이 중 Foundry Local만을 단독으로 심층 분석합니다. 연재에서 다룬 Azure 측과의 동일한 인터페이스 전환(연재 제5회 §4)이나 Windows ML의 EP 배포(연재 제4회)는 전제로 하며, 본 기사에서는 Foundry Local 내부의 메커니즘에 집중합니다.

1. Foundry Local의 정체: 이면 구성을 가진 런타임

Foundry Local의 첫 번째 걸림돌은 "Foundry Local"이 가리키는 대상 자체가 하나가 아니라는 점입니다. Ollama가 "상주 데몬(daemon) + CLI 클라이언트"라는 한 가지 형태만을 갖는 것에 반해, Foundry Local은 다음의 두 가지 얼굴을 가집니다.

얼굴기동 형태통신API
CLI 계통별도 프로세스의 서비스 (foundry service status / restart로 관리)앱 ↔ 서비스 간 HTTPOpenAI 호환 REST
SDK 계통앱의 프로세스 내부에 in-process로 네이티브 라이브러리를 로드함수 호출 (HTTP 오버헤드 없음)각 언어의 네이티브 API, 옵션으로 OpenAI 호환 REST도 기동 가능

공식 아키텍처 개요에는 다음과 같이 적혀 있습니다.

Foundry Local is an end-to-end local AI solution that ships as a single native library inside your application.

별도의 서비스나 데몬 (daemon)에 연결하는 대신, 코드가 Foundry Local Core API를 인프로세스 (in-process) 방식으로 로드하고 언어별 소프트웨어 개발 키트 (SDKs)를 통해 이를 호출합니다.

— Foundry Local 아키텍처 개요

즉, SDK 측은 '클라이언트'가 아니라 '라이브러리'라는 점이 핵심입니다. Core API는 플랫폼 특화 (platform-specific) 네이티브 라이브러리 (Windows에서는 .dll, Linux에서는 .so, macOS에서는 .dylib)로 구성되어 앱의 프로세스 공간에 로드됩니다.

반면, CLI로 설치했을 때(winget install Microsoft.FoundryLocal 또는 brew install foundrylocal) 실행되는 것은 서비스입니다. foundry service status를 통해 엔드포인트 URL을 확인할 수 있으며, OpenAI 호환 REST 서버로서 다른 프로세스에서 호출할 수 있습니다 (Use the Foundry Local CLI (preview)).

사용 기준

  • CLI 계열이 적합한 경우: 로컬에서의 테스트, LangChain / Open WebUI 등 HTTP 기반 도구 통합, 여러 프로세스에서 동일한 모델을 공유할 때
  • SDK 계열이 적합한 경우: 자신의 앱 내부에 포함하여 동작시키는 프로덕션 배포. SDK는 CLI 설치를 전제로 하지 않습니다 (Foundry Local SDK Reference)

SDK는 엔드 유저의 머신에 Foundry Local CLI가 설치되어 있을 필요가 없으므로, 사용자에게 추가 설정 단계 없이 애플리케이션을 배포할 수 있습니다 — 즉, 애플리케이션이 셀프 컨테인드 (self-contained) 상태가 됩니다.

— Foundry Local SDK Reference

이러한 '앱 셀프 컨테인드 (self-contained)' 특성은 Ollama와 같은 데몬 (daemon) 기반 도구와는 큰 차이점입니다. 엔드 유저에게 별도의 서비스를 설치하게 할 필요가 없다는 점에서 배포물로서의 완성도가 다릅니다.

2. 최단 경로: 설치부터 채팅까지

실제로 직접 실행해 보는 최단 경로를 3단계로 나눕니다. CLI로 동작 확인 → OpenAI SDK로 호출 → 네이티브 SDK로 통합하는 순서입니다.

2.1 CLI로 30초 만에 실행하기

Windows라면 winget, macOS라면 Homebrew로 설치할 수 있습니다.

winget install Microsoft.FoundryLocal
foundry --version

최초 모델 열거 시, 하드웨어에 맞는 EP가 다운로드됩니다. 여기서 Foundry Local이 자체적으로 EP를 가져온다는 점이 중요합니다 (§4에서 상세 설명).

foundry model list
foundry model run phi-4-mini

foundry model run을 입력하면, 첫 실행 시 모델이 다운로드되고 대화형 프롬프트가 열립니다. /exit로 종료합니다.

연결되지 않을 때의 일반적인 해결 방법도 숙지해 두시기 바랍니다.

foundry service status # 엔드포인트 (Endpoint) URL 및 서비스 가동 확인
foundry service restart # 「Request to local service failed」가 발생했을 때

출처: Use the Foundry Local CLI (preview), Foundry Local CLI Reference.

2.2 OpenAI SDK로 호출하기

CLI 계열의 서비스는 OpenAI 호환 REST 서버이므로, OpenAI SDK를 그대로 사용할 수 있습니다.

from openai import OpenAI
client = OpenAI(
base_url="http://localhost:XXXXX/v1", # foundry service status 의 URL
...

포트 번호는 고정되어 있지 않으므로, foundry service status 명령어로 확인하여 전달합니다.

"Azure OpenAI와 동일한 OpenAI SDK로 호출할 수 있다"는 연재 제5회 §4의 내용은 이 CLI 계열에 관한 이야기입니다. SDK 계열에서 REST를 구축하지 않는다면, 엔드포인트(Endpoint) 교체라는 개념은 등장하지 않습니다 (대신 SDK의 manager 인스턴스를 교체하게 됩니다).

2.3 네이티브 SDK로 통합하기 (C# / Python)

프로덕션 애플리케이션에 통합하려면 SDK 계열을 선택합니다. Windows용으로는 ** *.WinML 변체 (variant)**를 채택하는 것이 권장됩니다 (§4의 이유에 따름).

# C# Windows용
dotnet add package Microsoft.AI.Foundry.Local.WinML
# Python Windows용
...

공식 설명은 다음과 같습니다.

"The Windows package integrates with the Windows ML runtime — it provides the same API surface area with a wider breadth of hardware acceleration."

— Foundry Local SDK Reference

(한국어 번역: "Windows 패키지는 Windows ML 런타임 (runtime)과 통합되어 있으며, 더 넓은 범위의 하드웨어 가속 (hardware acceleration)과 함께 동일한 API 표면 영역 (API surface area)을 제공합니다.")

C#의 최소 스니펫(snippet)은 Foundry Local이 공개한 FoundryLocalManager를 기점으로 작성합니다 (Get started with Foundry Local (Windows)).

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging.Abstractions;
// 1. Foundry Local 초기화 (필요 시 서비스를 시작)
...

이 코드는 localhost:XXXXX와 같은 URL을 전혀 포함하지 않습니다. SDK 계열은 인프로세스 (in-process) 방식이므로, 함수 호출만으로 완결됩니다.

3. 모델 카탈로그 읽는 법: alias와 variant

Foundry Local의 모델 지정에는 Ollama의 phi3:latest와 같이 "태그 (tag)"와 비슷해 보이지만, 배후에서 작동하는 하드웨어 적합성 선택 방식이 다른 메커니즘이 있습니다.

alias = 하드웨어 적합성 자동 선택

foundry model run phi-4-mini와 같이 alias를 전달하면, Foundry Local이 "호스트의 하드웨어 (hardware)에 최적화된 변체 (variant)"를 선택합니다. Phi-4 mini에는 통상적으로 양자화 (quantization)나 EP별로 여러 변체 (variant)가 존재하며, 개발자가 이를 수동으로 선택할 필요는 없습니다.

"Use a model alias (like phi-4-mini) to let Foundry Local automatically select the best variant for your hardware. Use a full model ID to target a specific variant."

— Use the Foundry Local CLI (preview)

(한국어 번역: "모델 에일리어스 (alias, 예: phi-4-mini)를 사용하여 Foundry Local이 사용자의 하드웨어에 가장 적합한 변체 (variant)를 자동으로 선택하도록 하십시오. 특정 변체를 대상으로 하려면 전체 모델 ID를 사용하십시오.")

등)을 사용하여 Foundry Local이 하드웨어에 가장 적합한 변체 (variant)를 자동으로 선택할 수 있도록 한다. 특정 변체를 대상으로 하려면 전체 ID를 사용한다.")

특정 변체를 강제하고 싶은 경우에만 전체 ID를 전달합니다.

필터로 변체 (variant) 찾기

CLI에는 강력한 필터 기능이 있습니다.

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

지원되는 필터 키는 공식 레퍼런스(Foundry Local CLI Reference)에 정리되어 있습니다. provider=... 키는 Foundry Local이 인식하는 EP (Execution Provider)의 이름 그 자체이며, 다음 절에서 자세히 살펴보겠습니다.

캐시 조작

로컬 캐시는 독립된 CLI로 조작할 수 있습니다.

foundry cache list # 저장된 모델 목록
foundry cache location # 캐시 경로
foundry cache remove phi-4-mini
...

4. 하드웨어 추상화의 내부: WinML과의 역할 분담

Foundry Local의 "자동으로 빨라진다"라는 셀링 포인트의 실체를 살펴봅니다. 여기서 핵심은 Windows와 비 Windows 환경에서 수행하는 작업이 다르다는 점입니다.

4.1 Core API의 4단계 라이프사이클

공식 아키텍처 개요(Foundry Local architecture overview)에서는 모델 실행을 다음 4단계로 나누어 설명합니다.

  • Download — SDK가 alias를 통해 모델을 요청 → 없으면 Foundry Catalog에서 가져와 디스크에 저장
  • Load — 메모리에 로드, ONNX Runtime 세션 초기화, 사용 가능한 하드웨어에 맞춰 EP를 선택
  • Inference — 추론 (동기 / 스트리밍 모두 지원)
  • Unload — 메모리 해제, 캐시는 유지

이 중 **Step 2의 "EP 선택"**이 Foundry Local의 차별화 포인트입니다.

4.2 Windows에서의 EP 획득 경로

공식 아키텍처 개요에서는 Windows에서의 EP 획득을 명확하게 WinML에 위임하고 있다고 명시합니다.

On Windows, the Core API delegates execution provider management to the Windows ML runtime. WinML handles:

Execution provider plugin acquisition— sourcing hardware-matched execution provider plugins from the OS and Windows Update. Runtime registration— registering acquired execution providers with ONNX Runtime so they're available during inference. Driver compatibility— negotiating driver versions and handling compatibility checks to ensure stable execution.

(번역: "Windows에서는 Core API가 실행 프로바이더 (Execution Provider) 관리를 Windows ML 런타임에 위임합니다. WinML이 처리하는 작업은 다음과 같습니다: 실행 프로바이더 플러그인 획득 — OS 및 Windows Update로부터 하드웨어에 최적화된 실행 프로바이더 플러그인을 조달합니다. 런타임 등록 — 획득한 실행 프로바이더를 ONNX Runtime에 등록하여 추론 중에 사용할 수 있도록 합니다. 드라이버 호환성 — 드라이버 버전을 협상하고 안정적인 실행을 보장하기 위한 호환성 체크를 처리합니다.")

즉, 벤더 EP (Execution Provider) 플러그인의 획득, 등록, 드라이버 호환성 협상은 Windows ML이 대신 수행하며, Foundry Local 자체는 이를 래핑(wrap)하고 있을 뿐입니다. 연재 제1회 §3에서 다루었던 Windows ML의 ExecutionProviderCatalog 이야기와 Foundry Local이 내부적으로 연결되어 있는 지점은 바로 이 부분입니다.

이 때문에 Microsoft.AI.Foundry.Local.WinML 패키지가 "동일한 API로 하드웨어 가속 범위가 더 넓다"라고 공식적으로 설명하는 것입니다. Windows ML의 EP 풀(pool)을 그대로 사용할 수 있기 때문입니다.

4.3 Linux / macOS 처리

Windows가 아닌 환경에서는 WinML이 없기 때문에, SDK 자체가 EP 플러그인을 번들(bundle)합니다.

On Linux and macOS, the Core API registers execution providers directly with ONNX Runtime without a platform intermediary.

The SDK bundles the required execution provider plugins for each target platform, so registration is handled internally during model loading.

— Foundry Local architecture overview

(한국어 번역: "Linux 및 macOS에서 Core API는 플랫폼 중개 없이 실행 프로바이더(Execution Provider)를 ONNX Runtime에 직접 등록합니다. SDK는 각 타겟 플랫폼에 필요한 실행 프로바이더 플러그인을 번들링하므로, 등록은 모델 로딩 중에 내부적으로 처리됩니다.")

Windows 이외의 환경에서는 "OS의 EP 풀"이라는 개념이 없으며, 각 SDK 패키지가 대응하는 EP를 포함하여 배포합니다.

4.4 사용 가능한 EP

CLI 필터의 provider 값으로부터 Foundry Local이 인식하는 EP를 역추적할 수 있습니다 (Foundry Local CLI Reference).

EP 명(provider 값)역할
CPUExecutionProvider모든 환경의 최종 폴백(fallback) (MLAS 기반)
WebGpuExecutionProvider임의의 GPU를 위한 범용 폴백 (Dawn 경유)
CUDAExecutionProviderNVIDIA GPU용 상주 EP (RTX 30 시리즈 이후)
NvTensorRTRTXExecutionProviderNVIDIA RTX 시리즈에서 TensorRT 최적화를 적용하는 EP
OpenVINOExecutionProviderIntel CPU / iGPU / NPU
VitisAIExecutionProviderAMD Vitis AI (Ryzen AI NPU 등)
QNNExecutionProviderQualcomm Hexagon NPU (Snapdragon X)

Foundry Local의 내장(built-in) EP는 CPU / WebGPU / CUDA 세 가지이며, 그 외(NvTensorRTRTXExecutionProvider, OpenVINOExecutionProvider, QNNExecutionProvider, VitisAIExecutionProvider)는 Windows 상에서 **동적으로 다운로드 및 등록되는 플러그인 EP (plugin EP)**로 취급됩니다 (Foundry Local CLI Reference). Foundry Local 측의 카탈로그는 시기에 따라 인식하는 EP가 달라지므로, 반드시 최신 CLI 레퍼런스를 확인하시기 바랍니다 (GitHub issue 사례에서 variant 열거 방식이 버전 간에 변동된 사례가 있습니다. §8에서 다룹니다).

5. OpenAI 호환성: Chat Completions 엔드포인트를 중심으로

Foundry Local의 API는 OpenAI 사양에 맞춰져 있습니다.

OpenAI 호환 API — OpenAI Responses API 형식(format)을 포함하여 OpenAI 요청 및 응답 형식을 지원합니다. 애플리케이션이 이미 OpenAI SDK를 사용하고 있다면, 최소한의 코드 변경만으로 Foundry Local 엔드포인트를 가리키도록 설정할 수 있습니다.

— Foundry Local이란 무엇인가?

(일본어 번역: 「OpenAI 호환 API — OpenAI Responses API 포맷을 포함한 OpenAI 요청 및 응답 포맷을 지원합니다. 애플리케이션이 이미 OpenAI SDK를 사용하고 있는 경우, 최소한의 코드 변경으로 Foundry Local 엔드포인트를 향하게 할 수 있습니다.」)

이 부분은 공식 표현이 다소 모호하므로 주의해서 해석할 필요가 있습니다. REST API 레퍼런스(Foundry Local REST API Reference)를 보면, CLI 계열 서버가 실제로 공개하고 있는 OpenAI 호환 엔드포인트는 다음과 같습니다.

엔드포인트용도
POST /v1/chat/completionsChat Completions (OpenAI Chat Completions API와 완전 호환)
POST /v1/audio/transcriptions음성 전사 (Whisper 계열 모델용)

/v1/responses와 같은 Responses API에 상응하는 엔드포인트는 현재 공개되지 않았습니다. 인용된 "Responses API format"이라는 표현은, 요청/응답의 페이로드 형식(reasoning 관련 필드 등)을 수용한다는 정도의 의미로 읽는 것이 안전하며,

Foundry Local가 상태 유지(stateful) 도구 사용이나 세션 관리를 담당하는 Responses API급 엔드포인트를 제공한다는 의미가 아님에 주의해야 합니다.

실용적인 결론은 간단합니다. Foundry Local 단독으로는 다음과 같습니다.

  • CLI 계열: OpenAI SDK의 chat.completions를 엔드포인트만 교체하면 됨
  • SDK 계열: 앱 내에서 OpenAI 호환 REST를 옵션으로 실행할 수 있음 (단, HTTP 오버헤드가 발생하므로 성능 면에서는 in-process 함수 호출을 우선하는 것이 유리함)

이 두 가지 방식을 기억해 두는 것으로 충분합니다. 연재 제5회 §4에서 다룬 "Azure OpenAI와 Foundry Local의 동일한 전환" 역시 Chat Completions의 base_url 교체가 핵심이며, Responses API 기반의 코드를 그대로 옮기는 것을 의도한 것이 아닙니다.

6. BYOM: Hugging Face 모델을 Olive로 올리기

카탈로그에 없는 모델을 구동하고 싶은 경우, Foundry Local은 Olive를 사용하여 HF 모델을 ONNX로 변환하여 배치하는 경로를 제공합니다 (Compile Hugging Face models to run on Foundry Local). Ollama의 GGUF 가져오기보다 번거롭지만, EP(Execution Provider) 유형에 따른 양자화(quantization)를 Olive 측에서 처리할 수 있다는 점이 강점입니다.

최소 절차는 다음 세 가지입니다.

  • Olive로 convert / optimize / quantize (fp16 / fp32 / int4 / int8 지정 가능). Llama-3.2-1B-Instruct 예시의 경우, 컴파일 자체는 약 60초가 소요되며 다운로드 시간은 별도입니다.
  • 최소한의 메타데이터는 다음과 같습니다: inference_model.json

모델 디렉터리에 넣습니다. import json, os model_path = "models/llama" json_template = { "Name": "llama-3.2:1" } # 임의의 모델명, 기본 버전은 1 with open(os.path.join(model_path, "inference_model.json")), "w") as f: json.dump(json_template, f, indent=2)

Foundry Local에서 인식되는 (foundry model list에 나타남) → foundry model run이 가능합니다.

Important: The Olive CLI and optimization settings change over time, and a single command line example might not work for every model, device, or execution provider.

— Compile Hugging Face models to run on Foundry Local

(일본어 번역: "중요: Olive CLI와 최적화 설정은 시간이 지남에 따라 변경되므로, 단일한 커맨드라인 예시가 모든 모델, 장치 또는 실행 프로바이더에서 작동할 수는 없습니다.")

Olive의 최신 CLI와 최적화 설정은 버전별로 바뀌기 때문에, 공식적으로는 Olive Recipes 리포지토리(모델별/하드웨어별 최적화 설정 세트)를 참조하는 것을 권장합니다. BYOM(Bring Your Own Model)에 대한 최종 확인은 아티클이 아니라 Olive Recipes가 적절합니다.

7. Ollama / LM Studio와의 위치 파악

"그럼, Ollama나 LM Studio와는 무엇이 다른가?"는 Foundry Local을 처음 접하는 사람이 반드시 갖게 되는 질문입니다. 세 가지를 초기 사양(initial specification) 수준에서 나열하면 다음과 같습니다 (성능 벤치마크적인 주관 평가는 포함하지 않습니다).

AI 자동 생성 콘텐츠

본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0