Python에서 Foundation Models 사용하기: fm CLI

1년 동안 Apple의 온디바이스 대규모 언어 모델은 벽 뒤에 갇혀 있었습니다. 오직 Swift에서만, 그것도 Xcode로 직접 만든 앱 안에서만 접근할 수 있었습니다¹. macOS 27은 그 벽을 허뭅니다. 이제 Apple은 fm이라는 명령줄 도구를 OS에 사전 설치된 상태로 제공하고, pip으로 설치하는 Python용 Foundation Models SDK도 함께 내놓았습니다¹. 예전에는 프로젝트, 빌드, 그리고 컴파일된 Swift 안의 LanguageModelSession이 필요했던 모델이, 이제는 한 줄짜리 셸 명령에 응답하고 Jupyter 노트북 안에서 실행됩니다. Foundation Models Framework 팀의 엔지니어인 Eric Gourlaouen은 WWDC26 세션 334에서 이 변화를 이렇게 분명하게 표현했습니다. “지금까지 이 모델들은 Swift 코드에서만 사용할 수 있었습니다”¹. 바뀐 것은 새로운 모델이 아닙니다. 바뀐 것은 동일한 온디바이스 모델이 갑자기 앱 바깥에서 스크립트로 다루고, 자동화하고, 평가할 수 있게 되었다는 점이며, 그것도 API 키 없이 클라우드 비용 없이 가능합니다¹.

TL;DR

• macOS 27에는 온디바이스 Apple Foundation Model을 위한 사전 설치된 명령줄 도구 fm이 포함됩니다. 하위 명령으로는 respond(프롬프트 한 번을 stdout으로), chat(대화형 세션), schema(구조화된 출력 정의)가 있습니다¹.
• fm respond는 모델 관련 옵션(Private Cloud Compute로 전환), 이미지 입력, 구조화된 출력을 위한 스키마 옵션을 제공하며, 나머지는 --help로 확인할 수 있습니다¹.
• Python SDK는 동일한 온디바이스 모델에 Python에서 접근하며, Python 3.10 이상, Xcode 설치, Apple Silicon Mac이 필요하고, pip이나 다른 패키지 관리자로 설치합니다¹.
• 이 SDK는 Swift 프레임워크를 그대로 반영합니다. respond를 호출하는 LanguageModelSession, 도구 호출, 그리고 fm.respond에 생성 인자로 전달하는 fm.generable 데코레이터를 통한 가이드형 생성입니다¹.
• 두 방식 모두 기본적으로 항상 사용 가능한 온디바이스 모델을 사용하며, 더 강력하지만 사용량 제한이 있는 더 큰 Private Cloud Compute 모델로 전환할 수 있습니다¹.
• 그 결실은 프로토타이핑과 자동화입니다. 의미에 따라 파일을 분류하는 셸 스크립트, 그리고 Pandas와 matplotlib으로 프롬프트 변형을 채점하는 Python 평가 파이프라인을 만들 수 있습니다¹.

fm 명령줄 도구

macOS 27에서 Terminal을 열고 fm을 입력하면, 도구가 지원하는 명령을 출력합니다¹. Apple은 그중 세 가지를 강조합니다. fm respond는 모델에 프롬프트를 보내고 응답을 반환합니다. fm chat은 대화형 대화를 시작합니다. fm schema는 구조화된 출력을 위한 스키마를 생성합니다¹. 가장 단순한 사용법은 Eric이 처음으로 시연한 것입니다. fm respond를 입력하고, 프롬프트를 입력한 뒤 엔터를 누르면, 잠시 후 터미널에서 모델의 답을 읽을 수 있습니다¹.

두 개의 최상위 명령은 깔끔한 선을 따라 역할이 나뉩니다. 탐색이냐 스크립팅이냐입니다. fm chat은 모델의 첫 느낌을 잡기 위한 것입니다. 질문하고, 이어서 다시 질문해도 대화가 유지되며, 자체 슬래시 명령을 갖추고 있습니다. /model은 대화를 Private Cloud Compute 모델로 전환하고, /save는 대화를 저장해 나중에 이어갈 수 있게 합니다¹. 스크립트에서처럼 캡처할 수 있는 인라인 응답을 원할 때는 대신 fm respond를 사용하며, 이는 모델의 출력을 stdout에 씁니다¹.

옵션이 모여 있는 곳은 fm respond입니다. Eric은 세 가지를 명시적으로 언급했습니다. 모델 옵션은 기본 온디바이스 모델 대신 Private Cloud Compute 모델에 프롬프트를 보냅니다. 이미지 옵션은 프롬프트에 이미지를 포함합니다. 그리고 스키마 옵션은 fm schema object와 짝을 이루어 직접 정의한 구조로 출력을 제약합니다¹. 그는 옵션이 더 있다고 언급하며, 모두를 나열하기 위해 도움말 옵션을 가리켰습니다¹. 트랜스크립트는 각 옵션을 정확한 플래그 표기가 아니라 역할로 부르기 때문에(화면에 문자 그대로 표시된 유일한 형식은 fm schema object입니다), 아래에서 옵션을 설명하는 부분은 문서화된 동작을 서술하는 것이지 플래그 문자열을 임의로 만들어 내는 것이 아닙니다.

모델 선택은 가장 중요한 결정입니다. 기본적으로 fm은 macOS에 포함된 온디바이스 모델을 사용하며, 이는 항상 사용 가능합니다¹. Private Cloud Compute의 Apple Foundation Model로 전환할 수도 있으며, Eric은 이를 “온디바이스 모델보다 훨씬 큰 모델이라 복잡한 문제에서 더 나은 성능을 냅니다”라고 설명하면서, 그 대가로 사용량 제한이 따른다고 했습니다¹. 기본값이 올바른 출발점입니다. 무료이고, 로컬이며, 한도가 없습니다. 작업이 정말로 그것을 필요로 할 만큼 어려울 때 Private Cloud Compute로 한 단계 올리면 됩니다.

자동화 스크립트 만들기

파일 분류 데모는 CLI가 왜 중요한지를 가장 명확하게 보여주는 사례입니다. Eric은 초안 버전과 최종 버전 에셋이 가득한 프로젝트 폴더를 가지고 있었고, 최종본은 남겨 백업하고 초안은 아카이브 디스크로 옮기는 반복 가능한 스크립트를 원했습니다¹. 어려운 부분은 파일을 옮기는 것이 아닙니다. 어려운 부분은 이름이 지저분할 때 어느 파일이 초안인지 판단하는 것입니다. 그의 말처럼, 스크립트에서 언어 모델을 호출하면 “이름이 지저분하고 예측 가능하게 분류하기 어려운” 경우에도 “초안과 최종 파일을 분류”할 수 있습니다¹.

이 형태는 모든 “목록에 대한 판단” 자동화로 일반화됩니다. 스크립트는 작업 디렉터리의 파일을 불러온 뒤, fm respond를 통해 모델에 그 목록을 최종 파일과 초안 파일이라는 두 그룹으로 분류하도록 프롬프트를 보냅니다¹. 출력을 쓸 만하게 만들기 위해, 스크립트는 미리 fm schema object로 스키마를 정의하여 최종본 목록과 초안 목록이라는 두 필드를 기술하고, 그 스키마를 스키마 옵션을 통해 fm respond에 전달합니다¹. 모델은 답을 JSON으로 반환하고, 스크립트는 이를 읽어 최종본을 백업으로 복사하고 초안을 아카이브로 옮깁니다¹.

구조화된 출력 단계가 핵심을 떠받치는 부분입니다. 자유 형식 텍스트로 답이 오면 스크립트는 산문을 파싱할 수밖에 없는데, 이는 LLM과 대화하는 모든 셸 파이프라인에서 가장 취약한 부분입니다. fm schema object로 스키마를 선언하고 JSON을 받음으로써, 스크립트는 곧바로 다룰 수 있는 계약을 얻습니다¹. 이 패턴은 Swift 개발자가 가이드형 생성으로 알고 있는 바로 그것이며, 여기서는 CLI 옵션으로 노출됩니다¹. “모델의 결정을 바탕으로 결정론적인 무언가를 한다”로 끝나는 모든 작업은 정확히 이 형태를 원합니다. 프롬프트, 스키마, JSON, 실행입니다.

Python SDK

두 번째 방식은 다른 순간의 다른 사람을 위한 것입니다. Eric의 말처럼, “머신러닝 엔지니어라면 Swift보다 Python을 더 많이 쓸 수도 있습니다.” 그리고 SDK는 “온디바이스 모델을 Python 코드에서 쉽게 사용할 수 있게 합니다”¹. 그 핵심은 Python의 생태계에 있습니다. “Python에는 머신러닝과 데이터 과학을 위한 오픈소스 패키지의 풍부한 생태계가 있습니다.” 즉 평가 파이프라인을 작성하고 “그 패키지들을 활용해 기능의 품질을 정량화”할 수 있습니다¹.

설치에는 네 가지 요구 사항이 있으며, 모두 세션에서 언급되었습니다. Python 3.10 이상, Xcode 설치, Apple Silicon Mac이 필요하고, SDK는 pip이나 원하는 다른 어떤 패키지 관리자로든 설치합니다¹. Apple Silicon과 Xcode 요구 사항은 이 패키지가 호스팅형 API가 아니라 OS가 실행하는 바로 그 온디바이스 모델에 대한 바인딩임을 보여주는 단서입니다.

이 API는 Swift 프레임워크를 사용해 본 사람이라면 누구에게나 익숙하게 느껴질 것이며², 이는 의도된 것입니다. “API와 추상화는 금세 익숙하게 느껴질 것입니다”¹. LanguageModelSession을 생성하고, 선택적으로 지침을 전달한 뒤, 프롬프트와 함께 session.respond를 호출하여 프롬프트를 보냅니다. 그 결과에는 모델의 출력이 담겨 있습니다¹. SDK는 프레임워크의 핵심 기능을 그대로 옮겨 옵니다. 텍스트와 이미지 입력, 스트리밍 응답, 모델이 코드와 상호작용할 수 있게 하는 도구 호출, 그리고 구조화된 출력을 위한 가이드형 생성입니다¹.

이 기능들 가운데 두 가지가 구체적으로 다루어졌습니다. 도구 호출의 경우, Eric은 사용자의 최근 주문 몇 건을 가져오기 위해 모델이 호출할 수 있는 도구를 정의했는데, “더 개인화된 정보를 제공할 수 있도록” 하기 위해서였으며, 이는 Swift 프레임워크의 Tool 프로토콜과 같은 패턴입니다¹. 가이드형 생성의 경우, 그는 fm.generable 데코레이터를 사용해 원하는 출력 구조인 ItemsSuggestion 객체를 정의하고, 이를 생성 인자로 fm.respond에 전달했습니다¹. 이 데코레이터는 Swift의 @Generable 매크로에 해당하는 Python 버전이며, 생성 인자는 모델에게 돌려받고 싶은 형태를 건네는 방법입니다. 트랜스크립트는 이를 역할과 객체 이름으로만 보여줄 뿐 클래스 본문 전체를 출력하지 않으므로, ItemsSuggestion은 직접 정의할 구조에 대해 이 예시가 붙인 이름이라고 받아들이면 됩니다.

평가 파이프라인: Python을 쓰는 진짜 이유

이 사례 연구는 Python SDK가 단순한 편의성에 머물기를 멈추고 하나의 방법론이 되는 지점입니다. Eric은 사용자가 장바구니에 무엇을 담고 싶어 하는지 예측하는 기능을 만들고 있었고, 세 가지 서로 다른 프롬프트 구현을 가지고 있었습니다. 최소한의 것, 더 서술적인 것, 그리고 규칙의 전체 목록을 풀어 쓴 상세한 것입니다¹. 모든 프롬프트 엔지니어가 마주하는 질문은 어느 것이 실제로 가장 나은가이며, 정직한 답은 취향이 아니라 측정을 요구합니다.

Apple은 Swift 개발자에게는 여기에 대한 고유한 답이 있다고 분명히 밝힙니다. Evaluations 프레임워크는 Xcode 27에 포함되며, 평가를 손쉽게 만들고 반복(iteration)에 걸쳐 기능 정확도를 추적할 수 있게 합니다¹. Python SDK는 노트북 안에서 사는 데이터 과학자를 위한 병행 경로입니다. Eric은 전체 분석을 Jupyter에서 실행했습니다¹.

이 파이프라인은 온디바이스 모델을 겨냥한 표준적인 ML 평가 루프처럼 읽힙니다. 먼저 그는 큰 서버 모델을 사용해 평가 데이터를 생성하여, 각 입력과 기대 출력을 얻었습니다¹. 그다음 모든 입력에 대해 세 가지 프롬프트 구현 각각에서 출력을 생성하고, 입력과 출력을 Pandas DataFrame의 행으로 저장했습니다¹. 이어서 서버 모델에 기반한 채점 함수가 그가 선택한 기준에 따라 각 출력을 평가했고, 그 지표들이 다시 DataFrame으로 들어갔습니다¹. 마지막으로 matplotlib이 점수를 차트로 바꿨습니다¹.

차트는 프롬프트를 아무리 들여다봐도 알 수 없었을 이야기를 들려주었습니다. 상세한 프롬프트는 생성 오류 비율이 높았는데, Eric은 이를 모델의 최대 컨텍스트 윈도우 크기에 도달한 탓으로 돌렸습니다. 덜 상세한 두 프롬프트는 장바구니에 불필요한 항목을 추가한 반면, 상세한 것은 더 적게 추가했습니다. 상세한 프롬프트는 기대 항목을 더 많이 놓쳤고, 최소한의 프롬프트는 항목을 가장 많이 환각했습니다¹. 모든 프롬프트가 저마다 다른 실패 양상을 보였고, 그것을 드러낸 것은 오직 측정뿐이었습니다. 그것이 이 접근 전체를 뒷받침하는 논거입니다. “Python으로는 프로젝트 전체를 다시 빌드할 필요 없이 노트북에서 바로 그 반복을 빠르게 할 수 있습니다”라고 Eric은 말했습니다¹.

무엇을 언제 선택할까

위의 계약들에서 몇 가지 규칙이 따라 나옵니다.

셸 스크립트에 판단이 필요할 때는 fm respond를 선택하세요. 지저분한 파일명 분류, 입력된 한 줄의 분류, 비정형 텍스트에서 필드 추출 같은 작업입니다. fm schema object와 스키마 옵션을 함께 쓰면 스크립트가 산문을 파싱하는 대신 JSON을 다룹니다¹.

스크립팅이 아니라 탐색 중일 때는 fm chat을 선택하세요. 모델이 당신의 프롬프트를 어떻게 다루는지 첫 느낌을 잡는 가장 빠른 방법이며, /model로 Private Cloud Compute로 올리고 /save로 세션을 보관할 수 있습니다¹.

단순히 호출하는 것을 넘어 측정하고 싶을 때는 Python SDK를 선택하세요. 프롬프트가 둘 이상 생기고 어느 것이 더 나은지 알아야 하는 순간, 노트북과 Pandas와 matplotlib 루프가 바로 그 도구입니다. 온디바이스 모델은 무료이고 로컬이라 청구서 없이 평가 세트 전체를 실행할 수 있기 때문입니다¹.

기본은 온디바이스 모델, Private Cloud Compute로는 의도적으로 올리세요. 온디바이스 모델은 항상 사용 가능하고 사용량 제한이 없습니다. Private Cloud Compute는 더 크고 복잡한 문제에서 더 낫지만 사용량 제한이 따르므로, 그럴 만한 작업을 위해 아껴 두세요¹.

여기서 프로토타입을 만들고, Swift로 출시하세요. Eric 자신의 표현으로는, 이 도구들을 “Xcode 프로젝트와 나란히, 프롬프트를 프로토타이핑하고 평가하는 방법으로” 쓰거나, “그 자체로, 모델을 새로운 방식으로 사용하기 위해” 쓸 수 있습니다¹. 식료품 앱 예시는 “Swift로 구현하기 전에” Python에서 프롬프트를 프로토타이핑합니다¹. CLI와 SDK는 아이디어에서 증거까지의 루프를 짧게 하지만, 기능이 최종적으로 자리 잡는 곳은 여전히 앱입니다.

FAQ

fm 명령줄 도구란 무엇인가요?

fm은 macOS 27에 사전 설치되어 함께 제공되는 명령줄 도구로, Terminal 앱에서 온디바이스 Apple Foundation Model에 접근합니다¹. 하위 명령으로는 모델에 프롬프트를 보내 응답을 출력하는 respond, 대화형 대화를 시작하는 chat, 구조화된 출력을 정의하는 schema가 있습니다. 기본 모델이 온디바이스에서 실행되므로 API 키 없이, 클라우드 비용 없이 실행할 수 있습니다¹.

fm에서 구조화된 JSON을 얻으려면 어떻게 하나요?

fm schema object로 스키마를 정의한 다음, 그 스키마를 스키마 옵션을 통해 fm respond에 전달하세요. 모델은 그 스키마에 맞는 JSON으로 답을 반환하므로, 스크립트는 자유 텍스트를 파싱하는 대신 곧바로 다룰 수 있습니다¹. 이 메커니즘은 프레임워크의 가이드형 생성을 CLI로 옮긴 버전입니다¹.

Foundation Models Python SDK에는 무엇이 필요한가요?

Python 3.10 이상, Xcode 설치, Apple Silicon Mac입니다¹. pip이나 원하는 다른 패키지 관리자로 설치합니다. Apple Silicon과 Xcode 요구 사항은 SDK가 호스팅형 API를 호출하는 것이 아니라 OS가 실행하는 바로 그 온디바이스 모델에 바인딩한다는 점을 반영합니다¹.

Python SDK는 Swift 프레임워크와 어떻게 다른가요?

같은 모델이며, 의도적으로 익숙하게 만든 API를 다른 언어로 제공한 것입니다. LanguageModelSession을 생성하고, respond를 호출하고, 도구를 노출하고, 생성 인자로 fm.respond에 전달하는 fm.generable 데코레이터를 통해 가이드형 생성을 사용합니다¹. Python을 선택하는 이유는 그 생태계입니다. Pandas, matplotlib, Jupyter, 그리고 평가 파이프라인을 위한 나머지 데이터 과학 스택은 Swift가 그만큼 직접적으로 닿지 못하는 것들입니다¹.

온디바이스 모델 대신 Private Cloud Compute는 언제 써야 하나요?

fm과 SDK 모두 기본적으로 온디바이스 모델을 사용하며, 이는 항상 사용 가능하고 사용량 제한이 없습니다¹. 문제가 더 큰 모델을 필요로 할 만큼 복잡할 때는, fm respond의 모델 옵션이나 fm chat의 /model 명령을 통해 Private Cloud Compute로 전환하되, 사용량 제한이 따른다는 점을 받아들이세요¹.

전체 Apple Ecosystem 클러스터는 다음과 같습니다. 이 도구들이 반영하는 Swift 기반에 대해서는 Foundation Models 프레임워크 설명, 모델이 도구를 어떻게 사용하는지에 대해서는 iOS 27의 도구 호출 제어, 온디바이스 대 더 큰 모델 선택에 대해서는 Foundation Models의 에이전트형 워크플로, 그리고 에이전트 중심 워크플로의 IDE 내부 측면에 대해서는 Xcode 27의 코딩 에이전트를 참고하세요. 허브는 Apple Ecosystem 시리즈에 있습니다. 에이전트로 iOS를 구축하는 더 큰 그림에 대해서는 iOS 에이전트 개발 가이드를 참고하세요.