English · Français · Español · 简体中文 · Deutsch · 日本語 <!-- i18n-switcher -->

Atome LM

tests

Hugging Face

License: Apache 2.0

비트 단위 정확도를 갖춘 Python ↔ C99 추론 엔진을 가진 라우팅된 테너리(ternary) 초소형 언어 모델의 참고 구현체로, 마이크로컨트롤러급 RAM 예산에 맞춰 설계되었습니다.

세 가지 알려진 아이디어를 하나로 결합한 60K 기본 매개변수 LM 오픈 키트:
테너리 가중치(ternary weights) ([BitNet b1.58] 이후)
토큰별로 라우팅되는 하이브리드 SSM + 희소 어텐션(sparse-attention) + 로컬 컨볼루션 블록 ([Hymba] 및 [MossNet] 이후)
그리고 초소형 규모의 바이트 토크나이저 ([Guertler 2024] 이후).
기여는 아키텍처가 아닌 통합: 테스트를 통해 비트 단위 정확도의 Python ↔ C 일치가 강제된, 완전한 학습(train) → 테너리 내보내기(ternary export) → base-3 패킹 → C99 추론 경로입니다.

빠른 링크:

• 📄 아키텍처 설명: PAPER.md
• 🔬 정직한 결과, 944 K 역변환 포함: HONEST_RESULTS.md
• 🌐 브라우저 라이브 데모 (설치 불필요): atomelm.com/demo.html
• 🏠 프로젝트 홈: atomelm.com

키트 받기: 학습 코드, C 엔진, 벤치마크, 논문 및 학습된 가중치를 이 저장소에서 모두 제공하며, [Apache 2.0 License] 하에 배포됩니다. scripts/train_demo.py를 사용하여 CPU에서 약 30분 만에 자체 체크포인트를 학습시키거나, 번들된 944 K 체크포인트를 즉시 실행할 수 있습니다.

MCU 상태: QEMU ARM (Cortex-M3, MPS2-AN385) 패리티가 FP32로 통과하며, 재현 가능한 실제 실리콘 데모를 통해 물리적 ESP32-WROOM-32에서 944K 체크포인트를 구동합니다. 이는 일관된 텍스트를 완전히 오프라인으로 약 1 토큰/초 속도로 출력하며, hardware/esp32-wroom32/를 참조하세요 (사전 빌드 바이너리 + 직렬 로그 + 원클릭 플래시). 이 데모는 단순한 실행 증명(proof-of-execution)일 뿐이며, 상품화된 초기 구동(productized bring-up) — 즉 Atome Secure Boot Pack(서명된 .atome 블롭, 개발/운영 모드 플래그, 플랫폼별 보안 부팅, 검증)과 플랫폼별 강화(hardening)는 atomelm.com에서 통합 솔루션으로 판매합니다.

가중치(Weights)는 checkpoints/에 포함되어 있습니다:

• atome_944k.bin (271 KB) — 패킹된 C 엔진 블롭(ATOME01 형식)으로, 추론 엔진이 직접 로드할 수 있습니다.
• atome_1m_v1.pt (3.7 MB) — 이를 생성한 PyTorch 소스 체크포인트이며, 이 파일을 사용하여 미세 조정하거나 다른 #define 값에서 재내보낼 수 있습니다.
• vanilla_1m_v1.pt (3.7 MB) — HONEST_RESULTS.md의 944K A/B 역전 비교에 사용된 FP32 바닐라 GPT 기준선입니다. 비교를 엔드투엔드로 재현할 수 있도록 제공됩니다.

944K 체크포인트는 제품이 아닌 연구 데모 아티팩트입니다: 이는 폭이 좁고, 때로는 일관성이 떨어지며, 단일 코퍼스로 학습되었습니다. 이 파일은 아키텍처가 구동 가능하도록 만들기 위한 것이지, 품질 기준을 설정하기 위함이 아닙니다. 재현에는 포함된 학습 코드를 사용하여 CPU/GPU 기준으로 약 $1–2의 비용이 들며, 이 키트의 어떤 것도 재현 장벽이 되지 않습니다.

재현 가능한 결과, 좁은 영역(narrow regime)

TinyStories에서 3000 스텝, 단일 시드: 고정된 파라미터 개수에서 Atome의 라우팅된 테너리 블록은 바닐라 GPT-FP32 기준선 대비 6.31 ppl 대 8.12를 기록하며 (−22% 감소); 고정된 플래시 예산에서는 6.31 대 13.10 (−52% 감소)를 기록했습니다. 파라미터 일치 시 디스크 점유율은 16배 작습니다 (15.1 KB 대 237.5 KB).

결과는 944 K 파라미터에서 역전되며, 이 지점에서는 일반적인 FP32 기준 모델이 약 11% 더 우수합니다. Atome의 목표는 의도적으로 1M 미만, 즉 마이크로컨트롤러(MCU)급 영역에 맞춰져 있습니다. 그 이상으로 올라가면 테너리(ternary)의 용량 한계가 격차를 줄이고 오히려 앞지르게 됩니다. FRONTIER.md에서 전체 재현이 가능하며, 역전된 부분까지 포함한 완전하고 정직한 내용은 HONEST_RESULTS.md에서 읽을 수 있습니다.

왜 (Why)

데이터센터 LLM은 데이터센터 RAM을 전제로 합니다. 원격 센서에 벽에 박힌 $2짜리 마이크로컨트롤러, 보청기, 배터리 구동 장난감 또는 온도 조절기는 그러한 메모리를 갖추고 있지 않습니다. Atome LM은 이러한 제약 조건에 맞춘 모델 설계의 결과물입니다:

• 테너리 가중치 (Ternary weights) ({-α, 0, +α}를 각 텐서당 사용하며, BitNet b1.58 스타일). 추론 시 행렬 곱셈(matmul)에서 부동 소수점(float) 곱셈이 없습니다.
• 3가지 경로 블록 (3-pathway block) (로컬 깊이별 컨볼루션(local depthwise conv), 대각선 SSM, 상위 K 희소 어텐션(top-k sparse attention))을 토큰당 소프트 라우터(soft router)가 혼합합니다. Atome C99 엔진 구조에 정확히 맞도록 설계되어 훈련된 체크포인트가 플래시로 내보내지고 Python과 C 간에 **비트 단위의 동일성(bit-exact parity)**을 유지하며 실행됩니다.
• 바이트 토크나이저 (Byte tokenizer). 전송할 BPE 테이블이 없습니다.
• 라우터 엔트로피를 보정 신호로 사용. 토큰당 라우터 분포의 엔트로피는 모든 위치에서 무료로 관찰 가능합니다. Atome-LLM 엔진 기본값인 단일 좁은 코퍼스(narrow corpus)에 대한 60 K 파라미터 규모에서는 이 신호가 노출되지만, 해당 규모에서의 불확실성 추정기(uncertainty estimator)로서의 보정(calibration)은 여기서 측정되지 않았습니다. 우리는 예비적으로 (본 릴리스에 포함되지 않은 더 큰 3 M 파라미터 모델에서) 엔트로피가 도메인 외부 입력(out-of-domain inputs)을 추적하고 토큰당 손실과 상관관계가 있음을 관찰했습니다. 이는 아직 공개되지 않은 관측치로 보고되며, 측정값은 향후 릴리스에서 제공될 예정입니다.

이것이 무엇이고 무엇이 아닌지 (What this is and isn't)

• 특징: cents급 하드웨어에서 실행되는 테르너리 LM(ternary LM)의 Python 학습 측면 및 아키텍처입니다.
• 아닌 것: 범용 챗봇이 아닙니다. 엔진 기본 설정(d_model=64, n_layers=4)으로 모델은 약 60K개의 파라미터를 가지며, 약 20KB의 플래시로 내보내집니다. 특정 단일 도메인(임베디드 시스템 Q&A, 명령줄 도움말, 단일 FAQ)에 맞춰 학습시키면 해당 범위 내에서 유창하게 작동합니다. 이 크기에서 범용적으로 사용하려고 하면 일관성 없는 출력을 생성하는데, 이는 아키텍처의 문제가 아니라 용량(capacity)의 반영입니다. 더 많은 여유 공간이 필요하면 d_model과 n_layers를 늘리고 (예: d_model=128, n_layers=6 ≈ 600K 파라미터, ~150KB 패킹), 일치하는 #define을 사용하여 다시 내보내십시오.

설치(Install)

./install.sh          # CPU 전용 가상 환경(venv) + 종속성 + 환경 확인

또는 수동으로: pip install -e . (Python ≥ 3.10, PyTorch ≥ 2.0). 처음이신가요?
QUICKSTART.md는 클론부터 마이크로컨트롤러에 준비된 모델까지의 60초 경로입니다.

빠른 시작(Quick start)

import torch
from atome_llm.core.atome_lm import AtomeLM

...

작은 데모 학습(Train a tiny demo)

python scripts/train_demo.py --data path/to/text.txt --steps 1000 \
    --d-model 64 --n-layers 4 --output checkpoints/atome_demo.pt

내장된 build_corpus.py는 스모크 트레이닝(smoke training)을 위해 몇 가지 허가 라이선스가 부여된 소스(tinystories, esp-idf, mcu-wikipedia)를 가져옵니다:

python scripts/build_corpus.py --source tinystories --max-bytes 500000 \
    --output data/tinystories.txt

체크포인트 사용해보기(Try a checkpoint)

python scripts/demo.py --checkpoint checkpoints/atome_demo.pt
# 또는, 체크포인트 없이 플러그먼트(plumbing)를 테스트하려면:
python scripts/demo.py --random --temperature 0.8 --top-p 0.9

REPL은 프롬프트에 대한 연속된 내용과 레이어별 라우터 엔트로피 막대를 출력합니다. 이는 무료로 노출되는 메타인지(metacognition) 신호입니다.

샘플링(Sampling)

AtomeLM.generate(...)는 기본적으로 탐욕적 argmax(greedy argmax)를 사용하며 (C 엔진의 atome_predict_next와 일치), 선택적 인자인 temperature, top_p, top_k, 그리고 generator=를 통해 시드 기반 재현성(seeded reproducibility)을 갖춘 뉴클리어스/top-k 샘플링이 가능합니다.

벤치마크 (Benchmark)

python scripts/benchmark.py            # tiny / default / large

세 가지 대표 구성(config)에서의 CPU 순전파(forward) 및 생성(generate) 지연 시간입니다. 아키텍처 변경 후 회귀 검사(regression check)에 유용하며, MCU 수치는 아닙니다.

마이크로컨트롤러로 내보내기 (Export to a microcontroller)

python scripts/export_to_atome.py \
    --checkpoint checkpoints/atome_demo.pt \
    --output checkpoints/atome_demo.atome \
...

이 명령어는 .atome 플랫 바이너리를 생성하며, 이를 C에서 #include하고 atome_load(...)를 통해 Atome C99 엔진으로 로드할 수 있습니다. 기본 구성에서는 이 바이너리가 100 KB보다 훨씬 작아 ESP32-S3, STM32F4, RP2040, nRF52840, ESP32-C3에 편안하게 들어갑니다.

아키텍처 (Architecture)

x → LayerNorm → ┬─→ Local  (depthwise causal conv k=5)        ─→┐
                ├─→ State  (diagonal SSM, O(L))                 ─→ Σ → +x
                └─→ Sparse (top-k attention, O(L·k))            ─→┘
...

세 가지 경로입니다. 세 가지 다른 귀납적 편향(inductive biases)을 가집니다. 각 위치에 가장 적합한 경로를 학습하는 공유된 per-token 라우터가 존재합니다. 이 라우터의 per-token 엔트로피는 모든 레이어에서 무료로 제공되는 per-position 불확실성 신호로 노출됩니다.

전체 아키텍처 이야기는 PAPER.md에 있습니다.

테스트 (Tests)

pytest -q

라이선스 (License)

Apache License 2.0 — LICENSE와 NOTICE를 참조하십시오.

이 키트는 완전히 공개되어 있습니다: 좌석당 또는 장치당 비용 없이 사용, 수정, 재배포 및 상업 제품에 탑재할 수 있습니다. Apache 2.0 특허 부여는 여기서 출시된 3-경로 라우팅 테너리 아키텍처를 포함합니다.

checkpoints/에 배포된 체크포인트(atome_944k.bin, atome_1m_v1.pt, vanilla_1m_v1.pt) 역시 Apache-2.0 라이선스를 따릅니다. 이들은 제품이 아닌 참고용/연구용 아티팩트입니다. 상업적 통합 — 실리콘 초기 구동(silicon bring-up), Atome Secure Boot Pack (서명된 .atome 블롭, dev/prod 플래그, 플랫폼별 보안 부팅, 증명(attestation)), 플랫폼별 강화(hardening), 대형 내부 V2 모델의 커스텀 도메인 미세 조정(custom-domain fine-tuning) — 은 atomelm.com에서 이용 가능합니다.

인용 (Citation)

@software{atome_llm_2026,
  title  = {Atome LM: a tiny ternary language model for microcontroller deployment},
  author = {Atome LM contributors},
...