TensorFold란? Mac·RTX·DGX Spark의 로컬 모델 실행 엔진

TensorFold는 Apple Silicon과 NVIDIA GPU⁵에서 체크포인트를 읽고 Metal 또는 CUDA 커널로 답을 생성하는 로컬 추론 엔진이에요. 서버를 실행하면 클라이언트가 http://127.0.0.1:8080/v1로 프롬프트⁶를 보내고 답변을 받아요. 아래 흐름은 모델 선택, 서버 시작, 첫 요청을 차례로 보여 줘요.

이 예제는 TensorFold 1.0.8 공식 릴리스에 적힌 Metal 조합을 사용해요. 지원 체크포인트는 TensorFold/Qwen3.8-27B-MLX-4bit, 형식은 MLX⁷ affine 4-bit group 64, 지원 장비는 M5 Max와 M3 Ultra예요. Qwen3.8-27B용 DFlash2 초안 ID는 z-lab/Qwen3.8-27B-DFlash2예요.

릴리스의 Qualified models 표와 tensorfold models 결과를 함께 보면 이 파일과 내 플랫폼이 지원 조합인지 확인할 수 있어요.

표에는 TensorFold 1.0.8의 Metal·CUDA 조합을 적었어요. MIA의 별도 패치형 TensorFold 0.6.x 레시피는 버전과 실행 경로가 달라 이 목록과 구분해요.

Homebrew에서 TensorFold를 설치하고 버전을 확인해요. 이어서 지정된 Qwen3.8-27B 체크포인트를 받으면 TensorFold가 모델 파일 검증을 마치고 캐시에 저장해요.

brew install ashhart/tensorfold/tensorfold
tensorfold --version

모델을 받은 뒤 DFlash2 드래프터를 지정해 서버를 실행해요. 기본 API 주소는 http://127.0.0.1:8080/v1이고, --name qwen38-local로 API에서 부를 모델 이름을 정해요. 서버가 준비되면 터미널에 listening 상태가 표시되고, 이 창을 켜 둔 채 새 터미널에서 요청을 보내요.

tensorfold pull TensorFold/Qwen3.8-27B-MLX-4bit

tensorfold serve TensorFold/Qwen3.8-27B-MLX-4bit --name qwen38-local --drafter z-lab/Qwen3.8-27B-DFlash2 --context 4096 --parallel 1 --temperature 0

서버가 켜진 상태에서 두 번째 터미널을 열고 아래 요청을 보내요. choices[0].message.content에 모델의 한 문장 답이 나오면 요청까지 왕복한 거예요. 앱에서는 OpenAI 호환 제공자를 고르고 base URL http://127.0.0.1:8080/v1, 모델 이름 qwen38-local을 입력해요.

curl -fsS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen38-local","messages":[{"role":"user","content":"Explain what this function returns: def first_item(items): return items[0]"}],"max_tokens":128,"temperature":0}'

모델 ID를 찾지 못했다는 응답이면 tensorfold models에서 실제 캐시 이름을 확인해요. pull 중 sha 검증이나 네트워크 오류가 나면 같은 pull 명령을 다시 실행해 남은 파일을 받게 하고, tensorfold info TensorFold/Qwen3.8-27B-MLX-4bit로 형식과 정보를 확인해요. 서버 시작 때 unsupported family가 나오면 TensorFold 버전과 tensorfold models 목록을 대조해요. 이 모델 경로는 M5 Max와 M3 Ultra의 Metal 조합이에요.