API 및 통합

MiniMax M3.1 Flash GGUF: 로컬 실행, 메모리와 API 비용

Unsloth Q2는 160 GiB, Q4는 256 GiB 메모리를 기준으로 계획합니다. MiniMax 지원 llama.cpp 브랜치를 빌드하고 16K 서버를 실행한 뒤 API 응답과 OpenCode의 파일 읽기 도구 호출을 확인합니다. GGUF, Apple Silicon MLX, DGX Spark EXL3, AMD 경로를 비교합니다. 토큰 일치율과 코딩 작업 성공률을 구분하고 로컬 비용과 MiniMax API 요금을 계산합니다.

BT

BetterToken

편집팀
8 분 분량
목차
MiniMax M3.1 Flash GGUF: 로컬 실행, 메모리와 API 비용

MiniMax M3.1 Flash GGUF는 UD-Q2_K_XL과 160 GiB+ 메모리 예산으로 시작하는 것을 권장합니다. 메모리가 충분하다면 **256 GiB+**에서 UD-Q4_K_XL을 우선 선택합니다. 간헐적인 코딩 작업을 위해 하드웨어를 새로 사야 한다면 API를 먼저 시험하고 비용을 계산합니다.

2026-11-06 기준 Unsloth의 메모리 계획 수치는 16K 텍스트 컨텍스트와 서버 슬롯 하나를 전제로 합니다. RAM과 VRAM에 가중치를 나누어 배치하거나 통합 메모리를 사용할 수 있습니다. 아래 절차는 로컬 API 서버를 실행하고 OpenCode 1에 연결하는 전체 과정을 다룹니다.

M3.1 Flash에는 메모리가 얼마나 필요합니까?

양자화한 가중치 전체와 런타임의 추가 메모리를 함께 확보해야 합니다. MiniMax의 원본 모델 카드는 전체 파라미터가 약 428B이며, 토큰마다 23B가 활성화된다고 설명합니다. 활성 파라미터 수는 연산량을 줄여 줍니다. 하지만 메모리에 불러올 모델이 23B 크기가 되는 것은 아닙니다.

Unsloth가 공개한 다운로드 크기와 메모리 계획 수치는 다음과 같습니다. 다운로드 크기는 십진수 GB이며, 메모리 용량은 GiB입니다.

양자화 버전다운로드 크기가중치 크기메모리 계획 기준
UD-IQ1_M129.4 GB120.5 GiB메모리가 제한된 환경의 실험용. 아래 설명 참조
UD-Q2_K_XL143.9 GB134.0 GiB160 GiB+
UD-IQ3_XXS160.0 GB149.1 GiB176 GiB+
UD-IQ3_S175.5 GB163.4 GiB192 GiB+
UD-Q3_K_XL194.0 GB180.6 GiB208 GiB+
UD-Q4_K_XL249.4 GB232.3 GiB256 GiB+
UD-Q8_K_XL259.1 GB241.3 GiB272 GiB+

Unsloth는 가중치 외에 키-값 캐시, 런타임, 운영체제를 위해 약 20–32 GiB를 추가로 잡습니다. 키-값 캐시는 현재 컨텍스트의 어텐션 상태를 저장합니다. 컨텍스트 확대, 슬롯 추가, 비전 처리, 추측 디코딩에는 더 많은 메모리가 필요합니다.

128 GiB 시스템에서는 1-bit 가중치만 불러와도 7.5 GiB만 남습니다. 이는 안내된 추가 메모리 예산보다 적습니다. Q2에는 더 여유 있게 잡은 Unsloth의 160 GiB 권장치를 적용합니다.

RAM과 VRAM의 합계는 가중치 배치 계획을 위한 수치입니다. 두 메모리를 완전히 같은 자원처럼 사용할 수는 없습니다. 일부 가중치와 연산을 CPU로 옮기는 오프로딩을 사용할 때는 해당 가중치를 담을 호스트 RAM이 충분해야 합니다. 선택한 파일을 다운로드할 디스크 공간도 확보합니다.

모델이 지원한다고 발표한 1M 컨텍스트와 이 표의 메모리 조건은 구분해야 합니다. 이 수치는 1M 컨텍스트 실행에 필요한 메모리 추정치가 아닙니다. 16K로 시작한 뒤 실제 메모리 사용량을 확인하며 늘립니다.

어떤 양자화 버전을 선택해야 합니까?

먼저 Q2로 모델이 메모리에 들어가는지 확인합니다. 메모리가 허용하면 실제 코딩 작업으로 Q4와 비교합니다. Q4가 메모리 예산을 초과하면 3-bit 버전을 선택합니다.

Unsloth의 전체 요약 수치와 범주별 수치는 측정 범위가 다릅니다.

Unsloth가 보고한 top-1 일치율UD-Q2_K_XLUD-Q4_K_XL
가중치를 적용한 전체 요약91.5%98.0%
코딩91.2%97.6%
일반 대화88.5%97.3%
수학95.7%99.0%

전체 요약에는 일곱 범주의 결과에 가중치가 적용됩니다. 대화와 수학 행은 개별 범주를 나타냅니다. Q2에 91.5%와 88.5%라는 서로 다른 값이 있는 이유입니다.

Top-1 일치율은 양자화 모델이 기준 모델과 같은 최상위 토큰을 선택하는지 측정합니다. 코딩 작업의 통과율을 뜻하지 않습니다. 코딩 범주의 91.2%가 저장소 변경의 91.2%가 테스트를 통과한다는 의미는 아닙니다.

1-bit의 전체 일치율이 약 89.9%여도 메모리가 제한된 환경의 실험용으로 접근합니다. 어떤 양자화 버전이든 실제로 사용하기 전에 파일 수정, 도구 인수, 여러 단계의 동작을 검증합니다.

Q8은 Q4보다 다운로드 크기가 9.7 GB 더 큽니다. Unsloth는 공개된 가중치를 손실 없이 변환하며 NVFP4와 BF16의 혼합 형식을 유지한다고 설명합니다. 따라서 “8-bit”라는 이름이 모든 텐서에 동일한 정밀도를 적용한다는 뜻은 아닙니다.

하드웨어에 맞는 런타임은 어떻게 고릅니까?

사용할 런타임에 맞는 체크포인트와 설치 절차를 선택합니다. EXL3가 특정 메모리 용량에서 실행된다는 결과만으로 해당 GGUF도 들어간다고 판단할 수는 없습니다.

다음 경로의 문서는 2026-11-06 기준으로 확인했습니다.

하드웨어검토할 경로적용 범위와 제약
Apple SiliconMLX-community oQ3e 체크포인트와 oMLX드래프트 모델과 비전 구성 요소를 포함해 총 196.152 GB / 182.681 GiB입니다. 런타임과 컨텍스트 메모리를 추가해야 합니다.
DGX Spark 한 대vcruz305의 SAGE-EXL3 설치 절차128 GB GB10 시스템을 대상으로 합니다. 구성 요소 버전이 고정되어 있고 체크포인트 접근에 승인이 필요합니다. 텍스트 전용이며 디코딩 스트림은 하나입니다.
AMD InstinctAMD의 Quark MXFP4 체크포인트문서의 구성은 MI350/MI355, Linux, ROCm 7.2.3을 명시합니다. GPU 네 개를 사용하는 텐서 병렬화 예제를 제공합니다. 일반적인 Radeon 설치 절차는 아닙니다.
RTX 3090 네 장MiniMax의 11월 1일 커뮤니티 게시물에 소개된 맞춤형 추론MiniMax는 @superalesha가 양자화 가중치, 전문가 캐싱, 시스템 RAM을 결합했다고 설명합니다. 이 소개가 다른 구성에서도 같은 성능을 보장하지는 않습니다.

처음 GGUF를 배포한다면 아래의 구체적인 llama.cpp 절차를 따릅니다. 상업적으로 배포하기 전에는 MiniMax Community License를 확인합니다. 저작자 표시와 통지 조건도 살펴야 합니다.

llama.cpp를 빌드하고 16K 서버 실행하기

Unsloth가 링크한 MiniMax 지원 브랜치를 사용합니다. 2026-11-06 기준 llama.cpp PR #31192는 열린 상태이며 아직 병합되지 않았습니다. 이 예제는 확인 당시의 최신 커밋을 고정합니다.

빌드와 다운로드

NVIDIA CUDA 툴킷이 설치된 Ubuntu 또는 WSL에서 Bash를 사용합니다. 나머지 필수 패키지를 설치하고 서버를 빌드합니다.

sudo apt-get update
sudo apt-get install -y build-essential cmake git libssl-dev python3-venv curl jq

git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp fetch origin pull/31192/head:minimax-m31
git -C llama.cpp checkout --detach 6b95a9908d2c7b242817a447708aec38e937e2c0

cmake llama.cpp -B llama.cpp/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --target llama-server

macOS에서는 Xcode 명령줄 도구, CMake, Python, jq를 설치하고 apt-get 명령은 생략합니다. -DGGML_CUDA=ON을 -DGGML_CUDA=OFF로 바꿉니다. 빌드 문서에 따르면 macOS에서는 Metal이 기본으로 활성화됩니다.

Hugging Face CLI로 Q2의 분할 파일 네 개를 모두 다운로드합니다.

python3 -m venv .venv-m31
source .venv-m31/bin/activate
python -m pip install -U huggingface_hub

hf download unsloth/MiniMax-M3.1-Flash-GGUF \
  --local-dir unsloth/MiniMax-M3.1-Flash-GGUF \
  --include "UD-Q2_K_XL/*"

분할 파일은 함께 보관합니다. 첫 번째 파일을 지정하면 서버가 전체 파일을 불러옵니다.

서버 시작과 동작 확인

슬롯 하나, 명시적인 16K 컨텍스트, 일반 텍스트 디코딩으로 시작합니다.

./llama.cpp/build/bin/llama-server \
  --model unsloth/MiniMax-M3.1-Flash-GGUF/UD-Q2_K_XL/MiniMax-M3.1-Flash-UD-Q2_K_XL-00001-of-00004.gguf \
  --alias m31-local \
  --ctx-size 16384 \
  --parallel 1 \
  --n-gpu-layers auto \
  --jinja \
  --flash-attn on \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 0 \
  --min-p 0.0 \
  --chat-template-kwargs '{"reasoning_effort":"high"}' \
  --host 127.0.0.1 \
  --port 8080

이 희소 어텐션 실행 경로에서 PR은 Jinja, Flash Attention, 슬롯 하나를 지정합니다. llama-server 옵션은 GPU 레이어의 자동 할당을 지원합니다.

이 명령은 비전 프로젝터나 DSpark 드래프트 모델을 추가하지 않습니다. API 키도 설정하지 않습니다. 서버는 로컬 루프백 주소에서만 연결을 받습니다.

VRAM 할당이 실패하면 GPU 레이어 수를 줄이고 사용 가능한 호스트 RAM을 확인합니다. 전체 메모리가 부족하면 더 작은 양자화 버전을 선택하거나 메모리를 추가합니다. 오프로딩해도 가중치를 저장할 공간은 필요합니다.

두 번째 Bash 터미널에서 서버의 준비 상태를 확인합니다.

curl -sS -i http://127.0.0.1:8080/health

HTTP 200과 {"status":"ok"}를 받으면 다음 단계로 진행합니다. HTTP 503과 Loading model은 초기화가 아직 진행 중이라는 뜻입니다.

이어서 모델 목록을 조회하고 응답을 요청합니다.

curl -sS http://127.0.0.1:8080/v1/models | jq '.data[].id'

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "m31-local",
    "messages": [
      {"role": "user", "content": "Reply with LOCAL_OK."}
    ],
    "reasoning_effort": "low",
    "max_tokens": 4096,
    "stream": false
  }' | jq '{message: .choices[0].message, finish_reason: .choices[0].finish_reason}'

모델 목록에 m31-local이 있고 message.content에 요청한 답이 들어 있는지 확인합니다. 이 기본 동작 확인에서는 요청의 low 추론 수준이 서버의 기본값 high보다 우선합니다.

finish_reason이 length이면 응답이 출력 한도에 도달한 상태입니다. 최종 텍스트가 없다고 모델 로딩 실패로 판단하기 전에 전체 컨텍스트 예산 안에서 출력 한도를 늘립니다.

OpenCode 1 연결과 도구 호출 확인

OpenCode 문서의 사용자 지정 공급자 연동으로 코딩 클라이언트를 연결합니다. OpenCode는 파일 도구를 실행하고, llama-server는 모델 응답을 생성합니다.

이 설정은 OpenCode 1 문서를 따릅니다. OpenCode 1과 OpenCode 2는 모두 opencode 명령을 사용합니다. 이미 V2를 사용한다면 별도 환경에 설치합니다.

Node.js와 npm이 있는 환경에서 V1을 새로 설치합니다.

npm install -g opencode-ai
opencode --version

프로젝트 루트의 opencode.json에 다음 설정을 기존 설정과 병합합니다. 공식 llama.cpp 공급자 예제를 따른 구성입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MiniMax local",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "m31-local": {
          "name": "MiniMax M3.1 Flash Q2",
          "limit": {
            "context": 16384,
            "output": 4096
          }
        }
      }
    }
  }
}

이 로컬 설정에는 임시로 만든 가짜 API 키가 필요하지 않습니다. 컨텍스트 한도는 실행 중인 서버와 같습니다. 출력 한도는 응답에 배정한 값이며, 모델 자체의 최대 한도를 뜻하지 않습니다.

package.json이 있는 Node 프로젝트에서 다음 명령을 실행합니다. 파일 도구로 package.json을 읽고 scripts.test를 보고하거나 해당 항목이 없다고 답하도록 요청합니다. 파일 수정과 명령 실행은 하지 않도록 제한합니다.

opencode run --model local/m31-local \
  "Read package.json with a file tool. Report scripts.test, or say it is missing. Do not edit files or run commands."

파일 읽기 도구가 실제로 실행된 단계를 찾고 응답을 파일 내용과 비교합니다. 모델이 파일을 읽었다고 말하는 것만으로는 충분하지 않습니다.

클라이언트가 연결되지 않으면 /v1을 포함한 기본 URL과 모델 별칭을 확인합니다. 서버가 실행 중인지도 확인합니다. 텍스트는 작동하지만 도구 실행이 실패하면 --jinja를 확인하고, 저장소를 수정하기 전에 이 제한된 검증을 반복합니다.

첫 세션은 작게 유지합니다. 도구 정의가 컨텍스트를 많이 차지한다면 서버 창을 늘리기 전에 MCP 컨텍스트 비용 가이드의 측정 방법을 적용합니다.

언제 API를 선택하는 편이 낫습니까?

가끔 사용하려고 하드웨어를 새로 사야 한다면 API로 시작합니다. 충분한 하드웨어가 이미 있거나 모델을 로컬에서 실행해야 한다면 로컬 배포를 검토합니다.

2026-11-06 기준 MiniMax의 표준 API 요금은 다음과 같습니다.

과금 항목1 million 토큰당 USD
캐시를 사용하지 않는 입력$0.15
캐시된 입력 읽기$0.015
출력$0.60

이 요금은 계정 잔액에서 차감되는 API 사용료입니다. MiniMax는 Flash의 토큰 단가가 일정하다고도 설명합니다. 캐시 요금 계산식은 새 입력, 캐시 적중, 출력에 요금을 적용하며 별도의 캐시 쓰기 항목을 추가하지 않습니다.

월간 예시로 캐시를 사용하지 않는 입력 20 million 토큰과 과금 대상 출력 2 million 토큰을 가정합니다.

API token charge = 20 × $0.15 + 2 × $0.60
                 = $4.20 per month

텍스트 요청만 사용하며, 캐시 적중과 유료 서버 도구가 없다는 가정입니다. 세금과 결제 시 부과되는 수수료는 제외합니다.

비교를 위해 다음과 같은 가상의 로컬 예산을 계산합니다.

Hardware allocation = $3,000 ÷ 36 months
                    = $83.33 per month

Active electricity  = 0.15 kW × 60 hours × $0.20/kWh
                    = $1.80 per month

Local subtotal      = $85.13 per month

로컬 계산에 들어간 모든 값은 가정입니다. 검증된 시스템의 견적도 아니며, 해당 시스템이 이 작업량을 60시간 안에 처리한다는 근거도 아닙니다. 구매를 결정하기 전에 유휴 전력, 설정, 유지보수, 장비 업그레이드 비용을 더해야 합니다.

실제 실행 결과를 비교할 때는 추론 수준을 맞춥니다. MiniMax API의 기본값은 max이며, 이 로컬 서버의 기본값은 high입니다. 과금된 출력 사용량을 기준으로 완료한 코딩 작업당 비용을 평가합니다. 재시도와 실패한 도구 단계도 포함합니다.

BetterToken도 2026-11-06 기준 MiniMax-M3.1-Flash를 사용량 기반 요금으로 제공합니다. 문서에 명시된 OpenAI 호환 기본 URL은 https://www.bettertoken.ai/v1입니다. 이 경로의 비용은 현재 요금으로 계산합니다.

하드웨어가 이미 있다면 예시의 하드웨어 배분액을 실제 추가 비용으로 바꿉니다. 그런 다음 대표 작업을 측정합니다. 모델이 메모리에 들어가고, 작업 시간이 허용 범위이며, 결과를 실제로 채택할 수 있어야 로컬 배포가 유용합니다.

BetterTokenAI MODEL APIs모든 모델을 하나의 API로GPTClaudeDeepSeekQwenGLMKimiMiniMaxAI API · 사용량 기반 요금BetterToken으로 개발 시작하기API 키를 만들고 첫 요청을 보내세요.시작하기bettertoken.ai
API 및 통합Kimi K2 API 종료: K2.7 Code에서 K3.1 Pro로 이전API 및 통합OpenCode Claude Agent: 설정, 구독 한도와 이용 조건API 및 통합Claude Opus 4.8 빠른 모드 종료: 11월 30일 전에 Opus 5.5로 이전

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.

무료로 시작하기