Mac에서 Codex와 Hermes를 사용해 Rapid-MLX로 로컬 코딩 에이전트 실행하기

README 링크에서 발견 · 2 days ago

Apple Silicon에서 로컬 MLX 모델을 대상으로 Codex 및 Hermes 코딩 에이전트를 실행합니다.

What they did

Mac에서 클라우드 API 키 없이 완전히 로컬로 실행되는 코딩 에이전트를 원했다. curl 설치 스크립트를 사용해 기본 Apple Silicon 머신에 Rapid-MLX를 설치하고, ~/.local/bin이 PATH에 포함되도록 터미널을 재시작한 뒤 rapid-mlx CLI를 사용할 수 있음을 확인했다. 다음으로 선택한 코딩 에이전트(Codex와 Hermes)를 평소처럼 설치한 후, `rapid-mlx launch codex`와 `rapid-mlx launch hermes`를 사용해 각 에이전트를 Rapid의 프라이빗 프로필로 실행했다. 이 프로필은 에이전트를 로컬 OpenAI/Anthropic 호환 엔드포인트와 로컬 MLX 모델로 연결한다. 기존 에이전트 설정은 그대로 두고 프라이빗 프로필에 의존해, 나중에 `--remove`로 연결을 깔끔하게 되돌릴 수 있도록 했다. 동일한 4-bit 가중치에서 mlx-lm 및 LM Studio와 디코드 속도를 비교했고, 에이전트 루프가 이에 의존하므로 툴 호출 신뢰성도 확인했다.

How it went

두 에이전트 모두 API 키 없이 로컬 모델을 대상으로 엔드 투 엔드로 실행되었고, 디코드 속도는 일반적인 작업에서 mlx-lm보다 약 1.5배 빨랐습니다(일부에서는 최대 4배). 도구 호출은 다단계 에이전트 루프에 충분할 만큼 잘 유지되었습니다. 모델을 다운로드하고 로드하는 동안 첫 응답이 느렸고, 더 큰 모델은 소형 Mac이 제공하는 것보다 더 많은 통합 메모리를 필요로 했습니다.

Worth knowing

Apple Silicon 전용이며 Python 3.12+가 필요합니다. 첫 실행 지연 시간에는 모델 다운로드와 로드가 포함됩니다. 속도 수치는 특정 하드웨어에서의 단일 실행 결과이므로 방향성 참고 자료로만 활용하세요. 각 코딩 에이전트는 직접 설치해야 하며, 프라이빗 프로필은 Rapid-MLX가 실행 방법을 아는 에이전트만 지원합니다.

Wiring

Rapid-MLX 설치(curl 스크립트 또는 brew), ~/.local/bin이 PATH에 있는지 확인, 코딩 에이전트를 별도로 설치한 다음, `rapid-mlx launch <agent>`를 실행하면 로컬 서버가 시작되고 비공개 프로필을 통해 에이전트가 해당 서버를 가리키게 됩니다. 서버는 OpenAI 및 Anthropic 호환 엔드포인트를 노출하므로 두 프로토콜 중 하나를 사용하는 에이전트 모두 작동합니다. `--remove`는 비공개 프로필만 삭제합니다.

Try it yourself

# Rapid-MLX on Apple Silicon: 설정 및 로컬 모델 에이전트 실행

## 1) 공식 설치 스크립트로 설치

```bash
curl -fsSL https://get.rapid-mlx.dev/install.sh | sh
```

설치 스크립트는 기본적으로 `~/.rapid-mlx/bin`에 바이너리를 배치합니다. 설치가 끝나면 스크립트가 출력하는 안내 문구(설치 경로, 버전)를 확인하세요.

## 2) PATH 수정

셸에 따라 아래 중 하나를 `~/.zshrc`(기본 zsh) 또는 `~/.bashrc`에 추가합니다.

```bash
export PATH="$HOME/.rapid-mlx/bin:$PATH"
```

적용:

```bash
source ~/.zshrc   # 또는 source ~/.bashrc
```

## 3) 버전 확인

```bash
rapid-mlx --version
```

정상이라면 `rapid-mlx x.y.z` 형태의 버전 문자열이 출력됩니다. 명령을 찾을 수 없다면 PATH 적용이 안 된 것이니 2)를 다시 확인하세요.

## 4) RAM에 맞는 4-bit Qwen 모델 선택

Apple Silicon 통합 메모리 기준 대략적인 가이드입니다(4-bit 양자화, KV 캐시 및 오버헤드 포함 여유분 고려).

| 통합 메모리 | 권장 모델 |
|---|---|
| 16 GB | `Qwen2.5-Coder-7B-Instruct` (4-bit) |
| 24–32 GB | `Qwen2.5-Coder-14B-Instruct` (4-bit) |
| 48 GB 이상 | `Qwen2.5-Coder-32B-Instruct` (4-bit) |

모델을 미리 받아두려면:

```bash
rapid-mlx pull qwen2.5-coder-14b-instruct-4bit
```

(정확한 모델 식별자는 `rapid-mlx models list` 또는 `rapid-mlx pull --help`로 확인하세요. 위 이름은 일반적인 명명 규칙 예시입니다.)

## 5) 프라이빗 프로필로 에이전트 실행

기존 에이전트 설정은 건드리지 않고, 격리된 프라이빗 프로필을 사용합니다.

```bash
rapid-mlx launch <agent> --profile private --model qwen2.5-coder-14b-instruct-4bit
```

`<agent>`에는 사용 중인 코딩 에이전트 이름을 넣습니다(예: `claude`, `cursor`, `aider` 등 — `rapid-mlx launch --help`로 지원 목록 확인). 프라이빗 프로필은 별도 디렉터리에 설정을 두므로 기존 `~/.config/<agent>` 등은 변경되지 않습니다.

## 6) 툴 콜링 스모크 테스트

프라이빗 프로필 세션 안에서 다음 세 가지를 순서대로 요청합니다.

1. **파일 읽기**: "`README.md`를 읽고 첫 5줄을 요약해줘."
2. **파일 편집**: "`smoke_test.txt`를 만들어 `hello from rapid-mlx` 한 줄을 써줘."
3. **테스트 실행**: "`npm test`(또는 `pytest -q`)를 실행하고 결과를 알려줘."

각 단계에서 에이전트가 실제 툴 호출을 수행하는지, 인자 형식이 올바른지 확인합니다. 디코드 속도는 세션 로그 또는 `rapid-mlx stats`(지원 시)에서 확인하세요.

### 보고 형식 예시

- **디코드 속도**: `__ tok/s` (모델·프롬프트 길이에 따라 변동)
- **툴 콜 실패**: 없음 / 또는 실패한 호출과 원인(예: JSON 인자 파싱 오류, 존재하지 않는 경로, 권한 문제)

> 실제 수치는 이 Mac에서 실행한 뒤 채워 넣어야 합니다. 위 표와 명령은 환경에 맞춰 조정하세요.

## 정리: 프라이빗 프로필 제거

테스트가 끝나면 프라이빗 프로필만 삭제합니다(기존 에이전트 설정은 그대로 유지).

```bash
rapid-mlx launch <agent> --profile private --remove
```

`--remove`는 프라이빗 프로필 디렉터리와 해당 프로필에서 생성된 캐시만 정리합니다. 기존 에이전트 설정 파일은 건드리지 않습니다.

Source

English