먼저 읽는 30초 요약
이 글에서 가져갈 것
- 모델은 `name:tag`까지 완전 동일해야 요청/로드가 일치합니다.
- 같은 기반 모델이어도 양자화 버전이 다르면 워커 레지스트리에서 서로 다른 엔트리로 동작합니다.
- 배포 후에는 모델 목록을 그대로 복사해 쓰기보다 등록 기준 이름을 고정해 두세요.
왜 '비슷한 이름'이 문제인지
사람은 같은 모델을 하나로 보지만, 시스템은 문자열을 그대로 비교합니다. `gemma3:12b`와 `gemma3:4b`는 다른 모델이고, 라벨과 캐시 경로를 분리합니다.
양자화 표기(`q4_0`, `q4_K_M`) 역시 모델 식별의 일부로 동작할 수 있습니다.
검증할 때는 모델·런타임 버전, 입력 자료, 주요 설정과 결과를 한 묶음으로 저장합니다. 다른 조건을 그대로 둔 채 한 요소만 바꾸어 다시 실행하고, 예상과 다른 결과와 아직 확인하지 못한 한계까지 기록해야 이 설명을 자신의 환경에 안전하게 적용할 수 있습니다.
등록 실패의 세 단계
1) 목록 조회에서 요청한 이름과 정확히 동일한 항목이 있는지 확인
2) 워커가 실제로 참조하는 내부 이름(풀 경로, 베이스명, 태그)이 일치하는지 확인
3) 충돌이 있으면 기존 등록을 지우고 명시적 이름으로 재등록
실수 많은 영역
UI에서는 짧은 표시명만 보여도 내부에는 전체 태그가 남아 있을 수 있습니다.
정확한 이름을 강제하지 않으면 동일 모델로 보여도 워커 매칭이 실패해 실행 요청에서 404, 500 계열이 발생합니다.
모든 항목의 중요도가 같지는 않으므로 데이터 손실, 외부 노출과 복구 실패처럼 영향이 큰 조건은 필수 통과 항목으로 분리합니다. 선택 항목은 보류 이유와 재검토 시점을 적어 완료 상태와 미확인 상태가 섞이지 않게 합니다.
- 원본 모델명 유지
- 업로드한 태그 복사
- 대/소문자 일치
- 특수문자 오타 검사
현장에서 바로 쓰는 정리법
배포 스크립트에 `ollama ls`/`lms list`와 일치 체크를 넣습니다.
모델명 목록을 수동으로 복사해 스니펫 템플릿에 넣고, 배포 시점마다 같은 이름이 쓰였는지 확인하면 재발이 줄어듭니다.
검증할 때는 모델·런타임 버전, 입력 자료, 주요 설정과 결과를 한 묶음으로 저장합니다. 다른 조건을 그대로 둔 채 한 요소만 바꾸어 다시 실행하고, 예상과 다른 결과와 아직 확인하지 못한 한계까지 기록해야 이 설명을 자신의 환경에 안전하게 적용할 수 있습니다.
자주 묻는 질문
UI에서 보이는 이름과 실행 이름이 다른가요?
네, 내부 등록 문자열이 다르면 동일 모델처럼 보여도 다른 워커로 간주할 수 있습니다. 모델은 `name:tag`까지 완전 동일해야 요청/로드가 일치합니다. 실제로 적용할 때는 본문의 ‘왜 '비슷한 이름'이 문제인지’ 절차를 따라 한 조건씩 확인하고 결과를 기록하세요.
양자화 값만 다르면 왜 실패하죠?
양자화는 같은 모델이라도 런타임 파일·최적화 경로가 달라질 수 있어 별도 엔트리로 처리되어 충돌할 수 있습니다. 같은 기반 모델이어도 양자화 버전이 다르면 워커 레지스트리에서 서로 다른 엔트리로 동작합니다. 실제로 적용할 때는 본문의 ‘등록 실패의 세 단계’ 절차를 따라 한 조건씩 확인하고 결과를 기록하세요.
해결은 반드시 재등록인가요?
일반적으로 등록 기준 이름 정합성 점검 후 재등록하면 정합됩니다. 이미지를 갱신할 땐 기존 등록 상태도 같이 정리하세요. 실제로 적용할 때는 본문의 ‘실수 많은 영역’ 절차를 따라 한 조건씩 확인하고 결과를 기록하세요.
공식 출처
세부 동작과 최신 버전은 아래 원문을 함께 확인하세요.
Ollama 모델 지정 규칙 LM Studio 모델 등록