2026년 4월 26일 | 개발 깨알 상식_Tips
Gemini CLI 0.40 preview에 gemini gemma 명령이 들어온 걸 보고 제일 먼저 메모한 건, 이제 로컬 모델을 답변용이 아니라 라우팅용으로 붙일 수 있다는 점이었다. 실제 응답은 여전히 Flash나 Pro가 만들고, 그 앞단에서 어떤 요청을 어느 모델로 보낼지를 로컬 Gemma가 먼저 가른다. 바이브코딩할 때 짧은 확인 턴이 유난히 많아지는 흐름을 생각하면, 이 구분이 꽤 실용적이다.
내가 이 변화를 바로 체크한 이유는 "로컬 모델 지원"이라는 말보다 구조가 더 마음에 들었기 때문이다. 로컬 Gemma를 메인 모델로 쓰는 얘기가 아니라, 작은 판단을 로컬로 내리고 본문 생성은 기존 호스티드 모델에 맡기는 식이다. npm view 기준으로 preview 채널은 4월 25일에 0.40.0-preview.4까지 올라와 있었고, 실제 CLI 도움말에도 gemini gemma = Manage local Gemma model routing으로 바로 잡힌다.
Figure 1. Gemini CLI 공식 README 스크린샷. 이번에 눈에 들어온 포인트는 메인 답변 모델이 아니라 로컬 Gemma 라우팅 명령이 별도 진입점으로 올라왔다는 점이었다.
1. 이 기능이 괜찮았던 이유는 로컬 모델의 역할을 작게 잡았기 때문이다
공식 Gemini CLI 릴리스 노트와 패키지 문서를 같이 보면, 로컬 Gemma는 routing decisions를 맡는다고 설명된다. 나는 이 표현이 좋았다. 보통 로컬 모델을 붙인다고 하면 바로 "이걸로 답변까지 다 바꾸자"로 가기 쉬운데, 그 방향은 품질과 운영 이슈가 한꺼번에 커진다. 반대로 분기 결정만 맡기면 실패 표면이 훨씬 좁다.
특히 에이전트 CLI를 오래 켜 두고 쓰다 보면, 실제로는 무거운 추론보다 짧은 질문, 파일 확인, 얕은 코드 수정, 다음 행동 결정 같은 자잘한 턴이 훨씬 많다. 이런 구간까지 전부 동일한 비용 구조로 보내는 건 아깝다고 느낄 때가 있다. 로컬 Gemma 라우터는 바로 그 지점에 꽂힌다. 답을 로컬로 만들지 않으면서도 라우팅 비용은 줄여 보는 실험이 가능해진다.
Figure 2. 로컬 Gemma는 응답 자체보다 "이 요청을 Flash로 보낼지 Pro로 보낼지"를 먼저 고르는 분기기로 보는 편이 이해가 빠르다.
2. 내가 바로 따라 적은 최소 루프는 세 명령이다
이번 기능에서 제일 마음에 든 건 명령 진입점이 단순하다는 점이다. 도움말 기준으로 핵심은 setup, start, status 세 개다. 처음에는 setup으로 LiteRT-LM 런타임과 Gemma 모델을 깔고, 애매할 때는 start로 서버를 직접 띄워 보고, 마지막에는 status로 지금 라우터 상태를 확인하면 된다. 나는 이런 구조가 좋은 이유가, 설치 문제 / 서버 문제 / 설정 문제를 한 단계씩 분리하기 쉽기 때문이라고 본다.
npm install -g @google/gemini-cli@preview
gemini gemma setup --consent
gemini gemma status공식 도움말에서 바로 보이는 옵션도 꽤 실무적이다. setup에는 --port, --skip-model, --start, --force, --consent가 있고, start와 status는 포트만 맞춰 주면 된다. 나는 처음 붙일 때는 기본 포트 9379 그대로 가는 쪽이 낫다고 본다. 포트를 먼저 바꾸면 문제를 좁히기 전에 설정 지점만 하나 더 늘어난다.
공식 Local Model Routing 문서는 LiteRT-LM이 떠 있는지 아래처럼 HTTP 호출로도 확인하게 해 둔다. 이 한 번의 체크가 꽤 중요하다. gemini 쪽에서 잘 안 붙는다고 바로 CLI를 의심하기보다, 로컬 서버가 Gemma API 형식으로 실제 응답하는지를 먼저 보는 편이 훨씬 빠르다.
curl "http://localhost:9379/v1beta/models/gemma3-1b-gpu-custom:generateContent" \
-H 'Content-Type: application/json' \
-X POST \
-d '{"contents":[{"role":"user","parts":[{"text":"Tell me a joke."}]}]}'3. 설정은 user보다 workspace부터 넣는 쪽이 덜 헷갈렸다
Gemini CLI 설정 문서를 읽다가 바로 밑줄 친 부분은 파일 위치였다. 설정은 ~/.gemini/settings.json과 프로젝트/.gemini/settings.json 두 군데에 둘 수 있고, 문서에도 workspace settings override user settings라고 명시돼 있다. 내 경험상 이런 기능은 처음부터 글로벌로 켜기보다 repo 단위로 좁혀서 실험하는 편이 훨씬 낫다.
특히 로컬 라우터는 잘 붙으면 조용히 좋은데, 안 붙을 때는 왜 안 붙는지 추적할 표면이 제법 넓다. 그래서 나는 처음엔 프로젝트 루트의 .gemini/settings.json에만 넣고, 특정 저장소에서만 써 보는 방식을 추천하고 싶다. 그렇게 해 두면 다른 프로젝트 세션까지 같이 흔들리지 않고, 나중에 되돌릴 때도 범위가 작다.
{
"experimental": {
"gemmaModelRouter": {
"enabled": true,
"classifier": {
"host": "http://localhost:9379",
"model": "gemma3-1b-gpu-custom"
}
}
}
}여기서 같이 봐둘 옵션이 두 개 더 있다. 문서 기준으로 experimental.gemmaModelRouter.autoStartServer가 있으면 CLI 시작 때 LiteRT 서버를 자동으로 띄울 수 있고, experimental.gemmaModelRouter.binaryPath를 쓰면 기본 경로 대신 원하는 LiteRT-LM 바이너리를 지정할 수 있다. 다만 둘 다 설정 변경 후 재시작이 필요하다고 적혀 있어서, 나는 처음에는 자동 시작보다 수동 start 쪽으로 붙여 보는 편이 디버깅이 쉽다고 느꼈다.
| 설정 위치 | 내가 쓰는 상황 | 이유 |
|---|---|---|
~/.gemini/settings.json |
여러 프로젝트에 같은 라우팅 정책을 공통 적용할 때 | 한 번만 맞추면 되지만, 실패 범위가 넓다. |
프로젝트/.gemini/settings.json |
새 기능을 repo 단위로 시험할 때 | workspace가 user를 덮기 때문에 실험 범위를 좁히기 쉽다. |
4. 붙여 놓고도 헷갈리기 쉬운 지점은 네 가지였다
- Gemma가 답변 모델이라고 생각하지 않기: 이 기능은 응답 자체보다 라우팅 결정을 맡긴다.
- 설정 바꾼 뒤 재시작 빼먹지 않기: 문서에 restart required가 명시돼 있다.
- 포트 바꿨으면 host도 같이 바꾸기:
start --port와classifier.host가 어긋나면 바로 꼬인다. --skip-model은 이미 모델이 있는 경우에만 쓰기: 처음 설치라면 괜히 단계 하나를 생략하지 않는 편이 낫다.
내가 이걸 "바이브코딩 쪽에서 꽤 괜찮은 팁"이라고 느낀 건, 요즘 코딩 에이전트 운영이 결국 큰 모델을 어디에만 쓰고 어디에는 안 쓸지를 나누는 문제로 가고 있기 때문이다. 무거운 모델을 무조건 줄이자는 얘기가 아니라, 작은 판단을 어디까지 로컬로 당길 수 있는지를 먼저 실험해 볼 수 있게 됐다는 점이 좋았다. 실제로는 성능보다 운영 감각 차이가 더 크게 날 수도 있다.
관련해서 같이 본 링크는 npm 패키지 페이지, Gemini CLI README, 공식 릴리스 노트, Local Model Routing 문서, Settings 문서다. 이 정도만 읽어도, 이번 변화는 단순한 신기능 소개보다 로컬 분기기라는 운영 레이어가 하나 더 생겼다는 쪽으로 보는 편이 훨씬 유용했다.