# llama-server로 내 PC에 OpenAI 호환 API 열기

> llama.cpp의 llama-server에 GGUF 모델을 올려 OpenAI와 같은 형식의 /v1/chat/completions 주소를 만듭니다. 127.0.0.1에만 열고, requests와 openai 파이썬 라이브러리로 호출해 한 번에 받기와 스트리밍을 확인합니다.

- 주소: https://copyandrun.com/blog/llama-server-openai-compatible-api/
- 분야: AI
- 발행일: 2026-10-28
- 태그: llama.cpp, llama-server, OpenAI 호환, GGUF

OpenAI API 형식에 맞춰 짠 프로그램은 주소만 바꾸면 로컬 모델로도 돌릴 수 있습니다. llama.cpp에 들어 있는 `llama-server`가 그 주소를 열어 줍니다. 이 글에서는 7B 모델 파일(GGUF) 하나를 올려 서버를 띄우고, 같은 서버를 `requests`와 `openai` 라이브러리로 부른 뒤 서버를 내립니다.

## 준비물

| 항목 | 확인한 버전 |
|---|---|
| llama.cpp | 빌드 3980e04d5 (9050), Windows, Vulkan 백엔드 |
| 모델 | `Qwen2.5-7B-Instruct-Q4_K_M.gguf` (4.36GiB) |
| Python | 3.12.10, `requests` 2.34.2, `openai` 3.8.0 |

## 1. 서버 띄우기

<!-- files: server_demo.py -->

```bash
./llama-server.exe -m Qwen2.5-7B-Instruct-Q4_K_M.gguf --host 127.0.0.1 --port 8091 -ngl 99 -c 4096
```

| 옵션 | 뜻 |
|---|---|
| `--host 127.0.0.1` | 이 PC 안에서만 접속 허용. 기본값을 믿지 말고 직접 지정 |
| `--port 8091` | 다른 프로그램이 쓰지 않는 포트 |
| `-ngl 99` | 모든 층을 그래픽 쪽에 올림 |
| `-c 4096` | 한 번에 기억하는 길이(토큰) |

모델이 올라오는 데 시간이 걸리므로 준비됐는지 확인합니다.

```bash
curl -s localhost:8091/health
```

```
# 기대 출력
{"status":"ok"}
```

로그에는 `server is listening on http://127.0.0.1:8091`이 찍혔고, `netstat`에서도 `127.0.0.1:8091`만 `LISTENING`이었습니다.

## 2. requests로 부르기

<!-- files: server_demo.py -->

```python
import requests

r = requests.post("http://127.0.0.1:8091/v1/chat/completions", json={
    "model": "any",
    "messages": [{"role": "user", "content": "한국어로 로컬 AI의 장점을 한 문장으로 말해 주세요."}],
    "max_tokens": 80})
d = r.json()
print(r.status_code)
print(d["choices"][0]["message"]["content"])
print(d["usage"], d["timings"]["predicted_per_second"])
```

```
# 기대 출력(이 PC)
200
로컬 AI는 데이터 처리 속도가 빠르고, 프라이버시 보호에 효과적입니다.
{'completion_tokens': 28, 'prompt_tokens': 48, ...} 38.36
```

응답은 OpenAI와 같은 `choices[0].message.content` 구조이고, `usage`에 토큰 수가 들어 있습니다. `timings.predicted_per_second`는 llama-server가 덧붙이는 항목으로, 이 실행에서는 초당 약 38토큰이었습니다. `model` 값은 아무 문자열이나 넣어도 동작했습니다. 서버에 모델이 하나뿐이어서 그런 것으로 보이며, 여러 모델을 올렸을 때의 동작은 확인하지 않았습니다. 올라간 모델 이름은 `/v1/models`에서 확인합니다.

## 3. openai 라이브러리로 부르기

<!-- files: server_demo.py -->

주소만 바꾸면 기존 코드를 그대로 쓸 수 있습니다. `api_key`는 필수 입력이라 아무 문자열이나 넣습니다.

```python
from openai import OpenAI

c = OpenAI(base_url="http://127.0.0.1:8091/v1", api_key="none")
r = c.chat.completions.create(model="any", max_tokens=80,
    messages=[{"role": "user", "content": "두 문장으로 자기소개 해 주세요."}])
print(r.choices[0].message.content, r.usage.completion_tokens)

for ch in c.chat.completions.create(model="any", max_tokens=40, stream=True,
        messages=[{"role": "user", "content": "1부터 5까지 세어 주세요."}]):
    print(ch.choices[0].delta.content or "", end="", flush=True)
```

한 번에 받기와 스트리밍 모두 정상 동작했습니다. 자기소개 답은 48토큰이었고, 모델이 스스로를 Qwen이라고 소개했습니다.

## 4. 서버 내리기

실습이 끝나면 서버를 끕니다. 포그라운드로 띄웠다면 `Ctrl+C`, 백그라운드라면 작업 관리자나 `taskkill`로 해당 프로세스를 종료합니다. 종료 뒤 `netstat`에서 8091이 사라진 것을 확인했습니다.

## 전체 코드

서버 시작, 준비 확인, 열린 주소 확인, 두 가지 호출, 스트리밍, 서버 종료를 한 번에 하는 파일입니다. `server_demo.py`로 저장하고 `SERVER`와 `MODEL` 경로를 내 PC에 맞게 고친 뒤 `python -X utf8 server_demo.py`로 실행합니다. 이 파일이 띄운 서버만 끝내므로 이미 돌고 있는 다른 서버에는 영향이 없습니다.

![server_demo.py 실행 결과에서 /health가 4초 만에 ok가 되고 127.0.0.1:8091만 LISTENING이며, 같은 질문 세 번이 모두 200과 34토큰으로 초당 39~40토큰, openai 라이브러리 호출과 스트리밍이 성공하고, 종료 뒤 8091 LISTENING 줄이 0인 것을 확인합니다.](https://copyandrun.com/img/llama-server-openai-compatible-api/01-서버-호출-결과.png)

```python
"""llama-server 를 127.0.0.1 에만 열고 requests 와 openai 라이브러리로 부른 뒤 서버를 내린다.

준비: llama.cpp Vulkan 빌드(llama-server.exe), GGUF 모델, pip install requests openai
주의: 이 파일이 띄운 서버만 끝낸다. 다른 llama-server 는 건드리지 않는다.
실행: python -X utf8 server_demo.py   (모델 올리는 시간 포함 약 1분)
"""
import subprocess
import time

import requests
from openai import OpenAI

SERVER = r"C:\llama.cpp\llama-server.exe"
MODEL = r"C:\models\Qwen2.5-7B-Instruct-Q4_K_M.gguf"
PORT = 8091
BASE = f"http://127.0.0.1:{PORT}"

proc = subprocess.Popen([SERVER, "-m", MODEL, "--host", "127.0.0.1", "--port", str(PORT),
                         "-ngl", "99", "-c", "4096"],
                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
try:
    print("## 1. 준비될 때까지 /health 확인")
    t0 = time.time()
    while True:
        try:
            h = requests.get(f"{BASE}/health", timeout=2).json()
            if h.get("status") == "ok":
                break
        except requests.RequestException:
            pass
        time.sleep(1)
    print(f"/health -> ok ({time.time() - t0:.0f}초 걸림)")

    print("## 2. 열린 주소 확인(127.0.0.1 에만 열렸는지)")
    out = subprocess.run(["netstat", "-an"], capture_output=True, text=True).stdout
    print("\n".join(l.strip() for l in out.splitlines() if f":{PORT} " in l and "LISTENING" in l))

    print("## 3. /v1/models")
    print([m["id"] for m in requests.get(f"{BASE}/v1/models").json()["data"]])

    print("## 4. requests 로 부르기(3번, 속도는 서버가 알려 준 값)")
    for i in range(3):
        r = requests.post(f"{BASE}/v1/chat/completions", json={
            "model": "any",
            "messages": [{"role": "user", "content": "한국어로 로컬 AI의 장점을 한 문장으로 말해 주세요."}],
            "max_tokens": 80, "temperature": 0})
        d = r.json()
        print(r.status_code, d["choices"][0]["message"]["content"],
              "| 생성", d["usage"]["completion_tokens"], "토큰,", round(d["timings"]["predicted_per_second"], 1), "토큰/초")

    print("## 5. openai 라이브러리로 부르기")
    c = OpenAI(base_url=f"{BASE}/v1", api_key="none")
    r = c.chat.completions.create(model="any", max_tokens=80, temperature=0,
                                  messages=[{"role": "user", "content": "두 문장으로 자기소개 해 주세요."}])
    print(r.choices[0].message.content, "|", r.usage.completion_tokens, "토큰")

    print("## 6. 스트리밍")
    for ch in c.chat.completions.create(model="any", max_tokens=40, stream=True, temperature=0,
                                        messages=[{"role": "user", "content": "1부터 5까지 세어 주세요."}]):
        print(ch.choices[0].delta.content or "", end="", flush=True)
    print()
finally:
    proc.terminate()
    proc.wait(timeout=30)
    time.sleep(1)
    out = subprocess.run(["netstat", "-an"], capture_output=True, text=True).stdout
    # 접속이 끝난 연결(TIME_WAIT)은 한동안 남으므로 LISTENING 만 센다
    left = [l for l in out.splitlines() if f":{PORT} " in l and "LISTENING" in l]
    print("## 7. 서버 종료 후 8091 LISTENING 줄:", len(left))
```

`temperature`를 0으로 두면 같은 질문에 같은 답이 나옵니다. 위 화면에서 세 번 모두 같은 문장과 34토큰이 나온 이유입니다. 속도는 39.4에서 40.1토큰/초로 거의 같았습니다.

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| `/health`가 바로 안 됩니다 | 모델을 올리는 중입니다. 몇 초에서 수십 초 뒤에 다시 부릅니다 |
| 포트가 이미 사용 중이라고 나옵니다 | `netstat -ano`로 쓰는 프로세스를 찾아 다른 포트를 고릅니다 |
| `openai` 라이브러리가 키를 요구합니다 | `api_key`에 임의 문자열을 넣습니다 |
| 한글 출력이 깨집니다 | `python -X utf8 파일.py`로 실행합니다 |

## 이어서 해 볼 것

- **여러 모델 전환**: 서버 하나에 모델 여러 개를 두고 `model` 값으로 고르는 방식은 시험하지 않았습니다.
- **외부 접속**: `--host 0.0.0.0`으로 열면 같은 네트워크의 누구나 접속할 수 있습니다. 인증 없이 열지 않는 편이 좋고, 이 글에서는 열어 보지 않았습니다.

## 확인 범위

- **해 본 것:** 2026-10-28, Windows 11 · llama.cpp 빌드 9050에서 서버 시작, `/health`, `/v1/chat/completions`, `/v1/models`, `openai` 라이브러리 호출과 스트리밍, 서버 종료를 실행했습니다. 29일에 전체 스크립트로 같은 순서를 다시 실행했습니다(준비 4초, 같은 질문 세 번 39~40토큰/초).
- **해 보지 않은 것:** Linux와 macOS, CUDA 빌드, 도구 호출과 이미지 입력.
- **읽을 때 주의:** 28일 값(38토큰/초)은 한 번만 잰 값이고, 29일 값은 세 번 잰 값입니다. 서버를 띄운 시간과 속도는 이 PC에서만 의미가 있습니다.
