~/ / AI 기사 / VPS에서 로컬 LLM / 내 코드에서 로컬 모델 호출하기: Ollama의 구조화된 출력과 OpenAI 호환 API

내 코드에서 로컬 모델 호출하기: Ollama의 구조화된 출력과 OpenAI 호환 API

서버에서 Ollama를 실행하고 나면, 직접 작성한 코드에는 두 가지가 필요합니다. 정해진 형태로 답을 받는 방법, 그리고 이미 OpenAI API를 사용하는 라이브러리에서 서버에 접속하는 방법입니다. Ollama는 이 둘을 모두 문서화하고 있습니다. 이 글은 구조화된 출력 페이지와 OpenAI 호환성 페이지를 요약하고, 문서에서 지원하지 않는다고 밝힌 부분을 짚어 줍니다.

게시: 2026-10-26 · 읽는 데 약 5분 · 2026-10-26에 Ollama 공식 문서와 대조해 확인했습니다. 지원 기능은 버전에 따라 바뀌므로 최신 문서에서 확인하세요.

같은 서버를 부르는 두 가지 방법

Ollama에는 자체 API가 있으며, 문서의 예제는 http://localhost:11434/api/chat 으로 POST합니다. 또한 /v1/ 아래에 OpenAI 호환 API도 제공하므로, 기존 OpenAI 클라이언트는 기본 URL만 바꾸면 Ollama와 통신할 수 있습니다.

항목	네이티브 API	OpenAI 호환 API
기본 주소	http://localhost:11434/api/chat	http://localhost:11434/v1/
API 키	예제에는 언급되지 않음	api_key='ollama' (페이지에는 필수이지만 무시된다고 표시됨)
구조화된 출력 필드	format	response_format

API 키 항목은 문서의 로컬 서버 예제에서 가져온 것입니다. 클라우드의 경우 페이지는 base_url https://ollama.com/v1 과 Ollama 계정의 API 키를 보여 주는데, 이는 다른 경우입니다.

구조화된 출력: format 필드

format 필드는 응답을 제한합니다. 일반 JSON을 뜻하는 문자열 json 또는 JSON schema 객체를 받을 수 있습니다. 문서의 cURL 예제에서 요청 본문에는 model, messages, false로 설정한 stream, format의 네 필드가 있습니다. 예제의 스키마는 type, properties, required로 이루어져 있습니다.

format의 값	문서에 따른 효과
"json"	모델이 일반 JSON으로 답합니다
JSON schema 객체	응답이 해당 스키마에 맞도록 제한됩니다

문서에서는 모델의 응답이 흐트러지지 않도록 프롬프트에도 JSON schema를 문자열로 함께 전달하는 것이 이상적이라고 합니다.
또한 더 결정적인 완성 결과를 얻으려면 temperature를 예를 들어 0으로 낮추라고 합니다.
Python과 JavaScript에서는 스키마를 검증에도 재사용할 수 있도록 Pydantic 또는 Zod로 정의할 것을 권합니다.
비전 모델도 같은 format 매개변수를 받습니다. 문서의 비전 예제는 이미지와 스키마를 함께 전달합니다.
페이지에 따르면 Ollama의 클라우드는 현재 구조화된 출력을 지원하지 않습니다.

스키마에 의존하기 전에 먼저 검사하세요. 아래의 JSON Schema Validator는 스키마 자체가 유효한지, 그리고 샘플 응답이 스키마에 맞는지 알려 줍니다.

보내는 스키마를 확인하기

실수가 있는 스키마는 첫 요청이 모델에 도달했을 때에야 뒤늦게 실패할 수 있습니다. 스키마와 기대하는 JSON 샘플을 붙여 넣고, 둘이 일치하는지 확인해 보세요.

직접 해 보기: JSON Schema Validator

JSON SchemaJSON 데이터

지원하는 키워드는 JSON Schema Draft 2020-12를 따릅니다. $ref는 같은 스키마 안에서만 읽습니다.

모든 처리는 브라우저 안에서 이루어집니다. 스키마와 데이터는 업로드되지 않습니다.

OpenAI 호환 엔드포인트

엔드포인트	페이지에 나열된 항목	지원하지 않는 것으로 나열된 항목
/v1/chat/completions	채팅, 스트리밍, JSON mode, 재현 가능한 출력, 비전, tools, 추론 제어	logprobs, tool_choice, logit_bias, user, n; 이미지 URL (base64 사용)
/v1/completions	완성, 스트리밍, JSON mode, 재현 가능한 출력	logprobs, best_of, echo, logit_bias, user, n
/v1/models	모델 목록 조회 및 개별 조회	나열되지 않음
/v1/embeddings	문자열 또는 문자열 배열 입력, 인코딩 형식, 차원 수	토큰 배열, user
/v1/responses	스트리밍, 함수 호출 tools, 추론 요약	상태를 유지하는 요청: previous_response_id, conversation, truncation

채팅 엔드포인트에서 페이지는 지원하는 요청 필드로 response_format, tools, stream, stream_options, seed, stop, temperature, top_p, max_tokens, frequency_penalty, presence_penalty를 나열합니다.
페이지에는 구조화된 출력이 response_format을 통해 OpenAI 호환 API에서도 동작한다고 적혀 있습니다.
코드에서 지원하지 않는 항목의 필드를 사용한다면, 서버가 그것을 무시해 주기를 기대하지 말고 코드를 수정하세요. 문서는 지원하지 않는 각 필드를 어떻게 처리하는지 밝히지 않으며, 지원하지 않는 값에 400 오류를 반환하는 음성(speech)만 예외입니다.

tools와 도구 정의의 형식

네이티브 API와 OpenAI 호환 채팅 엔드포인트 모두 tools를 받습니다. 도구를 OpenAI 형태로 기술한다면, 이 사이트의 Tool Definition Checker가 전송하기 전에 이름, 설명, 매개변수 스키마를 그 형식에 비추어 검사해 줍니다.

그래도 답이 유효한 JSON이 아닐 때

출력을 제한하는 것은 유효한 JSON을 받기 위한 것이지만, 다른 모델이나 이전 버전, 또는 format 없는 요청에서는 코드가 여전히 일반 텍스트를 받을 수 있습니다. 아래 도구는 코드 펜스, 끝에 붙은 쉼표, 잘못된 따옴표 같은 흔한 문제를 복구하고, 복구로 의미가 바뀌는 경우에는 경고합니다.

직접 해 보기: LLM JSON Repair

모델 응답 또는 깨진 JSON

들여쓰기공백 2칸공백 4칸탭압축

답이 하나로 정해지는 수정만 적용합니다. 그 밖의 문제는 추측하지 않고 위치와 함께 알려 줍니다.

모든 처리는 브라우저 안에서 이루어집니다. 붙여넣은 텍스트는 업로드되지 않습니다.

접근에 관한 참고

문서의 로컬 예제는 API 키가 필수이지만 무시된다고 설명합니다. 문서의 진술이 아닌 우리의 해석입니다: 이 키는 서버를 보호하지 않으므로, Ollama는 기본 주소에 두고 다른 기기에서 접속해야 한다면 그 앞단에 인증을 두세요.