Inkling 2 Mini 시작하기: 모델 다운로드 및 로컬 추론 실행

Inkling 2 Mini의 가중치가 공개되어 이제 클라우드 API를 통해서만 사용하는 대신 자신의 컴퓨터에서 실행할 수 있습니다. 이 튜토리얼은 환경 확인부터 Ollama로 모델을 가져와 첫 번째 응답을 생성하고, 마지막으로 curl을 사용해 프로그램에서 호출하는 전체 과정을 안내합니다. 모든 과정은 Apple 칩 Mac을 기준으로 하며, 각 단계에서 성공 여부를 판단하는 방법을 알려드립니다.

환경 확인: 먼저 기기가 실행 가능한지 확인

무엇을 다운로드하기 전에 세 가지 조건을 확인하세요. '터미널'(Terminal)을 열고 다음 명령을 순서대로 실행합니다:

uname -m
sysctl hw.memsize
df -h /

첫 번째 명령의 출력이 arm64이면 Apple 칩입니다. x86_64라면 Intel Mac에서 다른 방법을 찾아야 합니다. 두 번째 명령은 메모리 바이트 수를 출력하며, 34359738368은 32 GB에 해당합니다. 우리는 최소한 이 용량을 권장합니다. 세 번째 명령은 디스크 여유 공간을 확인합니다. 모델 파일은 약 20 GB이며, 런타임 및 시스템 캐시를 위해 추가로 캐시와 실행 공간을 확보하세요.

공식 모델 카드에 따르면 Apple 칩 환경은 통합 메모리가 32 GB 이상이어야 합니다. 실제로 구성 가능한 컨텍스트 길이는 런타임 및 캐시 오버헤드에 따라 달라집니다.

Ollama 설치: 모델 페이지에 따라 버전 선택

우리는 Ollama를 주요 경로로 사용합니다. 모델 형식, 양자화, 캐시를 모두 캡슐화하여 내부 세부 사항을 신경 쓸 필요가 없기 때문입니다. Ollama 다운로드 페이지로 이동하여 데스크톱 앱을 설치하고, 설치 후 실행하면 메뉴 바에 작은 아이콘이 표시됩니다. 그런 다음 터미널로 돌아가 버전을 확인합니다:

ollama --version

command not found가 표시되면 데스크톱 앱이 실행 중인지 먼저 확인하세요. Ollama 데스크톱 버전이 실행되면 백그라운드에서 서비스가 실행되며, 앱 안내에 따라 명령줄 도구를 설치하세요. 버전 번호가 출력되면 환경이 준비된 것입니다.

버전 관련 주의사항: Inkling 2 Mini의 Ollama 모델 페이지에서는 특정 버전 이상의 Ollama에서만 해당 아키텍처를 지원합니다. 이전 버전을 사용 중이라면 ollama pull 시 unsupported model architecture와 같은 오류가 발생할 수 있습니다. 이런 메시지가 표시되면 모델 페이지 설명에 따라 해당 모델을 지원하는 버전을 설치하세요.

모델 가져오기 및 다운로드 확인

이제 모델을 가져옵니다. 약 20 GB이며 네트워크 속도에 따라 다릅니다:

ollama pull inkling-2-mini

다운로드 중 진행률 표시줄과 속도가 표시됩니다. 이 단계의 성공 표시는 오류 메시지가 전혀 없고, 마지막 줄에 success가 표시되는 것입니다. 다음으로 실제로 로컬에 있는지 확인합니다:

ollama list

출력에 inkling-2-mini 줄이 있어야 하며, SIZE 열에 약 20 GB가 표시됩니다. 태그 및 크기는 모델 라이브러리와 로컬 목록을 기준으로 합니다.

다운로드 중에 ~/.ollama/models 디렉터리를 관찰하면 파일 크기가 계속 증가하는 것을 볼 수 있습니다. 그러나 수동으로 조작할 필요는 없으며, 데이터가 실제로 디스크에 저장되었는지 확인하기 위한 것입니다.

첫 번째 응답 실행

결과를 확인하는 순간입니다. 다음을 실행합니다:

ollama run inkling-2-mini "KV 캐시가 무엇인지 세 문장으로 설명하세요"

첫 실행에는 모델을 로드해야 하며, 로드가 완료되면 터미널에 모델이 생성한 응답이 표시됩니다. 응답이 보이면 모델이 로컬에서 성공적으로 로드되고 추론이 한 번 실행된 것입니다.

로드 중 memory error가 표시되거나 갑자기 종료되면 아래의 문제 해결 섹션을 참조하세요. 로드 오류를 먼저 해결한 다음 API를 테스트하세요.

API 호출: 프로그램에서 사용하는 방법

프로그램은 Ollama의 로컬 HTTP API를 통해 동일한 모델을 호출할 수 있습니다. Ollama가 시작되면 기본적으로 127.0.0.1:11434를 수신합니다. curl로 직접 테스트합니다:

curl http://127.0.0.1:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inkling-2-mini",
    "messages": [{"role": "user", "content": "희소 어텐션이란 무엇인가요?"}],
    "stream": false
  }'

응답은 JSON이며, 답변 내용은 message.content 필드에 있습니다. 파이프를 사용하여 추출할 수 있습니다:

curl -s http://127.0.0.1:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{"model":"inkling-2-mini","messages":[{"role":"user","content":"희소 어텐션이란 무엇인가요?"}],"stream":false}' \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['message']['content'])"

connection refused가 반환되면 Ollama 서비스가 실행되지 않은 것입니다. 데스크톱 앱으로 돌아가 메뉴 바에 아이콘이 있는지 확인하세요. JSON이 반환되었지만 message 필드가 없으면 요청 또는 추론이 실패한 것입니다. 먼저 HTTP 상태와 JSON의 error 필드를 확인하고 ollama list와 모델 이름을 대조하세요.

다른 경로: Hugging Face 원본 가중치

Ollama는 빠른 시작에 적합하지만 vLLM이나 다른 추론 프레임워크를 사용하려면 원본 가중치가 필요합니다. Hugging Face 저장소로 이동하면 총 약 20.2 GB이며 safetensors, 구성 파일, 토크나이저 등이 포함되어 있습니다.

먼저 공식 명령줄 도구를 설치합니다:

python3 -m pip install -U huggingface_hub

그런 다음 지정된 디렉터리에 다운로드합니다:

hf download thinkingmachines/Inkling-2-Mini --local-dir ./Inkling-2-Mini

이 단계는 파일만 다운로드하며 추론 기능은 포함하지 않습니다. 다운로드가 완료되면 model.safetensors.index.json과 주요 가중치 파일이 표시됩니다. 이들은 모델 매개변수입니다. 실제로 실행하려면 이러한 가중치를 로드하는 추론 프레임워크가 필요합니다. vLLM, SGLang 등이 있으며 각각 설치 및 구성 문서가 있습니다. Ollama도 내부적으로 유사한 작업을 수행하지만 캡슐화되어 있습니다.

두 경로의 역할 분담: Ollama는 가중치와 런타임을 관리하고, Hugging Face 경로는 완전한 제어권을 제공하지만 프레임워크 호환성을 직접 처리해야 합니다. 가중치의 혼합 정밀도 형식(NVFP4/MXFP8)은 추론 프레임워크에 요구사항이 있으므로, 선택 시 공식 모델 카드의 호환성 목록을 확인하세요.

일반적인 문제 해결

모델 다운로드 중단 또는 검증 실패
먼저 디스크 여유 공간을 확인하세요. df -h /로 모델과 캐시를 수용할 수 있는지 확인합니다. 그런 다음 ollama pull inkling-2-mini를 다시 실행합니다. 반복적으로 중단되면 네트워크 문제일 수 있으므로 네트워크 환경을 변경해 보세요.

ollama --version이 command not found를 보고
데스크톱 앱이 실행되지 않았거나 설치 경로가 PATH에 추가되지 않았습니다. 먼저 메뉴 바의 Ollama 아이콘을 클릭하여 서비스가 실행 중인지 확인하고, 새 터미널 창을 열어 다시 시도하세요.

API가 connection refused 반환
Ollama 서비스가 11434 포트를 수신하지 않습니다. macOS에서 가장 흔한 시나리오는 데스크톱 앱이 종료된 경우입니다. 다시 시작하세요. 확인 방법: curl http://127.0.0.1:11434, 연결되면 Ollama is running이 반환됩니다.

모델 로드 중 메모리 부족
공식 최소 요구사항은 32 GB 통합 메모리입니다. 이보다 낮으면 전체 모델을 시도하지 마세요. 기기가 32 GB인데도 로드가 실패하면 위의 API 요청 JSON에 "options": {"num_ctx": 2048}을 추가하여 짧은 프롬프트로 검증한 다음, 실제 메모리와 작업에 따라 컨텍스트를 점진적으로 늘리세요.

ollama run에서 모델 아키텍처가 지원되지 않는다는 오류
Ollama 버전이 너무 오래되었습니다. 모델 페이지의 현재 설치 지침을 확인하고 로컬 버전을 확인하세요.

Hugging Face 다운로드 속도가 느림
먼저 Hugging Face에 접근할 수 있는지 확인하고 대상 디스크의 여유 공간을 확인하세요. 네트워크가 복구된 후 동일한 다운로드 명령을 다시 실행하세요.

추가 읽을거리: 더 자세히 탐구

공식 모델 카드에는 아키텍처 세부 정보와 벤치마크가 포함되어 있어 자세히 읽을 가치가 있습니다. Ollama의 API 문서에는 온도, top-p 등 더 많은 매개변수가 있으며, 애플리케이션 요구에 맞게 조정할 수 있습니다. vLLM으로 이 모델을 실행하려면 해당 문서에서 Inkling 2 호환성 정보를 검색하세요.

모델의 중간 12개 레이어는 동일한 가중치 세트를 재사용하여 세 번 실행됩니다. 약 20 GB의 파일 크기는 NVFP4와 MXFP8 혼합 정밀도에 의존합니다. 1M 토큰은 모델이 지원하는 상한이며, 로컬 컨텍스트는 사용 가능한 메모리에 따라 구성해야 합니다.