문서
← 모든 문서

문서

Ollama의 OpenAI 호환 API

Ollama는 로컬 모델을 위한 OpenAI 호환 API를 제공합니다. OpenAI SDK로 호출하는 방법과 base_url 및 model만 바꿔 같은 코드로 호스팅 Claude와 GPT를 사용하는 방법을 알아보세요.

Ollama는 오픈 모델을 사용자 컴퓨터에서 실행하고 OpenAI 호환 API http://localhost:11434/v1를 통해 제공합니다. 전송 형식이 OpenAI와 일치하므로 공식 OpenAI SDK를 변경 없이 Ollama에서 사용할 수 있으며, 기본 URL만 바꾸면 같은 코드로 호스팅 최첨단 모델도 사용할 수 있습니다.

요약 — Ollama의 OpenAI API 주소는 http://localhost:11434/v1입니다. OpenAI 클라이언트의 base_url를 해당 주소로 설정하고 임의의 api_key를 지정하세요. 호스팅 Claude/GPT를 사용하려면 base_url를 https://api.kunavo.com/v1와 모델 슬러그로 변경하면 됩니다. 다른 부분은 바뀌지 않습니다.

Ollama의 OpenAI 호환 API란

Ollama는 Llama, Qwen, Mistral 같은 모델을 로컬에서 실행하기 위한 별도의 오픈 소스 프로젝트입니다. 자체 API와 함께 OpenAI 호환 인터페이스도 제공하므로 OpenAI용으로 만든 도구를 다시 작성하지 않고 사용할 수 있습니다. 대부분의 앱에서 사용하는 다음 엔드포인트를 구현합니다.

엔드포인트용도
POST /v1/chat/completions채팅 — 대부분의 앱에서 사용하는 엔드포인트
POST /v1/completions레거시 텍스트 completions
POST /v1/embeddings로컬 모델용 임베딩
GET /v1/models로컬에 내려받은 모델 목록

채팅, completions, 임베딩과 멀티모달 로컬 모델의 비전 입력을 지원합니다. 이미지, 동영상, 오디오는 생성하지 않습니다. Kunavo도 동일한 /v1/chat/completions 계약을 구현합니다. 해당 문서는 모든 매개변수, 스트리밍 delta 형식, usage 객체를 설명하며 Ollama의 v1 인터페이스와의 항목별 동등성 표를 제공합니다.

OpenAI SDK로 Ollama 호출하기

base_url를 http://localhost:11434/v1로 지정하세요. SDK에는 api_key가 필요하지만 로컬 Ollama는 그 값을 무시하므로 아무 문자열이나 전달하면 됩니다. model는 내려받은 모델로 설정하세요(예: ollama pull llama3.2).

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible API
    api_key="ollama",  # required by the SDK, ignored by local Ollama
)

resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

또는 curl 사용:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [{"role": "user", "content": "Hello, Ollama"}]
  }'

같은 코드로 호스팅 최첨단 모델 사용하기

Ollama는 오프라인 개발과 개인정보 보호가 중요한 작업에 적합하지만, 어려운 추론, 코딩, 긴 컨텍스트 처리에서는 로컬 모델이 최첨단 모델에 미치지 못합니다. Kunavo도 OpenAI와 호환되므로 base_url와 모델 슬러그 두 줄만 바꾸면 호출을 호스팅 모델로 전환할 수 있습니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",  # only this line changes
    api_key="sk-kn-...",               # a real key now
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # a hosted frontier model
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)
Ollama(로컬)Kunavo(호스팅)
기본 URLlocalhost:11434/v1api.kunavo.com/v1
실행 위치사용자 컴퓨터관리형 API
모델로컬 오픈 모델Claude, GPT, Veo, Suno
모달리티텍스트 + 임베딩텍스트, 이미지, 동영상, 오디오
비용사용자 하드웨어 / 전기 요금토큰당, 정가 미만
적합한 용도오프라인 개발, 개인정보 보호프로덕션급 최첨단 품질
Kunavo 키 하나로 모든 호스팅 모델을 사용할 수 있고 Stripe를 통해 한 번만 청구됩니다. 첫 호출 방법은 빠른 시작을 참조하세요.

환경 변수로 전환

일반적인 패턴은 로컬 개발에는 Ollama를, 프로덕션에는 호스팅 모델을 사용하고 환경 변수로 선택하는 것입니다. 클라이언트와 요청 코드는 동일하며 base_url와 모델만 달라집니다.

import os
from openai import OpenAI

# One client, switched by environment. Local for dev, hosted for prod.
if os.getenv("APP_ENV") == "production":
    client = OpenAI(base_url="https://api.kunavo.com/v1",
                    api_key=os.environ["KUNAVO_API_KEY"])
    MODEL = "claude-haiku-4-5"
else:
    client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
    MODEL = "llama3.2"

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

자주 묻는 질문

Ollama에 OpenAI 호환 API가 있나요?

네. Ollama는 /chat/completions, /completions, /embeddings, /models를 제공하는 OpenAI 호환 REST API를 http://localhost:11434/v1에서 노출합니다. 공식 OpenAI SDK의 base_url을 이 주소로 설정하고 임의의 문자열을 api_key로 전달하면 됩니다(Ollama는 로컬에서 이를 무시합니다). model은 llama3.2와 같이 가져온 모델로 설정하세요. 요청 및 응답 형식은 OpenAI와 일치합니다.

Ollama의 OpenAI API는 어떤 기본 URL을 사용하나요?

http://localhost:11434/v1 by default. Set the OpenAI client base_url to that value. If Ollama runs on another host or port, substitute it — the /v1 suffix stays.

Ollama에서 호스팅 모델로 어떻게 전환하나요?

두 API 모두 OpenAI와 호환되므로 base_url과 model만 변경하면 됩니다. http://localhost:11434/v1을 https://api.kunavo.com/v1로 바꾸고, 실제 sk-kn- 키를 사용한 뒤, model을 claude-sonnet-5 또는 claude-haiku-4-5 같은 호스팅 모델 슬러그로 설정하세요. 다른 코드는 변경할 필요가 없습니다.

Ollama의 OpenAI API는 이미지나 동영상을 지원하나요?

Ollama의 OpenAI 호환 인터페이스는 채팅, completions, 임베딩과 멀티모달 로컬 모델의 비전 입력을 지원합니다. 이미지, 동영상, 오디오는 생성하지 않습니다. 동일한 OpenAI 스타일 API에서 호스팅 이미지, 동영상, 오디오 생성을 사용하려면 Kunavo의 /v1/images, /v1/video, /v1/audio 엔드포인트를 사용하세요.

다음 단계