ThorOdinson246/whatisit-nl2sh

Local natural-language-to-shell command generator. A 941 MB fine-tuned Qwen2.5-Coder-1.5B running on CPU in ~1s.

whatisit‑nl2sh – 일반 영어를 셸 명령으로 변환 (오프라인)

기능 – whatisit은 작업의 자연어 설명을 받아 해당하는 Unix 셸 명령을 반환하는 작은 명령줄 도구입니다. llama.cpp를 통해 로컬에서 1.5 B 매개변수 LLM을 실행하므로, 명시적으로 원격 OpenAI 호환 엔드포인트를 지정하지 않는 한 데이터가 머신을 벗어나지 않습니다.

중요성 – 웹을 검색하거나 정확한 구문을 기억하지 않고도 빠르게 그럴듯한 명령을 얻을 수 있으며, 개인 정보를 보호하고 클라우드 API의 지연을 피할 수 있습니다. 모델은 작고(약 941 MiB) CPU 전용 노트북에서도 실행할 수 있습니다.

빠른 시작

# CLI 설치 (pipx 권장, 일반 pip도 가능)
pipx install whatisit          # 또는: pip install whatisit
whatisit setup                 # 모델 다운로드 및 llama.cpp 바이너리 확인

이미 llama.cpp 빌드가 있다면 --bin-dir로 whatisit에 지정하세요.

일반적인 사용법

# 간단한 쿼리 – 명령 출력
whatisit find files bigger than 100MB in this folder
# → find . -size +100M -exec ls -lh {} \;

# 확인 후 명령 실행
whatisit -e compress the logs directory into a tarball

# 여러 대안 가져오기
whatisit -n 3 list python files modified today

# 스크립트에서 출력 사용
cd "$(whatisit -q the directory holding the largest log file)"

플래그:

-e/--execute – 확인을 요청한 후 명령을 실행합니다.
-n N – N개의 후보 명령을 반환합니다.
-q/--quiet – 원시 명령만 출력합니다 (명령 치환에 유용).
-t/--timing – 생성에 걸린 시간을 표시합니다.
-p/--prefill-command – 실행 전에 생성된 명령을 편집 가능한 프롬프트에서 엽니다.

셸 프롬프트에 통합할 수도 있습니다:

# ~/.bashrc 또는 ~/.zshrc에 추가
eval "$(whatisit shell-init)"

이제 whatisit <request>는 생성된 명령을 다음 프롬프트 줄에 배치하여 쉽게 편집할 수 있습니다.

내부 작동 방식

모델 – Qwen2.5‑Coder‑1.5B‑Instruct(또는 선택적 3 B 변형)의 LoRA 미세 조정 버전으로, GGUF Q4_K_M(약 941 MiB)으로 양자화되었습니다. 훈련에는 125 k개의 NL‑to‑command 쌍이 사용되었습니다.
런타임 – 모델은 llama.cpp의 llama-server에 의해 제공됩니다. 첫 번째 호출은 상주 서버를 시작하고, 이후 호출은 모델이 RAM에 유지되므로 빠릅니다(1.5 B 모델의 경우 약 1.6 GiB).
생성 – 온도 0의 탐욕 디코딩으로 동일한 쿼리는 항상 동일한 명령을 생성합니다. Intel i5‑11320H에서의 일반적인 처리량: 약 39 tokens/s, 워밍업 후 지연 시간 약 0.6초.
안전 계층 – 출력 전에 규칙 기반 검사기가 위험한 패턴(/의 재귀 삭제, 블록 장치 쓰기, 권한 상승 트릭, 리버스 셸 등)을 스캔합니다. 플래그가 지정된 명령은 DANGER(자동 실행 금지) 또는 CAUTION(경고하지만 선택 가능)으로 표시됩니다.

오프라인 vs. 원격 모드

기본 – 완전 오프라인; 요청이 호스트를 벗어나지 않습니다.
원격 – 설정에서 openai_base_url 및 openai_model(또는 Ollama 엔드포인트)을 설정하여 쿼리를 호스팅 API로 라우팅합니다. 도구는 원격 호출마다 경고를 출력합니다.

설치 세부 사항

단계	필요한 것
CLI	`pipx install whatisit`(또는 venv에서 `pip install whatisit`)
모델 파일	Hugging Face에서 `huggingface_hub`를 통해 `nl2sh-1.5b-Q4_K_M.gguf`(약 941 MiB) 다운로드
`llama.cpp` 바이너리	사전 빌드 릴리스(`llama-server`, `llama-cli`)를 가져오거나 직접 빌드; Linux에서는 glibc ≥ 2.34 필요
설정	`whatisit setup --model <path> --bin-dir <path/to/llama.cpp/bin>`

Nix/NixOS 사용자를 위해 Nix flake도 제공되며, llama.cpp 패키지가 자동으로 연결됩니다.

성능 및 벤치마크

InterCode‑ALFA 벤치마크(300개의 NL‑to‑shell 작업)
- whatisit(1.5 B) – 62 % 통과율, 워밍업 후 중앙값 지연 0.59초, 콜드 스타트 2초.
- 선택적 3 B 모델 – 65.7 % 통과, 생성이 느림(약 17 tok/s) 및 RAM 사용량 높음(약 3.4 GiB).
- 미세 조정되지 않은 Qwen2.5‑Coder‑7B(61.3 %) 및 GPT‑4o(73 %)와 비교.
미세 조정되지 않은 기본 모델(54 %) 대비 개선은 통계적으로 유의미합니다(p ≈ 0.004).

안전 및 제한 사항

안전 – 재귀 삭제, 블록 장치 쓰기, 권한 변경, 네트워크 가져오기 명령 등을 포함하는 규칙 기반 거부 목록. 샌드박스가 아니므로 출력을 검토해야 합니다.
제한 사항 – 단일 턴만 지원(셸 상태 없음), 최대 64‑token 출력(다중 줄 스크립트에는 부적합), 영어 전용, 벤치마크 특정 성능.

라이선스 및 귀속

코드: Apache‑2.0
모델: Qwen2.5‑Coder‑1.5B‑Instruct(Apache‑2.0)에서 파생되었으며, 다양한 허용 라이선스(MIT, CC‑BY‑4.0, CC0, Apache‑2.0)의 소스에서 훈련 데이터를 사용. 전체 데이터 세트는 나중에 공개될 예정입니다.

다음 단계

더 높은 정확도를 위해 3 B 모델을 시도하세요(whatisit setup --size 3b).
안전 검사기 개선 또는 다중 턴 상호 작용 지원에 기여하세요.
저장소를 팔로우하여 매일 업데이트 확인(설정에서 비활성화 가능).

요약 – whatisit은 일상적인 영어 지침을 셸 명령으로 변환하는 개인 정보 보호, 저자원 방법을 제공하며, 내장 안전 필터와 선택적 원격 API 폴백을 갖추고 있습니다.