설치

단체 PC 한 대에 세웁니다

필요한 것은 파이썬 3.10 이상, llama.cpp 의 llama-server, 모델 파일 하나(약 1GB)입니다. pip 패키지는 없습니다. 설치 프로그램과 zip 은 준비 중이라 지금은 저장소를 받아 씁니다.

Windows · Linux · macOS 어디서든 같은 명령입니다. 라즈베리파이·폐폰(Termux)은 지원 기기에.

요구 사양

조건은 하나, CPU 가 있을 것

항목	최소	비고
CPU	x86-64 또는 ARM64, 코어 2개 이상	GPU 불필요. 스레드 수는 코어 수의 절반부터 시험
메모리	4GB	모델 약 1GB + 문맥 2048 토큰. 4GB 폰에서 실측 중
저장공간	2GB	모델 파일 + 작업공간
소프트웨어	Python 3.10+ · llama-server	llama.cpp 릴리스의 CPU 빌드 하나를 풀면 됩니다
인터넷	필요 없음	모델 파일을 받을 때만 한 번

설치 절차

여섯 줄

# 1) 저장소와 모델 파일
git clone https://github.com/StopOrder/matjangbu && cd matjangbu
#    Qwen2.5-1.5B-Instruct Q4_K_M(Apache-2.0) gguf 를 ~/models/qwen1.5b.gguf 로 받아 둔다

# 2) 작업공간 — 명부 CSV(id,이름,구역,세대,옛이름)를 넣는다
python3 -m engine init ~/맞장부 --roster 명부.csv

# 3) 모델 서버(포트 8107) — 명령을 보여주고, --run 을 붙이면 바로 띄운다
python3 -m engine serve --model ~/models/qwen1.5b.gguf --run

# 4) 화면 — 브라우저에서 http://127.0.0.1:8108/try/
python3 -m web --workspace ~/맞장부

로컬 모드는 127.0.0.1에만 엽니다. 인증이 없으므로 --host 0.0.0.0으로 열지 마십시오. 모델 서버가 없어도 규칙 2단까지는 돌고, 남은 줄은 확인 큐에 「모델 미실행」으로 올라옵니다.

설치하면 생기는 것

폴더 하나가 단체 하나

~/맞장부/
  명부.csv          id,이름,구역,세대,옛이름 — 엑셀로 편집
  들어옴/           은행 CSV 를 넣는 곳(화면에서 올려도 여기 저장)
  내보내기/         주간명단·개인별누적·연말합산 CSV
  .matjangbu/
    aliases.json    별칭 사전 — 확인 큐에서 고른 답
    lines.jsonl     줄 대장 — 지우지 않고 덧붙이기만
    imports.jsonl   불러온 파일 대장 — 같은 파일은 다시 넣지 않는다

이 폴더를 통째로 복사해 두는 것이 백업입니다. 대장은 append-only 라 되돌리기도 새 줄로 남습니다. 암호화 백업은 준비 중입니다.

흐름

명부 등록에서 연말 합산까지 네 단계

명부를 넣습니다

이름·구역·세대·옛이름. 세대 칸에 세대주 이름을 적어 두면 가족 명의 이체가 규칙으로 후보에 걸립니다.

은행 CSV 를 불러오거나 봉투를 칩니다

주차와 날짜를 고르고 파일을 올리면 줄마다 3단으로 맞춥니다. 봉투는 명부 자동완성으로 칩니다.

확인 큐에서 고릅니다

남은 줄만 사람에게 옵니다. 고른 답은 별칭 사전에 쌓여 다음 주부터 자동입니다.

기록을 내보냅니다

주간 명단·개인별 누적·연말 합산을 CSV 로. 엑셀에서 그대로 열립니다.

개발자라면

지금 터미널에서

python3 -m venv .venv && .venv/bin/pip install pytest
.venv/bin/python -m pytest -q                       # 모델 서버 없이 전부 돈다(모델은 주입)
python3 -m engine import ~/맞장부 은행.csv --week 2026-W10 --no-model
python3 -m engine list ~/맞장부 --held
python3 -m engine confirm ~/맞장부 <줄id> --person p19
python3 -m engine report ~/맞장부 year --year 2026
bench/bench.sh --model qwen --threads 4              # 3단 실측 30건 → bench/results/
python3 -m web.record --device "…" --model-name "…" --threads 4   # 체험용 기록 다시 만들기

아무것도 나가지 않습니다. 엔진과 웹서버는 외부 주소를 부르지 않습니다. 모델 서버는 127.0.0.1에서만 듣습니다. 이 사이트의 체험 인스턴스는 가공 샘플만 다루고 파일 업로드를 받지 않습니다.

준비 중

설치 프로그램 · zip 준비 중

기기 사양을 재서 모델과 스레드 수를 고르는 설치기는 나비(nabi-core)의 것을 이어받아 만들 예정입니다. 그 전까지는 위 절차로 세웁니다.