한 줄 정의

한 줄로 잡으면, 서버 주소에 JSON 요청을 보내고 모델 응답을 받게 해 주는 호출 인터페이스야. API라는 큰 개념 안에서도, 여기서는 사람이 누르는 웹 화면보다 앱이 서버 endpoint를 부르는 네트워크 계약에 가까워.

AI 문서에서 이 말이 나오면 먼저 “모델이 무엇인가”보다 “어느 주소로 어떤 요청을 보낼 수 있나”를 보는 편이 맞아. llama-server는 GGUF 모델을 올리고 http://localhost:8080 같은 주소로 HTTP API를 열어 주고, llm-server는 그 서버를 어떤 하드웨어와 어떤 플래그로 띄울지 자동화하는 쪽이야.

실제로 무엇을 하나

실무 흐름은 단순해 보여도 꽤 구체적이야. llama-server -m model.gguf --port 8080처럼 서버를 띄우면 앱은 base_url을 http://localhost:8080/v1 같은 주소로 바꾸고, 대화 생성, responses, embeddings route를 호출해. 서버 README는 기본 quick start에서 127.0.0.1:8080으로 listen한다고 적고, OpenAI 호환 route와 Anthropic Messages 호환 경로를 함께 소개해.

이때 HTTP API는 세 가지를 고정해 줘.

  • 요청 경로: /completion, 대화 생성 route, /health처럼 어떤 endpoint를 부를지 정해.
  • 요청 모양: header, JSON body, model 필드, messages 배열처럼 서버가 읽을 입력 형식을 정해.
  • 응답 기준: health check의 200/503, 생성 결과 JSON, 오류 응답처럼 앱이 어떻게 성공과 실패를 판단할지 정해.

그래서 이 용어는 SDK와도 달라. SDK는 코드에서 부르기 편하게 감싼 도구고, HTTP API는 그 아래에서 실제로 오가는 네트워크 계약이야. 기존 OpenAI 형식 클라이언트를 쓰더라도 결국은 base_url, route, 모델 이름, 응답 필드가 맞아야 돌아간다.

왜 중요한가

HTTP API가 중요한 이유는 모델 파일과 앱 사이의 교체 지점을 만들어 주기 때문이야. 내부 챗봇이나 문서 요약 도구가 이미 OpenAI API 형식으로 짜여 있다면, 관리형 API를 계속 쓸 수도 있고, llama-server가 연 로컬 endpoint로 옮겨 볼 수도 있어. 이때 바뀌는 건 보통 모델 서버 주소, 모델 이름, 인증 방식, 지원 endpoint야. 앱 전체를 새로 쓰는 문제와는 결이 다르다.

Local LLM 운영에서는 이 차이가 더 크게 느껴져. llm-server README의 Qwen3.5-122B 예시는 raw llama-server 4.1 tok/s, heuristic 11.2 tok/s, --ai-tune 17.47 tok/s를 같은 행에 놓고 비교해. 이건 HTTP API가 빨라졌다는 뜻이 아니라, 같은 서버 호출 경계 위에서 하드웨어 배치와 실행 플래그를 바꾸면 생성 속도가 달라진다는 뜻이야.

또 하나는 운영 감시야. GET /health가 모델 로딩 중이면 503, 준비가 끝나면 200을 돌려준다는 식의 endpoint가 있으면, 앱은 서버가 아직 모델을 올리는 중인지, 요청을 받을 준비가 됐는지 구분할 수 있어. 모델 품질과는 별개로, 실제 서비스에서는 이런 작은 응답 규칙이 배포와 장애 대응을 훨씬 덜 헷갈리게 만든다.

주의해서 볼 점

첫째, HTTP API는 보안 보장이 아니야. 기본 localhost에서만 듣는 서버와 --host 0.0.0.0으로 외부 네트워크에 여는 서버는 완전히 다른 운영 문제야. 외부에 열면 인증 키, 방화벽, 프록시, 로그, 요청 제한을 같이 봐야 해. “HTTP로 호출 가능”은 “안전하게 공개 가능”이라는 뜻이 아니야.

둘째, OpenAI-compatible이라는 말도 좁게 읽어야 해. 요청 모양이 비슷하다는 뜻이지, OpenAI 서비스의 가격표, 품질, 정책, 모델 동작까지 같다는 뜻은 아니야. 같은 대화 생성 호출이라도 로컬 GGUF 모델, 양자화 비트 수, 컨텍스트 윈도우, GPU VRAM 예산에 따라 결과와 속도가 달라져.

셋째, endpoint 이름만 보고 기능을 확정하면 안 돼. embeddings, multimodal, reranking route가 문서에 보여도 실제로는 로드한 모델, mmproj 파일, pooling 설정, 실행 옵션이 맞아야 쓸 수 있어. HTTP API는 “어떻게 부를지”를 정해 주는 경계고, “무엇을 잘할지”는 모델과 런타임 조건이 따로 결정해.

그래서 HTTP API가 보이면 먼저 주소, route, 요청 형식, 응답 형식, 인증, health check를 확인해. 그다음에야 benchmark, context-window, GPU VRAM, 4.1 tok/s 같은 속도 숫자를 붙여서 실제 운영 판단을 하는 편이 덜 위험해.