Arthur-Ficial/apfel

apfel – Apple Silicon용 온디바이스 LLM

무엇인가요 – apfel은 Apple Silicon Mac에 내장된 Apple 제공 Foundation Models LLM을 래핑하는 Swift 기반 명령줄 도구입니다. 터미널에서 모델에 질의하거나, 로컬 OpenAI 호환 HTTP 서버를 실행함으로써 기존 SDK(파이썬, Node 등)가 클라우드 키 없이 온디바이스 모델과 통신할 수 있게 해줍니다.

주요 기능

• 순수 온디바이스 추론 – 내장된 SystemLanguageModel 사용; API 키나 네트워크 트래픽 없음.
• 두 가지 사용 모드 – 파이프 친화적인 CLI(apfel "prompt", apfel -f file …)와 즉시 사용 가능한 OpenAI 서버(apfel --serve는 http://localhost:11434/v1에서 대기).
• 도구 호출 / MCP – 로컬 또는 원격 Model Context Protocol (MCP) 도구를 호출 가능하며, 내장된 계산기 예제 포함.
• 풍부한 출력 옵션 – 일반 텍스트, JSON(-o json), 스키마 검증된 JSON, 스트리밍, 종료 코드 신호, 파일 첨부 처리(텍스트, PDF, 이미지, macOS 27에서 OCR/비전 지원).
• 채팅 REPL – apfel --chat로 대화형 세션 시작.
• 설정 없음 – 모든 동작은 플래그나 환경 변수로 제어; 선택적 래퍼 apfel-run은 TOML 설정 지원 제공.

일반적인 워크플로우

1. 설치 – brew install apfel (또는 Swift 6.3으로 소스에서 빌드).
2. 프롬프트 실행 – apfel "Summarise this repo" 또는 파일을 파이프: cat README.md | apfel.
3. 스크립트에서 사용 – 자동화용 JSON 출력: apfel -o json "Translate to German: hello" | jq .content.
4. 로컬 서버 실행 – apfel --serve로 http://localhost:11434/v1에 연결 가능한 OpenAI 클라이언트 설정.
5. 도구 추가 – apfel --mcp ./mcp/calculator/server.py "What is 15×27?".

제한 사항

• macOS 26(Tahoe) 이상, Apple Silicon Mac에서만 작동; 모델 크기는 고정(~3B 파라미터).
• macOS 26 / M1–M2에서는 컨텍스트 창이 4096 토큰, macOS 27에서 M3+ 12GB에서는 8192 토큰.
• 임베딩 없음, 대규모 병렬 처리 가속 없음; 응답은 몇 초 소요.
• 가드레일이 일부 프롬프트를 차단할 수 있음; --permissive로 완화 가능.
• 비전 지원(이미지 이해)은 macOS 27에서만 가능.

누구를 위한가요

• 클라우드 사용료를 지불하지 않고도 로컬 스크립트, CI 파이프라인, 프로토타이핑에 빠르고 개인 정보 보호가 가능한 LLM을 원하는 개발자.
• 이미 OpenAI 호환 SDK를 사용 중이며 Mac 워크스테이션에 즉시 사용 가능한 로컬 백엔드를 원하는 팀.
• 셸 중심의 AI 어시스턴트를 즐기며 MCP를 통한 도구 호출을 원하는 파워 유저.

더 알아보기

• 전체 설치 가이드: docs/install.md.
• CLI 플래그 참조: docs/cli-reference.md.
• OpenAI 호환성 세부 정보: docs/openai-api-compatibility.md.
• MCP 도구 예제: docs/mcp-calculator.md 및 포함된 demo/ 폴더.
• 예제 프롬프트: docs/EXAMPLES.md.

결론 – apfel은 Apple이 제공하는 온디바이스 LLM을 유연한 유닉스 유틸리티와 로컬 OpenAI 호환 서버로 변환하여, 외부 API 없이 macOS에서 프라이버시 중심의 AI 워크플로우를 가능하게 합니다.