~/tools / 서버에서 로컬 LLM 실행하기 / Ollama API Request Builder

Ollama API Request Builder — Ollama /api/chat용 curl 요청 만들기: format, tools, think, options

폼으로 Ollama의 /api/chat 엔드포인트에 보낼 요청을 만듭니다. 모델, 시스템 메시지와 사용자 메시지, format과 JSON Schema를 이용한 구조화된 출력, 도구 정의, 사고(thinking), 스트리밍, temperature나 num_ctx 같은 옵션, 중지 시퀀스, keep_alive를 지정할 수 있습니다. 바로 실행할 수 있는 curl 명령과 JSON 본문을 얻습니다. 모든 필드는 공식 Ollama API 레퍼런스에 나온 것입니다. 입력한 내용은 브라우저 밖으로 나가지 않습니다.

Ollama 주소모델기본 인증 사용자 이름(선택)

시스템 메시지(선택)사용자 메시지

출력 형식 (format)사고 (think)답 스트리밍 (stream)

답의 JSON Schema도구 (tools), JSON 배열(선택)

옵션, 중지 시퀀스, keep_alive

빈 칸은 보내지 않으므로 모델의 설정이 그대로 적용됩니다.

temperature높을수록 더 무작위적입니다seed같은 시드면 같은 출력이 나옵니다num_ctx컨텍스트 길이(토큰 단위)num_predict생성할 최대 토큰 수top_k가능성이 높은 상위 K개 토큰 중에서만 고릅니다top_p누적 확률 임계값min_p토큰의 최소 확률

중지 시퀀스 (options.stop), 한 줄에 하나씩모델을 불러 둔 채로 유지 (keep_alive)

curl 명령

Ollama에 접속할 수 있는 컴퓨터의 터미널에서 실행하세요.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:4b",
  "messages": [
    {
      "role": "user",
      "content": "Tell me about Canada."
    }
  ],
  "format": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "capital": {
        "type": "string"
      },
      "languages": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": [
      "name",
      "capital",
      "languages"
    ]
  },
  "options": {
    "temperature": 0
  },
  "stream": false
}'

JSON 본문

{
  "model": "qwen3:4b",
  "messages": [
    {
      "role": "user",
      "content": "Tell me about Canada."
    }
  ],
  "format": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "capital": {
        "type": "string"
      },
      "languages": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": [
      "name",
      "capital",
      "languages"
    ]
  },
  "options": {
    "temperature": 0
  },
  "stream": false
}

필드는 /api/chat의 Ollama API 레퍼런스에 나온 내용을 2026-11-03에 확인한 것입니다. Ollama API: 채팅 메시지 생성

모든 처리는 브라우저에서 이루어집니다. 도구는 명령만 작성하며 아무것도 전송하지 않습니다.

Ollama의 /api/chat 엔드포인트는 모델과 messages 목록이 담긴 JSON 본문을 받으며, 선택 필드를 더할 수 있습니다. 함수 호출용 tools, JSON 답이나 JSON Schema를 따르는 답을 요구하는 format, temperature나 num_ctx 같은 설정을 담는 options, 그리고 stream, think, keep_alive입니다. 이 본문을 터미널에서 직접 쓰면 실수하기 쉽습니다. 쉼표 하나가 빠지면 깨지고, 메시지 안의 작은따옴표가 셸의 따옴표를 닫아 버리며, 문자로 입력한 숫자는 숫자로 읽히지 않을 수 있습니다. 이 도구는 폼에서 본문을 만들어 Ollama 문서의 예시와 같은 형태의 curl 명령에 담고, 작은따옴표는 셸용으로 이스케이프합니다. JSON Schema와 도구 목록이 올바른 JSON인지, 각 도구에 API 레퍼런스가 요구하는 type, name, parameters가 있는지, options가 올바른 종류의 숫자인지 검사합니다. 생성한 명령을 qwen2.5:7b로 Ollama 0.40.11에 실행해 보았습니다. JSON Schema를 지정한 요청은 그 형태의 답을 반환했고, 도구를 지정한 요청은 도구 호출을 반환했으며, 스트리밍, json 모드, 중지 시퀀스, keep_alive는 오류 없이 동작했습니다.

이 도구의 핵심 로직은 MIT 라이선스의 오픈 소스로 공개되어 있습니다. github.com/seigo5555/toolkitbox-lib/src/ollama-api-request.ts

이럴 때 사용

코드를 쓰기 전에 내 서버에서 구조화된 출력을 시험하기: JSON Schema를 붙여 넣고 모델이 무엇을 반환하는지 확인
애플리케이션에서 쓸 도구 정의로 모델이 내 함수를 호출하는지 확인하기
비밀번호가 있는 nginx 프록시 뒤의 Ollama를 올바른 URL과 curl -u로 호출하기

사용법

Ollama 서버의 주소(비워 두면 http://localhost:11434)와 모델 이름을 입력하고, 사용자 메시지를 쓰세요. 원하면 시스템 메시지도 쓰세요.
출력 형식을 고르고, 도구 정의를 JSON 배열로 추가하고, 사고와 스트리밍을 설정하세요. 옵션을 열면 temperature, num_ctx, 시드, 중지 시퀀스, keep_alive를 설정할 수 있습니다. 빈 칸은 출력되지 않습니다.
curl 명령을 복사해 Ollama에 접속할 수 있는 컴퓨터의 터미널에서 실행하세요. 직접 만든 코드에서 보내고 싶을 때를 위해 JSON 본문은 따로 표시됩니다.

FAQ

stream은 무엇을 하나요?

API 레퍼런스에서 stream의 기본값은 true입니다. 스트리밍된 답은 줄바꿈으로 구분된 JSON으로 한 조각씩 도착합니다. stream을 false로 하면 문서에 따라 답이 하나의 JSON 객체로 돌아오는데, 스트리밍 페이지는 이를 처리하기 더 간단하고 짧은 응답이나 구조화된 출력에 더 좋다고 설명합니다. 도구는 스트리밍을 껐을 때만 "stream": false를 씁니다.

think에는 어떤 값을 쓸 수 있나요?

API 레퍼런스에 따르면 true는 사고를 요청하고, false는 사고 출력을 요청하지 않으며, 문자열은 모델이 정의하는 수준을 고릅니다. 숫자는 지원되지 않습니다. 문서는 모델이 지원하는 값을 /api/show로 알아보라고 하며, think를 설정하면 도구가 그 명령을 보여 줍니다. 우리 테스트에서 qwen2.5:7b는 think를 false로 하면 동작했고, true는 "qwen2.5:7b" does not support thinking 오류로 거부되었습니다.

format의 json과 JSON Schema는 무엇이 다른가요?

API 레퍼런스에 따르면 format에는 json 또는 JSON schema를 쓸 수 있습니다. json은 유효한 JSON이기만 하면 된다는 요청입니다. 스키마는 속성 이름과 필수 항목 같은 정확한 형태를 기술하며, 우리 테스트에서는 답이 그대로 따랐습니다. 도구는 스키마를 문자열이 아니라 객체로 보냅니다.

도구 정의는 어떻게 써야 하나요?

API 레퍼런스는 항상 function인 type과, name과 parameters가 있는 function 객체를 요구합니다. parameters는 인자의 JSON Schema이고 description은 선택입니다. 도구는 이 필드들을 검사합니다. 모델이 함수를 호출하기로 하면 답에는 텍스트 대신 message.tool_calls가 들어 있습니다.

비밀번호가 있는 Ollama는 어떻게 호출하나요?

프록시의 주소(예: https://ollama.example.com)와 사용자 이름을 입력하세요. 도구가 curl 명령에 그 이름으로 -u를 추가하고, curl이 비밀번호를 물으므로 비밀번호는 명령에 들어가지 않습니다. 이 사이트의 Ollama nginx Config Generator로 그런 프록시를 만들 수 있습니다.

서버로 전송되는 것이 있나요?

아니요. 도구는 명령만 작성합니다. 직접 실행하기 전에는 아무것도 전송되지 않습니다.