ONEDEV

apfel

Local AI RunnersCLISwift

★ 6,372주당 +30조회 4

무엇인가

apfel은 Apple FoundationModels 프레임워크가 노출하는 온디바이스 언어 모델을 호출하는 실행기다. 모델 가중치를 따로 내려받지 않고 macOS에 내장된 시스템 모델을 그대로 쓴다. 같은 바이너리가 UNIX 명령줄 도구, OpenAI 호환 HTTP 서버, 대화형 REPL 세 가지 모드로 동작한다. Swift 6.3 엄격 동시성 모드로 작성됐고 순수 로직을 담은 ApfelCore 타깃을 포함한다.

어떻게 동작하나

CLI 모드에서는 인자를 프롬프트로 받아 표준출력으로 응답을 낸다. `apfel --serve`는 `http://localhost:11434/v1`을 베이스 URL로 OpenAI `/v1/*` 스키마를 구현한다. `apfel --chat`은 컨텍스트를 자동으로 잘라내는 REPL이다. 컨텍스트 윈도우 크기는 `SystemLanguageModel.contextSize`에서 런타임에 읽고 `apfel --model-info`로 확인한다. `max_tokens`를 생략하면 값이 nil로 전달되어 모델이 남은 윈도우를 전부 쓴다. `--mcp`로 Model Context Protocol 서버를 붙이면 도구를 검색·호출해 결과를 응답에 반영하고, 원격 서버는 Streamable HTTP(MCP spec 2025-03-26)로 연결한다. 데모 셸 스크립트는 바이너리에 번들되어 `apfel demos`로 실행 가능한 파일로 풀린다.

무엇과 다른가

Ollama나 llama.cpp 계열 러너는 모델 파일을 내려받아 디스크와 메모리에 올린다. apfel에는 그 단계가 없고 어떤 모델이 쓰이는지는 macOS 버전이 결정한다. 대신 노출되는 인터페이스는 같은 OpenAI 호환 엔드포인트다. apfel 자체에는 설정 파일이 없고 플래그와 환경변수만 쓴다. TOML 설정이 필요하면 execve 드롭인 래퍼인 apfel-run을 별도로 얹는다.

어떻게 쓰나

설치는 `brew install apfel`이다. 첫 실행은 `apfel 'Hello, Mac!'`처럼 프롬프트를 작은따옴표로 감싸 넘긴다. 서버는 `apfel --serve`로 띄우고 기존 OpenAI 클라이언트의 베이스 URL만 바꾼다. `apfel --chat`은 프롬프트나 MCP 서버를 시험하는 REPL이고 Ctrl-C로 끝낸다. `apfel demos`는 cmd, oneliner, mac-narrator, wtd, explain, naming, port, gitsum 스크립트를 `./apfel-demos`에 쓴다. `-f`는 PDF·이미지·텍스트에서 내용을 추출해 프롬프트에 넣는다.

전제와 한계

macOS 26 Tahoe 이상, Apple Silicon(M1 이상), Apple Intelligence 활성화가 전제다. 컨텍스트 윈도우는 입력과 출력을 합쳐 macOS 26에서 4096, macOS 27에서 8192 토큰이다. 프롬프트가 윈도우를 넘으면 생성이 시작되지 않고 `[context overflow]`로 실패한다(HTTP 400 / CLI 종료 코드 4). `max_tokens`가 0 이하면 거부된다. 생성이 한계에 닿으면 `finish_reason: "length"`와 함께 부분 응답이 반환된다. 날짜에 의존하는 프롬프트는 시스템 메시지로 현재 날짜를 주입해야 하며, 그래도 3B 모델의 학습 시점 관련 환각은 남는다. `--serve --permissive`는 프로세스가 처리하는 모든 요청에 Apple의 `.permissiveContentTransformations` 가드레일을 적용하고 요청별 재정의는 없다. 평문 `http://` 위의 bearer 토큰은 거부된다.

유사 도구