---
title: "파이썬 노트북에서 노드 기반 AI 실험 러너로 넘어간 개인 프로젝트"
published: 2026-05-19T21:50:13.000Z
canonical: https://jeff.news/article/3023
---
# 파이썬 노트북에서 노드 기반 AI 실험 러너로 넘어간 개인 프로젝트

이 글은 로컬 AI 모델로 자기 글쓰기 스타일을 흉내 내보려다, 범용 AI 실험 러너를 만들게 된 과정을 담은 저장소 소개야. 핵심은 Node 20 기반 runner, macOS Apple Silicon용 MLX, YAML recipe, 로컬 UI를 한 번에 실행해보는 작은 starter 구조임. 연구 논문급 새 기술이라기보다는 개인 AI 실험을 반복 가능하게 묶어보려는 오픈소스 도구에 가까워.

- 이 저장소는 “내 글쓰기 스타일을 따라 하는 로컬 AI 모델”을 만들려다 생긴 AI 실험 runner starter임
  - 출발점은 포틀랜드를 배경으로 한 weird fiction을 쓰던 개인 프로젝트였음
  - 처음엔 Python notebook으로 시작했는데, 끝까지 가보니 Node 기반 범용 실험 runner 형태가 됐다는 이야기임
  - 생성 예시 문단도 포함돼 있는데, 글쓴이는 embedding보다 keyword retrieval 쪽이 voice 유지에 영향을 줬다고 설명함

- 사용 흐름은 꽤 작게 설계돼 있음
  - clone, install, run을 하면 1분 안쪽으로 test pipeline이 end-to-end로 실행되는 걸 목표로 함
  - package.json에는 runner GitHub 의존성, setup/pipeline/ui/clean 스크립트, 그 외에는 거의 아무것도 없음
  - recipe나 override는 runner package에서 오거나 첫 실행 때 scaffold되는 구조임

- 요구 환경은 Node 중심이지만, MLX를 쓰려면 애플 생태계 제약이 붙음
  - Node 20 이상이 필요하고, runner는 CoffeeScript와 node:sqlite를 사용함
  - Python 3.10 이상은 MLX 표면을 실행할 때 필요함
  - MLX는 Apple Silicon 전용이라, 해당 부분까지 쓰려면 macOS와 Apple Silicon이 사실상 전제임

- run-first.sh는 setup부터 demo까지 한 번에 묶어주는 입구임
  - npm run setup은 override.test.yaml을 override.yaml로 복사하고 Python 가상환경을 만든 뒤 MLX 관련 패키지를 설치함
  - npm run demo 또는 npm run pipeline은 override.yaml에 지정된 pipeline을 실행함
  - npm run ui는 127.0.0.1:4311에서 로컬 UI 서버를 띄움
  - npm run clean은 runtime artifact를 지워 fresh clone 상태로 되돌림

- 흥미로운 건 UI를 node_modules 안에 숨기지 않고 프로젝트 루트에 둔다는 점임
  - ui와 ui_server.coffee가 first-class project file로 제공됨
  - 사용자는 패널 추가, protocol 변경, layout 교체 같은 수정을 프로젝트 파일에서 바로 할 수 있음
  - 패키지 업데이트가 이 파일들을 건드리지 않고, 필요하면 npm run ui:reset으로 기본값을 다시 덮어쓸 수 있음

- 실험 확장은 override.yaml과 recipe 교체로 하는 방식임
  - 기본 pipeline은 test이고, 9단계로 runner 메커니즘을 한 번씩 보여주는 용도임
  - prompt_ite는 iterative prompt generation, diary_ite는 LoRA 유무에 따른 diary generation A/B, lora_ite는 LoRA adapter training 쪽임
  - oracle_ite는 raw story에서 KAG extraction을 하는 흐름이고, diary_translate_ite는 adapter 기반 translation recipe임

- 자기 recipe를 만들려면 config 디렉터리와 scripts 디렉터리를 프로젝트 쪽에서 덮어쓰면 됨
  - config/myname.yaml을 만들고 override.yaml에서 pipeline 값을 myname으로 바꾸는 식임
  - step을 바꾸고 싶으면 scripts/name.coffee를 두면 runner가 제공하는 파일보다 프로젝트 파일이 우선함
  - 즉, engine은 패키지에서 가져오고 실험 구성과 override는 로컬 프로젝트에서 관리하는 모델임

- 한국 개발자 관점에서는 “대세 도구”라기보다 로컬 LLM 실험을 구조화하는 참고 샘플에 가까움
  - Apple Silicon에서 MLX로 이것저것 실험하는 사람에게는 setup, recipe, UI 분리 방식이 꽤 참고될 수 있음
  - 반대로 클라우드 GPU나 리눅스 서버 중심 워크플로우라면 바로 가져다 쓰기엔 제약이 많음
  - 그래도 notebook에 실험이 흩어지는 문제를 runner와 YAML lifecycle로 묶는 접근은 꽤 현실적인 포인트임

## 핵심 포인트

- Node 20 이상, Python 3.10 이상, Apple Silicon macOS에서 MLX 기반 실험을 돌릴 수 있음
- run-first.sh나 npm script로 setup, demo, ui, clean 라이프사이클을 제공함
- 프로젝트 루트의 UI 파일을 직접 고칠 수 있고, 패키지 업데이트와 분리됨
- pipeline recipe를 바꿔 prompt, diary, LoRA, oracle, translation 실험으로 확장할 수 있음
- override.yaml과 config YAML, CoffeeScript step override로 실험 구성을 바꾸는 구조임

## 인사이트

개인 창작용 로컬 모델 실험에서 시작했지만, 실제로는 “AI 실험을 매번 노트북에서 손으로 굴리지 말고 recipe와 runner로 관리하자”는 쪽에 더 가까운 프로젝트야. 다만 Apple Silicon과 MLX에 묶인 부분이 있어서 한국 개발자 전체보다는 로컬 LLM 실험을 하는 사람에게 더 직접적으로 맞음.