POST /api/chat — 대화형 endpoint · Local AI Quest

모양

/api/chat은 messages array (system / user / assistant / tool role) 받아서 streaming NDJSON이나 single JSON 객체 (stream에 따라) 반환. Raw completion / FIM 빼고 다 이 endpoint 써.

Request 필드

model (필수). ollama list에 뜨는 그대로의 모델 이름을 써.
messages — {role, content, images?, tool_calls?} array. Role: system, user, assistant, tool.
stream — boolean (default true).
format — "json" 또는 JSON Schema 객체 (structured output용).
options — Inference parameter (temperature, top_p, num_ctx, num_predict 등).
tools — OpenAI-format tool 정의 array (function calling용).
keep_alive — 이 request 후에 모델을 메모리에 얼마나 붙들어 둘지 (default는 "5m"). Pin은 숫자 -1로 해. "-1" 문자열은 duration으로 파싱되다가 time: missing unit in duration "-1"으로 거절돼.
think — reasoning 모델의 thinking 출력을 켜. boolean도 되고 레벨도 돼. "low", "medium", "high", "max".

Response 필드 (non-streaming)

message — {role, content, tool_calls?}.
done — boolean (stream off일 땐 항상 true).
시간, 단위는 nanosecond: total_duration, load_duration, prompt_eval_duration (prompt에 쓴 시간), eval_duration (생성에 쓴 시간).
개수, 단위는 토큰: prompt_eval_count (prompt 토큰 수), eval_count (생성된 토큰 수). 시간인 건 _duration으로 끝나는 것들뿐이야. 그래서 초당 토큰이 개수 ÷ 시간인 거고, 아래 코드가 딱 그렇게 하고 있어.

왜 /api/chat을 /api/generate보다 선호?

messages 모양이 role 경계 (system instruction vs user turn vs assistant output vs tool result) 의식하게 강제해. 그 구조가 뒤에서 tool 사용, multi-turn context, adapter 패턴이 일관되게 굴러가게 해주는 거야. /api/generate는 단순해 보이는데, prompt를 문자열 하나로 이어 붙이게 몰아가서 오히려 조합하기가 더 어려워져.

EV v3 · 2026-09-18: 이 레슨은 prompt_eval_count랑 eval_count를 “Timing … 다 nanosecond” 아래에 넣어 뒀었어. 둘은 토큰 개수고, 처음부터 그랬어. nanosecond인 건 _duration 필드들뿐이야. 바로 아래 Python 블록은 이미 그걸 알고 있었어. eval_duration을 1e9로 나누고 eval_count는 토큰 수로 쓰고 있었거든. 한 화면 안에서 산문이 코드랑 반대로 말하고 있었던 거지. ollama 0.34.1에 두 줄짜리 대화를 직접 던져 보면 eval_duration: 322823000 옆에 prompt_eval_count: 19, eval_count: 4가 나와. 19랑 4는 시간일 수가 없지. 필드 목록을 시간이랑 개수로 갈라놨으니까 이제 한 덩어리로 읽힐 일은 없을 거야. 작은 수정 둘이 같이 들어갔고, 둘 다 처음부터 틀렸던 거야. 모델을 pin하려면 숫자 -1이어야 하는데 이 레슨이 찍어 두던 "-1" 문자열은 그냥 거절돼 (time: missing unit in duration "-1", 직접 확인했어). 그리고 think는 boolean 말고 레벨도 받아.

Code

Python — non-streaming chat·python

import httpx

def chat(model: str, messages: list[dict]) -> dict:
    resp = httpx.post(
        "http://localhost:11434/api/chat",
        json={"model": model, "messages": messages, "stream": False},
        timeout=120.0,
    )
    resp.raise_for_status()
    return resp.json()

result = chat("qwen2.5:7b", [
    {"role": "system", "content": "You are concise."},
    {"role": "user", "content": "Define quantization in two sentences."},
])
print(result["message"]["content"])
print(f"Took {result['total_duration'] / 1e9:.2f}s")
print(f"Generated {result['eval_count']} tokens at "
      f"{result['eval_count'] / (result['eval_duration'] / 1e9):.1f} tok/s")

TypeScript — non-streaming chat·typescript

type Msg = { role: "system" | "user" | "assistant" | "tool"; content: string };

async function chat(model: string, messages: Msg[]) {
  const res = await fetch("http://localhost:11434/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ model, messages, stream: false }),
  });
  if (!res.ok) throw new Error(`Ollama ${res.status}: ${await res.text()}`);
  return res.json();
}

const out = await chat("qwen2.5:7b", [
  { role: "system", content: "You are concise." },
  { role: "user", content: "Define quantization in two sentences." },
]);
console.log(out.message.content);

POST /api/chat — 대화형 endpoint

모양

Request 필드

Response 필드 (non-streaming)

왜 /api/chat을 /api/generate보다 선호?

Code

External links

Exercise

Progress

댓글 0