한국어 문서

Pi 구성, 확장, 플랫폼 설정 및 API 참조.

llama.cpp

Pi는 llama.cpp 라우터 서버를 지원합니다. 라우터는 여러 GGUF 모델을 발견하고 요청 시 이를 로드하거나 언로드합니다.

라우터를 지원하는 최신 llama.cpp 빌드를 사용하세요. build instructions를 따르거나 플랫폼에 맞는 prebuilt release를 설치하세요.

라우터 시작

--model 또는 -m 없이 llama-server를 시작하세요. 모델을 전달하면 라우터 모드 대신 단일 모델 모드가 시작됩니다.

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

중요 옵션:

  • --models-dir ~/models 로컬 GGUF 파일을 검색합니다.
  • --no-models-autoload는 /llama을 통해 명시적인 항목을 계속 로드합니다.
  • --jinja 호환 가능한 채팅 템플릿과 도구 호출이 가능합니다.
  • -ngl 999 최대한 많은 레이어를 GPU로 오프로드합니다.
  • -c 32768는 로드된 각 모델에 대한 컨텍스트 창을 설정합니다. 모델의 기본 컨텍스트를 사용하려면 이를 생략하세요. 이 경우 훨씬 더 많은 메모리가 필요할 수 있습니다.

단일 파일 모델은 모델 디렉터리에 직접 위치할 수 있습니다. 다중 모드 및 다중 샤드 모델을 별도의 하위 디렉터리에 넣습니다.

~/models/
├── llama-3.2-1b-Q4_K_M.gguf
├── gemma-3-4b-it-Q4_K_M/
│   ├── gemma-3-4b-it-Q4_K_M.gguf
│   └── mmproj-F16.gguf
└── large-model-Q4_K_M/
    ├── large-model-Q4_K_M-00001-of-00003.gguf
    ├── large-model-Q4_K_M-00002-of-00003.gguf
    └── large-model-Q4_K_M-00003-of-00003.gguf

수동으로 파일을 추가한 후 라우터를 다시 시작하세요. 모델별 컨텍스트 크기 및 기타 옵션을 보려면 llama.cpp model presets를 사용하세요.

구성 Pi

Pi를 시작하고 공급자를 구성합니다.

/login llama.cpp

라우터 URL을 입력하고 선택사항 API key을 입력하세요. 기본 URL은 http://127.0.0.1:8080입니다.

환경 변수는 /login 없이 동일한 값을 구성할 수 있습니다.

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret
pi

서버가 API key를 사용하는 경우 일치하는 --api-key 값으로 llama-server를 시작합니다. 로컬 전용 액세스의 경우 --host 127.0.0.1를 유지하세요.

모델 관리

달리다:

/llama
  • 언로드된 모델을 선택하여 로드하세요.
  • 로드된 모델을 선택하여 언로드합니다.
  • **모델 다운로드…**를 선택하고 Hugging Face를 검색한 다음 저장소와 양자화를 선택합니다. 정확한 owner/repository[:quant] 값도 작동합니다.
  • 취소를 확인하려면 로드 또는 다운로드 중에 Esc 키를 누르세요.

Hugging Face 검색은 설정 시 HF_TOKEN를 사용한 후 $HF_TOKEN_PATH, $HF_HOME/token, $XDG_CACHE_HOME/huggingface/token, ~/.cache/huggingface/token를 확인합니다. 검색은 인증 없이도 작동하며 더 낮은 비율 제한이 적용됩니다. Pi 제한 저장소와 액세스 페이지 링크를 다운로드하기 전에 경고합니다. llama.cpp 서버는 다운로드를 수행하므로 선택한 저장소에 액세스가 필요할 때 해당 프로세스에도 HF_TOKEN가 있어야 합니다.

다른 모델이 로드된 경우 Pi는 해당 모델을 먼저 언로드할지 아니면 계속 로드할지 묻습니다. Pi는 모델을 자동으로 언로드하지 않으며 모델 파일을 삭제하지 않습니다. 라우터는 다른 클라이언트와 공유될 수 있으므로 /llama는 항상 라우터의 현재 상태를 표시합니다.

/model에는 로드된 모델만 나타납니다. 모델을 로드한 후 /model를 실행하여 현재 Pi 세션에 대해 모델을 선택합니다.

라우터 연결이 끊어지면 /llama에 재시도 및 닫기가 표시됩니다. 재시도는 중단된 작업을 재생하지 않고 모델 상태를 다시 연결하고 새로 고칩니다.

문제 해결

라우터에 연결할 수 있는지 확인하세요.

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/models
  • /llama에 모델이 없습니다: --models-dir 디렉토리 레이아웃을 확인하고 라우터를 다시 시작하세요.
  • /model에서 누락된 모델: 먼저 /llama로 로드하세요.
  • 로드 실패 또는 너무 많은 메모리 사용: -c를 낮추거나 다른 모델을 언로드합니다.
  • 서버가 라우터 모드에 있지 않습니다. --model, -m 또는 -hf 없이 시작하세요.