채팅 메시지 생성하기

채팅 메시지 생성하기 (Generate a chat message)

사용자와 어시스턴트가 대화를 주고받는 채팅 앱을 만든다면 단순 생성보다 대화 이력 을 함께 보내는 게 자연스러워요. Ollama의 POST /api/chat 엔드포인트는 사용자와 어시스턴트 사이 대화에서 다음 채팅 메시지를 생성해 줘요. 툴 호출, 구조화된 출력, 멀티모달 이미지까지 지원하는 유연한 인터페이스예요.

출처: Ollama 공식 문서 — Generate a chat message

엔드포인트

경로: POST /api/chat
요약: 사용자와 어시스턴트 사이의 대화에서 다음 채팅 메시지를 생성합니다.
operationId: chat

요청 본문에서 model 과 messages 가 필수예요. messages 는 각각 role(역할)과 content(내용)를 가진 메시지 객체의 배열로, 대화 이력을 담아요.

기본 요청 (비스트리밍)

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "why is the sky blue?"
    }
  ],
  "stream": false
}'

stream: false 로 두면 응답을 한 번에 받고, 생략하면 기본적으로 스트리밍 방식으로 토큰이 이어져 와요.

구조화된 출력

format 으로 응답 형식을 지정할 수도 있어요. 다만 chat 요청에서 format 을 쓰려면 stream: false 를 함께 설정해야 해요.

curl -X POST http://localhost:11434/api/chat -H "Content-Type: application/json" -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "What are the populations of the United States and Canada?"
    }
  ],
  "stream": false,
  "format": {
    ...
  }
}'

툴 호출

tools 필드로 함수 정의를 넘기면 모델이 도구를 호출하도록 유도할 수 있어요. 각 도구는 type: "function" 과 함수 이름·파라미터를 담은 function 객체로 정의해요.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather today in Paris?"
    }
  ],
  "stream": false,
  "tools": [
    {
      "type": "function",
      "function": {
        ...
      }
    }
  ]
}'

응답 필드

응답에는 응답 생성에 사용된 model, ISO 8601 타임스탬프인 created_at, 그리고 message 객체가 있어요. 모델 응답의 message.role 은 항상 assistant 이고, content 에 생성된 텍스트가 담겨요. 멀티모달 모델에는 Base64로 인코딩한 images 를 보낼 수 있고, 도구 호출 결과는 tool_calls 에 담겨요.

실행 옵션 (ModelOptions)

options 로 생성 동작을 제어할 수 있어요. temperature, top_k, top_p, min_p, stop, num_ctx, num_predict 등이 대표적이에요.

채팅 메시지 생성하기