README-kr.md

metadata

license: mit
pipeline_tag: text-generation
library_name: mlx
base_model: moonshotai/Kimi-Linear-48B-A3B-Instruct
tags:
  - mlx
  - quantization
  - mxfp4
  - mixture-of-experts

Kimi-Linear-48B-A3B-Instruct · MXFP4 · 32-Group (MLX)

moonshotai/Kimi-Linear-48B-A3B-Instruct 기본 모델을 mlx-lm 0.28.4
MXFP4 그룹사이즈 32 설정에 맞춰 양자화한 결과물과 허깅페이스 업로드용 메타데이터가 포함되어 있습니다.
모든 가중치와 부가 파일은 Apple Silicon용 MLX 런타임과 즉시 호환됩니다.

한국어 | English

모델 요약

• 아키텍처: config.json에 정의된 KimiLinear MoE 디코더 전용 트랜스포머 (27 레이어, 히든 사이즈 2304, 어텐션 헤드 32개, 전문가 256명, 토큰당 8명 활성화).
• 컨텍스트 길이: 선형 어텐션 기반 블록으로 약 100만 토큰 수준까지 튜닝되어 있으며, 실제 윈도우는 --max-kv-size 등 런타임 메모리 설정에 따라 달라집니다.
• 토크나이저: tiktoken 기반 BPE (tokenizer_config.json, tiktoken.model)이며 특수 토큰 ID는 파일 내부에 정의되어 있어 카드에서 하드코딩하지 않습니다.
• 채팅 템플릿: 공식 Kimi 툴 호출 흐름을 반영한 다중 턴 템플릿이 chat_template.jinja에 포함되어 있습니다.
• 라이선스: 업스트림 moonshotai/Kimi-Linear-48B-A3B-Instruct와 동일하게 MIT.

양자화 세부 정보

• 툴링: python3 -m mlx_lm.convert -q (mlx-lm 0.28.4 이상)으로 MXFP4 가중치를 생성.
• 포맷: MXFP4 4비트 / 그룹사이즈 32가 모든 주요 선형 계층에 적용됩니다.
• 예외: Mixture-of-Experts 게이트 프로젝션은 라우팅 안정성을 위해 8비트 / 그룹사이즈 64로 유지되며 quantization_config 내에 전부 명시되어 있습니다.
• 샤드 구성: model-0000n-of-00005.safetensors 5개와 model.safetensors.index.json으로 스트리밍 로드를 지원합니다.
• 메모리: Apple Silicon 통합 메모리 약 26~29 GB 수준에서 가중치를 수용하며, KV 캐시는 컨텍스트 길이에 따라 추가 메모리를 요구합니다.

config.json 미리보기:

"quantization_config": {
  "group_size": 32,
  "bits": 4,
  "mode": "mxfp4",
  "model.layers.1.mlp.gate": {"group_size": 64, "bits": 8},
  "model.layers.2.mlp.gate": {"group_size": 64, "bits": 8},
  "model.layers.3.mlp.gate": {"group_size": 64, "bits": 8},
  "...": "26번 레이어까지 동일 패턴"
}

포함 파일

파일	용도
config.json, generation_config.json, configuration_kimi.py	HF 설정 + 맞춤 MLX Config 클래스
model-0000*-of-00005.safetensors, model.safetensors.index.json	양자화된 MXFP4 샤드
modeling_kimi.py	KimiLinearForCausalLM 구현
tokenizer_config.json, special_tokens_map.json, tiktoken.model, tokenization_kimi.py	토크나이저 자산
chat_template.jinja	apply_chat_template용 템플릿
README.md, README-kr.md	영문/국문 모델 카드

사용 의도 및 제한

• 권장 사용처: Apple Silicon 환경에서 다국어 어시스턴트, 툴 호출, 롱컨텍스트 RAG.
• 비권장 사용처: 의료·법률·금융 등 검증이 필요한 결정 혹은 필터링되지 않은 위험 지시 처리.
• 안전: 기본 모델의 안전 프로필을 그대로 따르므로, 제품 배포 시 추가 필터링과 RLHF 계층을 권장합니다.
• 보안: modeling_kimi.py에 커스텀 모듈이 있으므로 CLI 실행 시 --trust-remote-code, 파이썬 API에서는 trust_remote_code=True를 반드시 사용하고 민감 데이터는 오프라인/격리 환경에서 다루세요.

MLX 사용 방법

1. macOS 13.6+ / Apple Silicon에서 MLX 툴 설치:

   pip install -U mlx-lm  # 혹은 main: pip install -U "git+https://github.com/ml-explore/mlx-lm.git@main"
   # 오프라인 캐시 전용:
   # HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 ...
   

2. CLI 채팅 (템플릿·정지 규칙 자동 적용):

   mlx_lm.chat \
     --model /path/to/Kimi-Linear-48B-A3B-Instruct-MXFP4-GS32-MLX \
     --trust-remote-code \
     --max-tokens 512 --temperature 0.7 --top-p 0.9
   

   256K 토큰 이상 실험 시 --max-kv-size 262144(또는 필요에 따라 더 큰 값)을 추가하세요.

3. 파이썬 예시:

   from mlx_lm import load, generate
   from mlx_lm.sample_utils import make_sampler, make_logits_processors
   
   model, tok = load(
       "/path/to/Kimi-Linear-48B-A3B-Instruct-MXFP4-GS32-MLX",
       trust_remote_code=True,
   )
   
   messages = [{"role": "user", "content": "Kimi Linear 구조를 간단히 요약해줘."}]
   prompt = tok.apply_chat_template(messages, add_generation_prompt=True)
   
   sampler = make_sampler(temperature=0.7, top_p=0.9)
   procs = make_logits_processors(repetition_penalty=1.1, repetition_context_size=64)
   
   print(
       generate(
           model,
           tok,
           prompt,
           max_tokens=512,
           sampler=sampler,
           logits_processors=procs,
       )
   )
   

   허브를 쓰지 않아야 한다면 실행 전에 HF_HUB_OFFLINE=1, TRANSFORMERS_OFFLINE=1을 설정하세요.

변환 메모

• 원본 체크포인트: 2025-11-07 UTC 기준 moonshotai/Kimi-Linear-48B-A3B-Instruct.
• 실제 사용 커맨드:

  python3 -m mlx_lm.convert \
    --hf-path moonshotai/Kimi-Linear-48B-A3B-Instruct \
    --q-bits 4 -q \
    --group-size 32 \
    -o Kimi-Linear-48B-A3B-Instruct-MXFP4-GS32-MLX
  

• 양자화 이후 mlx_lm.chat 샌티티 검사와 safetensors 체크섬으로 무결성을 검증했습니다.

무결성 & 검증

업로드 후에도 로컬에서 샤드 무결성을 재확인하세요:

cd /path/to/Kimi-Linear-48B-A3B-Instruct-MXFP4-GS32-MLX
shasum -a 256 model-*.safetensors > SHA256SUMS
shasum -c SHA256SUMS

추가 팁

• modeling_kimi.py 커스텀 레이어를 등록하려면 항상 --trust-remote-code를 포함하세요.
• mlx_lm.cache_prompt와 --max-kv-size 조합을 활용하면 1M급 프롬프트에서도 통합 메모리 사용량을 안정적으로 제어할 수 있습니다.

무한한 감사

• Moonshot AI — Kimi 패밀리와 Kimi Linear 아키텍처 공개는 언제나 고맙습니다. Moonshot AI GitHub, Kimi Linear, 기술 리포트를 참고하세요.
• Apple Machine Learning Research — 지속적인 업데이트를 통한 지원 덕분에 열심히 학습하고 있습니다. 고맙습니다. MLX, MLX-LM.
• MLX Community — MLX 가중치와 예제를 언제나 빠르게 공유해주어 고맙습니다. 언제나 참고하고 있습니다. mlx-community HF.

저와 같이 개인으로써 새로운 도전을 지속하시는 모든 한국인들을 응원합니다. 직진합시다. (펄럭~)

인용 안내

이 모델을 사용한다면 Moonshot AI와 본 양자화 릴리스를 문서나 연구 결과에 함께 인용해주세요.