README-kr.md

---
license: mit
pipeline_tag: text-generation
library_name: mlx
base_model: moonshotai/Kimi-Linear-48B-A3B-Instruct
tags:
  - mlx
  - quantization
  - mxfp4
  - mixture-of-experts
---
<div align="center">
  <h1><em><strong>Kimi-Linear-48B-A3B-Instruct · MXFP4 · 32-Group (MLX)</strong></em></h1>
  <strong>moonshotai/Kimi-Linear-48B-A3B-Instruct</strong> 기본 모델을 <code>mlx-lm 0.28.4</code><br>
  MXFP4 그룹사이즈 32 설정에 맞춰 양자화한 결과물과 허깅페이스 업로드용 메타데이터가 포함되어 있습니다.<br>
  모든 가중치와 부가 파일은 Apple Silicon용 MLX 런타임과 즉시 호환됩니다.
  
  [한국어](./README-kr.md) | [English](./README.md)

</div>

## 모델 요약

- **아키텍처**: `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` 미리보기:

```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 툴 설치:
   ```bash
   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 채팅 (템플릿·정지 규칙 자동 적용):
   ```bash
   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. 파이썬 예시:

   ```python
   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`.
- 실제 사용 커맨드:
  ```bash
  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` 체크섬으로 무결성을 검증했습니다.

## 무결성 & 검증

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

```bash
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](https://github.com/moonshotai), [Kimi Linear](https://github.com/MoonshotAI/Kimi-Linear), 기술 리포트를 참고하세요.
- **Apple Machine Learning Research** — 지속적인 업데이트를 통한 지원 덕분에 열심히 학습하고 있습니다. 고맙습니다. [MLX](https://github.com/ml-explore/mlx), [MLX-LM](https://github.com/ml-explore/mlx-lm).
- **MLX Community** — MLX 가중치와 예제를 언제나 빠르게 공유해주어 고맙습니다. 언제나 참고하고 있습니다. [mlx-community HF](https://huggingface.co/mlx-community).

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

## 인용 안내

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