llama-server (HTTP 서버)

llama.cpp는 httplib과 nlohmann::json을 기반으로 하는 가볍고 빠른 순수 C/C++ HTTP 서버를 제공해요. REST API와 웹 UI가 함께 들어 있어서, 로컬에서 한 번 띄워 두면 OpenAI 호환 방식으로도 쓸 수 있어요.

출처: llama-server README

특징

GPU·CPU에서 F16·양자화 모델 LLM 추론
OpenAI API 호환 chat completions, responses, embeddings 라우트
Anthropic Messages API 호환 chat completions
Reranking 엔드포인트
다중 사용자 병렬 디코딩
연속 배치 (continuous batching)
멀티모달 — OpenAI 호환 API 지원
모니터링 엔드포인트
스키마 제약 JSON 응답
함수 호출 / 도구 사용
추측 디코딩
쓰기 쉬운 웹 UI

기본 실행과 curl 테스트

서버는 llama serve(또는 llama-server)로 띄우고, 기본 포트는 8080이에요. 커맨드라인에서 completion 엔드포인트로 바로 테스트할 수 있어요.

curl --request POST \
    --url http://localhost:8080/completion \
    --header "Content-Type: application/json" \
    --data '{"prompt": "Building a website can be done in 10 simple steps:","n_predict": 128}'

주요 API 엔드포인트

GET `/health` — 헬스 체크

모델이 아직 로딩 중이면 HTTP 503({"error": {"code": 503, "message": "Loading model", ...}})을, 로딩이 끝나면 200({"status": "ok"})을 반환해요. /v1/health도 동작해요. 이 엔드포인트는 API 키 체크 없이 공개예요.

POST `/completion` — 프롬프트 기반 완성

중요: 이 엔드포인트는 OpenAI 호환이 아니에요. OAI 호환 클라이언트라면 /v1/completions를 쓰세요.

prompt는 문자열, 토큰 배열, 문자열·토큰 혼합 배열, 그리고 { "prompt_string": "...", "multimodal_data": ["base64"] } 같은 JSON 객체까지 여러 형태를 받아요. 여러 프롬프트 입력도 지원해서 응답은 배열로 옵니다.

temperature: 생성 랜덤성 조절 (기본 0.8)
top_k: 다음 토큰 후보를 확률 상위 K개로 제한 (기본 40)
top_p: 누적 확률이 임계값을 넘는 토큰 집합으로 제한 (기본 0.95)
n_predict: 예측할 최대 토큰 수 (기본 -1, -1이면 무한)

서버 설정 옵션(컨텍스트 크기, 배치 크기, GPU 오프로드 등)은 README의 파라미터 표를 참고하면 되고, --device·--list-devices로 백엔드 디바이스를 고를 수 있어요.

더 알아보기

함수 호출 — 도구 사용
멀티모달 — 이미지·오디오 입력
추측 디코딩 — 생성 가속

llama-server (HTTP 서버)