# 파이썬에서 로컬 Ollama API 호출하기: 응답 받기, JSON 형식 고정, 스트리밍

> requests만으로 내 PC의 Ollama를 호출합니다. 한 번에 받기, 옵션 넘기기, JSON 스키마로 출력 형식 고정하기, 글자가 나오는 대로 받는 스트리밍을 실행해 결과를 확인합니다. 한글이 깨지는 Windows 함정도 함께 정리합니다.

- 주소: https://copyandrun.com/blog/ollama-python-api-json-streaming/
- 분야: AI
- 발행일: 2026-10-28
- 태그: Ollama, Python, JSON, 스트리밍

Ollama는 설치하면 `http://localhost:11434`에서 HTTP API를 엽니다. 이 API를 부르면 내 프로그램 안에서 로컬 모델을 쓸 수 있습니다. 별도 SDK 없이 `requests`만으로 충분합니다. 여기서는 `exaone3.5:2.4b` 모델로 세 가지 호출 방식, 곧 한 번에 받기, 형식 고정하기, 스트리밍을 차례로 해 봅니다.

## 준비물

| 항목 | 확인한 버전 |
|---|---|
| Ollama | 0.32.15 (Windows 11), 모델 `exaone3.5:2.4b` |
| Python | 3.12.10 |
| requests | 2.34.2 (`pip install requests`) |

## 1. 한 번에 받기

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

```python
import requests

URL = "http://localhost:11434"

def chat(model, prompt, **kw):
    r = requests.post(f"{URL}/api/chat", json={
        "model": model, "stream": False,
        "messages": [{"role": "user", "content": prompt}], **kw}, timeout=300)
    r.raise_for_status()
    return r.json()

d = chat("exaone3.5:2.4b", "회사 노트북 비밀번호를 잊어버렸습니다. 어떻게 해야 하나요?")
print(d["message"]["content"][:200], "|", d["eval_count"], "tokens")
```

`stream: False`이면 답이 다 만들어진 뒤 한 덩어리로 옵니다. 응답에는 본문(`message.content`) 말고도 만든 토큰 수(`eval_count`), 걸린 시간(`eval_duration`, 나노초)이 들어 있어 속도를 바로 계산할 수 있습니다.

모델을 불러오는 중이면 첫 호출이 느리므로 `timeout`을 넉넉히 줍니다. 위 예에서는 371토큰짜리 답이 나왔습니다.

## 2. 옵션 넘기기

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

`temperature`나 기억 길이는 `options`로 호출마다 바꿉니다. 같은 `chat` 함수에 키워드 인자를 하나 더 넘기면 됩니다.

```python
d = chat("exaone3.5:2.4b", "같은 질문", options={"temperature": 0.2, "num_ctx": 4096})
```

옵션을 바꾸면 모델을 다시 불러오느라 첫 응답이 조금 늦어질 수 있습니다. 이 글에서는 그 지연 시간을 재지 않았습니다.

## 3. JSON 형식으로 고정하기

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

프로그램이 답을 읽으려면 문장이 아니라 정해진 구조가 필요합니다. `format`에 JSON 스키마를 주면 모델이 그 구조로만 답합니다.

```python
import json

schema = {"type": "object",
          "properties": {"date": {"type": "string"}, "place": {"type": "string"}},
          "required": ["date", "place"]}
d = chat("exaone3.5:2.4b",
         "다음 문장에서 날짜와 장소를 뽑아 주세요: '다음 주 화요일 오후 3시에 서울 본사 3층 회의실에서 만납니다.'",
         format=schema)
print(d["message"]["content"])
print(json.loads(d["message"]["content"]).keys())
```

```
# 기대 출력
{"date": "다음 주 화요일", "place": "서울 본사 3층 회의실"}
dict_keys(['date', 'place'])
```

`json.loads`가 바로 통과하고 두 키가 모두 있습니다. 다만 값의 내용은 정확하지 않았습니다. 날짜에 "오후 3시"가 빠졌습니다. `format`은 구조를 보장할 뿐 내용이 맞는지는 보장하지 않으므로, 중요한 값은 코드에서 따로 검증합니다.

문장을 네 개로 늘려 다시 해 보니 구조는 네 번 모두 맞았지만 값에는 문제가 하나 있었습니다. "금요일 오후 2시 온라인으로 진행하며 장소는 따로 없습니다."에서 `place`가 `장소는 따로 없습니다`로 나왔습니다. 장소가 없다는 사실을 장소 값으로 적은 것입니다. 스키마의 `place`를 필수로 두었기 때문에 모델이 어떻게든 채웠다고 볼 수 있습니다. 값이 없을 수 있는 칸은 `"type": ["string", "null"]`로 허용하는 방법을 쓸 수 있지만, 이 글에서는 시험하지 않았습니다.

## 4. 스트리밍으로 받기

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

`stream: True`이면 답이 만들어지는 대로 한 줄씩 JSON이 옵니다. 사용자는 끝까지 기다리지 않고 글자가 나오는 것을 볼 수 있습니다.

```python
import time

t = time.time(); first = None; n = 0
with requests.post(f"{URL}/api/chat", stream=True, json={
        "model": "exaone3.5:2.4b", "stream": True,
        "messages": [{"role": "user", "content": "로컬 AI의 장점 두 가지를 말해 주세요."}]}) as r:
    for line in r.iter_lines():
        c = json.loads(line)
        if c["message"]["content"] and first is None:
            first = time.time() - t
        print(c["message"]["content"], end="", flush=True)
        n += 1
print("\nfirst chunk %.2fs, chunks %d" % (first, n))
```

```
# 기대 출력(마지막 줄, 이 PC)
first chunk 2.08s, chunks 159
```

첫 글자가 2.08초에 나왔고 조각이 159개 왔습니다. 한 번에 받기였다면 답이 끝날 때까지 아무것도 볼 수 없었을 시간입니다. 첫 글자까지의 시간에는 모델을 메모리에 올리는 시간이 섞일 수 있습니다.

## 전체 코드

위 네 가지를 한 번에 실행하는 파일입니다. `api_demo.py`로 저장하고 `python -X utf8 api_demo.py`로 실행합니다.

![api_demo.py 실행 결과에서 한 번에 받기는 474토큰을 94토큰/초로 받고, JSON 형식 고정은 문장 네 개 모두 date와 place 키를 갖지만 마지막 값이 장소는 따로 없습니다로 나오며, 스트리밍은 첫 조각이 2.07초에 오는 것을 확인합니다.](https://copyandrun.com/img/ollama-python-api-json-streaming/01-api-결과.png)

```python
"""Ollama HTTP API 를 requests 로 부른다: 한 번에 받기, 옵션 넘기기, JSON 형식 고정, 스트리밍.

준비: Ollama 실행 중, ollama pull exaone3.5:2.4b, pip install requests
실행: python -X utf8 api_demo.py   (약 40초)
"""
import json
import time

import requests

URL = "http://localhost:11434"
MODEL = "exaone3.5:2.4b"


def chat(prompt, **kw):
    r = requests.post(f"{URL}/api/chat", json={
        "model": MODEL, "stream": False,
        "messages": [{"role": "user", "content": prompt}], **kw}, timeout=300)
    r.raise_for_status()
    return r.json()


print("## 1. 한 번에 받기")
d = chat("회사 노트북 비밀번호를 잊어버렸습니다. 어떻게 해야 하나요?", options={"seed": 1})
sec = d["eval_duration"] / 1e9
print(d["message"]["content"][:80].replace("\n", " "), "...")
print(f"토큰 {d['eval_count']}개, 생성 {sec:.1f}초 = {d['eval_count'] / sec:.0f}토큰/초")

print("## 2. 옵션 넘기기: temperature 0.2 와 num_ctx 4096")
d = chat("로컬 AI의 장점을 한 문장으로 말해 주세요.", options={"temperature": 0.2, "num_ctx": 4096, "seed": 1})
print(d["message"]["content"].strip())

print("## 3. JSON 형식 고정: 문장 네 개에서 날짜와 장소 뽑기")
schema = {"type": "object",
          "properties": {"date": {"type": "string"}, "place": {"type": "string"}},
          "required": ["date", "place"]}
texts = ["다음 주 화요일 오후 3시에 서울 본사 3층 회의실에서 만납니다.",
         "10월 30일 아침 9시에 부산 지사 대강당에서 교육이 있습니다.",
         "내일 점심에 판교 사무실 1층 카페에서 보기로 했습니다.",
         "금요일 오후 2시 온라인으로 진행하며 장소는 따로 없습니다."]
ok = 0
for t in texts:
    d = chat(f"다음 문장에서 날짜와 장소를 뽑아 주세요: '{t}'", format=schema, options={"temperature": 0})
    try:
        j = json.loads(d["message"]["content"])
        ok += set(j) == {"date", "place"}
        print(" ", j)
    except json.JSONDecodeError:
        print("  파싱 실패:", d["message"]["content"][:60])
print(f"구조가 맞은 답: {ok}/{len(texts)}  (값이 맞는지는 따로 사람이 봐야 한다)")

print("## 4. 스트리밍")
t0 = time.time()
first = None
n = 0
text = ""
with requests.post(f"{URL}/api/chat", stream=True, json={
        "model": MODEL, "stream": True,
        "messages": [{"role": "user", "content": "로컬 AI의 장점 두 가지를 말해 주세요."}]}) as r:
    for line in r.iter_lines():
        c = json.loads(line)
        if c["message"]["content"] and first is None:
            first = time.time() - t0
        text += c["message"]["content"]
        n += 1
print(text[:60].replace("\n", " "), "...")
print(f"첫 조각 {first:.2f}초, 조각 {n}개, 전체 {time.time() - t0:.1f}초")
```

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| `UnicodeEncodeError: 'charmap' codec` | Windows 콘솔의 기본 인코딩이 한글을 찍지 못함. `python -X utf8 파일.py`로 실행 |
| 한글 질문에 엉뚱한 답 | Git Bash의 curl로 한글을 보냈을 때 같은 질문이 "메시지가 불완전하다"는 영어 답으로 돌아온 적 있음. Python에서는 정상. 원인은 미확인 |
| `ConnectionError` | Ollama가 꺼져 있음. `ollama list`가 되는지 먼저 확인 |
| 첫 호출만 매우 느림 | 모델 로딩 시간. `timeout`을 늘림 |
| JSON 파싱 오류 | `format` 없이 JSON을 요청하면 앞뒤에 설명 문장이 붙을 수 있음. 스키마를 `format`으로 지정 |

## 이어서 해 볼 것

- **도구 호출**: 모델이 함수를 부르게 하는 `tools` 파라미터는 시험하지 않았습니다.
- **원격 접속**: 다른 PC에서 이 API를 부르려면 서버를 외부에 여는 설정이 필요하지만, 인증이 없으므로 이 글에서는 다루지 않았습니다. 이 PC에서는 포트 11434가 `127.0.0.1`에서만 열려 있는 것을 확인했습니다.

## 확인 범위

- **해 본 것:** 2026-10-28, Windows 11 · Ollama 0.32.15 · Python 3.12.10에서 위 코드를 실행했습니다. 29일에 전체 스크립트로 문장 네 개의 JSON 추출과 스트리밍을 다시 확인했습니다(첫 조각 2.07초). 모든 측정은 한 번씩입니다.
- **해 보지 않은 것:** Linux와 macOS, 다른 모델의 JSON 형식 준수율, 긴 입력에서의 동작.
